Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alphagov/paas-grafana-annotation-resource

A concourse resource for creating and updating Grafana annotations, now maintained by GOV.UK Pay
https://github.com/alphagov/paas-grafana-annotation-resource

concourse concourse-resource govuk-pay grafana

Last synced: 5 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/alphagov/paas-grafana-annotation-resource
Owner: alphagov
License: mit
Created: 2019-10-13T16:49:10.000Z (about 5 years ago)
Default Branch: main
Last Pushed: 2024-05-20T09:32:40.000Z (6 months ago)
Last Synced: 2024-05-20T10:44:56.153Z (6 months ago)
Topics: concourse, concourse-resource, govuk-pay, grafana
Language: Go
Homepage:
Size: 75.2 KB
Stars: 12
Watchers: 11
Forks: 10
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

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

![CI Workflow GitHub Actions Badge](https://github.com/alphagov/paas-grafana-annotation-resource/workflows/ci/badge.svg)
![License GitHub Badge](https://img.shields.io/github/license/alphagov/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.

```
# Create a point-in-time annotation, e.g. a single event
- 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.