grafana-ansible-collection/README.md

155 lines
7.0 KiB
Markdown
Raw Normal View History

2022-08-30 08:46:55 +02:00
# Ansible Collection for Grafana Cloud
2022-08-09 08:38:20 +02:00
2023-03-03 09:53:02 +01:00
[![Grafana](https://img.shields.io/badge/grafana-%23F46800.svg?&logo=grafana&logoColor=white)](https://grafana.com)
[![Ansible Collection](https://img.shields.io/ansible/collection/1935?color=orange&style=flat-square)](https://galaxy.ansible.com/grafana/grafana)
[![GitHub tag](https://img.shields.io/github/tag/grafana/grafana-ansible-collection.svg)](https://github.com/grafana/grafana-ansible-collection/tags)
[![GitHub Last Commit](https://img.shields.io/github/last-commit/grafana/grafana-ansible-collection)](https://github.com/grafana/grafana-ansible-collection/tags)
[![GitHub Contributors](https://img.shields.io/github/contributors/grafana/grafana-ansible-collection)](https://github.com/grafana/grafana-ansible-collection/tags)
[![Lint](https://github.com/grafana/grafana-ansible-collection/actions/workflows/lint.yaml/badge.svg)](https://github.com/grafana/grafana-ansible-collection/actions/workflows/lint.yaml)
2022-08-23 15:46:47 +02:00
[![CI Tests](https://github.com/grafana/grafana-ansible-collection/actions/workflows/ci-test.yml/badge.svg)](https://github.com/grafana/grafana-ansible-collection/actions/workflows/ci-test.yml)
2022-08-23 15:46:11 +02:00
[![Full Integration Test](https://github.com/grafana/grafana-ansible-collection/actions/workflows/full-integration-test.yml/badge.svg?branch=main)](https://github.com/grafana/grafana-ansible-collection/actions/workflows/full-integration-test.yml)
2022-08-17 10:14:50 +02:00
2023-03-03 09:53:02 +01:00
This collection (`grafana.grafana`) contains modules and plugins to assist in automating managing of resources in **Grafana Cloud** with Ansible.
2022-08-09 08:38:20 +02:00
2023-03-24 06:27:45 +01:00
- [Ansible collection Documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/)
2023-03-03 09:53:02 +01:00
- [Grafana Site](https://grafana.com)
- [Grafana Cloud Site](https://grafana.com/products/cloud/)
2022-08-17 10:14:50 +02:00
2022-08-11 07:09:04 +02:00
## Ansible version compatibility
2022-08-09 08:38:20 +02:00
2023-03-03 09:53:02 +01:00
The collection is tested and supported with: `ansible >= 2.9`
2022-08-09 08:38:20 +02:00
2022-08-09 09:21:37 +02:00
## Installing the collection
2022-08-09 08:38:20 +02:00
2023-03-03 09:53:02 +01:00
Before using the Grafana collection, you need to install it using the below command:
2022-08-09 08:38:20 +02:00
```shell
2022-08-10 12:12:05 +02:00
ansible-galaxy collection install grafana.grafana
2022-08-09 08:38:20 +02:00
```
You can also include it in a `requirements.yml` file and install it via ansible-galaxy collection install -r `requirements.yml`, using the format:
```yaml
---
collections:
- name: grafana.grafana
```
2023-03-03 09:53:02 +01:00
2022-09-09 11:35:48 +02:00
A specific version of the collection can be installed by using the version keyword in the `requirements.yml` file:
2022-08-09 08:38:20 +02:00
```yaml
---
collections:
2022-08-09 11:42:25 +02:00
- name: grafana.grafana
version: 1.0.0
2022-08-09 08:38:20 +02:00
```
2023-03-03 09:53:02 +01:00
2022-08-09 08:38:20 +02:00
## Using this collection
You can call modules by their Fully Qualified Collection Namespace (FQCN), such as `grafana.grafana.cloud_stack`:
2023-03-03 09:53:02 +01:00
2022-08-09 08:38:20 +02:00
```yaml
- name: Using grafana collection
hosts: localhost
tasks:
- name: Create a Grafana Cloud stack
grafana.grafana.cloud_stack:
name: mystack
stack_slug: mystack
org_slug: myorg
cloud_api_key: "{{ cloud_api_key }}"
region: eu
state: present
```
or you can add full namespace and collection name in the `collections` element in your playbook
2023-03-03 09:53:02 +01:00
2022-08-09 08:38:20 +02:00
```yaml
- name: Using grafana collection
hosts: localhost
collection:
- grafana.grafana
tasks:
- name: Create a Grafana Cloud stack
cloud_stack:
name: mystack
stack_slug: mystack
org_slug: myorg
cloud_api_key: "{{ cloud_api_key }}"
region: eu
state: present
```
## Contributing
2023-03-03 09:53:02 +01:00
We are accepting GitHub pull requests and issues. There are many ways in which you can participate in the project, for example:
- Submit bugs and feature requests, and help us verify them
- Submit and review source code changes in GitHub pull requests
- Add new modules for more Grafana resources
2022-08-09 08:38:20 +02:00
## Testing and Development
If you want to develop new content for this collection or improve what is already
here, the easiest way to work on the collection is to clone it into one of the configured
[`COLLECTIONS_PATHS`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths),
and work on it there.
### Testing with `ansible-test`
We use `ansible-test` for sanity.
2023-03-03 09:53:02 +01:00
## Commands
| Command | Description |
| :--- | :----------- |
| `make setup` | Checks to see if necessary tools are installed |
| `make install` | Installs project dependencies |
| `make lint` | Performs all linting commands |
| `make lint-sh` / `make lint-shell` | Performs shell script linting |
| `make lint-md` / `make lint-markdown` | Performs Markdown linting |
| `make lint-txt` / `make lint-text` | Performs text linting |
| `make lint-yml` / `make lint-yaml` | Performs Yaml linting |
2023-03-03 10:04:11 +01:00
| `make lint-ec` / `make lint-editorconfig` | Performs EditorConfig Checks |
2023-03-03 09:53:02 +01:00
| `make lint-ansible` | Performs Ansible linting |
| `make clean` | Removes the `./node_modules` and `./build` directories |
| `make reinstall` | Shortcut to `make clean` and `make install` |
## Releasing, Versioning and Deprecation
This collection follows [Semantic Versioning](https://semver.org/). More details on versioning can be found [in the Ansible docs](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-versions).
We plan to regularly release new minor or bugfix versions once new features or bugfixes have been implemented.
2023-03-03 09:53:02 +01:00
Releasing the current major version on GitHub happens from the `main` branch by the
[GitHub Release Workflow](https://github.com/grafana/grafana-ansible-collection/blob/main/.github/workflows/release.yml).
Before the [GitHub Release Workflow](https://github.com/grafana/grafana-ansible-collection/blob/main/.github/workflows/release.yml)
is run, Contributors should push the new version on Ansible Galaxy Manually.
2023-03-03 09:53:02 +01:00
We currently are not planning any deprecations or new major releases. The current landscape includes minor version updates for
2023-03-27 06:36:27 +02:00
module's documentation in `2.0.1`.
To generate changelogs for a new release, Refer [Generating Changelogs](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_changelogs.html#generating-changelogs)
To generate the tarball to be uploaded on Ansible Galaxy, Refer [Building collection tarball](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_distributing.html#building-your-collection-tarball)
2022-08-11 07:09:04 +02:00
## Code of Conduct
2023-03-03 09:53:02 +01:00
This collection follows the Ansible project's [Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html).
Please read and familiarize yourself with this doc
2022-08-11 07:09:04 +02:00
2022-08-09 08:38:20 +02:00
## More information
2023-03-03 09:53:02 +01:00
- [Maintainer guidelines](https://docs.ansible.com/ansible/devel/community/maintainers.html)
- Subscribe to the [news-for-maintainers](https://github.com/ansible-collections/news-for-maintainers) repository and track announcements there.
- [Ansible Collection overview](https://github.com/ansible-collections/overview)
- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
- [Ansible Developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html)
- [Ansible Collection Developer Guide](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html)
- [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
2022-08-09 08:38:20 +02:00
## License
2022-09-09 11:35:48 +02:00
GPL-3.0-or-later