From 26a7187dcddc67e34cd94fcfe016c50fced09f40 Mon Sep 17 00:00:00 2001 From: Andreas Christou Date: Thu, 14 Aug 2025 20:08:54 +0200 Subject: [PATCH] [release-12.1.2] Update Influx Config Options Section in Docs (#109700) Update Influx Config Options Section in Docs (#108264) (cherry picked from commit c16117df4ecf86ad53bb3b3d7a8d359dd3e97f25) Co-authored-by: Zoe C <38118634+zoesyc@users.noreply.github.com> --- .../configure-influxdb-data-source/_index.md | 176 ++++++++++-------- 1 file changed, 99 insertions(+), 77 deletions(-) diff --git a/docs/sources/datasources/influxdb/configure-influxdb-data-source/_index.md b/docs/sources/datasources/influxdb/configure-influxdb-data-source/_index.md index d50db2e9d43..0c958283f0e 100644 --- a/docs/sources/datasources/influxdb/configure-influxdb-data-source/_index.md +++ b/docs/sources/datasources/influxdb/configure-influxdb-data-source/_index.md @@ -34,15 +34,11 @@ This document provides instructions for configuring the InfluxDB data source and To configure the InfluxDB data source you must have the `Administrator` role. -{{< admonition type="note" >}} -Select the query language you want to use with InfluxDB before adding the InfluxDB data source. Configuration options differ based on query language type. -{{< /admonition >}} - InfluxData provides three query languages. Some key points to consider: -- SQL is only available for InfluxDB v3.x. - Flux is a functional data scripting language for InfluxDB 2.x. Refer to [Query InfluxDB with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/get-started/query-influxdb/) for a basic guide on working with Flux. - InfluxQL is SQL-like query language developed by InfluxData. It doesn't support more advanced functions such as JOINs. +- SQL is only available for InfluxDB v3.x. To help choose the best language for your needs, refer to a [comparison of Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/) @@ -60,97 +56,123 @@ Complete the following steps to set up a new InfluxDB data source: You are taken to the **Settings** tab where you will configure the data source. -## InfluxDB common configuration options +## Configuration Options -The following configuration options apply to **all three query language options**. +The following is a list of configuration options for InfluxDB. + +![Name and Default settings for InfluxDB configuration](https://grafana.com/media/docs/influxdb/InfluxDB-ConfigV2-Name.png) + +The first option is to configure the name of your connection. - **Name** - Sets the name you use to refer to the data source in panels and queries. Examples: `InfluxDB-InfluxQL`, `InfluxDB_SQL`. - **Default** - Toggle to set as the default data source. -- **Query language** - Select the query language for your InfluxDB instance. The three options are: - - **InfluxQL** - SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users. - - **SQL** - Native SQL language starting with InfluxDB v.3.0. Refer to InfluxData's [SQL reference documentation](https://docs.influxdata.com/influxdb/cloud-serverless/reference/sql/) for a list of supported statements, operators, and functions. - - **Flux** - Flux is a data scripting language developed by InfluxData that allows you to query, analyze, and act on data. Refer to [Get started with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/get-started/) for guidance on using Flux. -**HTTP section:** +### URL and Authentication + +![URL and Authentication for InfluxDB configuration](https://grafana.com/media/docs/influxdb/InfluxDB-ConfigV2-URLAuth-Section.png) + +These settings identify the Influx instance and schema the data source is connecting to. - **URL** - The HTTP protocol, IP address, and port of your InfluxDB API. InfluxDB’s default API port is `8086`. +- **Product** - Select the product version of your Influx instance. +- **Query language** - Select the query language for your InfluxDB instance. This will determine the connection details needed in **Database Settings**. The three options are: + - **Flux** - Flux is a data scripting language developed by InfluxData that allows you to query, analyze, and act on data. Refer to [Get started with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/get-started/) for guidance on using Flux. + - **InfluxQL** - SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users. + - **SQL** - Native SQL language starting with **InfluxDB v.3.0**. Refer to InfluxData's [SQL reference documentation](https://docs.influxdata.com/influxdb/cloud-serverless/reference/sql/) for a list of supported statements, operators, and functions. + +{{< admonition type="note" >}} +_For InfluxQL only._ **Database + Retention Policy (DBRP) Mapping** must be configured before data can be queried for the following product versions: _Influx OSS 1.x_, _Influx OSS 2.x_, _Influx Enterprise 1.x_, _Influx Cloud (TSM)_, _Influx Cloud Serverless_ + +Refer to [Manage DBRP Mappings](https://docs.influxdata.com/influxdb/cloud/query-data/influxql/dbrp/) for guidance on setting this up via the CLI or API +{{< /admonition >}} + +#### Advanced HTTP Settings (Optional) + +Advanced HTTP Settings are optional settings that can be configured for more control over your data source. + - **Allowed cookies** - Defines which cookies are forwarded to the data source. All other cookies are deleted by default. - **Timeout** - Set an HTTP request timeout in seconds. -**Auth section:** +**Custom HTTP Headers** -- **Basic auth** - The most common authentication method. Use your InfluxData user name and password to authenticate. Toggling requires you to add the user and password under **Basic auth details**. -- **With credentials** - Toggle to enable credentials such as cookies or auth headers to be sent with cross-site requests. -- **TLS client auth** - Toggle to use client authentication. When enabled, add the `Server name`, `Client cert` and `Client key` under the **TLS/SSL auth details** section. The client provides a certificate that the server validates to establish the client’s trusted identity. The client key encrypts the data between client and server. -- **With CA cert** - Authenticate with a CA certificate. Follow the instructions of your CA (Certificate Authority) to download the certificate file. -- **Skip TLS verify** - Toggle to bypass TLS certificate validation. -- **Forward OAuth identity** - Forward the OAuth access token (and also the OIDC ID token if available) of the user querying the data source. - -**Basic auth details:** - -If you enable **Basic auth** under the Auth section you need to configure the following: - -- **User** - Add the username used to sign in to InfluxDB. -- **Password** - Defines the token you use to query the bucket defined in **Database**. Retrieve this from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) in the InfluxDB UI. - -**TLS/SSL auth details:** - -TLS/SSL certificates are encrypted and stored in the Grafana database. - -- **CA cert** - If you toggle **With CA cert** add your self-signed cert here. -- **Server name** - Name of the server. Example: server1.domain.com -- **Client cert** - Add the client certificate. -- **Client key** - Add the client key. - -**Custom HTTP headers:** +Click **+ Add header** to add one or more HTTP headers. HTTP headers pass additional context and metadata about the request/response. - **Header** - Add a custom HTTP header. Select an option from the drop-down. Allows custom headers to be passed based on the needs of your InfluxDB instance. - **Value** - The value for the header. -**Private data source connect:** +#### Auth and TSL/SSL Settings (Optional) -- **Private data source connect** - _Only for Grafana Cloud users._ Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). +There are several authentication methods you can choose in the Authentication section. + +- **No Authentication** - Make the data source available without authentication. Grafana recommends using some type of authentication method. +- **Basic auth** - The most common authentication method. Use your Influx instance username and password to authenticate. +- **Forward OAuth identity** - Forward the OAuth access token (and also the OIDC ID token if available) of the user querying the data source. +- **With credentials** - Toggle to enable credentials such as cookies or auth headers to be sent with cross-site requests. + +TLS/SSL Certificates are encrypted and stored in the Grafana database. + +- **TLS client auth** - When enabled, add the `Server name`, `Client cert` and `Client key`. The client provides a certificate that the server validates to establish the client’s trusted identity. The client key encrypts the data between client and server. + - **Server name** - Name of the server. Example: `server1.domain.com` + - **Client cert** - Add the client certificate. + - **Client key** - Add the client key. +- **CA cert** - Authenticate with a CA certificate. When enabled, follow the instructions of your CA (Certificate Authority) to download the certificate file. +- **Skip TLS verify** - Toggle to bypass TLS certificate validation. + +### Database Settings + +![Database Settings for InfluxDB configuration](https://grafana.com/media/docs/influxdb/InfluxDB-ConfigV2-DBSettings.png) + +{{< admonition type="note" >}} +Setting the database for this data source **does not deny access to other databases**. The InfluxDB query syntax allows switching the database in the query. For example: `SHOW MEASUREMENTS ON _internal` or `SELECT * FROM "_internal".."database" LIMIT 10` + +To support data isolation and security, make sure appropriate permissions are configured in InfluxDB. +{{< /admonition >}} + +These settings identify the Influx database your data source will connect to. The required information will vary by the query language selected in **URL and Authentication**. Each query language uses a different set of connection details. + +The table below illustrates the details needed for each query language: + +| **Setting** | **Flux** | **InfluxQL** | **SQL** | +| -------------------------- | -------- | ------------ | -------- | +| **Bucket** or **Database** | ✓ | ✓ | ✓ | +| **Organization** | ✓ | | | +| **Password** or **Token** | ✓ | ✓ | ✓ | +| **User** | | ✓ | | + +- **Bucket** or **Database** - Sets the ID of the bucket to query. Refer to [View buckets](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) in InfluxData's documentation on how to locate the list of available buckets and their corresponding IDs. +- **Organization** - Sets the [Influx organization](https://v2.docs.influxdata.com/v2.0/organizations/) used for Flux queries. Also used for the `v.organization` query macro. +- **Password** or **Token** - Specify the token used to query the bucket defined in **Database**. Retrieve this from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) in the InfluxDB UI. +- **User** - Add the username used to sign in to InfluxDB. + +**For Flux** + +- **Default bucket** is optional. The [Influx bucket](https://v2.docs.influxdata.com/v2.0/organizations/buckets/) used for the `v.defaultBucket` macro in Flux queries. +- With Influx 2.0 products, use the [influx authentication token to function](https://v2.docs.influxdata.com/v2.0/security/tokens/create-token/). Token must be set as `Authorization` header with the value `Token `. +- For Influx 1.8, the token is `username:password`. + +#### Advanced Database Settings (Optional) + +Advanced Database Settings are optional settings that give you more control over the query experience. + +- **Min time interval** - Sets the minimum time interval for auto group-by. Grafana recommends setting this to match the data write frequency. For example, if your data is written every minute, it’s recommended to set this interval to 1 minute, so that each group contains data from each new write. The default is `10s`. Refer to [Min time interval](#min-time-interval) for format examples. +- **Max series** - Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`. + +**For InfluxQL** + +- **HTTP method** - Sets the HTTP method used to query your data source. The POST method allows for larger queries that would return an error using the GET method. The default method is `POST`. +- **Autocomplete range** - Sets a time range limit for the query editor's autocomplete to reduce the execution time of tag filter queries. As a result, any tags not present within the defined time range will be filtered out. For example, setting the value to 12h will include only tag keys/values from the past 12 hours. This feature is recommended for use with very large databases, where significant performance improvements can be observed. + +**For SQL** + +- **Insecure Connection** - Toggle to disable gRPC TLS security. + +### Private Data Source Connect + +_For Grafana Cloud only._ Private data source connect (PDC) allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). Click **Manage private data source connect** to be taken to your PDC connection page, where you'll find your PDC configuration details. -Once you have added your connection settings, click **Save & test** to test the data source connection. - -### InfluxQL-specific configuration section - -The following settings are specific to the InfluxQL query language option. - -**InfluxQL InfluxDB details section:** - -- **Database** - Sets the ID of the bucket to query. Refer to [View buckets](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) in InfluxData's documentation on how to locate the list of available buckets and their corresponding IDs. -- **User** - The user name used to sign in to InfluxDB. -- **Password** - Defines the token used to query the bucket defined in **Database**. Retrieve the password from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) of the InfluxDB UI. -- **HTTP method** - Sets the HTTP method used to query your data source. The POST method allows for larger queries that would return an error using the GET method. The default method is `POST`. -- **Min time interval** - _(Optional)_ Sets the minimum time interval for auto group-by. Grafana recommends setting this to match the data write frequency. For example, if your data is written every minute, it’s recommended to set this interval to 1 minute, so that each group contains data from each new write. The default is `10s`. Refer to [Min time interval](#min-time-interval) for format examples. -- **Autocomplete range** - _(Optional)_ Sets a time range limit for the query editor's autocomplete to reduce the execution time of tag filter queries. As a result, any tags not present within the defined time range will be filtered out. For example, setting the value to 12h will include only tag keys/values from the past 12 hours. This feature is recommended for use with very large databases, where significant performance improvements can be observed. -- **Max series** - _(Optional)_ Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`. - -### SQL-specific configuration section - -The following settings are specific to the SQL query language option. - -**SQL InfluxDB details section:** - -- **Database** - Specify the **bucket ID**. Refer to the **Buckets page** in the InfluxDB UI to locate the ID. -- **Token** The API token used for SQL queries. Generated on InfluxDB Cloud dashboard under [Load Data > API Tokens](https://docs.influxdata.com/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) menu. -- **Insecure Connection** - Toggle to disable gRPC TLS security. -- **Max series** - _(Optional)_ Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`. - -### Flux-specific configuration section - -The following settings are specific to the Flux query language option. - -**Flux InfluxDB details section:** - -- **Organization** - The [Influx organization](https://v2.docs.influxdata.com/v2.0/organizations/) used for Flux queries. Also used for the `v.organization` query macro. -- **Token** - The authentication token used for Flux queries. With Influx 2.0, use the [influx authentication token to function](https://v2.docs.influxdata.com/v2.0/security/tokens/create-token/). Token must be set as `Authorization` header with the value `Token `. For Influx 1.8, the token is `username:password`. -- **Default bucket** - _(Optional)_ The [Influx bucket](https://v2.docs.influxdata.com/v2.0/organizations/buckets/) used for the `v.defaultBucket` macro in Flux queries. -- **Min time interval** - Sets the minimum time interval for auto group-by. Grafana recommends aligning this setting with the data write frequency. For example, if data is written every minute, set the interval to 1 minute to ensure each group includes data from every new write. The default is `10s`. -- **Max series** - Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`. +After you have added your connection settings, click **Save & test** to test the data source connection. ### Min time interval