diff --git a/docs/sources/as-code/infrastructure-as-code/_index.md b/docs/sources/as-code/infrastructure-as-code/_index.md index 1579602467b..c976df81106 100644 --- a/docs/sources/as-code/infrastructure-as-code/_index.md +++ b/docs/sources/as-code/infrastructure-as-code/_index.md @@ -4,17 +4,23 @@ keywords: - Quickstart - Grafana Cloud menuTitle: Infrastructure as code -title: Provision Grafana Cloud with infrastructure as code +title: Provision Grafana Cloud with Infrastructure as code weight: 800 +labels: + products: + - cloud canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ --- -# Provision Grafana Cloud with infrastructure as code +# Provision Grafana Cloud with Infrastructure as code -With Grafana Cloud, you can create dashboards via configuration files in source code. This enables you to review code, reuse it, and create better workflows. +With Grafana Cloud, you can use as-code tools to create and manage resources via code, and incorporate them efficiently into your own use cases. This enables you to review code, reuse it, and create better workflows. -Via code, you can _declaratively_ manage _what_ Grafana resources to use. -The as-code tools and tutorials that follow show you what do to, to declaratively manage Grafana resources, and incorporate them efficiently into your own use cases. +{{< admonition type="note" >}} + +Most of the tools defined here can be used with one another. + +{{< /admonition >}} ## Grafana Terraform provider @@ -67,7 +73,7 @@ To get started, see the [quickstart guides for the Grafana Ansible Collection](/ ### Who is this recommended for? -Like Terraform, the Grafana Ansible collection is best suited for people already using Ansible for non-Grafana use cases. The collection only works for Grafana Cloud right now, so it makes the most sense for Grafana Cloud customers who want to manage resources declaratively using Ansible. +Like Terraform, the Grafana Ansible collection is best suited for people already using Ansible for non-Grafana use cases. The collection only works for Grafana Cloud right now, so it makes the most sense for Grafana Cloud customers who want to manage resources using Ansible. ### Known limitations @@ -75,7 +81,7 @@ The Grafana Ansible collection only works for Grafana Cloud and only supports ei ## Grafana Operator -The Grafana Operator is a Kubernetes operator that can provision, manage, and operate Grafana instances and their associated resources within Kubernetes through Custom Resources. This Kubernetes-native tool eases the administration of Grafana, offering a declarative approach to managing dashboards, data sources, and folders. It also automatically syncs the Kubernetes Custom resources and the actual resources in the Grafana Instance. It supports leveraging Grafonnet for generating Grafana dashboard definitions for seamless dashboard configuration as code. +The Grafana Operator is a Kubernetes operator that can provision, manage, and operate Grafana instances and their associated resources within Kubernetes through Custom Resources. This Kubernetes-native tool eases the administration of Grafana, including managing dashboards, data sources, and folders. It also automatically syncs the Kubernetes Custom resources and the actual resources in the Grafana Instance. It supports leveraging Grafonnet for generating Grafana dashboard definitions for seamless dashboard configuration as code. To get started, see the [quickstart guides for the Grafana Operator](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/) or check out the [Grafana Operator's documentation](https://grafana.github.io/grafana-operator/). @@ -120,7 +126,7 @@ To get started with the Grafana Crossplane provider, install Crossplane in the K kubectl crossplane install provider grafana/crossplane-provider-grafana:v0.1.0 ``` -During installation of the provider, CRDs for all the resources supported by the Terraform provider are added to the cluster so users can begin defining their Grafana resources as Kubernetes custom resources. The Crossplane provider ensures that whatever is defined in the custom resource definitions is what is visible in Grafana UI. If any changes are made directly in the UI, the changes will be discarded when the provider resyncs. This helps ensure that whatever is defined declaratively in the cluster will be the source of truth for Grafana resources. +During installation of the provider, CRDs for all the resources supported by the Terraform provider are added to the cluster so users can begin defining their Grafana resources as Kubernetes custom resources. The Crossplane provider ensures that whatever is defined in the custom resource definitions is what is visible in Grafana UI. If any changes are made directly in the UI, the changes will be discarded when the provider resyncs. This helps ensure that whatever is defined via code in the cluster will be the source of truth for Grafana resources. To get started, refer to the examples folder in the Grafana Crossplane repository. @@ -152,16 +158,15 @@ To use the Crossplane provider, you must have the Crossplane CLI and Crossplane ## Grafana as code comparison -Most of the tools defined here can be used with one another. The following chart compares the properties and tools mentioned above. -| Property/Tool | Grafana Terraform Provider | Grafana Ansible Collection | Grafana Operator | Grizzly | Grafana Crossplane Provider | -| -------------------------------------- | --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| Grafana resources supported | All major Grafana resources | Grafana Cloud stack, plugins, API keys, dashboards, data sources, and folders | Dashboards, Datasources, Folders | Synthetic Monitoring checks, dashboards, data sources, folders, and Prometheus rules | All major Grafana resources | -| Tool format | HCL/JSON | YAML | YAML | Jsonnet/YAML/JSON | YAML/JSON | -| Follows Kubernetes-style manifests | | | ✓ | ✓ | ✓ | -| Easy dashboard building process | | | ✓ | ✓ | | -| Manage resources using Kubernetes | | | ✓ | | ✓ | -| Retrieves Grafana resource information | ✓ | | | | | -| Built-in resource sync process | | | ✓ | ✓ | ✓ | -| Recommended for | Existing Terraform users | Existing Ansible users | Users looking to manage Grafana resources from within Kubernetes | Users looking to define Grafana resources in a Kubernetes-style YAML and users looking to get built-in workflow support and sync process | Users looking to manage Grafana resources from within Kubernetes | +| Property/Tool | Grafana Terraform Provider | Grafana Ansible Collection | Grafana Operator | Grafana Crossplane Provider | +| -------------------------------------- | --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | +| Grafana resources supported | All major Grafana resources | Grafana Cloud stack, plugins, API keys, dashboards, data sources, and folders | Dashboards, data sources, Folders | All major Grafana resources | +| Tool format | HCL/JSON | YAML | YAML | YAML/JSON | +| Follows Kubernetes-style manifests | | | ✓ | ✓ | +| Easy dashboard building process | | | ✓ | | +| Manage resources using Kubernetes | | | ✓ | ✓ | +| Retrieves Grafana resource information | ✓ | | | | +| Built-in resource sync process | | | ✓ | ✓ | +| Recommended for | Existing Terraform users | Existing Ansible users | Users looking to manage Grafana resources from within Kubernetes | Users looking to manage Grafana resources from within Kubernetes | diff --git a/docs/sources/as-code/infrastructure-as-code/ansible/_index.md b/docs/sources/as-code/infrastructure-as-code/ansible/_index.md index 46d44ff1f90..2f977b0166e 100644 --- a/docs/sources/as-code/infrastructure-as-code/ansible/_index.md +++ b/docs/sources/as-code/infrastructure-as-code/ansible/_index.md @@ -8,22 +8,42 @@ menuTitle: Ansible title: Grafana Ansible collection weight: 110 canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ +aliases: + - ../../infrastructure-as-code/ansible/ansible-grafana-agent-linux + - ../../infrastructure-as-code/ansible/ansible-multiple-agents +labels: + products: + - cloud --- # Grafana Ansible collection -The [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/) provides configuration management resources for Grafana. You can use it to manage resources such as dashboards, Cloud stacks, folders, and more. +The [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/) provides configuration management resources for Grafana. You can use it to manage: -The collection also houses the [Grafana Agent role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent) which can be used to deploy and manage Grafana Agent across various Linux machines. +- Grafana Cloud stacks +- Dashboards +- Data sources +- Folders +- Alerting contact points +- Notification policies +- API keys + +If your resources aren't currently available in the Grafana Ansible collection, you can manage them on Grafana Cloud programmatically by writing Ansible playbooks that use the [Ansible's built-in URI module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html) to call the [HTTP APIs](/docs/grafana/latest/developers/http_api/) to manage resources for the Grafana Cloud portal, as well as those within a stack. + +## Learn more + +Refer to [Create and manage a Grafana Cloud stack using Ansible](ansible-cloud-stack/) to learn how to create a Grafana Cloud stack and add a data source and dashboard using [Ansible](https://www.ansible.com/). + +To learn more about managing Grafana with Infrastructure as code: + +- [Grafana Ansible collection documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/) +- [Ansible playbook best practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html) +- [Grafana API documentation](/docs/grafana/latest/developers/http_api/) +- [Grafana Cloud API documentation](https://grafana.com/docs/grafana-cloud/developer-resources/api-reference/) +- [Infrastructure as Code with Terraform](/docs/grafana/latest/as-code/infrastructure-as-code/terraform/) + +## Grafana Agent (deprecated) {{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}} -For resources currently not available in the Grafana Ansible collection, you can manage those resources on Grafana Cloud programmatically by writing Ansible playbooks that use the [Ansible's builtin uri module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html) to call the [HTTP APIs](/docs/grafana/latest/developers/http_api/) to manage resources for the Grafana Cloud portal, as well as those within a stack. - -Use the following guides to get started using Ansible to manage your Grafana Cloud stack: - -| Topic | Description | -| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| [Create and manage a Grafana Cloud stack using Ansible](ansible-cloud-stack/) | Describes how to create a Grafana Cloud stack and add a data source and dashboard using [Ansible](https://www.ansible.com/). | -| [Install Grafana Agent on a Linux host using Ansible](ansible-grafana-agent-linux/) | Describes how to install the Grafana Agent on a Linux node using Ansible and use it to push logs to Grafana Cloud. | -| [Monitor multiple Linux hosts with Grafana Agent Role](ansible-multiple-agents/) | Describes how to use the Grafana Ansible collection to manage agents across multiple Linux hosts. | +The Ansible collection also houses [Grafana Agent role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent), which is now deprecated. diff --git a/docs/sources/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/index.md b/docs/sources/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/index.md index 5dcab277f04..55f875fd1a7 100644 --- a/docs/sources/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/index.md +++ b/docs/sources/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/index.md @@ -4,64 +4,78 @@ keywords: - Quickstart - Grafana Cloud - Ansible -title: Create and manage a Grafana Cloud stack using Ansible +title: Create and manage your Grafana Cloud stack using Ansible +menuTitle: Manage stack using Ansible weight: 100 canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/ --- -# Create and manage a Grafana Cloud stack using Ansible +# Create and manage your Grafana Cloud stack using Ansible -Learn how to add a data source, a dashboard, and a folder to a Grafana Cloud stack using Ansible collection for Grafana. +This guide shows you how to create a Grafana Cloud stack and add a data source, dashboard, and folder using the Ansible Collection for Grafana. You'll manage your Grafana infrastructure through Ansible playbooks. ## Before you begin -Before you begin, you should have the following available: +Before you begin, make sure you have the following available: -- A Grafana Cloud account. +- A Grafana Cloud account - [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) installed on your machine +## Install the Grafana Ansible collection + +Install the Grafana Ansible collection: + +```sh +ansible-galaxy collection install grafana.grafana +``` + +This collection provides all the modules needed to manage Grafana Cloud stacks and resources. + ## Create a Cloud stack -1. Create a Grafana Cloud Access Policy and get a token. - You'll need this for the Ansible playbook to be able to create a Grafana Cloud stack. - Refer to [Create a Grafana Cloud Access Policy](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/). +First, create a Grafana Cloud Access Policy and get a token. You'll need this for the Ansible playbook to be able to create a Grafana Cloud stack. Refer to [Create a Grafana Cloud Access Policy](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/). -1. Create an Ansible playbook file. +Next, create an Ansible playbook file. This Ansible playbook creates a Grafana Cloud stack using the [Cloud stack module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/cloud_stack_module.html#ansible-collections-grafana-grafana-cloud-stack-module). - This Ansible playbook will create a Grafana Cloud stack by using the [Cloud stack module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/cloud_stack_module.html#ansible-collections-grafana-grafana-cloud-stack-module). +To do so, create a file named `cloud-stack.yml` and add the following: - Create a file named `cloud-stack.yml` and add the following: +```yaml +- name: Create Grafana Cloud stack + connection: local + hosts: localhost - ```yaml - - name: Create Grafana Cloud stack - connection: local - hosts: localhost + vars: + grafana_cloud_api_key: '' + stack_name: '' + org_name: '' - vars: - grafana_cloud_api_key: '' - stack_name: '' - org_name: '' + tasks: + - name: Create a Grafana Cloud stack + grafana.grafana.cloud_stack: + name: '{{ stack_name }}' + stack_slug: '{{ stack_name }}' + cloud_api_key: '{{ grafana_cloud_api_key }}' + org_slug: '{{ org_name }}' + delete_protection: true + state: present + register: stack_result - tasks: - - name: Create a Grafana Cloud stack - grafana.grafana.cloud_stack: - name: '{{ stack_name }}' - stack_slug: '{{ stack_name }}' - cloud_api_key: '{{ grafana_cloud_api_key }}' - org_slug: '{{ org_name }}' - delete_protection: true - state: present - ``` + - name: Display stack URL + debug: + msg: 'Stack created at: {{ stack_result.url }}' +``` -1. Replace the following field values: - - `` with a token from the Cloud Access Policy you created in the Grafana Cloud portal. - - `` with the name of your stack. - - `` with the name of the organization in Grafana Cloud. +Replace the placeholders with your values: -## Create an API key in the Grafana stack +- _``_: Token from the Cloud Access Policy you created in the Grafana Cloud portal +- _``_: Name of your stack +- _``_: Name of the organization in Grafana Cloud -Create an API key in the Grafana stack. -You'll need this key to configure Ansible to be able to create data source, folders, and dashboards. +The playbook registers the stack creation result and displays the stack URL, which you'll need for subsequent resource management. + +## Create an API key in your Grafana stack + +Create an API key in the Grafana stack. You'll need this key to configure Ansible to create data sources, folders, and dashboards. 1. Log into your Grafana Cloud instance. 2. Click **Administration** and select **API keys**. @@ -70,171 +84,169 @@ You'll need this key to configure Ansible to be able to create data source, fold 5. In **Role**, select **Admin** or **Editor** to associate the role with this API key. 6. Click **Copy** to save it for later use. -## Add a data source +## Add resources using playbooks -This guide uses the InfluxDB data source. -The required arguments vary depending on the type of data source you select. +### Add a data source -1. Create a file named `data-source.yml` and add the following: +The following steps use the InfluxDB data source. The required arguments vary depending on the type of data source you select. - ```yaml - - name: Add/Update data source - connection: local - hosts: localhost +Create a file named `data-source.yml`: - vars: - data_sources: - [ - { - name: '', - type: 'influxdb', - url: '', - user: '', - secureJsonData: { password: '' }, - database: '', - id: , - uid: '', - access: 'proxy', - }, - ] +```yaml +- name: Add/Update data source + connection: local + hosts: localhost - grafana_api_key: '' - stack_name: '' + vars: + grafana_url: 'https://.grafana.net' + grafana_api_key: '' + data_source_config: + name: '' + type: 'influxdb' + url: '' + user: '' + secureJsonData: + password: '' + database: '' + uid: '' + access: 'proxy' - tasks: - - name: Create/Update Data sources - grafana.grafana.datasource: - datasource: '{{ item }}' - stack_slug: '{{ stack_name }}' - grafana_api_key: '{{ grafana_api_key }}' - state: present - loop: '{{ data_sources }}' - ``` + tasks: + - name: Create/Update Data source + grafana.grafana.datasource: + dataSource: '{{ data_source_config }}' + grafana_url: '{{ grafana_url }}' + grafana_api_key: '{{ grafana_api_key }}' + state: present +``` -1. Replace the following field values: - - `` with the name of the data source to be added in Grafana. - - `` with URL of your data source. - - `` with the username for authenticating with your data source. - - `` with the password for authenticating with your data source. - - `` with name of your database. - - `` with the ID for your data source in Grafana. - - `` wth the UID for your data source in Grafana. - - `` with the name of your stack. - - `` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack). +Replace the placeholders with your values: -## Add a folder +- _``_: Name of the data source to be added in Grafana +- _``_: URL of your data source +- _``_: Username for authenticating with your data source +- _``_: Password for authenticating with your data source +- _``_: Name of your database +- _``_: UID for your data source in Grafana +- _``_: Name of your stack +- _``_: API key created in the Grafana instance -This Ansible playbook creates a folder in your Grafana instance by using the [Folder module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/folder_module.html#ansible-collections-grafana-grafana-folder-module). +### Add a folder -1. Create a file named `folder.yml` and add the following: +This playbook creates a folder in your Grafana instance using the [Folder module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/folder_module.html#ansible-collections-grafana-grafana-folder-module). - ```yaml - - name: Add/Update Folders - connection: local - hosts: localhost +Create a file named `folder.yml`: - vars: - folders: [{ title: '', uid: '' }] +```yaml +- name: Add/Update Folders + connection: local + hosts: localhost - stack_name: '' - grafana_api_key: +vars: + grafana_url: 'https://.grafana.net' + grafana_api_key: '' + folders: + - title: '' + uid: '' - tasks: - - name: Create/Update a Folder in Grafana - grafana.grafana.folder: - title: '{{ item.title }}' - uid: '{{ item.uid }}' - stack_slug: '{{ stack_name }}' - grafana_api_key: '{{ grafana_api_key }}' - state: present - loop: '{{ folders }}' - ``` + tasks: + - name: Create/Update a Folder in Grafana + grafana.grafana.folder: + title: '{{ item.title }}' + uid: '{{ item.uid }}' + grafana_url: '{{ grafana_url }}' + grafana_api_key: '{{ grafana_api_key }}' + state: present + loop: '{{ folders }}' +``` -1. Replace the following field values: - - `` with the name of the folder to be added in Grafana. - - `` with the UID for your folder in Grafana. - - `` with the name of your stack. - - `` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack). +Replace the placeholders with your values: -## Add a dashboard to the folder +- _``_: Name of the folder to be added in Grafana +- _``_: UID for your folder in Grafana +- _``_: Name of your stack +- _``_: API key created in the Grafana instance -This Ansible playbook iterates through the dashboard JSON source code files in the folder referenced in `dashboards_path` and adds them in the Grafana instance by using the [Dashboard module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/dashboard_module.html#ansible-collections-grafana-grafana-dashboard-module). +### Add a dashboard to the folder -1. Create a file named `dashboard.yml` and add the following: +This playbook iterates through the dashboard JSON source code files in the folder referenced in `dashboards_path` and adds them to the Grafana instance using the [Dashboard module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/dashboard_module.html#ansible-collections-grafana-grafana-dashboard-module). - ```yaml - - name: Add/Update Dashboards - connection: local - hosts: localhost +Create a file named `dashboard.yml`: - vars: - dashboards_path: # Example "./dashboards" - stack_name: "" - grafana_api_key: +```yaml +- name: Add/Update Dashboards + connection: local + hosts: localhost - tasks: - - name: Find dashboard files - find: - paths: "{{ dashboards_path }}" - file_type: file - recurse: Yes - patterns: "*.json" - register: files_matched - no_log: True + vars: + grafana_url: 'https://.grafana.net' + grafana_api_key: '' + dashboards_path: '' # Example "./dashboards" - - name: Create list of dashboard file names - set_fact: - dashboard_file_names: "{{ dashboard_file_names | default ([]) + [item.path] }}" - loop: "{{ files_matched.files }}" - no_log: True + tasks: + - name: Find dashboard files + find: + paths: '{{ dashboards_path }}' + file_type: file + recurse: true + patterns: '*.json' + register: files_matched + no_log: true - - name: Create/Update a dashboard - grafana.grafana.dashboard: - dashboard: "{{ lookup('ansible.builtin.file','{{ item }}' ) }}" - stack_slug: "{{ stack_name }}" - grafana_api_key: "{{ grafana_api_key }}" - state: present - loop: "{{ dashboard_file_names }}" - ``` + - name: Create list of dashboard file names + set_fact: + dashboard_file_names: '{{ dashboard_file_names | default([]) + [item.path] }}' + loop: '{{ files_matched.files }}' + no_log: true -1. Replace the following field values: - - `` with the path to the folder containing dashboard JSON source code files. - - `` with the name of your stack. - - `` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack). + - name: Create/Update a dashboard + grafana.grafana.dashboard: + dashboard: "{{ lookup('ansible.builtin.file', item) }}" + grafana_url: '{{ grafana_url }}' + grafana_api_key: '{{ grafana_api_key }}' + state: present + loop: '{{ dashboard_file_names }}' +``` + +Replace the placeholders with your values: + +- _``_: Path to the folder containing dashboard JSON source code files +- _``_: Name of your stack +- _``_: API key created in the Grafana instance ## Run the Ansible playbooks In a terminal, run the following commands from the directory where all of the Ansible playbooks are located. -1. To create the Grafana Cloud stack. +Create the Grafana Cloud stack: - ```shell - ansible-playbook cloud-stack.yml - ``` +```sh +ansible-playbook cloud-stack.yml +``` -1. To add a data source to the Grafana stack. +Add a data source to the Grafana stack: - ```shell - ansible-playbook data-source.yml - ``` +```sh +ansible-playbook data-source.yml +``` -1. To add a folder to the Grafana stack +Add a folder to the Grafana stack: - ```shell - ansible-playbook folder.yml - ``` +```sh +ansible-playbook folder.yml +``` -1. To add a dashboard to the folder in your Grafana stack. +Add a dashboard to the folder in your Grafana stack: - ```shell - ansible-playbook dashboard.yml - ``` +```sh +ansible-playbook dashboard.yml +``` -## Validation +## Validate your configuration -Once you run the Ansible playbooks, you should be able to verify the following: +After you've run the Ansible playbooks, you can verify the following: -- The new Grafana stack is created and visible in the Cloud Portal. +- The new Grafana Cloud stack is created and visible in the Cloud Portal. ![Cloud Portal](/static/img/docs/grafana-cloud/terraform/cloud_portal_tf.png) @@ -242,18 +254,22 @@ Once you run the Ansible playbooks, you should be able to verify the following: ![InfluxDB datasource](/media/docs/grafana-cloud/screenshot-influxdb_datasource_tf.png) -- A new folder in Grafana. - In the following image, a folder named `Demos` was added. +- A new folder is available in your Grafana stack. In the following image, a folder named `Demos` was added. ![Folder](/media/docs/grafana-cloud/screenshot-folder_tf.png) -- A new dashboard in the Grafana stack. - In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the "Demos" folder. +- A new dashboard is visible in the Grafana stack. In the following image, a dashboard named `InfluxDB Cloud Demos` was created inside the "Demos" folder. ![InfluxDB dashboard](/static/img/docs/grafana-cloud/terraform/influxdb_dashboard_tf.png) -## Summary +## Next steps -In this guide, you created a Grafana Cloud stack along with a data source, folder, and dashboard imported from a JSON file using Ansible. +You've successfully created a Grafana Cloud stack along with a data source, a folder, and a dashboard using Ansible. Your Grafana infrastructure is now managed through code. -To learn more about managing Grafana using Ansible, refer to the [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/). +To learn more about managing Grafana with Infrastructure as code: + +- [Grafana Ansible collection documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/) +- [Ansible playbook best practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html) +- [Grafana API documentation](/docs/grafana/latest/developers/http_api/) +- [Grafana Cloud API documentation](https://grafana.com/docs/grafana-cloud/developer-resources/api-reference/) +- [Infrastructure as Code with Terraform](/docs/grafana/latest/as-code/infrastructure-as-code/terraform/) diff --git a/docs/sources/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/index.md b/docs/sources/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/index.md deleted file mode 100644 index 8fa3a6f8357..00000000000 --- a/docs/sources/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/index.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -keywords: - - Infrastructure as Code - - Quickstart - - Grafana Cloud - - Ansible -title: Install Grafana Agent on a Linux host using Ansible -weight: 200 -canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/ ---- - -# Install Grafana Agent on a Linux host using Ansible - -{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}} - -This guide shows how to install Grafana Agent on a Linux host using [Ansible](https://www.ansible.com/) and to use it to push logs to Grafana Cloud. - -## Before you begin - -Before you begin, you should have the following available: - -- A Grafana Cloud account. -- A Linux machine -- Command line (terminal) access to that Linux machine with `unzip` binary installed -- Account permissions sufficient to install and use Grafana Agent on the Linux machine -- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) installed on the Linux machine - -## Choose your Grafana Agent installation method - -This guide covers two methods for installing and configuring Grafana Agent using Ansible: - -- Installing Grafana Agent in Flow mode -- Installing Grafana Agent in static mode - -Depending on your specific needs and the configuration of your environment, you may choose one method over the other for better compatibility or ease of setup. - - - -### Install Grafana Agent in flow mode using Ansible - -This Ansible playbook installs Grafana Agent in Flow mode and also creates a systemd service to manage it. - -It creates a user named `grafana-agent` on the Linux machine for running Grafana Agent. - -1. Create a file named `grafana-agent.yml` and add the following: - -```yaml -- name: Install Grafana Agent Flow - hosts: all - become: true - tasks: - - name: Install Grafana Agent Flow - ansible.builtin.include_role: - name: grafana.grafana.grafana_agent - vars: - grafana_agent_mode: flow - # Change config file on the host to .river - grafana_agent_config_filename: config.river - # Change config file to be copied - grafana_agent_provisioned_config_file: '' - # Remove default flags - grafana_agent_flags_extra: - server.http.listen-addr: '0.0.0.0:12345' -``` - -1. Replace the following field values: - - `` with the path to river configuration file on the Ansible Controller (Localhost). - -### Install Grafana Agent in static mode using Ansible - -This Ansible playbook installs Grafana Agent in static mode and also creates a systemd service to manage it. -It creates a user named `grafana-agent` on the Linux machine for running Grafana Agent. - -1. Create a file named `grafana-agent.yml` and add the following: - -```yaml -- name: Install Grafana Agent in static mode - hosts: all - become: true - - vars: - grafana_cloud_api_key: - logs_username: # Example - 411478 - loki_url: # Example - https://logs-prod-017.grafana.net/loki/api/v1/push - tasks: - - name: Install Grafana Agent in static mode - ansible.builtin.include_role: - name: grafana_agent - vars: - grafana_agent_logs_config: - configs: - - clients: - - basic_auth: - password: '{{ grafana_cloud_api_key }}' - username: '{{ logs_username }}' - url: '{{ loki_url }}' - name: default - positions: - filename: /tmp/positions.yaml - scrape_configs: - - job_name: integrations/node_exporter_direct_scrape - static_configs: - - targets: - - localhost - labels: - instance: hostname - __path__: /var/log/*.log - job: integrations/node_exporter - target_config: - sync_period: 10s -``` - -1. Replace the following field values: - - `` with a token from the Cloud Access Policy you created in the Grafana Cloud portal. - - `` with the Loki Username - - `` with the push endpoint URL of Loki Instance - -## Run the Ansible playbook on the Linux machine - -In the Linux machine's terminal, run the following command from the directory where the Ansible playbook is located. - -```shell -ansible-playbook grafana-agent.yml -``` - -## Validate - - - -1. Grafana Agent service on the Linux machine should be `active` and `running`. You should see a similar output: - - -```shell -$ sudo systemctl status grafana-agent.service - grafana-agent.service - Grafana Agent - Loaded: loaded (/etc/systemd/system/grafana-agent.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2022-07-20 09:56:15 UTC; 36s ago - Main PID: 3176 (agent-linux-amd) - Tasks: 8 (limit: 515) - Memory: 92.5M - CPU: 380ms - CGroup: /system.slice/grafana-agent.service - └─3176 /usr/local/bin/agent-linux-amd64 --config.file=/etc/grafana-cloud/agent-config.yaml -``` - -1. In a Grafana Cloud stack, click **Explore** in the left-side menu. - -1. At the top of the page, use the dropdown menu to select your Loki logs data source. In the Log Browser, run the query `{job="integrations/node_exporter"}` - - ![Loki Logs](/static/img/docs/grafana-cloud/ansible/ansible-agent-logs.png) - -## Summary - -In this guide, you installed Grafana Agent on a Linux node using Ansible and used it to pushed logs to Grafana Cloud. - -To learn more about the Grafana Ansible collection, refer to the [GitHub repository](https://github.com/grafana/grafana-ansible-collection) or its [documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html). diff --git a/docs/sources/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/index.md b/docs/sources/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/index.md deleted file mode 100644 index c6769e5ebde..00000000000 --- a/docs/sources/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/index.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -menuTitle: Monitor multiple Linux hosts with the grafana_agent role -title: Monitor multiple Linux hosts with grafana_agent role -weight: 300 -canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/ ---- - -# Monitor multiple Linux hosts with the `grafana_agent` role - -{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}} - -Monitoring multiple Linux hosts can be difficult. -To make it easier, you can use the `grafana_agent` role with the [Grafana Ansible collection](../). -This guide shows how to use the `grafana_agent` Ansible role to deploy and manage Grafana Agent across multiple Linux hosts so you can monitor them using Grafana Cloud. - -## Before you begin - -Before you begin, you should have: - -- Linux hosts -- SSH access to the Linux hosts -- Account permissions sufficient to install and use Grafana Agent on the Linux hosts - -## Install the Grafana Ansible collection - -The [`grafana_agent` role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent) is available in the Grafana Ansible collection as of the 1.1.0 release. - -To install the Grafana Ansible collection, run this command: - -``` -ansible-galaxy collection install grafana.grafana -``` - -## Create an Ansible inventory file - -Next, you will set up your hosts and create an inventory file. - -1. Create your hosts and add public SSH keys to them. - - This example uses eight Linux hosts: two Ubuntu hosts, two CentOS hosts, two Fedora hosts, and two Debian hosts. - -1. Create an Ansible inventory file. - - The Ansible inventory, which resides in a file named `inventory`, looks similar to this: - - ``` - 146.190.208.216 # hostname = ubuntu-01 - 146.190.208.190 # hostname = ubuntu-02 - 137.184.155.128 # hostname = centos-01 - 146.190.216.129 # hostname = centos-02 - 198.199.82.174 # hostname = debian-01 - 198.199.77.93 # hostname = debian-02 - 143.198.182.156 # hostname = fedora-01 - 143.244.174.246 # hostname = fedora-02 - ``` - -1. Create an `ansible.cfg` file within the same directory as `inventory`, with the following values: - ``` - [defaults] - inventory = inventory # Path to the inventory file - private_key_file = ~/.ssh/id_rsa # Path to my private SSH Key - remote_user=root # username - ``` - {{< admonition type="note" >}} - If you are copying the previously listed files, remove the comments (#). - {{< /admonition >}} - -## Use the `grafana_agent` Ansible role - -Next you will create an Ansible playbook that calls the `grafana_agent` role from the `grafana.grafana` Ansible collection. - -To use the `grafana_agent` Ansible role: - -1. Create a file named `deploy-agent.yml` in the same directory as `ansible.cfg` and `inventory` and add the configuration below. - - ```yaml - - name: Install Grafana Agent - hosts: all - become: true - - vars: - grafana_cloud_api_key: - metrics_username: # Example - 825019 - logs_username: # Example - 411478 - prometheus_url: # Example - https://prometheus-us-central1.grafana.net/api/prom/push - loki_url: # Example - https://logs-prod-017.grafana.net/loki/api/v1/push - tasks: - - name: Install Grafana Agent - ansible.builtin.include_role: - name: grafana.grafana.grafana_agent - vars: - grafana_agent_metrics_config: - configs: - - name: integrations - remote_write: - - basic_auth: - password: '{{ grafana_cloud_api_key }}' - username: '{{ metrics_username }}' - url: '{{ prometheus_url }}' - - global: - scrape_interval: 60s - wal_directory: /tmp/grafana-agent-wal - grafana_agent_logs_config: - configs: - - name: default - clients: - - basic_auth: - password: '{{ grafana_cloud_api_key }}' - username: '{{ logs_username }}' - url: '{{ loki_url }}' - positions: - filename: /tmp/positions.yaml - target_config: - sync_period: 10s - scrape_configs: - - job_name: varlogs - static_configs: - - targets: [localhost] - labels: - instance: ${HOSTNAME:-default} - job: varlogs - __path__: /var/log/*log - grafana_agent_integrations_config: - node_exporter: - enabled: true - instance: ${HOSTNAME:-default} - prometheus_remote_write: - - basic_auth: - password: '{{ grafana_cloud_api_key }}' - username: '{{ metrics_username }}' - url: '{{ prometheus_url }}' - grafana_agent_env_vars: - HOSTNAME: '%H' - ``` - - The playbook calls the `grafana_agent` role from the `grafana.grafana` Ansible collection. - - The Agent configuration in this playbook send metrics and logs from the Linux hosts to Grafana Cloud along with the hostname of each instance - - Refer to the [Grafana Ansible documentation](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent#role-variables) to understand the other variables you can pass to the `grafana_agent` role. - - When deploying the Agent across multiple instances for monitoring them, It is essential that the Agent is able to auto-detect the hostname for ease in monitoring. - Notice that the label `instance` has been set to the value `${HOSTNAME:-default}`, which is substituted by the value of the HOSTNAME environment variable in the Linux host. - - To read more about the variable substitution, refer to the Grafana Agent [node_exporter_config](/docs/grafana-cloud/send-data/agent/static/configuration/integrations/node-exporter-config/) documentation. - -1. To run the playbook, run this command: - - ``` - ansible-playbook deploy-agent.yml - ``` - -{{< admonition type="note" >}} -You can place the `deploy-agent.yml`, `ansible.cfg` and `inventory` files in different directories based on your needs. -{{< /admonition >}} - -## Check that logs and metrics are being ingested into Grafana Cloud - -Logs and metrics will soon be available in Grafana Cloud. -To test this, use the Explore feature. -Click the **Explore** icon (compass icon) in the vertical navigation bar. - -### Check logs - -To check logs: - -1. Use the drop-down menu at the top of the page to select your Loki logs data source. - -1. In the log browser, run the query `{instance="centos-01"}` where `centos-01` is the hostname of one of the Linux hosts. - - If you see log lines (shown in the example below), logs are being received. - - {{< figure alt="Grafana Explore showing a graph and log output from the preceding query" src="/static/assets/img/blog/ansible-to-manage-agent1.png" >}} - - If no log lines appear, logs aren't being collected. - -### Check metrics - -To check metrics: - -1. Use the drop-down menu at the top of the page to select your Prometheus data source. - -1. Run the query `{instance="centos-01"}` where `centos-01` is the hostname of one of the Linux hosts. - - If you see a metrics graph and table (shown in the example below), metrics are being received. - - {{< figure alt="Grafana Explore showing a graph and metrics table output from the preceding query" src="/static/assets/img/blog/ansible-to-manage-agent2.png" >}} - - If no metrics appear, metrics aren't being collected. - -### View dashboards - -Now that you have logs and metrics in Grafana, you can use dashboards to view them. -Here's an example of one of the prebuilt dashboards included with the Linux integration in Grafana Cloud: - -{{< figure alt="The Grafana Node Exporter integration dashboard showing panels of visualizations" src="/static/assets/img/blog/ansible-to-manage-agent3.png" >}} - -Using the **Instance** drop-down in the dashboard, you can select from the hostnames where you deployed Grafana Agent and start monitoring them. - -## Summary - -The `grafana_agent` Ansible role makes it easy to deploy and manage Grafana Agent across multiple machines. -This example showed Grafana Agent deployments across eight Linux hosts, but it's possible to monitor more hosts using the`grafana_agent` role. -To add monitor more Linux hosts, update the `inventory` file and re-run the Ansible playbook. - -To learn more about the Grafana Ansible collection, see its [GitHub repository](https://github.com/grafana/grafana-ansible-collection) or its [documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html). diff --git a/docs/sources/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd.md b/docs/sources/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd.md index 3c92270e860..0531a0c803f 100644 --- a/docs/sources/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd.md +++ b/docs/sources/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd.md @@ -5,295 +5,298 @@ keywords: - Grafana Cloud - Grafana Operator - ArgoCD -title: Manage Dashboards with GitOps Using ArgoCD +title: Manage dashboards with GitOps using ArgoCD +menuTitle: Manage dashboards with ArgoCD weight: 110 canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd/ --- -# Managing Grafana Dashboards with GitOps Using ArgoCD +# Manage Grafana dashboards with GitOps using ArgoCD -This guide will walk you through setting up a continuous deployment pipeline using ArgoCD to synchronize your Grafana dashboards with a Git repository. We'll use the Grafana Dashboard Custom Resource provided by the Grafana Operator to manage dashboard configurations declaratively. +This guide shows you how to set up a continuous deployment pipeline using ArgoCD to synchronize your Grafana dashboards with a Git repository. You'll use the Grafana Dashboard Custom Resource provided by the Grafana Operator to manage dashboard configurations declaratively. ## Prerequisites +Before you begin, make sure you have the following: + - An existing Grafana Cloud stack -- A Kubernetes cluster with Grafana Operator installed, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator). -- ArgoCD installed on your Kubernetes cluster. Refer the [Installation Guide](https://argo-cd.readthedocs.io/en/stable/getting_started/). -- Git repository to store your dashboard configurations. +- A Kubernetes cluster with Grafana Operator installed, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator) +- ArgoCD installed on your Kubernetes cluster. Refer to the [ArgoCD Installation Guide](https://argo-cd.readthedocs.io/en/stable/getting_started/) +- A Git repository to store your dashboard configurations -## Set Up Your Git Repository +## Set up your Git repository -Within the repository, create a directory structure to organize your grafana and dashboard configurations. For this tutorial, lets create a folder named `grafana`. +Create a directory structure in your repository to organize your Grafana and dashboard configurations. For this tutorial, create a folder named `grafana`. -## Grafana Operator Setup +## Set up the Grafana Operator -The Grafana Operator allows us to authenticate with the Grafana instance using the Grafana Custom Resource (CR). +The Grafana Operator allows you to authenticate with the Grafana instance using the Grafana Custom Resource (CR). -1. **Create the Grafana API Token Secret:** +### Create the Grafana API Token Secret -Store the Grafana API Token in a secret with the following content in a file named `grafana-token.yml` in the `grafana` folder in your Git repo: +Store the Grafana API Token in a secret. Create a file named `grafana-token.yml` in the `grafana` folder in your Git repository: ```yaml apiVersion: v1 kind: Secret metadata: name: grafana-cloud-credentials - namespace: + namespace: '' stringData: - GRAFANA_CLOUD_INSTANCE_TOKEN: + GRAFANA_CLOUD_INSTANCE_TOKEN: '' type: Opaque ``` -Replace the following field values: +Replace the placeholders with your values: -- `` with API key from the Grafana instance. To create an API key, refer [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/). -- `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +- _``_: API key from your Grafana instance. To create an API key, refer to [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/) +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster -2. **Configure the Grafana Custom Resource:** +### Configure the Grafana Custom Resource -Set up connection to your Grafana Cloud instance by creating a file named `grafana-cloud.yml` in the `grafana` folder in your Git repo with the following contents: +Set up the connection to your Grafana Cloud instance. Create a file named `grafana-cloud.yml` in the `grafana` folder in your Git repository: ```yaml apiVersion: grafana.integreatly.org/v1beta1 kind: Grafana metadata: - name: - namespace: + name: '' + namespace: '' labels: - dashboards: + dashboards: '' spec: external: - url: https://.grafana.net/ + url: https://.grafana.net/ apiKey: name: grafana-cloud-credentials key: GRAFANA_CLOUD_INSTANCE_TOKEN ``` -Replace the following field values: +Replace the placeholders with your values: -- `` with API key from the Grafana instance. -- `` with the name of your Grafana Cloud Stack. -- `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +- _``_: Name of your Grafana Cloud Stack +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster -## Add Dashboards to a Git repository +## Add dashboards to your Git repository -In your `grafana` directory, Create a sub-folder called `dashboards`. For this tutorial, we will create 3 seperate dashboards. +In your `grafana` directory, create a sub-folder called `dashboards`. -1. Under `dashboards` folder, Create a file named `simple-dashboard.yaml` with the following content for the first dashboard: +This guide shows you how to creates three separate dashboards. For all dashboard configurations, replace the placeholders with your values: - ```yaml - apiVersion: grafana.integreatly.org/v1beta1 - kind: GrafanaDashboard - metadata: - name: grafanadashboard-sample - namespace: - spec: - resyncPeriod: 30s - instanceSelector: - matchLabels: - dashboards: - json: > - { - "id": null, - "title": "Simple Dashboard", - "tags": [], - "style": "dark", - "timezone": "browser", - "editable": true, - "hideControls": false, - "graphTooltip": 1, - "panels": [], - "time": { - "from": "now-6h", - "to": "now" - }, - "timepicker": { - "time_options": [], - "refresh_intervals": [] - }, - "templating": { - "list": [] - }, - "annotations": { - "list": [] - }, - "refresh": "5s", - "schemaVersion": 17, - "version": 0, - "links": [] - } - ``` +- _``_: Name of your Grafana Cloud Stack +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster - Replace the following field values: - - `` with the name of your Grafana Cloud Stack. - - `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +### Create a simple dashboard -1. Under `dashboards` folder, Create a file named `dashboard-from-cm.yaml` with the following content for the second dashboard: +Under the `dashboards` folder, create a file named `simple-dashboard.yaml`: - ```yaml - apiVersion: v1 - kind: ConfigMap - metadata: - name: dashboard-definition - namespace: - spec: - resyncPeriod: 30s - instanceSelector: - matchLabels: - dashboards: - json: > - { - "id": null, - "title": "Simple Dashboard from ConfigMap", - "tags": [], - "style": "dark", - "timezone": "browser", - "editable": true, - "hideControls": false, - "graphTooltip": 1, - "panels": [], - "time": { - "from": "now-6h", - "to": "now" - }, - "timepicker": { - "time_options": [], - "refresh_intervals": [] - }, - "templating": { - "list": [] - }, - "annotations": { - "list": [] - }, - "refresh": "5s", - "schemaVersion": 17, - "version": 0, - "links": [] - } - --- - apiVersion: grafana.integreatly.org/v1beta1 - kind: GrafanaDashboard - metadata: - name: grafanadashboard-from-configmap - namespace: - spec: - instanceSelector: - matchLabels: - dashboards: - configMapRef: - name: dashboard-definition - key: json - ``` +```yaml +apiVersion: grafana.integreatly.org/v1beta1 +kind: GrafanaDashboard +metadata: + name: grafanadashboard-sample + namespace: '' +spec: + resyncPeriod: 30s + instanceSelector: + matchLabels: + dashboards: '' + json: > + { + "id": null, + "title": "Simple Dashboard", + "tags": [], + "style": "dark", + "timezone": "browser", + "editable": true, + "hideControls": false, + "graphTooltip": 1, + "panels": [], + "time": { + "from": "now-6h", + "to": "now" + }, + "timepicker": { + "time_options": [], + "refresh_intervals": [] + }, + "templating": { + "list": [] + }, + "annotations": { + "list": [] + }, + "refresh": "5s", + "schemaVersion": 17, + "version": 0, + "links": [] + } +``` - Replace the following field values: - - `` with the name of your Grafana Cloud Stack. - - `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +### Create a dashboard from ConfigMap -1. Under `dashboards` folder, Create a file named `dashboard-from-id.yaml` with the following content for the third dashboard: +Under the `dashboards` folder, create a file named `dashboard-from-cm.yaml`: - ```yaml - apiVersion: grafana.integreatly.org/v1beta1 - kind: GrafanaDashboard - metadata: - name: node-exporter-latest - namespace: - spec: - instanceSelector: - matchLabels: - dashboards: - grafanaCom: - id: 1860 - ``` +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: dashboard-definition + namespace: +data: + json: > + { + "id": null, + "title": "Simple Dashboard from ConfigMap", + "tags": [], + "style": "dark", + "timezone": "browser", + "editable": true, + "hideControls": false, + "graphTooltip": 1, + "panels": [], + "time": { + "from": "now-6h", + "to": "now" + }, + "timepicker": { + "time_options": [], + "refresh_intervals": [] + }, + "templating": { + "list": [] + }, + "annotations": { + "list": [] + }, + "refresh": "5s", + "schemaVersion": 17, + "version": 0, + "links": [] + } +--- +apiVersion: grafana.integreatly.org/v1beta1 +kind: GrafanaDashboard +metadata: + name: grafanadashboard-from-configmap + namespace: '' +spec: + instanceSelector: + matchLabels: + dashboards: '' + configMapRef: + name: dashboard-definition + key: json +``` - Replace the following field values: - - `` with the name of your Grafana Cloud Stack. - - `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +### Create a dashboard from Grafana.com -## Configure Argo CD to Sync the Git Repository +Under the `dashboards` folder, create a file named `dashboard-from-id.yaml`: -Once all changes are committed to Git, Log in to the Argo CD user interface or use the CLI. +```yaml +apiVersion: grafana.integreatly.org/v1beta1 +kind: GrafanaDashboard +metadata: + name: node-exporter-latest + namespace: '' +spec: + instanceSelector: + matchLabels: + dashboards: '' + grafanaCom: + id: 1860 +``` -2. Create an Argo CD application to manage the synchronization: +## Configure ArgoCD to sync the Git repository - **Using UI**: - - Navigate to 'New App' and fill out the form with your Git repository details and the path to your `grafana` folder. - - Make sure to tick mark directory Recurse. - - Set the sync policy to `Automatic`. +After you commit all changes to Git, log in to the ArgoCD user interface or use the CLI. - **Using CLI**: - - Prepare an application manifest named `argo-application.yaml` with the configuration pointing to your Git repository: +### Create an ArgoCD application - ```yaml - apiVersion: argoproj.io/v1alpha1 - kind: Application - metadata: - name: Grafana - namespace: - spec: - destination: - name: '' - namespace: '' - server: 'https://kubernetes.default.svc' - source: - path: - repoURL: '' - targetRevision: HEAD - directory: - recurse: true - sources: [] - project: default - syncPolicy: - automated: - prune: true - selfHeal: true - syncOptions: - - CreateNamespace=true - retry: - limit: 2 - backoff: - duration: 5s - maxDuration: 3m0s - factor: 2 - ``` +**Using the UI:** - Replace the following field values: - - `` with the URL of your GIT Repository. - - `` with the path to the `grafana` folder. - - `` with the namespace where ArgoCD is deployed in Kubernetes Cluster. +1. Navigate to **New App** and complete the form with your Git repository details and the path to your `grafana` folder +2. Enable **Directory Recurse** +3. Set the sync policy to **Automatic** - - Create the application in Argo CD: +**Using the CLI:** - ```shell - kubectl apply -f argo-application.yaml - ``` +Prepare an application manifest named `argo-application.yaml`: -## Verify Sync Status in Argo CD +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: Grafana + namespace: '' +spec: + destination: + name: '' + namespace: '' + server: 'https://kubernetes.default.svc' + source: + path: '' + repoURL: '' + targetRevision: HEAD + directory: + recurse: true + sources: [] + project: default + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true + retry: + limit: 2 + backoff: + duration: 5s + maxDuration: 3m0s + factor: 2 +``` -1. Monitor the newly created Argo CD application, ensuring that it successfully syncs your dashboard configuration. +Replace the placeholders with your values: -2. Visit the Argo CD dashboard and check the sync status. If it's successful, your Grafana dashboard should be up to date with the configuration from your Git repository. +- _``_: URL of your Git repository +- _``_: Path to the `grafana` folder in your repository +- _``_: Namespace where ArgoCD is deployed in your Kubernetes cluster -## Updating the Dashboards +Create the application in ArgoCD: + +```sh +kubectl apply -f argo-application.yaml +``` + +## Verify sync status in ArgoCD + +1. Monitor the newly created ArgoCD application to ensure it successfully syncs your dashboard configuration +2. Visit the ArgoCD dashboard and check the sync status. If it's successful, your Grafana dashboards should be up to date with the configuration from your Git repository + +## Update your dashboards To update an existing dashboard: -1. Make changes to the dashboard JSON configuration in your Git repository. -2. Commit and push the changes. -3. Argo CD will detect the update and synchronize the changes to your Cutom Resource. -4. Grafana Operator will then sync changes to the Grafana Instance. +1. Make changes to the dashboard JSON configuration in your Git repository +2. Commit and push the changes +3. ArgoCD detects the update and synchronizes the changes to your Custom Resource +4. Grafana Operator then syncs changes to the Grafana instance -## Validating the Grafana Dashboard Update +### Validate your dashboard updates -Log in to your Grafana dashboard and confirm that the changes have been applied. You should see the dashboard update reflected in the Grafana UI. +Log in to your Grafana dashboard and confirm that the changes are applied. You should see the dashboard updates reflected in the Grafana UI. -## Additional Tips +## Next steps -- You can also install the Grafana Operator's Helm Chart using ArgoCD to manage your setup with GitOps. -- You can follow a similar setup for Grafana Dashboards and Folders. +You've successfully set up a GitOps workflow to manage Grafana dashboards using ArgoCD and the Grafana Operator. Your dashboards are now version-controlled and can be consistently deployed across environments. This approach provides a reliable and auditable way to manage observability dashboards and scale your operations. -## Conclusion +To learn more about managing Grafana using Grafana Operator: -You've set up a GitOps workflow to manage Grafana dashboards using Argo CD and the Grafana Operator. Your dashboards are now version-controlled and can be consistently deployed across environments. This approach provides a reliable and auditable way to manage observability dashboards and scale your operations. +- [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/) +- [Grafana dashboard provisioning](/docs/grafana/latest/administration/provisioning/#dashboards) +- [ArgoCD best practices](https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/) -To learn more about managing Grafana using Grafana Operator, see the [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/). +### Additional considerations + +- You can install the Grafana Operator's Helm Chart using ArgoCD to manage your setup with GitOps +- You can follow a similar setup for Grafana Folders and other resources diff --git a/docs/sources/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources.md b/docs/sources/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources.md index 9d8617e12c6..e5bbc1467b8 100644 --- a/docs/sources/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources.md +++ b/docs/sources/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources.md @@ -5,26 +5,27 @@ keywords: - Grafana Cloud - Grafana Operator title: Manage folders, data sources, and dashboards using Grafana Operator +menuTitle: Manage resources with the Grafana Operator weight: 100 canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources/ --- -# Creating and managing folders, data sources, and dashboards using the Grafana Operator +# Manage folders, data sources, and dashboards using the Grafana Operator -Learn how to manage data sources, folders and dashboard, using Grafana Operator. +This guide shows you how to manage data sources, folders, and dashboards using the Grafana Operator. You'll create these resources declaratively using Kubernetes custom resources. ## Prerequisites -Before you begin, you should have the following available: +Before you begin, make sure you have the following: -- An existing Grafana Cloud stack. -- Grafana Operator Installed in your Cluster, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator). +- An existing Grafana Cloud stack +- Grafana Operator installed in your cluster, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator) -## Grafana Operator Setup +## Set up the Grafana Operator -The Grafana Operator allows us to authenticate with the Grafana instance using the Grafana Custom Resource (CR). +The Grafana Operator allows you to authenticate with your Grafana instance using the Grafana Custom Resource (CR). -1. **Create the Grafana API Token Secret:** +### Create the Grafana API Token Secret Store the Grafana API Token in a secret with the following content in a file named `grafana-token.yml`: @@ -33,61 +34,64 @@ apiVersion: v1 kind: Secret metadata: name: grafana-cloud-credentials - namespace: + namespace: '' stringData: - GRAFANA_CLOUD_INSTANCE_TOKEN: + GRAFANA_CLOUD_INSTANCE_TOKEN: '' type: Opaque ``` -Replace the following field values: +Replace the placeholders with your values: -- `` with API key from the Grafana instance. To create an API key, refer [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/). -- `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +- _``_: API key from your Grafana instance. To create an API key, refer to [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/) +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster -2. **Configure the Grafana Custom Resource:** +### Configure the Grafana Custom Resource -Set up connection to your Grafana Cloud instance by creating a file named `grafana-cloud.yml` with the following contents: +Set up connection to your Grafana Cloud instance. Create a file named `grafana-cloud.yml`: ```yaml apiVersion: grafana.integreatly.org/v1beta1 kind: Grafana metadata: - name: - namespace: + name: '' + namespace: '' labels: - dashboards: + dashboards: '' spec: external: - url: https://.grafana.net/ + url: https://.grafana.net/ apiKey: name: grafana-cloud-credentials key: GRAFANA_CLOUD_INSTANCE_TOKEN ``` -Replace the following field values: +Replace the placeholders with your values: -- `` with API key from the Grafana instance. -- `` with the name of your Grafana Cloud Stack. -- `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +- _``_: Name of your Grafana Cloud stack +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster ## Add a data source -The following steps use the Prometheus data source. The required arguments vary depending on the data source you select. +{{< admonition type="note" >}} -1. **Create the Data Source Configuration:** +This example uses the Prometheus data source. Note that the required arguments vary depending on the data source you select. -Save a new YAML file `datasource.yml` with the following content: +{{< /admonition >}} + +### Create a data source configuration + +Create and save a new YAML file `datasource.yml` with your data source's configuration: ```yaml apiVersion: grafana.integreatly.org/v1beta1 kind: GrafanaDatasource metadata: - name: - namespace: + name: '' + namespace: '' spec: instanceSelector: matchLabels: - dashboards: + dashboards: '' allowCrossNamespaceImport: true datasource: access: proxy @@ -95,74 +99,76 @@ spec: jsonData: timeInterval: 5s tlsSkipVerify: true - name: + name: '' type: prometheus - url: + url: '' ``` -Replace the following field values: +Replace the placeholders with your values: -- `` with the name of the data source to be added in Grafana. -- `` with URL of your data source. -- `` with the name of your Grafana Cloud Stack. -- `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +- _``_: Name of the data source to be added in Grafana +- _``_: URL of your data source +- _``_: Name of your Grafana Cloud stack +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster -## Add a dashboard to a folder +### Add a dashboard to a folder -Use the following YAML definition to create a simple dashboard in the Grafana instance under a custom folder. If the folder defined under spec.folder fields doesnt not exist, The operator will create it before placing the dashboard inside the folder. +Use the following YAML definition to create a simple dashboard in the Grafana instance under a custom folder. If the folder defined under the `spec.folder` field doesn't exist, the operator creates it before placing the dashboard inside the folder. -1. **Prepare the Dashboard Configuration File:** - -In `dashboard.yml`, define the dashboard and assign it to a folder: +Prepare the dashboard configuration. In `dashboard.yml`, define the dashboard and assign it to a folder: ```yaml apiVersion: grafana.integreatly.org/v1beta1 kind: GrafanaDashboard metadata: - name: - namespace: + name: '' + namespace: '' spec: instanceSelector: matchLabels: - dashboards: - folder: "" + dashboards: '' + folder: '' json: > - { - "title": "as-code dashboard", - “uid” : “ascode” - } + { + "title": "as-code dashboard", + "uid" : "ascode" + } ``` -Replace the following field values: +Replace the placeholders with your values: -- `` with the name of the folder in which you want the Dashboard to be created. -- `` with the name of your Grafana Cloud Stack. -- `` with the namespace where the grafana-operator is deployed in Kubernetes Cluster. +- _``_: Name of the folder in which you want the dashboard to be created +- _``_: Name of your Grafana Cloud stack +- _``_: Namespace where the `grafana-operator` is deployed in your Kubernetes cluster -## Apply Kubernetes Manifests +## Apply the Kubernetes manifests In a terminal, run the following commands from the directory where all of the above Kubernetes YAML definitions are located. -1. Create Kubernetes Custom resources for all of the above configurations. +Create Kubernetes Custom resources for all of the configurations: - ```shell - kubectl apply -f grafana-token.yml grafana-cloud.yml datasource.yml dashboard.yml - ``` +```sh +kubectl apply -f grafana-token.yml grafana-cloud.yml datasource.yml dashboard.yml +``` -## Validation +## Validate your configuration -Once you apply the configurations, you should be able to verify the following: +After you apply the configurations, verify that: -- A new data source is visible in Grafana. In the following image a datasource named `InfluxDB` was created. +- A new data source is visible in Grafana. In the following image, a data source named `InfluxDB` was created. ![InfluxDB datasource](/static/img/docs/grafana-cloud/terraform/influxdb_datasource_tf.png) -- A new dashboard and folder in Grafana. In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the `Demos` folder. +- A new dashboard and folder have been created in Grafana. In the following image, a dashboard named `InfluxDB Cloud Demos` was created inside the `Demos` folder. ![InfluxDB dashboard](/static/img/docs/grafana-cloud/grizzly/grizzly-folder-dashboard-datasource.png) -## Conclusion +## Next steps -In this guide, you created a data source, folder, and dashboard using the Grafana Operator. +You've successfully created a data source, folder, and dashboard using the Grafana Operator. Your Grafana resources are now managed declaratively through Kubernetes custom resources. -To learn more about managing Grafana using Grafana Operator, see the [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/). +To learn more about managing Grafana: + +- [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/) +- [Grafana dashboard provisioning](/docs/grafana/latest/administration/provisioning/#dashboards) +- [Grafana data source provisioning](/docs/grafana/latest/administration/provisioning/#data-sources) diff --git a/docs/sources/as-code/observability-as-code/schema-v2/_index.md b/docs/sources/as-code/observability-as-code/schema-v2/_index.md index 5eb693f0f1d..9be869a8391 100644 --- a/docs/sources/as-code/observability-as-code/schema-v2/_index.md +++ b/docs/sources/as-code/observability-as-code/schema-v2/_index.md @@ -13,7 +13,7 @@ labels: - enterprise - oss title: JSON schema v2 -weight: 200 +weight: 500 canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/ aliases: - ../../observability-as-code/schema-v2/ # /docs/grafana/next/observability-as-code/schema-v2/