paas-grafana-annotation-resource - GitLite

KO | EN

gitlite — search

#kubernetes #awesome #cli #codex #generative-ai #large-language-models #automation #framework #anthropic #android

paas-grafana-annotation-resource

(★ 12)

A concourse resource for creating and updating Grafana annotations, now maintained by GOV.UK Pay

File Explorer

ZIP Download

- - ci.yml
  - post-merge.yml
- dependabot.yml
- - main.go
- - main.go
- - main.go
- simple-pipeline.yml
- integration_test.go
- - check.go
  - check_test.go
- - in.go
  - in_test.go
- - out.go
  - out_test.go
- - tags.go
  - tags_test.go
- - resource_source.go
  - types.go
.gitignore
.pre-commit-config.yaml
.secrets.baseline
docker-compose.local.yml
docker-compose.yml
Dockerfile
go.mod
go.sum
LICENSE
Makefile
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

`paas-grafana-annotation-resource`
-----------------------------

![CI Workflow GitHub Actions Badge](https://github.com/govuk-pay/paas-grafana-annotation-resource/workflows/ci/badge.svg)
![License GitHub Badge](https://img.shields.io/github/license/govuk-pay/paas-grafana-annotation-resource?style=plastic)

A resource for adding annotations to Grafana dashboards.

The resource represents a single Grafana (`version >= 6.4`) and this resource
can be used to add and update annotations using tags. Version `6.4` and above is required because the resource assumes that resources are represented by a single annotation.

Usage
-----

See the example below for all the pipeline code.

If you create an annotation using with `put: resource-name`, it will be a
point-in-time annotation. This put step will write the ID of the current
resource to `resource-name/id`.

In order to make it the annotation a region annotation, put to the resource
again, but pass the resource name to the path `path` param.  This will update
the annotation, and make it a region beginning when the resource was created,
and ending at the current time.

```
- put: my-grafana-annotation

- task: do-a-thing-that-takes-some-time

# Update the point-in-time annotation to be a region
  # The region's duration will be the time taken by the task
- put: my-grafana-annotation
  params:
    path: my-grafana-annotation
```

Example
-------

In the following example, imagine we are running smoke tests from Concourse,
and we want to annotate our Grafana dashboard with a region during which the
smoke tests ran.

First define `grafana-annotation` as a resource type:

```
resource_types:
  - name: grafana-annotation
    type: docker-image
    source:
      repository: governmentdigitalservice/pay-grafana-annotation-resource
      tag: latest
```

Then declare a `grafana-annotation` resource with a descriptive name:

```
resources:
  - name: run-smoke-tests-annotation
    type: grafana-annotation
    source:
      url: http://grafana:3000
      username: admin
      password: admin

tags:
        - run-from-concourse
        - smoke-tests
```

Then use the resource:

```
jobs:
  - name: run-smoke-tests
    plan:
      - put: run-smoke-tests-annotation
        params:
          tags:
            - started

- task: run-smoke-tests
        config:
          platform: linux
          image_resource:
            type: docker-image
            source:
              repository: my-smoke-tests
              tag: latest
          run:
            path: /bin/smoke

- put: run-smoke-tests-annotation
        params:
          tags:
            - finished

# The path is the resource name, so the ID is identical to above.
          # This tells the resource that we are updating an existing annotation

path: run-smoke-tests-annotation
```

Configuration
-------------

The source can be configured like so:

```
resources:
  - name: my-resource-name
    type: grafana-annotation
    source:

# Required
      url: http://grafana:3000

# Optional; required if 'username' is absent
      api_token: 123456789

# Optional; required if 'api_token' is absent
      username: admin

# Optional; required if 'username' is present
      password: admin

# Optional
      tags:
        - tag1
        - tag2
        - ((environment))

# Optional
      env:
        MY_SRC_VAR: ((can_take_variables))
```

The params can be configured like so:

```
- put: my-resource-name
  params:

# Optional
    # These get merged with the env block from source
    env:
      MY_PARAM_VAR: foo-bar

# Optional
    # Can use environment variables
    template:  "${BUILD_ID} ; ${MY_SRC_VAR} ; ${MY_PARAM_VAR}"

# Optional
    # Are merged with tags from source
    tags:
      - started

# Optional
    # See example above
    # - Should not be present if creating a resource
    # - Should be the resource name if updating an annotation
    path: my-resource-name
```

Notes
-----

- The tags in source and params are merged

- When an existing annotation is updated, the tags from creation are
overwritten with the tags from the update

- You should ensure `put` steps to Grafana in `try` and `ensure` + `try` task
steps so that failure to create/update regions in Grafana does not impact your
pipeline.

- Currently updating individual dashboards and panels is not supported. Use
tags to view your resources instead.

Contributing
------------

Please raise a pull request, once you agree with the [LICENSE](/LICENSE).

To run the integration tests please first run:

```
docker-compose build
docker-compose up -d
docker-compose down
```

which will ensure that all software components are present, built, and ready to
test against.

## Licence

[MIT License](LICENSE)

## Vulnerability Disclosure

GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. Please refer to our [vulnerability disclosure policy](https://www.gov.uk/help/report-vulnerability) and our [security.txt](https://vdp.cabinetoffice.gov.uk/.well-known/security.txt) file for details.