From 96848e153aed8993ebf9e547093c80038011a1b5 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 26 Sep 2024 10:14:48 -0500 Subject: [PATCH 01/45] feat: load AI chat window --- assets/js/ai-interactions.js | 24 ++++++++++++++++++++++++ layouts/partials/header/javascript.html | 6 ++++-- 2 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 assets/js/ai-interactions.js diff --git a/assets/js/ai-interactions.js b/assets/js/ai-interactions.js new file mode 100644 index 0000000000..f9b8ba4eb2 --- /dev/null +++ b/assets/js/ai-interactions.js @@ -0,0 +1,24 @@ + +const ANON_USER_ID = null; + +function showAIChat() { + loadCommandAIChat(); + bootCommandAIChat(ANON_USER_ID); +} + +function loadCommandAIChat() { + // https://www.command.ai/docs/platform/installation/installing-in-web-app/ + + var o="",n="https://api.commandbar.com",a=void 0,t=window; + function r(o,n){void 0===n&&(n=!1),"complete"!==document.readyState&&window.addEventListener("load",r.bind(null,o,n),{capture:!1,once:!0});var a=document.createElement("script");a.type="text/javascript",a.async=n,a.src=o,document.head.appendChild(a)}function e(){var e;if(void 0===t.CommandBar){delete t.__CommandBarBootstrap__;var c=Symbol.for("CommandBar::configuration"),d=Symbol.for("CommandBar::disposed"),i=Symbol.for("CommandBar::isProxy"),m=Symbol.for("CommandBar::queue"),u=Symbol.for("CommandBar::unwrap"),s=Symbol.for("CommandBar::eventSubscriptions"),l=[],p=localStorage.getItem("commandbar.lc");p&&p.includes("local")&&(n="http://localhost:8000",a=void 0);var f=Object.assign(((e={})[c]={uuid:o,api:n,cdn:a},e[d]=!1,e[i]=!0,e[m]=new Array,e[u]=function(){return f},e[s]=void 0,e),t.CommandBar),v=["addCommand","boot","addEventSubscriber","addRecordAction","setFormFactor"],b=f;Object.assign(f,{shareCallbacks:function(){return{}},shareContext:function(){return{}}}),t.CommandBar=new Proxy(f,{get:function(o,n){return n in b?f[n]:"then"!==n?v.includes(n)?function(){var o=Array.prototype.slice.call(arguments);return new Promise((function(a,t){o.unshift(n,a,t),f[m].push(o)}))}:function(){var o=Array.prototype.slice.call(arguments);o.unshift(n),f[m].push(o)}:void 0}}),null!==p&&l.push("lc=".concat(p)),l.push("version=2"),a&&l.push("cdn=".concat(encodeURIComponent(a))),r("".concat(n,"/latest/").concat(o,"?").concat(l.join("&")),!0)}}e(); +} + +function bootCommandAIChat(userid) { + // https://www.command.ai/docs/platform/installation/installing-in-web-app/#booting-the-command-bar + try { + (window.CommandBar) ? window.CommandBar.boot(userid) : setTimeout(() => window.CommandBar.boot(userid), 1000); + } catch (error) { + console.error('Error booting CommandBar', error); + } + +} \ No newline at end of file diff --git a/layouts/partials/header/javascript.html b/layouts/partials/header/javascript.html index f257221be1..baab406be7 100644 --- a/layouts/partials/header/javascript.html +++ b/layouts/partials/header/javascript.html @@ -3,8 +3,10 @@ {{ $docsCookies := resources.Get "js/cookies.js" }} {{ $themes := resources.Get "js/docs-themes.js" }} {{ $sidebar := resources.Get "js/sidebar-toggle.js" }} -{{ $headerjs := slice $jquery $cookies $docsCookies $themes $sidebar | resources.Concat "js/header.bundle.js" | resources.Fingerprint }} +{{ $aichat := resources.Get "js/ai-interactions.js" }} +{{ $headerjs := slice $jquery $cookies $docsCookies $themes $sidebar $aichat | resources.Concat "js/header.bundle.js" | resources.Fingerprint }} - \ No newline at end of file + + \ No newline at end of file From fd724c485ad2e832710e6f066bf23404733c4649 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 25 Sep 2024 16:31:55 -0500 Subject: [PATCH 02/45] fix(api): Fix Cloud Dedicated /ping descriptions - Cloud Dedicated /ping only reports querier, not ingester, health - Update v1 docs API and client library recommendations. Closes 5610 --- .../v1-compatibility/swaggerV1Compat.yml | 77 +++++++++++++++++++ api-docs/cloud-dedicated/v2/ref.yml | 22 ++++-- 2 files changed, 91 insertions(+), 8 deletions(-) diff --git a/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml b/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml index 091885223b..e13b311fed 100644 --- a/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml +++ b/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml @@ -240,6 +240,83 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /ping: + get: + description: | + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. + + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). + + This endpoint doesn't require authentication. + operationId: GetPing + responses: + '204': + description: | + Success--the querier is available. + Headers contain InfluxDB version information. + headers: + X-Influxdb-Build: + description: | + The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: | + The version of InfluxDB. + schema: + type: integer + 4xx: + description: | + #### InfluxDB Cloud + - Doesn't return this error. + security: + - {} + servers: [] + summary: Get the status of the instance + tags: + - Ping + head: + description: | + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. + + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). + + This endpoint doesn't require authentication. + + operationId: HeadPing + responses: + '204': + description: | + Success--the querier is available. + Headers contain InfluxDB version information. + headers: + X-Influxdb-Build: + description: The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: | + The version of InfluxDB. + schema: + type: integer + 4xx: + description: | + #### InfluxDB Cloud + - Doesn't return this error. + security: + - {} + servers: [] + summary: Get the status of the instance + tags: + - Ping components: parameters: TraceSpan: diff --git a/api-docs/cloud-dedicated/v2/ref.yml b/api-docs/cloud-dedicated/v2/ref.yml index 15dbd9307b..b223b244ed 100644 --- a/api-docs/cloud-dedicated/v2/ref.yml +++ b/api-docs/cloud-dedicated/v2/ref.yml @@ -149,17 +149,20 @@ paths: /ping: get: description: | - Retrieves the status and InfluxDB version of the instance. + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). This endpoint doesn't require authentication. operationId: GetPing responses: '204': description: | - Success. + Success--the querier is available. Headers contain InfluxDB version information. headers: X-Influxdb-Build: @@ -184,17 +187,20 @@ paths: - Ping head: description: | - Returns the status and InfluxDB version of the instance. + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. + + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). This endpoint doesn't require authentication. operationId: HeadPing responses: '204': description: | - Success. + Success--the querier is available. Headers contain InfluxDB version information. headers: X-Influxdb-Build: From a9f1072f0377f9e03ab965392976cc39d6957d34 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 26 Sep 2024 09:16:18 -0500 Subject: [PATCH 03/45] fix(v1): update client library recommendations for v1, v3 --- content/influxdb/v1/tools/api.md | 63 +++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 22 deletions(-) diff --git a/content/influxdb/v1/tools/api.md b/content/influxdb/v1/tools/api.md index 0f743c2319..e304ee67b2 100644 --- a/content/influxdb/v1/tools/api.md +++ b/content/influxdb/v1/tools/api.md @@ -13,43 +13,62 @@ v2: /influxdb/v2/reference/api/ --- The InfluxDB API provides a simple way to interact with the database. -It uses HTTP response codes, HTTP authentication, JWT Tokens, and basic authentication, and responses are returned in JSON. +It uses HTTP authentication and JWT Tokens. +Responses use standard HTTP response codes and JSON format. + +To send API requests, you can use +the [InfluxDB v1 client libraries](/influxdb/v1/tools/api_client_libraries/), +the [InfluxDB v2 client libraries](/influxdb/v1/tools/api_client_libraries/), +[Telegraf](https://docs.influxdata.com/telegraf/v1/), +or the client of your choice. + +If you're getting started with InfluxDB v1, we recommend using the +InfluxDB v1 client libraries and InfluxQL for [InfluxDB v3 compatibility](#influxdb-v3-compatibility). The following sections assume your InfluxDB instance is running on `localhost` port `8086` and HTTPS is not enabled. Those settings [are configurable](/influxdb/v1/administration/config/#http-endpoints-settings). -- [InfluxDB 2.0 API compatibility endpoints](#influxdb-2-0-api-compatibility-endpoints) -- [InfluxDB 1.x HTTP endpoints](#influxdb-1-x-http-endpoints) +- [InfluxDB v3 compatibility](#influxdb-v3-compatibility) +- [InfluxDB 2.x API compatibility endpoints](#influxdb-2x-api-compatibility-endpoints) +- [InfluxDB 1.x HTTP endpoints](#influxdb-1x-http-endpoints) + +## InfluxDB v3 compatibility + +InfluxDB v3 is InfluxDB’s next generation that allows +infinite series cardinality without impact on overall database performance, and +brings native SQL support and improved InfluxQL performance. + +InfluxDB v3 supports the v1 `/write` and `/query` HTTP API endpoints. +InfluxDB v3 isn't optimized for Flux. -## InfluxDB 2.0 API compatibility endpoints +If you're getting started with InfluxDB v1, we recommend using the +InfluxDB v1 client libraries and InfluxQL. +When you're ready, you can migrate to InfluxDB v3 and continue using the v1 client +libraries as you gradually move your query workloads to use the v3 client libraries +(and the v3 Flight API). -InfluxDB 1.8.0 introduced forward compatibility APIs for InfluxDB 2.0. -There are multiple reasons for introducing these: +For more information, see [API compatibility and migration guides for InfluxDB v3](/influxdb/cloud-dedicated/guides). -- The latest [InfluxDB client libraries](/influxdb/v1/tools/api_client_libraries/) - are built for the InfluxDB 2.0 API, but now also work with **InfluxDB 1.8.0+**. -- InfluxDB Cloud is a generally available service across multiple cloud service providers and regions - that is fully compatible with the **latest** client libraries. +## InfluxDB 2.x API compatibility endpoints -If you are just getting started with InfluxDB 1.x today, we recommend adopting -the [latest client libraries](/influxdb/v1/tools/api_client_libraries/). -They allow you to easily move from InfluxDB 1.x to InfluxDB 2.0 Cloud or open source, -(when you are ready). +InfluxDB 1.8.0 introduced forward compatibility APIs for InfluxDB v2. +[InfluxDB v2 client libraries](/influxdb/v1/tools/api_client_libraries/) +are built for the InfluxDB v2 API, but also work with **InfluxDB 1.8+**. -The following forward compatible APIs are available: +The following v2 compatible APIs are available: | Endpoint | Description | |:---------- |:---------- | -| [/api/v2/query](#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and [Flux](/flux/latest/) | -| [/api/v2/write](#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API _(compatible with InfluxDB 2.0 client libraries)_ | +| [/api/v2/query](#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB v2 API and [Flux](/flux/latest/) | +| [/api/v2/write](#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB v2 API _(compatible with InfluxDB v2 client libraries)_ | | [/health](#health-http-endpoint) | Check the health of your InfluxDB instance | ### `/api/v2/query/` HTTP endpoint The `/api/v2/query` endpoint accepts `POST` HTTP requests. -Use this endpoint to query data using [Flux](/influxdb/v1/flux/) and [InfluxDB 2.0 client libraries](/influxdb/v2/api-guide/client-libraries/). - Flux is the primary language for working with data in InfluxDB 2.0. +Use this endpoint to query data using [Flux](/influxdb/v1/flux/) and [InfluxDB v2 client libraries](/influxdb/v2/api-guide/client-libraries/). + Flux is the primary language for working with data in InfluxDB v2. **Include the following HTTP headers:** @@ -90,11 +109,11 @@ curl -XPOST localhost:8086/api/v2/query -sS \ ### `/api/v2/write/` HTTP endpoint The `/api/v2/write` endpoint accepts `POST` HTTP requests. -Use this endpoint to write to an InfluxDB 1.8.0+ database using [InfluxDB 2.0 client libraries](/influxdb/v2/api-guide/client-libraries/). +Use this endpoint to write to an InfluxDB 1.8.0+ database using [InfluxDB v2 client libraries](/influxdb/v2/api-guide/client-libraries/). Both InfluxDB 1.x and 2.0 APIs support the same line protocol format for raw time series data. For the purposes of writing data, the APIs differ only in the URL parameters and request headers. -InfluxDB 2.0 uses [organizations](/influxdb/v2/reference/glossary/#organization) +InfluxDB v2 uses [organizations](/influxdb/v2/reference/glossary/#organization) and [buckets](/influxdb/v2/reference/glossary/#bucket) instead of databases and retention policies. The `/api/v2/write` endpoint maps the supplied version 1.8 database and retention policy to a bucket. @@ -112,7 +131,7 @@ The `/api/v2/write` endpoint maps the supplied version 1.8 database and retentio **Include the following HTTP header:** -- `Authorization`: In InfluxDB 2.0 uses [API Tokens](/influxdb/v2/admin/tokens/) +- `Authorization`: In InfluxDB v2 uses [API Tokens](/influxdb/v2/admin/tokens/) to access the platform and all its capabilities. InfluxDB v1.x uses a username and password combination when accessing the HTTP APIs. Use the Token schema to provide your InfluxDB 1.x username and password separated by a colon (`:`). From 3e436809d8a1b27d28f21fe08e60691cc6edc73d Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 26 Sep 2024 12:07:10 -0500 Subject: [PATCH 04/45] fix(v1): Make stable-version OSS-specific. Update API notes. --- .../reference/client-libraries/v2/_index.md | 4 ++-- .../reference/client-libraries/v2/_index.md | 7 +++---- .../reference/client-libraries/v2/_index.md | 4 ++-- .../v1/about_the_project/release-notes.md | 2 +- content/influxdb/v1/concepts/glossary.md | 2 +- content/influxdb/v1/guides/query_data.md | 2 +- content/influxdb/v1/tools/api.md | 5 ++++- content/influxdb/v1/tools/api_client_libraries.md | 15 ++++++++------- .../v2/api-guide/client-libraries/_index.md | 5 ----- layouts/partials/article/stable-version.html | 2 +- 10 files changed, 23 insertions(+), 25 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md index a1754ddc2f..279ef36c12 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md @@ -1,7 +1,7 @@ --- title: InfluxDB v2 API client libraries description: > - InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). + InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). View the list of available client libraries. weight: 101 menu: @@ -25,7 +25,7 @@ prepend: ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. -InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). +InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). Functionality varies among client libraries. InfluxDB client libraries are maintained by the InfluxDB community. diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md index 67b7830496..5cfd071201 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md @@ -1,7 +1,7 @@ --- title: InfluxDB v2 API client libraries description: > - InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). + InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). View the list of available client libraries. weight: 101 menu: @@ -25,11 +25,10 @@ prepend: ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. -InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). +InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). Functionality varies among client libraries. -These client libraries are in active development and may not be feature-complete. - +InfluxDB client libraries are maintained by the InfluxDB community. For specifics about a client library, see the library's GitHub repository. {{< children depth="999" type="list" >}} diff --git a/content/influxdb/clustered/reference/client-libraries/v2/_index.md b/content/influxdb/clustered/reference/client-libraries/v2/_index.md index 0be0dff524..3b1ba8b313 100644 --- a/content/influxdb/clustered/reference/client-libraries/v2/_index.md +++ b/content/influxdb/clustered/reference/client-libraries/v2/_index.md @@ -1,7 +1,7 @@ --- title: InfluxDB v2 API client libraries description: > - InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). + InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). View the list of available client libraries. weight: 101 menu: @@ -25,7 +25,7 @@ prepend: ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. -InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). +InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). Functionality varies among client libraries. InfluxDB client libraries are maintained by the InfluxDB community. diff --git a/content/influxdb/v1/about_the_project/release-notes.md b/content/influxdb/v1/about_the_project/release-notes.md index a7f8c6f8cb..32f6c4d812 100644 --- a/content/influxdb/v1/about_the_project/release-notes.md +++ b/content/influxdb/v1/about_the_project/release-notes.md @@ -163,7 +163,7 @@ This release updates support for the Flux language and queries. To learn about F #### Forward compatibility -- [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints) are now part of the InfluxDB 1.x line. +- [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints) are now part of the InfluxDB 1.x line. This allows you to leverage the new InfluxDB 2.0 [client libraries](/influxdb/v1/tools/api_client_libraries/) for both writing and querying data with Flux. Take advantage of the latest client libraries while readying your implementation for a move to InfluxDB 2.0 Cloud when you're ready to scale. diff --git a/content/influxdb/v1/concepts/glossary.md b/content/influxdb/v1/concepts/glossary.md index da30c706b1..22668d9372 100644 --- a/content/influxdb/v1/concepts/glossary.md +++ b/content/influxdb/v1/concepts/glossary.md @@ -27,7 +27,7 @@ Related entries: [InfluxDB line protocol](/influxdb/v1/concepts/glossary/#influx ## bucket -A bucket is a named location where time series data is stored in **InfluxDB 2.0**. In InfluxDB 1.8+, each combination of a database and a retention policy (database/retention-policy) represents a bucket. Use the [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api#influxdb-2-0-api-compatibility-endpoints) included with InfluxDB 1.8+ to interact with buckets. +A bucket is a named location where time series data is stored in **InfluxDB 2.0**. In InfluxDB 1.8+, each combination of a database and a retention policy (database/retention-policy) represents a bucket. Use the [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api#influxdb-2-0-api-compatibility-endpoints) included with InfluxDB 1.8+ to interact with buckets. ## continuous query (CQ) diff --git a/content/influxdb/v1/guides/query_data.md b/content/influxdb/v1/guides/query_data.md index 8194804ef8..b60adb5bc0 100644 --- a/content/influxdb/v1/guides/query_data.md +++ b/content/influxdb/v1/guides/query_data.md @@ -54,7 +54,7 @@ The header row defines column labels for the table. The `cpu` [measurement](/inf ### Flux Check out the [Get started with Flux](/influxdb/v2/query-data/get-started/) to learn more about building queries with Flux. -For more information about querying data with the InfluxDB API using Flux, see the [API reference documentation](/influxdb/v1/tools/api/#influxdb-2-0-api-compatibility-endpoints). +For more information about querying data with the InfluxDB API using Flux, see the [API reference documentation](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). ## Query data with InfluxQL diff --git a/content/influxdb/v1/tools/api.md b/content/influxdb/v1/tools/api.md index e304ee67b2..ff21219208 100644 --- a/content/influxdb/v1/tools/api.md +++ b/content/influxdb/v1/tools/api.md @@ -22,8 +22,11 @@ the [InfluxDB v2 client libraries](/influxdb/v1/tools/api_client_libraries/), [Telegraf](https://docs.influxdata.com/telegraf/v1/), or the client of your choice. +{{% note %}} If you're getting started with InfluxDB v1, we recommend using the -InfluxDB v1 client libraries and InfluxQL for [InfluxDB v3 compatibility](#influxdb-v3-compatibility). +InfluxDB v1 client libraries and InfluxQL for +[InfluxDB v3 compatibility](/influxdb/v1/tools/api/#influxdb-v3-compatibility). +{{% /note %}} The following sections assume your InfluxDB instance is running on `localhost` port `8086` and HTTPS is not enabled. diff --git a/content/influxdb/v1/tools/api_client_libraries.md b/content/influxdb/v1/tools/api_client_libraries.md index 36483663a8..e030250c89 100644 --- a/content/influxdb/v1/tools/api_client_libraries.md +++ b/content/influxdb/v1/tools/api_client_libraries.md @@ -13,15 +13,16 @@ menu: v2: /influxdb/v2/api-guide/client-libraries/ --- -InfluxDB client libraries are language-specific packages that integrate with the InfluxDB 2.0 API and support both **InfluxDB 1.8+** and **InfluxDB 2.0**. +InfluxDB v2 client libraries are language-specific packages that integrate +with the InfluxDB v2 API and support both **InfluxDB 1.8+** and **InfluxDB 2.x**. {{% note %}} -We recommend using the new client libraries on this page to leverage the new -read (via Flux) and write APIs and prepare for conversion to InfluxDB v2 and -InfluxDB Cloud. -For more information, see [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2-0-api-compatibility-endpoints). -Client libraries for [InfluxDB 1.7 and earlier](/influxdb/v1/tools/api_client_libraries/) -may continue to work, but are not maintained by InfluxData. +If you're getting started with InfluxDB v1, we recommend using the +InfluxDB v1 client libraries and InfluxQL for +[InfluxDB v3 compatibility](/influxdb/v1/tools/api/#influxdb-v3-compatibility). + +For more information about API and client library compatibility, see the +[InfluxDB v1 API reference](/influxdb/v1/tools/api/). {{% /note %}} ## Client libraries diff --git a/content/influxdb/v2/api-guide/client-libraries/_index.md b/content/influxdb/v2/api-guide/client-libraries/_index.md index 697dcdbc5a..fed8999ef6 100644 --- a/content/influxdb/v2/api-guide/client-libraries/_index.md +++ b/content/influxdb/v2/api-guide/client-libraries/_index.md @@ -19,9 +19,4 @@ influxdb/v2/tags: [client libraries] InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. The following **InfluxDB v2** client libraries are available: -{{% note %}} -These client libraries are in active development and may not be feature-complete. -This list will continue to grow as more client libraries are released. -{{% /note %}} - {{< children type="list" >}} diff --git a/layouts/partials/article/stable-version.html b/layouts/partials/article/stable-version.html index 0794eb6a1d..28e7f27a67 100644 --- a/layouts/partials/article/stable-version.html +++ b/layouts/partials/article/stable-version.html @@ -1,6 +1,6 @@ {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} {{ $product := index $productPathData 0 }} -{{ $productName := (index .Site.Data.products $product).name }} +{{ $productName := cond (isset (index .Site.Data.products $product) "altname") (index .Site.Data.products $product).altname (index .Site.Data.products $product).name }} {{ $currentVersion := index $productPathData 1 }} {{ $latestV2 := index (.Site.Data.products.influxdb.versions) 0 }} From f34a61a25acd6d2aab0bdf3bf11a78058a4e1644 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 27 Sep 2024 09:30:39 -0600 Subject: [PATCH 05/45] InfluxDB Clustered partial writes (#5594) * updated status code information for partial writes * docs: add environment variable tuning explanation (#5579) * WIP clustered partial writes * fixed yaml error * fixed duplicate key in clustered api docs * Apply suggestions from code review Co-authored-by: Jason Stirnaman * Update content/influxdb/clustered/admin/env-vars.md * Apply suggestions from code review * add placeholder release notes for next clustered version * update clustered release notes, remove option license info --------- Co-authored-by: Jack <56563911+jdockerty@users.noreply.github.com> Co-authored-by: Jason Stirnaman --- .../vocabularies/InfluxDataDocs/accept.txt | 2 +- api-docs/clustered/v2/ref.yml | 20 +- .../admin/bypass-identity-provider.md | 2 +- content/influxdb/clustered/admin/env-vars.md | 171 ++++++++++++++++++ content/influxdb/clustered/admin/licensing.md | 31 ---- .../influxdb/clustered/install/licensing.md | 57 +----- .../reference/release-notes/clustered.md | 127 ++++++++++++- .../clustered/write-data/troubleshoot.md | 40 +++- 8 files changed, 348 insertions(+), 102 deletions(-) create mode 100644 content/influxdb/clustered/admin/env-vars.md diff --git a/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt b/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt index dae2608d14..6c0a4fb860 100644 --- a/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt +++ b/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt @@ -68,7 +68,7 @@ influx3 influxctl influxd influxdata.com -iox +(iox|IOx) keep-url lat locf diff --git a/api-docs/clustered/v2/ref.yml b/api-docs/clustered/v2/ref.yml index 2398594570..b617a71033 100644 --- a/api-docs/clustered/v2/ref.yml +++ b/api-docs/clustered/v2/ref.yml @@ -646,17 +646,33 @@ paths: '204': description: Write data is correctly formatted and accepted for writing to the database. '400': + description: | + Data from the batch was rejected and not written. The response body indicates if a partial write occurred or all data was rejected. + If a partial write occurred, then some points from the batch are written and queryable. + The response body contains details about the [rejected points](/influxdb/clustered/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. content: application/json: + examples: + rejectedAllPoints: + summary: Rejected all points + value: + code: invalid + line: 2 + message: 'no data written, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' + partialWriteErrorWithRejectedPoints: + summary: Partial write rejects some points + value: + code: invalid + line: 2 + message: 'partial write has occurred, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' schema: $ref: '#/components/schemas/LineProtocolError' - description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. '401': content: application/json: schema: $ref: '#/components/schemas/Error' - description: Token doesn't have sufficient permissions to write to this database or the database doesn't exist. + description: Token doesn't have sufficient permissions to write to this database or the database doesn't exist. '403': content: application/json: diff --git a/content/influxdb/clustered/admin/bypass-identity-provider.md b/content/influxdb/clustered/admin/bypass-identity-provider.md index c9a3e6caa0..7edd944ede 100644 --- a/content/influxdb/clustered/admin/bypass-identity-provider.md +++ b/content/influxdb/clustered/admin/bypass-identity-provider.md @@ -7,7 +7,7 @@ description: > menu: influxdb_clustered: parent: Administer InfluxDB Clustered -weight: 208 +weight: 209 --- {{< product-name >}} generates a valid access token (known as the _admin token_) diff --git a/content/influxdb/clustered/admin/env-vars.md b/content/influxdb/clustered/admin/env-vars.md new file mode 100644 index 0000000000..a17bd82019 --- /dev/null +++ b/content/influxdb/clustered/admin/env-vars.md @@ -0,0 +1,171 @@ +--- +title: Manage environment variables in your InfluxDB Cluster +description: > + Use environment variables to define settings for individual components in your + InfluxDB cluster. +menu: + influxdb_clustered: + parent: Administer InfluxDB Clustered + name: Manage environment variables +weight: 208 +--- + +Use environment variables to define settings for individual components in your +InfluxDB cluster and adjust your cluster's running configuration. +Define environment variables for each component in your `AppInstance` resource. + +InfluxDB Clustered components support various environment variables. +While many of these variables have default settings, you can customize them by +setting your own values. + +{{% warn %}} +#### Overriding default settings may affect overall cluster performance + +{{% product-name %}} components have complex interactions that can be affected +when overriding default configuration settings. +Changing these settings may impact overall cluster performance. +Before making configuration changes using environment variables, consider +consulting [InfluxData Support](https://support.influxdata.com/) to identify any +potential unintended consequences. +{{% /warn %}} + +## AppInstance component schema + +In your `AppInstance` resource, configure individual component settings in the +`spec.package.spec.components` property. This property supports the following +InfluxDB Clustered component keys: + +- `ingester` +- `querier` +- `router` +- `compactor` +- `garbage-collector` + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + ingester: + # Ingester settings ... + querier: + # Querier settings ... + router: + # Router settings. ... + compactor: + # Compactor settings ... + garbage-collector: + # Garbage collector settings ... +``` + +_For more information about components in the InfluxDB v3 storage engine, see +the [InfluxDB v3 storage engine architecture](/influxdb/clustered/reference/internals/storage-engine/)._ + +## Set environment variables for a component + +1. Under the specific component property, use the + `.template.containers.iox.env` property to define environment + variables. +2. In the `env` property, structure each environment variable as a key-value pair. + For example, to configure environment variables for the Garbage collector: + + ```yaml + apiVersion: kubecfg.dev/v1alpha1 + kind: AppInstance + metadata: + name: influxdb + namespace: influxdb + spec: + package: + # ... + spec: + components: + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' + ``` + +3. Use `kubectl apply` to apply the configuration changes to your cluster and + add or update environment variables in each component. + + + + ```bash + kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb + ``` +{{% note %}} +#### Update environment variables instead of removing them + +Most configuration settings that can be overridden by environment variables have +default values that are used if the environment variable is unset. Removing +environment variables from your `AppInstance` resource configuration will not +remove those environment variables entirely; instead, they will revert to their +default settings. To revert to the default settings, simply unset the +environment variable or update the value in your `AppInstance` resource to the +default value. + +In the preceding example, the `INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF` environment +variable is set to `6h`. If you remove `INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF` from +the `env` property, the cutoff reverts to its default setting of `30d`. +{{% /note %}} + +{{< expand-wrapper >}} +{{% expand "View example of environment variables in all components" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_WAL_ROTATION_PERIOD_SECONDS: '360' + querier: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_BYTES: '10737418240' # 10GiB + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '5000' + compactor: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_PERCENT: '80' + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/admin/licensing.md b/content/influxdb/clustered/admin/licensing.md index 90f716bbe9..bda66025d6 100644 --- a/content/influxdb/clustered/admin/licensing.md +++ b/content/influxdb/clustered/admin/licensing.md @@ -27,20 +27,6 @@ the InfluxDB Clustered software. - [License expiry logs](#license-expiry-logs) - [Query brownout](#query-brownout) -{{% note %}} -#### License enforcement is currently an opt-in feature - -In currently available versions of InfluxDB Clustered, license enforcement is an -opt-in feature that allows InfluxData to introduce license enforcement to -customers, and allows customers to deactivate the feature if issues arise. -In the future, all releases of InfluxDB Clustered will require customers to -configure an active license before they can use the product. - -To opt into license enforcement, include the `useLicensedBinaries` feature flag -in your `AppInstance` resource _([See the example below](#enable-feature-flag))_. -To deactivate license enforcement, remove the `useLicensedBinaries` feature flag. -{{% /note %}} - ## Install your InfluxDB license {{% note %}} @@ -64,22 +50,6 @@ install your license. kubectl apply --filename license.yml --namespace influxdb ``` -4. - Update your `AppInstance` resource to include the `useLicensedBinaries` feature flag. - Add the `useLicensedBinaries` entry to the `.spec.package.spec.featureFlags` - property--for example: - - ```yml - apiVersion: kubecfg.dev/v1alpha1 - kind: AppInstance - # ... - spec: - package: - spec: - featureFlags: - - useLicensedBinaries - ``` - InfluxDB Clustered detects the `License` resource and extracts the credentials into a secret required by InfluxDB Clustered Kubernetes pods. Pods validate the license secret both at startup and periodically (roughly once @@ -115,7 +85,6 @@ license enforcement. ### A valid license is required -_When you include the `useLicensedBinaries` feature flag_, Kubernetes pods running in your InfluxDB cluster must have a valid `License` resource to run. Licenses are issued by InfluxData. If there is no `License` resource installed in your cluster, one of two things may happen: diff --git a/content/influxdb/clustered/install/licensing.md b/content/influxdb/clustered/install/licensing.md index df245008ff..a15b6ea0cb 100644 --- a/content/influxdb/clustered/install/licensing.md +++ b/content/influxdb/clustered/install/licensing.md @@ -17,20 +17,6 @@ related: Install your InfluxDB Clustered license in your cluster to authorize the use of the InfluxDB Clustered software. -{{% note %}} -#### License enforcement is currently an opt-in feature - -In currently available versions of InfluxDB Clustered, license enforcement is an -opt-in feature that allows InfluxData to introduce license enforcement to -customers, and allows customers to deactivate the feature if issues arise. -In the future, all releases of InfluxDB Clustered will require customers to -configure an active license before they can use the product. - -To opt into license enforcement, include the `useLicensedBinaries` feature flag -in your `AppInstance` resource _([See the example below](#enable-feature-flag))_. -To deactivate license enforcement, remove the `useLicensedBinaries` feature flag. -{{% /note %}} - ## Install your InfluxDB license 1. If you haven't already, @@ -46,46 +32,6 @@ To deactivate license enforcement, remove the `useLicensedBinaries` feature flag kubectl apply --filename license.yml --namespace influxdb ``` -4. - Update your `AppInstance` resource to activate the `useLicensedBinaries` feature flag: - - - If configuring the `AppInstance` resource directly, add the - `useLicensedBinaries` entry to the `.spec.package.spec.featureFlags` - property. - - If using the [InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered), add the `useLicensedBinaries` entry to the - `featureFlags` property in your `values.yaml`. - - {{< code-tabs-wrapper >}} -{{% code-tabs %}} -[AppInstance](#) -[Helm](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - featureFlags: - - useLicensedBinaries -``` - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -```yml -# values.yaml - -featureFlags: - - useLicensedBinaries -``` - -{{% /code-tab-content %}} - {{< /code-tabs-wrapper >}} - InfluxDB Clustered detects the `License` resource and extracts the credentials into a secret required by InfluxDB Clustered Kubernetes pods. Pods validate the license secret both at startup and periodically (roughly once @@ -97,7 +43,8 @@ If you are currently using a non-licensed preview release of InfluxDB Clustered and want to upgrade to a licensed release, do the following: 1. [Install an InfluxDB license](#install-your-influxdb-license) -2. If you [use the `AppInstance` resource configuration](/influxdb/clustered/install/configure-cluster/directly/) to configure your cluster, in your `myinfluxdb.yml`, +2. If you [use the `AppInstance` resource configuration](/influxdb/clustered/install/configure-cluster/directly/) + to configure your cluster, in your `myinfluxdb.yml`, update the package version defined in `spec.package.image` to use a licensed release. diff --git a/content/influxdb/clustered/reference/release-notes/clustered.md b/content/influxdb/clustered/reference/release-notes/clustered.md index 8ad663db54..cf1b3f234f 100644 --- a/content/influxdb/clustered/reference/release-notes/clustered.md +++ b/content/influxdb/clustered/reference/release-notes/clustered.md @@ -26,6 +26,129 @@ identified below with the icon. --- +## 20240925-1257864 {date="2024-09-25" .checkpoint} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:202409XX-XXXXXXX +``` + +### Highlights + +#### Default to partial write semantics + +In InfluxDB Clustered 20240925-1257864+, "partial writes" are enabled by default. +With partial writes enabled, InfluxDB accepts write requests with invalid or +malformed lines of line protocol and successfully write valid lines and rejects +invalid lines. Previously, if any line protocol in a batch was invalid, the +entire batch was rejected and no data was written. + +To disable partial writes and revert back to the previous behavior, set the +`INFLUXDB_IOX_PARTIAL_WRITES_ENABLED` environment variable on your cluster's +Ingester to `false`. Define this environment variable in the +`spec.package.spec.components.ingester.template.containers.iox.env` property in +your `AppInstance` resource. + +{{< expand-wrapper >}} +{{% expand "View example of disabling partial writes in your `AppInstance` resource" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + spec: + components: + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_PARTIAL_WRITES_ENABLED: false +``` + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information about defining variables in your InfluxDB cluster, see +[Manage environment variables in your InfluxDB Cluster](/influxdb/clustered/admin/env-vars/). + +##### Write API behaviors + +When submitting a write request that includes invalid or malformed line protocol, +The InfluxDB write API returns a 400 response code and does the following: + +- With partial writes _enabled_: + + - Writes all valid points and rejects all invalid points. + - Includes details about the [rejected points](/influxdb/clustered/write-data/troubleshoot/#troubleshoot-rejected-points) + (up to 100 points) in the response body. + +- With partial writes _disabled_: + + - Rejects all points in the batch. + - Includes an error message and the first malformed line of line protocol in + the response body. + +#### Deploy and use the Catalog service by default + +The Catalog service is a new IOx component that centralizes access to the +InfluxDB Catalog among Ingesters, Queriers, Compactors, and Garbage Collectors. +This is expected to improve Catalog query performance overall with an expected +drop in ninety-ninth percentile (p99) latencies. + +### Upgrade notes + +#### License now required + +A valid license token is now required to start up your InfluxDB Cluster. +To avoid possible complications, ensure you have a valid license token. If you +do not, contact your InfluxData sales representative to get a license token +**before upgrading to this release**. + +#### Removed prometheusOperator feature flag + +The `prometheusOperator` feature flag has been removed. +**If you current have this feature flag enabled in your `AppInstance` resource, +remove it before upgrading to this release.** +This flag was deprecated in a previous release, but from this release forward, +enabling this feature flag may cause errors. + +The installation of the Prometheus operator should be handled externally. + +### Changes + +#### Deployment + +- Introduces the `nodeAffinity` and CPU/Memory requests setting for "granite" + components. Previously, these settings were only available for core IOx + components. +- Prior to this release, many of the IOx dashboards deployed with the `grafana` + feature flag were showing "no data." This has been fixed and now all + dashboards should display actual data. + +#### Database Engine + +- Adjusted compactor concurrency scaling heuristic to improve performance as + memory and CPU scale. +- Adjusted default `INFLUXDB_IOX_COMPACTION_PARTITION_MINUTE_THRESHOLD` from + `20m` to `100m` to help compactor more quickly rediscover cool partitions. + +#### Configuration + +- Introduces the `podAntiAffinity` setting for InfluxDB Clustered components. + Previously, the scheduling of pods was influenced by the Kubernetes + scheduler's default behavior. For further details, see the + [Kubernetes pod affinity documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#types-of-inter-pod-affinity-and-anti-affinity). + +--- + ## 20240819-1176644 {date="2024-08-19" .checkpoint} ### Quickstart @@ -463,7 +586,7 @@ mounted into your existing Grafana instance. An authentication component, previously known as `authz`, has been consolidated into the `token-management` service. -There is now a temporary `Job` in place, `delete-authz-schema`, that +Now there is a temporary `Job` in place, `delete-authz-schema`, that automatically removes the `authz` schema from the configured PostgreSQL database. ### Changes @@ -704,7 +827,7 @@ the `create-admin-token` job. #### Deployment -- Increase HTTP write request limit from 10MB to 50MB. +- Increase HTTP write request limit from 10 MB to 50 MB. - Added support for [Telegraf Operator](https://github.com/influxdata/telegraf-operator). We have added the `telegraf.influxdata.com/port` annotation to all the pods. No configuration is required. We don't yet provide a way to specify the diff --git a/content/influxdb/clustered/write-data/troubleshoot.md b/content/influxdb/clustered/write-data/troubleshoot.md index 1c7c9b5f50..5e397c5e49 100644 --- a/content/influxdb/clustered/write-data/troubleshoot.md +++ b/content/influxdb/clustered/write-data/troubleshoot.md @@ -5,7 +5,8 @@ weight: 106 description: > Troubleshoot issues writing data. Find response codes for failed writes. - Discover how writes fail, from exceeding rate or payload limits, to syntax errors and schema conflicts. + Discover how writes fail, from exceeding rate or payload limits, to syntax + errors and schema conflicts. menu: influxdb_clustered: name: Troubleshoot issues @@ -17,7 +18,8 @@ related: - /influxdb/clustered/reference/internals/durability/ --- -Learn how to avoid unexpected results and recover from errors when writing to {{% product-name %}}. +Learn how to avoid unexpected results and recover from errors when writing to +{{% product-name %}}. - [Handle write responses](#handle-write-responses) - [Review HTTP status codes](#review-http-status-codes) @@ -26,12 +28,26 @@ Learn how to avoid unexpected results and recover from errors when writing to {{ ## Handle write responses -In {{% product-name %}}, writes are synchronous. -After InfluxDB validates the request and ingests the data, it sends a _success_ response (HTTP `204` status code) as an acknowledgement that the data is written and queryable. -To ensure that InfluxDB handles writes in the order you request them, wait for the acknowledgement before you send the next request. +{{% product-name %}} does the following when you send a write request: -If InfluxDB successfully writes all the request data to the database, it returns _success_ (HTTP `204` status code). -The first rejected point in a batch causes InfluxDB to reject the entire batch and respond with an [HTTP error status](#review-http-status-codes). +1. Validates the request. +2. If successful, attempts to ingest data from the request body; otherwise, + responds with an [error status](#review-http-status-codes). +3. Ingests or rejects data in the batch and returns one of the following HTTP + status codes: + + - `204 No Content`: All data in the batch is ingested. + - `400 Bad Request`: Some or all of the data has been rejected. + Data that has not been rejected is ingested and queryable. + +The response body contains error details about +[rejected points](#troubleshoot-rejected-points), up to 100 points. + +Writes are synchronous--the response status indicates the final status of the +write and all ingested data is queryable. + +To ensure that InfluxDB handles writes in the order you request them, +wait for the response before you send the next request. ### Review HTTP status codes @@ -42,7 +58,7 @@ Write requests return the following status codes: | HTTP response code | Message | Description | | :-------------------------------| :--------------------------------------------------------------- | :------------- | | `204 "Success"` | | If InfluxDB ingested the data | -| `400 "Bad request"` | `message` contains the first malformed line | If data is malformed | +| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | If some or all request data isn't allowed (for example, if it is malformed or falls outside of the bucket's retention period)--the response body indicates whether a partial write has occurred or if all data has been rejected | | `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/clustered/admin/tokens/) doesn't have [permission](/influxdb/clustered/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb/clustered/get-started/write/#write-line-protocol-to-influxdb) in write requests. | | `404 "Not found"` | requested **resource type** (for example, "organization" or "database"), and **resource name** | If a requested resource (for example, organization or database) wasn't found | | `500 "Internal server error"` | | Default status for an error | @@ -62,6 +78,10 @@ If you notice data is missing in your database, do the following: ## Troubleshoot rejected points -InfluxDB rejects points that fall within the same partition (default partitioning is measurement and day) as existing bucket data and have a different data type for an existing field. +InfluxDB rejects points that fall within the same partition (default partitioning +is by measurement and day) as existing bucket data and have a different data type +for an existing field. -Check for [field data type](/influxdb/clustered/reference/syntax/line-protocol/#data-types-and-format) differences between the rejected data point and points within the same database and partition--for example, did you attempt to write `string` data to an `int` field? +Check for [field data type](/influxdb/clustered/reference/syntax/line-protocol/#data-types-and-format) +differences between the rejected data point and points within the same database +and partition--for example, did you attempt to write `string` data to an `int` field? From 1d627033030152ff1ffe62ea3ec09c8a661ae2c1 Mon Sep 17 00:00:00 2001 From: Jeffrey Smith II Date: Mon, 30 Sep 2024 15:34:37 -0400 Subject: [PATCH 06/45] fix: serverless/dedicated/clustered support chunked and chunk_size (#5624) * fix: serverless/dedicated/clustered support chunked and chunk_size * chore: cleanup Co-authored-by: Scott Anderson * chore: cleanup Co-authored-by: Scott Anderson * chore: cleanup Co-authored-by: Scott Anderson --------- Co-authored-by: Scott Anderson --- .../cloud-dedicated/guides/api-compatibility/v1/_index.md | 3 ++- .../cloud-serverless/query-data/execute-queries/v1-http.md | 3 ++- .../influxdb/clustered/guides/api-compatibility/v1/_index.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md b/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md index d654d00a4d..8a434a5224 100644 --- a/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md +++ b/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md @@ -457,7 +457,8 @@ For {{% product-name %}} v1 API `/query` requests, set parameters as listed in t Parameter | Allowed in | Ignored | Value ----------|------------|---------|------------------------------------------------------------------------- -`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_ +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. `db` | Query string | Honored | Database name | `epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) | `p` | Query string | Honored | Database token diff --git a/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md b/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md index 9496364214..6b9a3ba059 100644 --- a/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md +++ b/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md @@ -62,7 +62,8 @@ For {{% product-name %}} v1 API `/query` requests, set parameters as listed in t Parameter | Allowed in | Ignored | Value ------------|--------------|---------|------------------------------------------------------------------------- -`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_ +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. `db` | Query string | Honored | Database name [mapped to a bucket](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets) `epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) `pretty` | Query string | Ignored | N/A diff --git a/content/influxdb/clustered/guides/api-compatibility/v1/_index.md b/content/influxdb/clustered/guides/api-compatibility/v1/_index.md index 23330633b6..520f2a25cc 100644 --- a/content/influxdb/clustered/guides/api-compatibility/v1/_index.md +++ b/content/influxdb/clustered/guides/api-compatibility/v1/_index.md @@ -456,7 +456,8 @@ For {{% product-name %}} v1 API `/query` requests, set parameters as listed in t Parameter | Allowed in | Ignored | Value ----------|------------|---------|------------------------------------------------------------------------- -`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_ +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. `db` | Query string | Honored | Database name | `epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) | `p` | Query string | Honored | Database token From 1e6ee0ebdaa2dfda0b8b950a27821bcd073037b9 Mon Sep 17 00:00:00 2001 From: B Tasker <88340935+btasker@users.noreply.github.com> Date: Wed, 2 Oct 2024 14:28:29 +0100 Subject: [PATCH 07/45] docs: make description less ambiguous about what the function does --- .../stdlib/influxdata/influxdb/cardinality.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md index 0a1d5672f6..40429d941f 100644 --- a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md +++ b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md @@ -1,7 +1,7 @@ --- title: influxdb.cardinality() function description: > - `influxdb.cardinality()` returns the series cardinality of data stored in InfluxDB. + `influxdb.cardinality()` returns the series cardinality of data retrieved from InfluxDB. menu: flux_v0_ref: name: influxdb.cardinality @@ -28,9 +28,16 @@ Fluxdoc syntax: https://github.com/influxdata/flux/blob/master/docs/fluxdoc.md -------------------------------------------------------------------------------> -`influxdb.cardinality()` returns the series cardinality of data stored in InfluxDB. +`influxdb.cardinality()` returns the series cardinality of data retrieved from InfluxDB. +{{% note %}} +Although this function is similar to InfluxQL's [`SHOW SERIES CARDINALITY`](/influxdb/v1/query_language/spec/#show-series-cardinality), +it works in a slightly different manner. + +`influxdb.cardinality()` is time bounded and reports the cardinality of the data that's passed into it rather than the cardinality of the bucket as a whole. +{{% /note %}} + ##### Function type signature @@ -107,6 +114,12 @@ The cardinality calculation excludes points that match the specified start time. Use a relative duration or absolute time. For example, `-1h` or `2019-08-28T22:00:00Z`. Durations are relative to `now()`. Default is `now()`. +{{% note %}} +The default value is `now()`, so any points that have been written into the future will +not be counted unless a future `stop` date is provided. +{{% /note %}} + + ### predicate Predicate function that filters records. From 13daf75d88407aa60b14848dac2cd18d74fd55a0 Mon Sep 17 00:00:00 2001 From: B Tasker <88340935+btasker@users.noreply.github.com> Date: Wed, 2 Oct 2024 14:29:21 +0100 Subject: [PATCH 08/45] fix: adjust examples to do what the headers suggest --- content/flux/v0/stdlib/influxdata/influxdb/cardinality.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md index 40429d941f..20461bd583 100644 --- a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md +++ b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md @@ -139,9 +139,10 @@ Default is `(r) => true`. ```js import "influxdata/influxdb" -influxdb.cardinality(bucket: "example-bucket", start: -1y) +influxdb.cardinality(bucket: "example-bucket", start: 1) ``` +Note: if points have been written into the future, you will need to add an appropriate `stop` date ### Query series cardinality in a measurement// @@ -151,7 +152,7 @@ import "influxdata/influxdb" influxdb.cardinality( bucket: "example-bucket", - start: -1y, + start: 1, predicate: (r) => r._measurement == "example-measurement", ) @@ -163,7 +164,7 @@ influxdb.cardinality( ```js import "influxdata/influxdb" -influxdb.cardinality(bucket: "example-bucket", start: -1y, predicate: (r) => r.exampleTag == "foo") +influxdb.cardinality(bucket: "example-bucket", start: 1, predicate: (r) => r.exampleTag == "foo") ``` From 41edaadc129dffdc9cdb771f0de2bdaea18b1440 Mon Sep 17 00:00:00 2001 From: B Tasker <88340935+btasker@users.noreply.github.com> Date: Wed, 2 Oct 2024 14:33:06 +0100 Subject: [PATCH 09/45] fix: use correct closing tag --- content/influxdb/v2/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/v2/reference/faq.md b/content/influxdb/v2/reference/faq.md index 5e134a7bce..a0e692d5cd 100644 --- a/content/influxdb/v2/reference/faq.md +++ b/content/influxdb/v2/reference/faq.md @@ -1088,7 +1088,7 @@ Each InfluxDB Cloud organization has a series cardinality limit to prevent runaway cardinality. For information about adjusting cardinality limits, see [How do I increase my organization’s rate limits and quotas?](#how-do-i-increase-my-organizations-rate-limits-and-quotas). -{{% /oss-only %}} +{{% /cloud-only %}} Use [`influxdb.cardinality()`](/flux/v0/stdlib/influxdata/influxdb/cardinality/) in Flux or [`SHOW SERIES CARDINALITY`](/influxdb/v1/query_language/spec/#show-series-cardinality) From f3f7ffa5e806e70fd9045bb1ee4231e7dd795811 Mon Sep 17 00:00:00 2001 From: B Tasker <88340935+btasker@users.noreply.github.com> Date: Wed, 2 Oct 2024 15:19:51 +0100 Subject: [PATCH 10/45] docs: tweak wording --- content/flux/v0/stdlib/influxdata/influxdb/cardinality.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md index 20461bd583..3beb808931 100644 --- a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md +++ b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md @@ -35,7 +35,7 @@ Fluxdoc syntax: https://github.com/influxdata/flux/blob/master/docs/fluxdoc.md Although this function is similar to InfluxQL's [`SHOW SERIES CARDINALITY`](/influxdb/v1/query_language/spec/#show-series-cardinality), it works in a slightly different manner. -`influxdb.cardinality()` is time bounded and reports the cardinality of the data that's passed into it rather than the cardinality of the bucket as a whole. +`influxdb.cardinality()` is time bounded and reports the cardinality of data that matches the conditions passed into it rather than that of the bucket as a whole. {{% /note %}} From b9023c83f726ae344c9d35fec6498e3e7189ee97 Mon Sep 17 00:00:00 2001 From: B Tasker <88340935+btasker@users.noreply.github.com> Date: Wed, 2 Oct 2024 15:27:21 +0100 Subject: [PATCH 11/45] fix: influxdb.cardinality() can't accept an integer as start --- content/flux/v0/stdlib/influxdata/influxdb/cardinality.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md index 3beb808931..70e68c66f6 100644 --- a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md +++ b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md @@ -139,7 +139,7 @@ Default is `(r) => true`. ```js import "influxdata/influxdb" -influxdb.cardinality(bucket: "example-bucket", start: 1) +influxdb.cardinality(bucket: "example-bucket", start: time(v: 1)) ``` Note: if points have been written into the future, you will need to add an appropriate `stop` date @@ -152,7 +152,7 @@ import "influxdata/influxdb" influxdb.cardinality( bucket: "example-bucket", - start: 1, + start: time(v: 1), predicate: (r) => r._measurement == "example-measurement", ) @@ -164,7 +164,7 @@ influxdb.cardinality( ```js import "influxdata/influxdb" -influxdb.cardinality(bucket: "example-bucket", start: 1, predicate: (r) => r.exampleTag == "foo") +influxdb.cardinality(bucket: "example-bucket", start: time(v: 1), predicate: (r) => r.exampleTag == "foo") ``` From 8bf686f5b6308eed36997edc462f05d95e7eac27 Mon Sep 17 00:00:00 2001 From: B Tasker <88340935+btasker@users.noreply.github.com> Date: Wed, 2 Oct 2024 15:28:26 +0100 Subject: [PATCH 12/45] feat: add example --- .../flux/v0/stdlib/influxdata/influxdb/cardinality.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md index 70e68c66f6..c6c845c086 100644 --- a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md +++ b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md @@ -133,6 +133,7 @@ Default is `(r) => true`. - [Query series cardinality in a bucket](#query-series-cardinality-in-a-bucket) - [Query series cardinality in a measurement//](#query-series-cardinality-in-a-measurement) - [Query series cardinality for a specific tag](#query-series-cardinality-for-a-specific-tag) +- [Query series cardinality of Data Written In the Last 4 Hours](#query-series-cardinality-of-data-written-in-the-last-4-hours) ### Query series cardinality in a bucket @@ -168,3 +169,12 @@ influxdb.cardinality(bucket: "example-bucket", start: time(v: 1), predicate: (r) ``` + +### Query Cardinality of Data Written In the Last 4 hours +```js +import "influxdata/influxdb" + +influxdb.cardinality(bucket: "example-bucket", start: -4h) + +``` + From 7a52a2cf09f8a9a2487d6124b917ed46d8c36963 Mon Sep 17 00:00:00 2001 From: Ilario Gelmetti Date: Wed, 2 Oct 2024 12:17:57 +0200 Subject: [PATCH 13/45] enable-tls add IP in san.cnf --- content/influxdb/v2/admin/security/enable-tls.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/influxdb/v2/admin/security/enable-tls.md b/content/influxdb/v2/admin/security/enable-tls.md index e633d3405a..1e0ffefaf4 100644 --- a/content/influxdb/v2/admin/security/enable-tls.md +++ b/content/influxdb/v2/admin/security/enable-tls.md @@ -116,6 +116,7 @@ cat > san.cnf < Date: Wed, 2 Oct 2024 12:24:11 +0200 Subject: [PATCH 14/45] enable-tls add chown of .crt and .key to influxdb user --- content/influxdb/v2/admin/security/enable-tls.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/influxdb/v2/admin/security/enable-tls.md b/content/influxdb/v2/admin/security/enable-tls.md index 1e0ffefaf4..8ee72dbc2a 100644 --- a/content/influxdb/v2/admin/security/enable-tls.md +++ b/content/influxdb/v2/admin/security/enable-tls.md @@ -151,11 +151,12 @@ The user running InfluxDB must have read permissions on the TLS certificate file Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate. {{% /note %}} -In your terminal, run `chmod` to set permissions on your installed certificate files--for example: -The following example shows how to set read permissions on the self-signed +In your terminal, run `chown` to set the owner and `chmod` to set permissions on your installed certificate files--for example: +The following example shows how to transfer the ownership to the user and group `influxdb` and to set read permissions on the self-signed certificate and key files generated in [the preceding step](#1-download-or-generate-certificate-files): ```bash +sudo chown influxdb: /etc/ssl/influxdb-selfsigned.crt /etc/ssl/influxdb-selfsigned.key sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt sudo chmod 600 /etc/ssl/influxdb-selfsigned.key ``` From 594017415fb755c1c2cb1ea74a87b7f41210a76a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Oct 2024 09:29:01 -0500 Subject: [PATCH 15/45] Update content/influxdb/v2/admin/security/enable-tls.md --- content/influxdb/v2/admin/security/enable-tls.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/influxdb/v2/admin/security/enable-tls.md b/content/influxdb/v2/admin/security/enable-tls.md index 8ee72dbc2a..9f740ef967 100644 --- a/content/influxdb/v2/admin/security/enable-tls.md +++ b/content/influxdb/v2/admin/security/enable-tls.md @@ -151,7 +151,8 @@ The user running InfluxDB must have read permissions on the TLS certificate file Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate. {{% /note %}} -In your terminal, run `chown` to set the owner and `chmod` to set permissions on your installed certificate files--for example: +In your terminal, run `chown` to set the owner and `chmod` to set permissions on your installed certificate files. + The following example shows how to transfer the ownership to the user and group `influxdb` and to set read permissions on the self-signed certificate and key files generated in [the preceding step](#1-download-or-generate-certificate-files): From 437e569ca7347925ad2dd1e22e11a5963c057519 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Oct 2024 09:29:36 -0500 Subject: [PATCH 16/45] Update content/influxdb/v2/admin/security/enable-tls.md --- content/influxdb/v2/admin/security/enable-tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/v2/admin/security/enable-tls.md b/content/influxdb/v2/admin/security/enable-tls.md index 9f740ef967..1fa90cdc76 100644 --- a/content/influxdb/v2/admin/security/enable-tls.md +++ b/content/influxdb/v2/admin/security/enable-tls.md @@ -153,7 +153,7 @@ Ultimately, make sure all users running InfluxDB have read permissions for the T In your terminal, run `chown` to set the owner and `chmod` to set permissions on your installed certificate files. -The following example shows how to transfer the ownership to the user and group `influxdb` and to set read permissions on the self-signed +The following example shows how to transfer the ownership to the user and group `influxdb` and set read permissions on the self-signed certificate and key files generated in [the preceding step](#1-download-or-generate-certificate-files): ```bash From c722780b520d41bbfc4a46918da466ba428eb6a0 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 1 Oct 2024 17:15:25 -0500 Subject: [PATCH 17/45] fix(v2): v1-compat 404 due to alias typo --- content/influxdb/v2/api-guide/influxdb-1x/_index.md | 2 +- content/influxdb/v2/reference/api/_index.md | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/content/influxdb/v2/api-guide/influxdb-1x/_index.md b/content/influxdb/v2/api-guide/influxdb-1x/_index.md index a97cb9d3f6..9aa3df46ac 100644 --- a/content/influxdb/v2/api-guide/influxdb-1x/_index.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/_index.md @@ -12,7 +12,7 @@ influxdb/v2/tags: [influxql, query, write] related: - /influxdb/v2/query-data/influxql - /influxdb/v2/install/upgrade/v1-to-v2/ -alias: +aliases: - /influxdb/v2/reference/api/influxdb-1x/ --- diff --git a/content/influxdb/v2/reference/api/_index.md b/content/influxdb/v2/reference/api/_index.md index cc060f5260..69ebe1c37b 100644 --- a/content/influxdb/v2/reference/api/_index.md +++ b/content/influxdb/v2/reference/api/_index.md @@ -12,6 +12,9 @@ weight: 3 influxdb/v2/tags: [api] aliases: - /influxdb/v2/concepts/api/ +related: + - /influxdb/v2/api-guide/api_intro/ + - /influxdb/v2/api-guide/influxdb-1x/ --- The InfluxDB HTTP API provides a programmatic interface for interactions such as writing and querying data, and managing resources in {{% product-name %}}. @@ -38,6 +41,6 @@ and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localh InfluxDB v1 API for {{% product-name %}} -The InfluxDB HTTP API includes [InfluxDB v1 compatibility endpoints](/influxdb/v2/reference/api/influxdb-1x/) +The InfluxDB HTTP API includes InfluxDB v1 compatibility endpoints that work with InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. From 0db99c4c52227dac960d97fa82f86959a8a3251a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Oct 2024 11:00:29 -0500 Subject: [PATCH 18/45] fix(v2): add IP address info to TLS config and troubleshooting explanation (closes #5630) --- .../influxdb/v2/admin/security/enable-tls.md | 70 +++++++++++++------ 1 file changed, 50 insertions(+), 20 deletions(-) diff --git a/content/influxdb/v2/admin/security/enable-tls.md b/content/influxdb/v2/admin/security/enable-tls.md index 1fa90cdc76..9bf2603b39 100644 --- a/content/influxdb/v2/admin/security/enable-tls.md +++ b/content/influxdb/v2/admin/security/enable-tls.md @@ -15,15 +15,11 @@ aliases: Enabling TLS encrypts the communication between clients and the InfluxDB server. When configured with a signed certificate, TLS also allows clients to verify the authenticity of the InfluxDB server. -To set up TLS over HTTPS, do the following: +Follow steps to set up TLS over HTTPS, connect to your server, and troubleshoot problems: - [Obtain requirements](#obtain-requirements) - - [Single domain certificates signed by a Certificate Authority (CA)](#single-domain-certificates-signed-by-a-certificate-authority-ca) - - [Wildcard certificates signed by a Certificate Authority](#wildcard-certificates-signed-by-a-certificate-authority) - - [Self-signed certificates](#self-signed-certificates) - [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls) - [Connect Telegraf to a secured InfluxDB instance](#connect-telegraf-to-a-secured-influxdb-instance) - - [Example Telegraf configuration](#example-telegraf-configuration) - [Troubleshoot TLS](#troubleshoot-tls) {{% warn %}} @@ -59,12 +55,19 @@ You can generate a self-signed certificate on your own machine. ## Configure InfluxDB to use TLS -1. [Download or generate certificate files](#1-download-or-generate-certificate-files) -2. [Set certificate file permissions](#2-set-certificate-file-permissions) -3. [Run `influxd` with TLS flags](#3-run-influxd-with-tls-flags) -4. [Verify TLS connection](#4-verify-tls-connection) +1. [Download or generate certificate files](download-or-generate-certificate-files) +2. [Set certificate file permissions](#set-certificate-file-permissions) +3. [Run `influxd` with TLS flags](#run-influxd-with-tls-flags) +4. [Verify TLS connection](#verify-tls-connection) -### 1. Download or generate certificate files +### Download or generate certificate files + +Choose one of the following: + +- [Download and install CA certificate files](#download-and-install-ca-certificate-files) +- [Generate self-signed certificates](#generate-and-self-signed-certificates) + +#### Download and install CA certificate files If using a [certificate signed by a CA](#single-domain-certificates-signed-by-a-certificate-authority-ca), follow their instructions to download and install the certificate files. Note the location where certificate files are installed, and then continue to [set certificate file permissions](#set-certificate-file-permissions). @@ -78,10 +81,16 @@ For example, if [Let's Encrypt](https://letsencrypt.org/) is your CA and you use `/etc/letsencrypt/live/$domain`. For more information about Let's Encrypt certificate paths, see [Where are my certificates?](https://eff-certbot.readthedocs.io/en/latest/using.html#where-are-my-certificates) {{% /note %}} +#### Generate self-signed certificates + To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system. -The following example shows how to generate certificates located in `/etc/ssl` -on Unix-like systems and Windows. +The following example: + +1. Configures [Subject Alternative Name](https://docs.openssl.org/master/man5/x509v3_config/#subject-alternative-name) (`subjectAltName`, SAN) + for your TLS certificate. +2. Generates certificates located in `/etc/ssl` for Unix-like and Windows systems. + _For example purposes only, the code creates an unencrypted private key._ {{% warn %}} @@ -139,11 +148,22 @@ rm san.cnf Replace the following with your own values: -- {{% code-placeholder-key %}}`NUMBER_OF_DAYS`{{% /code-placeholder-key %}}: the number of days for files to remain valid -- {{% code-placeholder-key %}}`/etc/ssl`{{% /code-placeholder-key %}}: the SSL configurations directory for your system -- Configuration field values in `req_distinguished_name` and `alt_names` +- {{% code-placeholder-key %}}`NUMBER_OF_DAYS`{{% /code-placeholder-key %}}: + the number of days for files to remain valid +- {{% code-placeholder-key %}}`/etc/ssl`{{% /code-placeholder-key %}}: the SSL + configurations directory for your system +- Configuration field values in `req_distinguished_name` and `alt_names`--for + example, in the `[alt_names]` section, set the domain names and IP addresses + you use to access your InfluxDB server. -### 2. Set certificate file permissions +The output is a private key and a CSR that includes the +specified domain names and IP address in the +[Subject Alternative Name](https://docs.openssl.org/master/man5/x509v3_config/#subject-alternative-name) +SAN extension. +The resulting certificate is valid for `example.com`, `www.example.com`, and +the IP address `10.1.2.3`. + +### Set certificate file permissions The user running InfluxDB must have read permissions on the TLS certificate files. @@ -154,7 +174,7 @@ Ultimately, make sure all users running InfluxDB have read permissions for the T In your terminal, run `chown` to set the owner and `chmod` to set permissions on your installed certificate files. The following example shows how to transfer the ownership to the user and group `influxdb` and set read permissions on the self-signed -certificate and key files generated in [the preceding step](#1-download-or-generate-certificate-files): +certificate and key files generated in [the preceding step](#download-or-generate-certificate-files): ```bash sudo chown influxdb: /etc/ssl/influxdb-selfsigned.crt /etc/ssl/influxdb-selfsigned.key @@ -162,7 +182,7 @@ sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt sudo chmod 600 /etc/ssl/influxdb-selfsigned.key ``` -### 3. Verify certificate and key files +### Verify certificate and key files To ensure that the certificate and key files are correct and match each other, enter the following commands in your terminal: @@ -172,7 +192,7 @@ openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5 openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5 ``` -### 4. Run `influxd` with TLS flags +### Run `influxd` with TLS flags To start InfluxDB with TLS command line flags, enter the following command with paths to your key and certificate files: @@ -185,7 +205,7 @@ influxd \ If successful, InfluxDB runs in the background and logs to `influxdb.log`. -### 4. Verify TLS connection +### Verify TLS connection To test your certificates, access InfluxDB using the `https://` protocol--for example, using cURL: @@ -316,6 +336,16 @@ Ensure that the TLS configuration in InfluxDB is correct. Check the paths to the certificate and key files in the InfluxDB configuration or command line flags. +#### Example error: cannot validate certificate for + +```log +Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055617Z lvl=error msg="Unable to gather" log_id=0rr6jG30000 service=scraper scraper-name="new target" error="Get \"https://10.1.2.3:8086/metrics\": tls: failed to verify certificate: x509: cannot validate certificate for 10.1.2.3 because it doesn't contain any IP SANs" +Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055397Z lvl=info msg="http: TLS handshake error from 10.1.2.3:46380: remote error: tls: bad certificate" log_id=0rr6jG30000 service=http +``` + +If you access your InfluxDB server via IP address, then include the address in +your subjectAltName configuration. + ### Update OpenSSL and InfluxDB Ensure that you are using the latest versions of OpenSSL and InfluxDB, as From b671f13be4f7b652cc87ccf3e6ee103f315f9268 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 26 Sep 2024 13:57:44 -0500 Subject: [PATCH 19/45] fix(influxdb): npm -y expects an existing template - Closes #5619 - Update example to first create the directory and then init the package inside the directory. - Explain the -y flag and apply to other examples. - Fix typescript examples. --- .../v2/javascript/nodejs/install.md | 18 ++++++--- .../v2/javascript/nodejs/install.md | 20 +++++++--- .../v2/javascript/nodejs/install.md | 18 ++++++--- .../client-libraries/nodejs/install.md | 40 ++++++++++++++----- 4 files changed, 69 insertions(+), 27 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md index 8026aa552d..97d5438fa1 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md @@ -33,11 +33,13 @@ prepend: 3. In your terminal, create a directory for your Node.js project and change to it. ```sh - mkdir influx-node-app && cd $_ + mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. - The `npm` package manager is included with Node.js. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts ```sh npm init -y @@ -53,15 +55,21 @@ Follow these steps to initialize the TypeScript project: ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md index 968529dbf5..a5874dc3f0 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md @@ -35,11 +35,13 @@ Install the Node.js JavaScript client library to write data to InfluxDB {{% prod 3. In your terminal, create a directory for your Node.js project and change to it. ```sh - mkdir influx-node-app && cd $_ + mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. - The `npm` package manager is included with Node.js. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts ```sh npm init -y @@ -55,15 +57,21 @@ Follow these steps to initialize the TypeScript project: ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies @@ -84,7 +92,7 @@ It only works with InfluxDB v2 management APIs. The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.js) module for accessing your InfluxDB properties from environment variables or from `env.js`. The examples use these properties to interact with the InfluxDB API. -Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), [token](/influxdb/cloud-serverless/security/tokens/), and [url](/influxdb/cloud-serverless/reference/urls/). +Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), [token](/influxdb/cloud-serverless/security/tokens/), and [URL](/influxdb/cloud-serverless/reference/urls/). ```sh export INFLUX_URL=https://{{< influxdb/host >}} diff --git a/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md index a50e10d4ed..8e779acf2a 100644 --- a/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md @@ -33,11 +33,13 @@ prepend: 3. In your terminal, create a directory for your Node.js project and change to it. ```sh - mkdir influx-node-app && cd $_ + mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. - The `npm` package manager is included with Node.js. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts ```sh npm init -y @@ -53,15 +55,21 @@ Follow these steps to initialize the TypeScript project: ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies diff --git a/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md b/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md index cebfe2a986..4d7fd0e7f2 100644 --- a/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md +++ b/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md @@ -21,31 +21,47 @@ aliases: 2. Ensure that InfluxDB is running and you can connect to it. For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2/reference/urls/). -3. Start a new Node.js project. - The `npm` package manager is included with Node.js. +3. Create a directory for your new Node.js project, and then change to the + directory--for example, enter the following command into your terminal: - ```sh - npm init -y influx-node-app - ``` + ```sh + mkdir influx-node-app && cd influx-node-app + ``` + +4. Enter the following command to generate an npm package for your project. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts + + ```sh + npm init -y + ``` ## Install TypeScript -Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). Follow these steps to initialize the TypeScript project. +Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). +Follow these steps to initialize the TypeScript project: 1. Install TypeScript and type definitions for Node.js. ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies @@ -76,7 +92,7 @@ The client examples include an [`env`](https://github.com/influxdata/influxdb-cl The examples use these properties to interact with the InfluxDB API. {{% /note %}} -1. Set environment variables or update `env.mjs` with your InfluxDB [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), [token](/influxdb/v2/admin/tokens/), and [url](/influxdb/v2/reference/urls/). +1. Set environment variables or update `env.mjs` with your InfluxDB [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), [token](/influxdb/v2/admin/tokens/), and [URL](/influxdb/v2/reference/urls/). ```sh export INFLUX_URL=http://localhost:8086 @@ -89,7 +105,9 @@ The examples use these properties to interact with the InfluxDB API. - *`YOUR_ORG`*: InfluxDB organization ID - *`YOUR_BUCKET`*: InfluxDB bucket name -2. Run an example script. +2. Run one of the [`influxdb-client-js` example scripts](https://github.com/influxdata/influxdb-client-js/tree/master/examples/). + + ```sh query.ts From 253bc79c248e4a8fed8643e07e84fb9e9716ed7d Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 3 Oct 2024 12:38:38 -0500 Subject: [PATCH 20/45] fix(v2): remove dead native mqtt shortcut --- content/influxdb/v2/write-data/no-code/load-data.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/influxdb/v2/write-data/no-code/load-data.md b/content/influxdb/v2/write-data/no-code/load-data.md index df2c213a34..de82ee930b 100644 --- a/content/influxdb/v2/write-data/no-code/load-data.md +++ b/content/influxdb/v2/write-data/no-code/load-data.md @@ -17,7 +17,6 @@ Load data from the following sources in the InfluxDB user interface (UI): - [Line protocol](#load-data-using-line-protocol) - [Client libraries](#load-data-from-a-client-library-in-the-ui) - [Telegraf plugins](#load-data-from-a-telegraf-plugin-in-the-ui) -- {{% cloud-only %}}[Native MQTT subscriptions](#set-up-a-native-mqtt-subscription){{% /cloud-only %}} ### Load CSV or line protocol in UI From e78d28f16a9dc71717171c06b8c34b4133002353 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 3 Oct 2024 14:01:33 -0500 Subject: [PATCH 21/45] chore(v2): provide additional information about the output plugin. - Closes #4244, which seems to have been addressed by settings and comments in the output plugin configuration. - This commit just adds some context about the output plugin. --- .../influxdb/v2/write-data/no-code/load-data.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/content/influxdb/v2/write-data/no-code/load-data.md b/content/influxdb/v2/write-data/no-code/load-data.md index de82ee930b..07e795df2e 100644 --- a/content/influxdb/v2/write-data/no-code/load-data.md +++ b/content/influxdb/v2/write-data/no-code/load-data.md @@ -75,11 +75,16 @@ Load CSV or line protocol data by uploading a file or pasting the data manually - **Create a new configuration**: Enter a configuration name and select an output bucket, and then click **Continue Configuring**. - **Add to an existing configuration**: Select an existing Telegraf configuration to add this plugin to, and then click **Add to Existing Config**. 5. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. -6. Adjust configuration settings as needed. To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). -7. Click **Save and Test**. -8. The **Test Your Configuration** page provides instructions for how to start +6. Adjust configuration settings as needed. + The configuration includes settings for the [InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2) to write to your bucket. + To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). +7. Click **Save and Test**. Your input plugin configuration is appended to the default agent settings and the InfluxDB output plugin configuration. +8. The **Test Your Configuration** page provides instructions for how to start Telegraf using the generated configuration. _See [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf) below for detailed information about what each step does._ -9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. +9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. Once confirmed, a **Connection Found!** message appears. -10. Click **Finish**. Your Telegraf configuration name and the associated bucket name appear in the list of Telegraf configurations. +10. Click **Finish**. + Your Telegraf configuration name and the associated bucket name appear in the list of Telegraf configurations. +11. To view or edit the configuration, click the configuration name. +12. To view default settings used to write data to InfluxDB, click **InfluxDB Output Plugin**. From 5a63f3f7b1bc1c6521c4d77da12c1a999c9ef3e8 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 3 Oct 2024 16:18:34 -0500 Subject: [PATCH 22/45] fix(v1,v2): bad aliases causing 404s - Cleanup use of alias singular - Fix lint error Closes #5632 --- content/chronograf/v1/administration/managing-security.md | 3 ++- content/enterprise_influxdb/v1/guides/query_data.md | 3 +-- content/influxdb/cloud/api-guide/influxdb-1x/_index.md | 2 +- content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md | 2 +- content/influxdb/cloud/api-guide/influxdb-1x/query.md | 2 +- content/influxdb/cloud/api-guide/influxdb-1x/write.md | 2 +- content/influxdb/cloud/write-data/bulk-ingest-cloud.md | 4 ++-- content/influxdb/v1/about_the_project/_index.md | 4 ++-- content/influxdb/v1/guides/query_data.md | 2 +- content/influxdb/v2/api-guide/influxdb-1x/dbrp.md | 2 +- content/influxdb/v2/api-guide/influxdb-1x/query.md | 2 +- content/influxdb/v2/api-guide/influxdb-1x/write.md | 2 +- content/influxdb/v2/query-data/flux/_index.md | 2 +- content/platform/install-and-deploy/install/oss-install.md | 3 ++- 14 files changed, 18 insertions(+), 17 deletions(-) diff --git a/content/chronograf/v1/administration/managing-security.md b/content/chronograf/v1/administration/managing-security.md index 72900b77b3..b3d694b995 100644 --- a/content/chronograf/v1/administration/managing-security.md +++ b/content/chronograf/v1/administration/managing-security.md @@ -1,7 +1,8 @@ --- title: Manage Chronograf security description: Manage Chronograf security with OAuth 2.0 providers. -aliases: /chronograf/v1/administration/security-best-practices/ +aliases: + - /chronograf/v1/administration/security-best-practices/ menu: chronograf_v1: name: Manage Chronograf security diff --git a/content/enterprise_influxdb/v1/guides/query_data.md b/content/enterprise_influxdb/v1/guides/query_data.md index 25585a4acd..65adedbda0 100644 --- a/content/enterprise_influxdb/v1/guides/query_data.md +++ b/content/enterprise_influxdb/v1/guides/query_data.md @@ -1,14 +1,13 @@ --- title: Query data with the InfluxDB API description: Query data with Flux and InfluxQL in the InfluxDB API. -alias: - -/docs/v1.8/query_language/querying_data/ menu: enterprise_influxdb_v1: weight: 20 parent: Guides aliases: - /enterprise_influxdb/v1/guides/querying_data/ + - /docs/v1.8/query_language/querying_data/ v2: /influxdb/v2/query-data/ --- diff --git a/content/influxdb/cloud/api-guide/influxdb-1x/_index.md b/content/influxdb/cloud/api-guide/influxdb-1x/_index.md index e720ec2422..cdc3b5ea4d 100644 --- a/content/influxdb/cloud/api-guide/influxdb-1x/_index.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/_index.md @@ -11,7 +11,7 @@ weight: 104 influxdb/cloud/tags: [influxql, query, write] related: - /influxdb/cloud/query-data/influxql -alias: +aliases: - /influxdb/cloud/reference/api/influxdb-1x/ --- diff --git a/content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md b/content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md index af1322c197..4c4645107b 100644 --- a/content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md @@ -13,7 +13,7 @@ related: - /influxdb/cloud/reference/api/influxdb-1x/write - /influxdb/cloud/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint - /influxdb/cloud/query-data/influxql/ -alias: +aliases: - /influxdb/cloud/reference/api/influxdb-1x/dbrp/ --- diff --git a/content/influxdb/cloud/api-guide/influxdb-1x/query.md b/content/influxdb/cloud/api-guide/influxdb-1x/query.md index 4676c6e99c..284c740723 100644 --- a/content/influxdb/cloud/api-guide/influxdb-1x/query.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/query.md @@ -15,7 +15,7 @@ list_code_example: | related: - /influxdb/cloud/query-data/influxql -alias: +aliases: - /influxdb/cloud/reference/api/influxdb-1x/query/ --- diff --git a/content/influxdb/cloud/api-guide/influxdb-1x/write.md b/content/influxdb/cloud/api-guide/influxdb-1x/write.md index 53845b0aad..871b510172 100644 --- a/content/influxdb/cloud/api-guide/influxdb-1x/write.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/write.md @@ -16,7 +16,7 @@ list_code_example: | related: - /influxdb/cloud/reference/syntax/line-protocol -alias: +aliases: - /influxdb/cloud/reference/api/influxdb-1x/write/ --- diff --git a/content/influxdb/cloud/write-data/bulk-ingest-cloud.md b/content/influxdb/cloud/write-data/bulk-ingest-cloud.md index a3743e7bc5..7d71f099b6 100644 --- a/content/influxdb/cloud/write-data/bulk-ingest-cloud.md +++ b/content/influxdb/cloud/write-data/bulk-ingest-cloud.md @@ -9,11 +9,11 @@ menu: influxdb_cloud: name: Bulk ingest historical data parent: Write data -alias: +aliases: - /influxdb/v2/write-data/bulk-ingest-cloud --- -To upload a large amount **(10GB or greater)** of previously existing *historical* +To upload a large amount **(10 GB or greater)** of previously existing *historical* data into InfluxDB Cloud, contact [InfluxData Support](https://support.influxdata.com/) for assistance. We’ll review your ingest rate limits, volume, and existing [data schema](/influxdb/cloud/reference/key-concepts/data-schema) to ensure the diff --git a/content/influxdb/v1/about_the_project/_index.md b/content/influxdb/v1/about_the_project/_index.md index b237231135..87d4629d45 100644 --- a/content/influxdb/v1/about_the_project/_index.md +++ b/content/influxdb/v1/about_the_project/_index.md @@ -2,8 +2,8 @@ title: About InfluxDB OSS description: > Release notes, licenses, contribution guidelines, and third-party software details for InfluxDB. -alias: - -/docs/v1.8/about/ +aliases: + - /docs/v1.8/about/ menu: influxdb_v1: name: About the project diff --git a/content/influxdb/v1/guides/query_data.md b/content/influxdb/v1/guides/query_data.md index b60adb5bc0..3046d0c937 100644 --- a/content/influxdb/v1/guides/query_data.md +++ b/content/influxdb/v1/guides/query_data.md @@ -1,7 +1,7 @@ --- title: Query data with the InfluxDB API description: Query data with Flux and InfluxQL in the InfluxDB API. -alias: +aliases: -/docs/v1.8/query_language/querying_data/ menu: influxdb_v1: diff --git a/content/influxdb/v2/api-guide/influxdb-1x/dbrp.md b/content/influxdb/v2/api-guide/influxdb-1x/dbrp.md index bea0b732f1..86a0136b38 100644 --- a/content/influxdb/v2/api-guide/influxdb-1x/dbrp.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/dbrp.md @@ -13,7 +13,7 @@ related: - /influxdb/v2/reference/api/influxdb-1x/write - /influxdb/v2/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint - /influxdb/v2/query-data/influxql/ -alias: +aliases: - /influxdb/v2/reference/api/influxdb-1x/dbrp/ --- diff --git a/content/influxdb/v2/api-guide/influxdb-1x/query.md b/content/influxdb/v2/api-guide/influxdb-1x/query.md index caed8965b1..5c8b30e2dd 100644 --- a/content/influxdb/v2/api-guide/influxdb-1x/query.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/query.md @@ -15,7 +15,7 @@ list_code_example: | related: - /influxdb/v2/query-data/influxql -alias: +aliases: - /influxdb/v2/reference/api/influxdb-1x/query/ --- diff --git a/content/influxdb/v2/api-guide/influxdb-1x/write.md b/content/influxdb/v2/api-guide/influxdb-1x/write.md index e443f4aa35..eb9df477ff 100644 --- a/content/influxdb/v2/api-guide/influxdb-1x/write.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/write.md @@ -16,7 +16,7 @@ list_code_example: | related: - /influxdb/v2/reference/syntax/line-protocol -alias: +aliases: - /influxdb/v2/reference/api/influxdb-1x/write/ --- diff --git a/content/influxdb/v2/query-data/flux/_index.md b/content/influxdb/v2/query-data/flux/_index.md index 6d98e91bfc..8fd735b156 100644 --- a/content/influxdb/v2/query-data/flux/_index.md +++ b/content/influxdb/v2/query-data/flux/_index.md @@ -7,7 +7,7 @@ menu: influxdb_v2: name: Query with Flux parent: Query data -alias: +aliases: - /influxdb/v2/query-data/guides/ --- diff --git a/content/platform/install-and-deploy/install/oss-install.md b/content/platform/install-and-deploy/install/oss-install.md index 485031117b..e4bc6808f2 100644 --- a/content/platform/install-and-deploy/install/oss-install.md +++ b/content/platform/install-and-deploy/install/oss-install.md @@ -2,7 +2,8 @@ title: Install the InfluxData 1.x TICK stack (OSS) list_title: TICK stack (OSS) description: Install and configure the open source InfluxData 1.x TICK stack – Telegraf, InfluxDB, Chronograf, and Kapacitor. -alias: /platform/installation/oss-install +aliases: + - /platform/installation/oss-install menu: platform: name: TICK stack (OSS) From 3ed8509fe20e1396fc0bf248caf8694a0121dfd4 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 3 Oct 2024 16:21:09 -0500 Subject: [PATCH 23/45] fix(link): Closes #5623 --- content/influxdb/v2/reference/internals/data-retention.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/v2/reference/internals/data-retention.md b/content/influxdb/v2/reference/internals/data-retention.md index 28dbd1e39e..911b592e96 100644 --- a/content/influxdb/v2/reference/internals/data-retention.md +++ b/content/influxdb/v2/reference/internals/data-retention.md @@ -32,7 +32,7 @@ configuration option. - [When does data actually get deleted?](#when-does-data-actually-get-deleted) ## Bucket retention period -A **bucket retention period** is the [duration](/influxdb/v2/glossary/#duration) of time that a bucket retains data. +A **bucket retention period** is the [duration](/influxdb/v2/reference/glossary/#duration) of time that a bucket retains data. Retention periods can be infinite or as short as an hour. [Points](/influxdb/v2/reference/glossary/#point) in a bucket with timestamps beyond the defined retention period (relative to now) are _eligible_ for deletion. From 1ee16ae7943beb4748e0608af032f16576242a65 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 3 Oct 2024 16:25:43 -0500 Subject: [PATCH 24/45] fix(link): Closes #5609 --- .../query-data/troubleshoot-and-optimize/optimize-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md index c4856774ab..9b7c00e2cd 100644 --- a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -86,7 +86,7 @@ less efficient. Use the following tools to analyze and troubleshoot queries and find performance bottlenecks: -- [Analyze a query plan](/influxdb/cloud-serverless/query-data/analyze-query-plan/) +- [Analyze a query plan](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan/) - [Enable trace logging for a query](#enable-trace-logging-for-a-query) ### Enable trace logging for a query From 7a37e3993c0a48e1d0fa29dbf903d3496cb65165 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 3 Oct 2024 16:38:09 -0500 Subject: [PATCH 25/45] fix(link): Broken link in Chronograph Getting Started pane (Closes #5311 - I'm not sure this is a direct replacement, but it's the best fit I could find. --- .../v1/troubleshooting/frequently-asked-questions.md | 2 ++ content/enterprise_influxdb/v1/concepts/glossary.md | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/content/chronograf/v1/troubleshooting/frequently-asked-questions.md b/content/chronograf/v1/troubleshooting/frequently-asked-questions.md index d141303e4e..343bd62de3 100644 --- a/content/chronograf/v1/troubleshooting/frequently-asked-questions.md +++ b/content/chronograf/v1/troubleshooting/frequently-asked-questions.md @@ -6,6 +6,8 @@ menu: name: Frequently asked questions (FAQs) weight: 10 parent: Troubleshoot +aliases: + - /chronograf/latest/guides/transition-web-admin-interface/ --- ## How do I connect Chronograf to an InfluxDB Enterprise cluster? diff --git a/content/enterprise_influxdb/v1/concepts/glossary.md b/content/enterprise_influxdb/v1/concepts/glossary.md index dfa681991e..6cc1fb5a11 100644 --- a/content/enterprise_influxdb/v1/concepts/glossary.md +++ b/content/enterprise_influxdb/v1/concepts/glossary.md @@ -449,8 +449,8 @@ Related entries: [tsm](#tsm-time-structured-merge-tree) ## web console -Legacy user interface for the InfluxDB Enterprise. +Legacy user interface for InfluxDB Enterprise. This interface has been deprecated. We recommend using [Chronograf](/chronograf/v1/introduction/). -If you are transitioning from the Enterprise Web Console to Chronograf, see how to [transition from the InfluxDB Web Admin Interface](/chronograf/v1/guides/transition-web-admin-interface/). +If you are transitioning from the Enterprise Web Console to Chronograf, see how to [connect Chronograf to an InfluxDB Enterprise cluster](/chronograf/v1/troubleshooting/frequently-asked-questions/#how-do-i-connect-chronograf-to-an-influxdb-enterprise-cluster). From c8b977790a5e6218f2913b53cb1d52e7a821213c Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 4 Oct 2024 14:02:30 -0600 Subject: [PATCH 26/45] Note removal of Flux MQTT package support OSS 2.7+ (#5634) * WIP added prepend to mqtt package frontmatter * WIP excluded mqtt package from oss 2.7+ * WIP add nightly version exclude * add nightly exclude to flux function support modal, closes influxdata/DAR#437 * updated mqtt warn message and version exclude pattern * Apply suggestions from code review Co-authored-by: Jason Stirnaman * exclude mqtt package from all oss versions * exclude mqtt package from everything but cloud --------- Co-authored-by: Jason Stirnaman --- data/flux_stdlib_frontmatter.yml | 38 +++++++++++++++++++ .../footer/modals/flux-influxdb-versions.html | 3 +- 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/data/flux_stdlib_frontmatter.yml b/data/flux_stdlib_frontmatter.yml index 200c2e5453..4b92702e44 100644 --- a/data/flux_stdlib_frontmatter.yml +++ b/data/flux_stdlib_frontmatter.yml @@ -920,11 +920,49 @@ aliases: - /influxdb/v2/reference/flux/stdlib/experimental/mqtt/ - /influxdb/cloud/reference/flux/stdlib/experimental/mqtt/ + prepend: + block: warn + content: | + #### Only supported in InfluxDB Cloud (TSM) + + The `experimental/mqtt` package only supported in InfluxDB Cloud (TSM). + It is still available to import in InfluxDB OSS and Enterprise, but + functions will not successfully publish to an MQTT broker. + exclude_from: + nightly: true + oss: ^* + enterprise: ^* /flux/v0/stdlib/experimental/mqtt/to.md: | aliases: - /influxdb/v2/reference/flux/stdlib/experimental/mqtt/to/ - /influxdb/cloud/reference/flux/stdlib/experimental/mqtt/to/ + prepend: + block: warn + content: | + #### Only supported in InfluxDB Cloud (TSM) + + The `experimental/mqtt` package only supported in InfluxDB Cloud (TSM). + It is still available to import in InfluxDB OSS and Enterprise, but + functions will not successfully publish to an MQTT broker. + exclude_from: + nightly: true + oss: ^* + enterprise: ^* + +/flux/v0/stdlib/experimental/mqtt/publish.md: | + prepend: + block: warn + content: | + #### Only supported in InfluxDB Cloud (TSM) + + The `experimental/mqtt` package only supported in InfluxDB Cloud (TSM). + It is still available to import in InfluxDB OSS and Enterprise, but + functions will not successfully publish to an MQTT broker. + exclude_from: + nightly: true + oss: ^* + enterprise: ^* /flux/v0/stdlib/experimental/oee/_index.md: | aliases: diff --git a/layouts/partials/footer/modals/flux-influxdb-versions.html b/layouts/partials/footer/modals/flux-influxdb-versions.html index 722bfd019b..cc69dd83a5 100644 --- a/layouts/partials/footer/modals/flux-influxdb-versions.html +++ b/layouts/partials/footer/modals/flux-influxdb-versions.html @@ -45,7 +45,8 @@

InfluxDB Open Source (OSS)

{{ $versionSemVer := split $value "." }} {{ $supported := cond (ge (index $versionSemVer 0) (index $introducedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $introducedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $introducedSemVer 2)) true false) false) false }} {{ $deprecated := and (isset $.Page.Params "deprecated") (cond (ge (index $versionSemVer 0) (index $deprecatedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $deprecatedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $deprecatedSemVer 2)) true false) false) false) }} - {{ $excluded := gt (len (findRE (string $excludePatternOSS) $key)) 0 }} + {{ $nightlyExcluded := and (eq $key "nightly") $.Page.Params.exclude_from.nightly }} + {{ $excluded := or (gt (len (findRE (string $excludePatternOSS) $key)) 0) $nightlyExcluded }}

InfluxDB {{ $key }}

From 5c016e2a2346ad7c77163b99c280db50fcd11b99 Mon Sep 17 00:00:00 2001 From: David Rusnak <106361125+david-rusnak@users.noreply.github.com> Date: Wed, 9 Oct 2024 19:11:17 -0400 Subject: [PATCH 27/45] docs: add other required fields to user setup for clustered (#5639) --- content/influxdb/clustered/admin/users/add.md | 28 ++++++++++++++++--- .../install/configure-cluster/directly.md | 14 ++++++++-- .../install/configure-cluster/use-helm.md | 14 ++++++++-- 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/content/influxdb/clustered/admin/users/add.md b/content/influxdb/clustered/admin/users/add.md index e4ed4859cd..04c92d9f98 100644 --- a/content/influxdb/clustered/admin/users/add.md +++ b/content/influxdb/clustered/admin/users/add.md @@ -119,7 +119,12 @@ spec: jwksEndpoint: |- https://AUTH0_HOST/.well-known/openid-configuration users: - - AUTH0_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -152,7 +157,12 @@ spec: jwksEndpoint: |- https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys users: - - AZURE_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Azure. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -249,7 +259,12 @@ admin: https://AUTH0_HOST/.well-known/openid-configuration # The list of users to grant access to Clustered via influxctl users: - - AUTH0_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -280,7 +295,12 @@ admin: https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys # The list of users to grant access to Clustered via influxctl users: - - AZURE_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Azure. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} diff --git a/content/influxdb/clustered/install/configure-cluster/directly.md b/content/influxdb/clustered/install/configure-cluster/directly.md index dc11b643d1..28630d24b5 100644 --- a/content/influxdb/clustered/install/configure-cluster/directly.md +++ b/content/influxdb/clustered/install/configure-cluster/directly.md @@ -747,7 +747,12 @@ spec: jwksEndpoint: |- https://AUTH0_HOST/.well-known/openid-configuration users: - - AUTH0_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -782,7 +787,12 @@ spec: jwksEndpoint: |- https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys users: - - AZURE_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Azure. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} diff --git a/content/influxdb/clustered/install/configure-cluster/use-helm.md b/content/influxdb/clustered/install/configure-cluster/use-helm.md index e85c4acb3a..7ecf852a81 100644 --- a/content/influxdb/clustered/install/configure-cluster/use-helm.md +++ b/content/influxdb/clustered/install/configure-cluster/use-helm.md @@ -764,7 +764,12 @@ admin: https://AUTH0_HOST/.well-known/openid-configuration # The list of users to grant access to Clustered via influxctl users: - - AUTH0_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -797,7 +802,12 @@ admin: https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys # The list of users to grant access to Clustered via influxctl users: - - AZURE_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Azure. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} From aafd2c9b39d01aaec2d6d4d5fe9b5963ca2ab2d7 Mon Sep 17 00:00:00 2001 From: Fraser Savage Date: Fri, 11 Oct 2024 15:25:26 +0100 Subject: [PATCH 28/45] fix(dedicated): Update links to database token management API reference Links what have been broke, have done unbroke. --- .../influxdb/cloud-dedicated/admin/tokens/database/create.md | 4 ++-- .../influxdb/cloud-dedicated/admin/tokens/database/delete.md | 2 +- .../influxdb/cloud-dedicated/admin/tokens/database/list.md | 2 +- .../influxdb/cloud-dedicated/admin/tokens/database/update.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md index 69d1cbf11d..a342611f48 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md @@ -50,7 +50,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) to create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster. +or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) to create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} {{% tabs %}} @@ -435,4 +435,4 @@ curl \ {{% /code-placeholders %}} {{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} \ No newline at end of file +{{< /code-tabs-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md b/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md index b4232c2621..416d86b44a 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md @@ -32,7 +32,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) +or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) to delete a database token from your {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/list.md b/content/influxdb/cloud-dedicated/admin/tokens/database/list.md index cfa05bf4a7..baa6f33b3f 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/list.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/list.md @@ -36,7 +36,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) +or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) to list database tokens in your {{< product-name omit=" Clustered" >}} cluster. [List database tokens](#list-database-tokens) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/update.md b/content/influxdb/cloud-dedicated/admin/tokens/database/update.md index c728685baa..2b63fe7db5 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/update.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/update.md @@ -53,7 +53,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) +or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) to update a database token's permissions {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} From 3b75f7fdb6ee258e507667ca778415dd458a6655 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Oct 2024 10:19:34 -0500 Subject: [PATCH 29/45] Update content/influxdb/cloud-dedicated/admin/tokens/database/create.md --- .../influxdb/cloud-dedicated/admin/tokens/database/create.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md index a342611f48..d0be6c137a 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md @@ -50,7 +50,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) to create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster. +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} {{% tabs %}} From 9cbc01024b9e3bf71b808d9ef7fc180147178a12 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Oct 2024 10:19:54 -0500 Subject: [PATCH 30/45] Update content/influxdb/cloud-dedicated/admin/tokens/database/list.md --- content/influxdb/cloud-dedicated/admin/tokens/database/list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/list.md b/content/influxdb/cloud-dedicated/admin/tokens/database/list.md index baa6f33b3f..aaecbb1fe9 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/list.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/list.md @@ -36,7 +36,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to list database tokens in your {{< product-name omit=" Clustered" >}} cluster. [List database tokens](#list-database-tokens) From f04a860f46cb31fee2cabb04547bb82777a82916 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Oct 2024 10:20:13 -0500 Subject: [PATCH 31/45] Update content/influxdb/cloud-dedicated/admin/tokens/database/delete.md --- .../influxdb/cloud-dedicated/admin/tokens/database/delete.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md b/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md index 416d86b44a..fce52f8158 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md @@ -32,7 +32,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to delete a database token from your {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} From 4d798b6dcf2517892e1d03aa9bf0bb636085162b Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Oct 2024 10:20:24 -0500 Subject: [PATCH 32/45] Update content/influxdb/cloud-dedicated/admin/tokens/database/update.md --- .../influxdb/cloud-dedicated/admin/tokens/database/update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/update.md b/content/influxdb/cloud-dedicated/admin/tokens/database/update.md index 2b63fe7db5..69abd75685 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/update.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/update.md @@ -53,7 +53,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/reference/api/management/) +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to update a database token's permissions {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} From cd1e0712bbb29bbe28cd997d479db9c83d5fa312 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 16 Oct 2024 13:20:39 -0500 Subject: [PATCH 33/45] fix: Misc. typos and style --- .ci/vale/styles/Google/Ordinal.yml | 6 ++++++ .../v1/administration/monitor/_index.md | 4 ++-- .../monitor/monitor-with-cloud.md | 2 +- .../admin/monitor-your-cluster.md | 20 +++++++++---------- .../cloud-dedicated/get-started/setup.md | 1 + 5 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.ci/vale/styles/Google/Ordinal.yml b/.ci/vale/styles/Google/Ordinal.yml index d1ac7d27e8..e777601ab8 100644 --- a/.ci/vale/styles/Google/Ordinal.yml +++ b/.ci/vale/styles/Google/Ordinal.yml @@ -5,3 +5,9 @@ level: error nonword: true tokens: - \d+(?:st|nd|rd|th) + - tenth + +exceptions: + - 0th + - 50th + - 90th diff --git a/content/enterprise_influxdb/v1/administration/monitor/_index.md b/content/enterprise_influxdb/v1/administration/monitor/_index.md index 970db3fc4b..a73e849078 100644 --- a/content/enterprise_influxdb/v1/administration/monitor/_index.md +++ b/content/enterprise_influxdb/v1/administration/monitor/_index.md @@ -12,7 +12,7 @@ Monitoring is the act of observing changes in data over time. There are multiple ways to monitor your InfluxDB Enterprise cluster. See the guides below to monitor a cluster using another InfluxDB instance. -Alternatively, to view your output data occasionally (_e.g._, for auditing or diagnostics), +Alternatively, to view your output data occasionally (for example, for auditing or diagnostics), do one of the following: - [Log and trace InfluxDB Enterprise operations](/enterprise_influxdb/v1/administration/monitor/logs/) @@ -22,7 +22,7 @@ do one of the following: ### Monitor with InfluxDB Insights For InfluxDB Enterprise customers, Insights is a free service that monitors your cluster and sends metrics to a private Cloud account. This allows InfluxDB Support to monitor your cluster health and access usage statistics when assisting with support tickets that you raise. -To apply for this service, please contact the [support team](https://support.influxdata.com/s/login/). +To apply for this service, please [contact InfluxData support](https://support.influxdata.com). {{% /note %}} {{< children >}} diff --git a/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md b/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md index 4b0984679f..cd1020b068 100644 --- a/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md +++ b/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md @@ -182,4 +182,4 @@ Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgradin For InfluxDB Enterprise customers, Insights is a free service that monitors your cluster and sends metrics to a private Cloud account. This allows InfluxDB Support to monitor your cluster health and access usage statistics when assisting with support tickets that you raise. -To apply for this service, please contact the [InfluxData Support team](mailto:support@influxdata.com). +To apply for this service, please [contact InfluxData support](https://support.influxdata.com). diff --git a/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md b/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md index 99c31c5e6b..7ca67867cd 100644 --- a/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md +++ b/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md @@ -10,9 +10,9 @@ menu: weight: 104 --- -InfluxData provides a Grafana operational dashboard that provide observability -into the your {{< product-name >}} cluster. Use the operational dashboard to -monitor your cluster. +InfluxData provides a Grafana operational dashboard that provides observability +into your {{< product-name >}} cluster. +Use the operational dashboard to monitor your cluster. {{% note %}} #### Not available for all clusters @@ -40,7 +40,7 @@ If you do not have login credentials, [contact InfluxData support](https://suppo ## Dashboard sections and cells -The dashboard is divided into the following sections that visualize metrics +The dashboard contains the following sections that visualize metrics related to the health of components in your {{< product-name >}} cluster: - [Query Tier Cpu/Mem](#query-tier-cpumem) @@ -156,7 +156,7 @@ to the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engi #### CPU Utilization Ingesters (k8s) -CPU Utilization of Ingester pods as reported by the Kubernetes container usage. +CPU utilization of Ingester pods as reported by the Kubernetes container usage. Usage is reported by the number of CPU cores used by pods, including fractional cores. The CPU limit is represented by the top line in the visualization. @@ -284,7 +284,7 @@ _These do not represent the most recent logs._ The **Compaction Tier Cpu/Mem** section displays the CPU and memory usage of Compactor pods as reported by Kubernetes. [Compactors](/influxdb/cloud-dedicated/reference/internals/storage-engine/#compactor) -process and compress parquet files in the +process and compress Parquet files in the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engine/#object-store) to continually optimize storage. @@ -330,10 +330,10 @@ following levels: Parquet files store data partitioned by time and optionally tags _(see [Manage data partition](https://docs.influxdata.com/influxdb/cloud-dedicated/admin/custom-partitions/))_. -After four L0 files accumulate for a partition, they are are eligible for compaction. +After four L0 files accumulate for a partition, they're eligible for compaction. If the compactor is keeping up with the incoming write load, all compaction -events will have exactly four files. If the number of L0 files compacted begins to -to increase, it indicates the compactor is not keeping up. +events have exactly four files. +An increase in the number of L0 files compacted indicates the compactor isn't keeping up. This histogram helps to determine if the Compactor is starting compactions as soon as it can. @@ -367,7 +367,7 @@ that the Catalog may be overloaded or unresponsive. #### Catalog Op Latency (P90) -The 90th percentile (P90) of query latency against the catalog service per operation. +The 90th percentile (P90) query latency for each operation against the catalog service. A high P90 value indicates that the Catalog may be overloaded. --- diff --git a/content/influxdb/cloud-dedicated/get-started/setup.md b/content/influxdb/cloud-dedicated/get-started/setup.md index dc9ecc8ddc..17c0591107 100644 --- a/content/influxdb/cloud-dedicated/get-started/setup.md +++ b/content/influxdb/cloud-dedicated/get-started/setup.md @@ -14,6 +14,7 @@ weight: 101 metadata: [1 / 3] related: - /influxdb/cloud-dedicated/admin/databases/ + - /influxdb/cloud-dedicated/admin/tokens/ - /influxdb/cloud-dedicated/reference/cli/influxctl/ - /influxdb/cloud-dedicated/reference/api/ --- From 0e62742901f70567080d6244d765bfdb9e1cbdca Mon Sep 17 00:00:00 2001 From: Dane Strandboge <136023093+DStrand1@users.noreply.github.com> Date: Wed, 16 Oct 2024 16:40:43 -0500 Subject: [PATCH 34/45] Release influxctl v2.9.8 (#5647) * Release influxctl v2.9.8 * add doc updates for influctl 2.9.7 and 2.9.8 (#5649) --------- Co-authored-by: Scott Anderson --- .../reference/cli/influxctl/_index.md | 26 ++++----- .../reference/release-notes/influxctl.md | 56 +++++++++++++++++- .../reference/cli/influxctl/_index.md | 26 ++++----- .../reference/release-notes/influxctl.md | 58 ++++++++++++++++++- data/products.yml | 2 +- 5 files changed, 136 insertions(+), 32 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md index 1aad420ea3..d5f69eb407 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md @@ -17,7 +17,7 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. - [Usage](#usage) - [Commands](#commands) -- [Flags](#command-flags) +- [Global flags](#global-flags) - [Download and install influxctl](#download-and-install-influxctl) - [Configure connection profiles](#configure-connection-profiles) - [Authentication](#authentication) @@ -25,14 +25,14 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. ## Usage ```sh -influxctl [flags] [command] +influxctl [global-flags] [command] ``` ## Commands | Command | Description | | :-------------------------------------------------------------------------- | :------------------------------------- | -| [auth](/influxdb/cloud-dedicated/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | +| [auth](/influxdb/cloud-dedicated/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | | [cluster](/influxdb/cloud-dedicated/reference/cli/influxctl/cluster/) | List InfluxDB v3 cluster information | | [database](/influxdb/cloud-dedicated/reference/cli/influxctl/database/) | Manage InfluxDB v3 databases | | [help](/influxdb/cloud-dedicated/reference/cli/influxctl/help/) | Output `influxctl` help information | @@ -45,15 +45,16 @@ influxctl [flags] [command] ## Global flags -| Flag | | Description | -| :--- | :---------- | :--------------------------------------------------------- | -| | `--debug` | Enable debug logging | -| | `--account` | Override account ID value in configuration file | -| | `--cluster` | Override cluster ID value in configuration file | -| | `--config` | Path to configuration file to use | -| | `--profile` | Specify a connection profile to use (default is `default`) | -| | `--trace` | Enable more verbose debug logging | -| `-h` | `--help` | Show help | +| Flag | | Description | +| :--- | :---------- | :----------------------------------------------------------- | +| | `--debug` | Enable debug logging | +| | `--account` | Override account ID value in configuration file | +| | `--cluster` | Override cluster ID value in configuration file | +| | `--config` | Path to configuration file to use | +| | `--profile` | Specify a connection profile to use (default is `default`) | +| | `--timeout` | Specify a timeout duration for API calls (default is `1m0s`) | +| | `--trace` | Enable more verbose debug logging | +| `-h` | `--help` | Show help | --- @@ -344,7 +345,6 @@ If stored at a non-default location, include the `--config` flag with each ## OAuth2 client authorization settings # [profile.auth.oauth2] # client_id = "" - # client_secret = "" # scopes = [""] # parameters = { audience = "" } # token_url = "https://indentityprovider/oauth2/v2/token" diff --git a/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md b/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md index 25c8ecadb9..06b540bdf9 100644 --- a/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md +++ b/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md @@ -11,12 +11,54 @@ menu: weight: 202 --- +## v2.9.8 {date="2024-10-15"} + +### Bug Fixes + +- Continue revoking tokens on error. +- Reject unsupported input to `--template-timeformat`. +- Remove unused `client_secret` option from + [connection configuration profiles](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles). + +### Dependency Updates + +- Update Go to v1.23.2. +- Update `github.com/jedib0t/go-pretty/v6` from 6.5.9 to 6.6.0. +- Update `github.com/urfave/cli/v2` from 2.27.4 to 2.27.5. +- Update `google.golang.org/grpc` from 1.66.0 to 1.67.1. +- Update `google.golang.org/protobuf` from 1.34.2 to 1.35.1. + +--- + +## v2.9.7 {date="2024-09-11"} + +### Features + +- Add [global `--timeout` flag](/influxdb/cloud-dedicated/reference/cli/influxctl/#global-flags). +- Improve timezone support. + +### Bug Fixes + +- Use passthrough resolver for gRPC. + +### Dependency Updates + +- Update Go to 1.23.1. +- Update `github.com/pelletier/go-toml/v2` from 2.2.2 to 2.2.3. +- Update `golang.org/x/mod` from 0.20.0 to 0.21.0. +- Update `golang.org/x/oauth2` from 0.22.0 to 0.23.0. +- Update `google.golang.org/grpc` from 1.65.0 to 1.66.0. + +--- + ## v2.9.6 {date="2024-08-15"} ### Bug Fixes - Update query to wait for EOF on stdin instead of the first newline. +--- + ## v2.9.5 {date="2024-08-13"} ### Bug Fixes @@ -29,6 +71,8 @@ weight: 202 - Update `golang.org/x/mod` from 0.19.0 to 0.20.0 - Update `golang.org/x/oauth2` from 0.21.0 to 0.22.0 +--- + ## v2.9.4 {date="2024-07-25"} ### Bug Fixes @@ -40,12 +84,16 @@ weight: 202 - Update `golang.org/x/mod` from 0.18.0 to 0.19.0 - Update `google.golang.org/grpc` from 1.64.0 to 1.65.0 +--- + ## v2.9.3 {date="2024-06-26"} ### Bug Fixes - Update query subcommand to safely handle null timestamp in response. +--- + ## v2.9.2 {date="2024-06-17"} ### Bug Fixes @@ -56,6 +104,8 @@ weight: 202 - Update `google.golang.org/protobuf` from 1.34.1 to 1.34.2. +--- + ## v2.9.1 {date="2024-06-06"} ### Dependency Updates @@ -69,6 +119,8 @@ weight: 202 - Update `google.golang.org/protobuf` from 1.34.0 to 1.34.1 - Update build dependencies. +--- + ## v2.9.0 {date="2024-05-06"} ### Features @@ -80,7 +132,7 @@ weight: 202 - Update unimplemented error message with additional information. -### Dependecy Updates +### Dependency Updates - Update `github.com/apache/arrow/go/v16` from 16.0.0-20240401180149-68241d8a86e9 to 16.0.0. - Update `github.com/jedib0t/go-pretty/v6` from 6.5.8 to 6.5.9. @@ -188,7 +240,7 @@ associated with another InfluxDB cluster. ### Bug Fixes -- Update arrow to allow non-TLS connections. +- Update Arrow to allow non-TLS connections. - Do not attempt to load cached tokens when an admin token file is provided. - Print retention period up to days rather than very large hours. - Fix indentation of help output. diff --git a/content/influxdb/clustered/reference/cli/influxctl/_index.md b/content/influxdb/clustered/reference/cli/influxctl/_index.md index a7c0bc8ee5..6fda5d1c03 100644 --- a/content/influxdb/clustered/reference/cli/influxctl/_index.md +++ b/content/influxdb/clustered/reference/cli/influxctl/_index.md @@ -17,7 +17,7 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. - [Usage](#usage) - [Commands](#commands) -- [Flags](#command-flags) +- [Global flags](#global-flags) - [Download and install influxctl](#download-and-install-influxctl) - [Configure connection profiles](#configure-connection-profiles) - [Authentication](#authentication) @@ -25,14 +25,14 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. ## Usage ```sh -influxctl [flags] [command] +influxctl [global-flags] [command] ``` ## Commands | Command | Description | | :-------------------------------------------------------------------- | :------------------------------------- | -| [auth](/influxdb/clustered/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | +| [auth](/influxdb/clustered/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | | [cluster](/influxdb/clustered/reference/cli/influxctl/cluster/) | List InfluxDB v3 cluster information | | [database](/influxdb/clustered/reference/cli/influxctl/database/) | Manage InfluxDB v3 databases | | [help](/influxdb/clustered/reference/cli/influxctl/help/) | Output `influxctl` help information | @@ -45,15 +45,16 @@ influxctl [flags] [command] ## Global flags -| Flag | | Description | -| :--- | :---------- | :--------------------------------------------------------- | -| | `--debug` | Enable debug logging | -| | `--account` | Override account ID value in configuration file | -| | `--cluster` | Override cluster ID value in configuration file | -| | `--config` | Path to configuration file to use | -| | `--profile` | Specify a connection profile to use (default is `default`) | -| | `--trace` | Enable more verbose debug logging | -| `-h` | `--help` | Show help | +| Flag | | Description | +| :--- | :---------- | :----------------------------------------------------------- | +| | `--debug` | Enable debug logging | +| | `--account` | Override account ID value in configuration file | +| | `--cluster` | Override cluster ID value in configuration file | +| | `--config` | Path to configuration file to use | +| | `--profile` | Specify a connection profile to use (default is `default`) | +| | `--timeout` | Specify a timeout duration for API calls (default is `1m0s`) | +| | `--trace` | Enable more verbose debug logging | +| `-h` | `--help` | Show help | --- @@ -354,7 +355,6 @@ If stored at a non-default location, include the `--config` flag with each ## OAuth2 client authorization settings [profile.auth.oauth2] client_id = "OAUTH_CLIENT_ID" - client_secret = "" scopes = [""] parameters = { audience = "" } token_url = "OAUTH_TOKEN_URL" diff --git a/content/influxdb/clustered/reference/release-notes/influxctl.md b/content/influxdb/clustered/reference/release-notes/influxctl.md index ca796a5327..4dd477b77e 100644 --- a/content/influxdb/clustered/reference/release-notes/influxctl.md +++ b/content/influxdb/clustered/reference/release-notes/influxctl.md @@ -12,11 +12,53 @@ weight: 202 canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ --- +## v2.9.8 {date="2024-10-15"} + +### Bug Fixes + +- Continue revoking tokens on error. +- Reject unsupported input to `--template-timeformat`. +- Remove unused `client_secret` option from + [connection configuration profiles](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles). + +### Dependency Updates + +- Update Go to v1.23.2. +- Update `github.com/jedib0t/go-pretty/v6` from 6.5.9 to 6.6.0. +- Update `github.com/urfave/cli/v2` from 2.27.4 to 2.27.5. +- Update `google.golang.org/grpc` from 1.66.0 to 1.67.1. +- Update `google.golang.org/protobuf` from 1.34.2 to 1.35.1. + +--- + +## v2.9.7 {date="2024-09-11"} + +### Features + +- Add [global `--timeout` flag](/influxdb/clustered/reference/cli/influxctl/#global-flags). +- Improve timezone support. + +### Bug Fixes + +- Use passthrough resolver for gRPC. + +### Dependency Updates + +- Update Go to 1.23.1. +- Update `github.com/pelletier/go-toml/v2` from 2.2.2 to 2.2.3. +- Update `golang.org/x/mod` from 0.20.0 to 0.21.0. +- Update `golang.org/x/oauth2` from 0.22.0 to 0.23.0. +- Update `google.golang.org/grpc` from 1.65.0 to 1.66.0. + +--- + ## v2.9.6 {date="2024-08-15"} ### Bug Fixes -- Update query subcommand to wait for EOF on stdin instead of the first newline. +- Update query to wait for EOF on stdin instead of the first newline. + +--- ## v2.9.5 {date="2024-08-13"} @@ -31,6 +73,8 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `golang.org/x/mod` from 0.19.0 to 0.20.0 - Update `golang.org/x/oauth2` from 0.21.0 to 0.22.0 +--- + ## v2.9.4 {date="2024-07-25"} ### Bug Fixes @@ -42,12 +86,16 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `golang.org/x/mod` from 0.18.0 to 0.19.0 - Update `google.golang.org/grpc` from 1.64.0 to 1.65.0 +--- + ## v2.9.3 {date="2024-06-26"} ### Bug Fixes - Update query subcommand to safely handle null timestamp in response. +--- + ## v2.9.2 {date="2024-06-17"} ### Bug Fixes @@ -58,6 +106,8 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `google.golang.org/protobuf` from 1.34.1 to 1.34.2. +--- + ## v2.9.1 {date="2024-06-06"} ### Dependency Updates @@ -71,6 +121,8 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `google.golang.org/protobuf` from 1.34.0 to 1.34.1 - Update build dependencies. +--- + ## v2.9.0 {date="2024-05-06"} ### Features @@ -82,7 +134,7 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update unimplemented error message with additional information. -### Dependecy Updates +### Dependency Updates - Update `github.com/apache/arrow/go/v16` from 16.0.0-20240401180149-68241d8a86e9 to 16.0.0. - Update `github.com/jedib0t/go-pretty/v6` from 6.5.8 to 6.5.9. @@ -197,7 +249,7 @@ associated with another InfluxDB cluster. ### Bug Fixes -- Update arrow to allow non-TLS connections. +- Update Arrow to allow non-TLS connections. - Do not attempt to load cached tokens when an admin token file is provided. - Print retention period up to days rather than very large hours. - Fix indentation of help output. diff --git a/data/products.yml b/data/products.yml index e855037218..b0b43207db 100644 --- a/data/products.yml +++ b/data/products.yml @@ -55,7 +55,7 @@ influxdb_cloud_dedicated: list_order: 3 latest: cloud-dedicated link: "https://www.influxdata.com/contact-sales-form/" - latest_cli: 2.9.7 + latest_cli: 2.9.8 placeholder_host: cluster-id.a.influxdb.io influxdb_clustered: From 138e99c322eb3e57e2a6bdbb23b9f6ccb3e5677e Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 17 Oct 2024 10:22:17 -0500 Subject: [PATCH 35/45] fix(v3): broken optimize-queries links, typos, placeholder --- .../troubleshoot-and-optimize/analyze-query-plan.md | 6 +++--- .../troubleshoot-and-optimize/optimize-queries.md | 1 + .../troubleshoot-and-optimize/analyze-query-plan.md | 8 ++++---- .../troubleshoot-and-optimize/optimize-queries.md | 1 + .../troubleshoot-and-optimize/analyze-query-plan.md | 6 +++--- .../troubleshoot-and-optimize/optimize-queries.md | 1 + 6 files changed, 13 insertions(+), 10 deletions(-) diff --git a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md index 915b956833..f0da76fe13 100644 --- a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md +++ b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md @@ -25,7 +25,7 @@ By learning how to generate and interpret reports for the query plan, you can better understand how the query is executed and identify bottlenecks that affect the performance of your query. For example, if the query plan reveals that your query reads a large number of Parquet files, -you can then take steps to [optimize your query](/influxdb/cloud-dedicated/query-data/optimize-queries/), such as add filters to read less data or +you can then take steps to [optimize your query](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/), such as add filters to read less data or configure your cluster to store fewer and larger files. - [Use EXPLAIN keywords to view a query plan](#use-explain-keywords-to-view-a-query-plan) @@ -113,7 +113,7 @@ Plans are in _tree format_--each plan is an upside-down tree in which execution and data flow from _leaf nodes_, the innermost steps in the plan, to outer _branch nodes_. Whether reading a logical or physical plan, keep the following in mind: -- Start at the the _leaf nodes_ and read upward. +- Start at the _leaf nodes_ and read upward. - At the top of the plan, the _root node_ represents the final, encompassing step. In a [physical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan), each step is an [`ExecutionPlan` node](/influxdb/cloud-dedicated/reference/internals/query-plan/#execution-plan-nodes) that receives expressions for input data and output requirements, and computes a partition of data. @@ -770,4 +770,4 @@ Operator structure for aggregating, sorting, and final output. - `SortPreservingMergeExec: [city@0 ASC NULLS LAST]`: Merges and sorts the four sorted streams for the final output. In the preceding examples, the `EXPLAIN` report shows the query plan without executing the query. -To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-dedicated/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-dedicated/query-data/optimize-queries/#enable-trace-logging) for further debugging, if necessary. +To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-dedicated/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/#enable-trace-logging) for further debugging, if necessary. diff --git a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md index 5a297bd9af..350a0136ce 100644 --- a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -16,6 +16,7 @@ related: aliases: - /influxdb/cloud-dedicated/query-data/execute-queries/optimize-queries/ - /influxdb/cloud-dedicated/query-data/execute-queries/analyze-query-plan/ + - /influxdb/cloud-dedicated/query-data/optimize-queries/ --- Optimize SQL and InfluxQL queries to improve performance and reduce their memory and compute (CPU) requirements. diff --git a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md index e2926ca494..8d61f55081 100644 --- a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md +++ b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md @@ -24,7 +24,7 @@ By learning how to generate and interpret reports for the query plan, you can better understand how the query is executed and identify bottlenecks that affect the performance of your query. For example, if the query plan reveals that your query reads a large number of Parquet files, -you can then take steps to [optimize your query](/influxdb/cloud-serverless/query-data/optimize-queries/), such as add filters to read less data. +you can then take steps to [optimize your query](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries/), such as add filters to read less data. - [Use EXPLAIN keywords to view a query plan](#use-explain-keywords-to-view-a-query-plan) - [Read an EXPLAIN report](#read-an-explain-report) @@ -65,7 +65,7 @@ import pandas as pd import tabulate # Required for pandas.to_markdown() # Instantiate an InfluxDB client. -client = InfluxDBClient3(token = f"TOKEN", +client = InfluxDBClient3(token = f"API_TOKEN", host = f"{{< influxdb/host >}}", database = f"BUCKET_NAME") @@ -109,7 +109,7 @@ Plans are in _tree format_--each plan is an upside-down tree in which execution and data flow from _leaf nodes_, the innermost steps in the plan, to outer _branch nodes_. Whether reading a logical or physical plan, keep the following in mind: -- Start at the the _leaf nodes_ and read upward. +- Start at the _leaf nodes_ and read upward. - At the top of the plan, the _root node_ represents the final, encompassing execution step. In a [physical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan), each step is an [`ExecutionPlan` node](/influxdb/cloud-serverless/reference/internals/query-plan/#executionplan-nodes) that receives expressions for input data and output requirements, and computes a partition of data. @@ -766,4 +766,4 @@ Operator structure for aggregating, sorting, and final output. - `SortPreservingMergeExec: [city@0 ASC NULLS LAST]`: Merges and sorts the four sorted streams for the final output. In the preceding examples, the `EXPLAIN` report shows the query plan without executing the query. -To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-serverless/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-serverless/query-data/optimize-queries/#enable-trace-logging) for further debugging, if necessary. +To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-serverless/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries/#enable-trace-logging) for further debugging, if necessary. diff --git a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md index 9b7c00e2cd..7db3037516 100644 --- a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -15,6 +15,7 @@ related: - /influxdb/cloud-serverless/query-data/execute-queries/analyze-query-plan/ aliases: - /influxdb/cloud-serverless/query-data/execute-queries/optimize-queries/ + - /influxdb/cloud-serverless/query-data/optimize-queries/ --- Optimize SQL and InfluxQL queries to improve performance and reduce their memory and compute (CPU) requirements. diff --git a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md index 898b014967..c5c3471839 100644 --- a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md +++ b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md @@ -25,7 +25,7 @@ By learning how to generate and interpret reports for the query plan, you can better understand how the query is executed and identify bottlenecks that affect the performance of your query. For example, if the query plan reveals that your query reads a large number of Parquet files, -you can then take steps to [optimize your query](/influxdb/clustered/query-data/optimize-queries/), such as add filters to read less data or +you can then take steps to [optimize your query](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/), such as add filters to read less data or configure your cluster to store fewer and larger files. - [Use EXPLAIN keywords to view a query plan](#use-explain-keywords-to-view-a-query-plan) @@ -113,7 +113,7 @@ Plans are in _tree format_--each plan is an upside-down tree in which execution and data flow from _leaf nodes_, the innermost steps in the plan, to outer _branch nodes_. Whether reading a logical or physical plan, keep the following in mind: -- Start at the the _leaf nodes_ and read upward. +- Start at the _leaf nodes_ and read upward. - At the top of the plan, the _root node_ represents the final, encompassing step. In a [physical plan](/influxdb/clustered/reference/internals/query-plan/#physical-plan), each step is an [`ExecutionPlan` node](/influxdb/clustered/reference/internals/query-plan/#executionplan-nodes) that receives expressions for input data and output requirements, and computes a partition of data. @@ -770,4 +770,4 @@ Operator structure for aggregating, sorting, and final output. - `SortPreservingMergeExec: [city@0 ASC NULLS LAST]`: Merges and sorts the four sorted streams for the final output. In the preceding examples, the `EXPLAIN` report shows the query plan without executing the query. -To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/clustered/reference/sql/explain/#explain-analyze) to generate the report and use [tracing](/influxdb/clustered/query-data/optimize-queries/#enable-trace-logging) for further debugging, if necessary. +To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/clustered/reference/sql/explain/#explain-analyze) to generate the report and use [tracing](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/#enable-trace-logging) for further debugging, if necessary. diff --git a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md index 69a66af6fe..3b3b0684ce 100644 --- a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -16,6 +16,7 @@ related: aliases: - /influxdb/clustered/query-data/execute-queries/optimize-queries/ - /influxdb/clustered/query-data/execute-queries/analyze-query-plan/ + - /influxdb/clustered/query-data/optimize-queries/ --- Optimize SQL and InfluxQL queries to improve performance and reduce their memory and compute (CPU) requirements. From 4fe3cf75f7483e00b7f4681fee13d65b88121e12 Mon Sep 17 00:00:00 2001 From: Sven Rebhan <36194019+srebhan@users.noreply.github.com> Date: Thu, 17 Oct 2024 22:15:34 +0200 Subject: [PATCH 36/45] Telegraf v1.32.1 (#5638) Co-authored-by: Jason Stirnaman Co-authored-by: Scott Anderson --- content/telegraf/v1/release-notes.md | 46 ++++++++++++++++++++++++++++ data/products.yml | 2 +- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/content/telegraf/v1/release-notes.md b/content/telegraf/v1/release-notes.md index 60c502ec69..c1fdac6364 100644 --- a/content/telegraf/v1/release-notes.md +++ b/content/telegraf/v1/release-notes.md @@ -11,6 +11,52 @@ menu: weight: 60 --- +## v1.32.1 {date="2024-10-07"} + +### Important Changes + +- PR [#15796](https://github.com/influxdata/telegraf/pull/15796) changes the + delivery state update of un-parseable messages from `ACK` to `NACK` without + requeueing. This way, those messages are not lost and can optionally be + handled using a dead-letter exchange by other means. + +### Bugfixes + +- [#15969](https://github.com/influxdata/telegraf/pull/15969) `agent` Fix buffer not flushing if all metrics are written +- [#15937](https://github.com/influxdata/telegraf/pull/15937) `config` Correctly print removal version info +- [#15900](https://github.com/influxdata/telegraf/pull/15900) `common.http` Keep timeout after creating oauth client +- [#15796](https://github.com/influxdata/telegraf/pull/15796) `inputs.amqp_consumer` NACKing messages on non-delivery related errors +- [#15923](https://github.com/influxdata/telegraf/pull/15923) `inputs.cisco_telemetry_mdt` Handle NXOS DME subtree telemetry format +- [#15907](https://github.com/influxdata/telegraf/pull/15907) `inputs.consul` Move config checking to Init method +- [#15982](https://github.com/influxdata/telegraf/pull/15982) `inputs.influxdb_v2_listener` Fix concurrent read/write dict +- [#15960](https://github.com/influxdata/telegraf/pull/15960) `inputs.vsphere` Add tags to VSAN ESA disks +- [#15921](https://github.com/influxdata/telegraf/pull/15921) `parsers.avro` Add mutex to cache access +- [#15965](https://github.com/influxdata/telegraf/pull/15965) `processors.aws_ec2` Remove leading slash and cancel worker only if it exists + +### Dependency Updates + +- [#15932](https://github.com/influxdata/telegraf/pull/15932) `deps` Bump cloud.google.com/go/monitoring from 1.20.2 to 1.21.1 +- [#15863](https://github.com/influxdata/telegraf/pull/15863) `deps` Bump github.com/Azure/azure-kusto-go from 0.15.3 to 0.16.1 +- [#15862](https://github.com/influxdata/telegraf/pull/15862) `deps` Bump github.com/Azure/azure-sdk-for-go/sdk/azcore from 1.13.0 to 1.14.0 +- [#15957](https://github.com/influxdata/telegraf/pull/15957) `deps` Bump github.com/aws/aws-sdk-go-v2/feature/ec2/imds from 1.16.12 to 1.16.14 +- [#15859](https://github.com/influxdata/telegraf/pull/15859) `deps` Bump github.com/aws/aws-sdk-go-v2/service/dynamodb from 1.34.4 to 1.34.9 +- [#15931](https://github.com/influxdata/telegraf/pull/15931) `deps` Bump github.com/boschrexroth/ctrlx-datalayer-golang from 1.3.0 to 1.3.1 +- [#15890](https://github.com/influxdata/telegraf/pull/15890) `deps` Bump github.com/harlow/kinesis-consumer from v0.3.6-0.20240606153816-553e2392fdf3 to v0.3.6-0.20240916192723-43900507c911 +- [#15904](https://github.com/influxdata/telegraf/pull/15904) `deps` Bump github.com/netsampler/goflow2/v2 from 2.1.5 to 2.2.1 +- [#15903](https://github.com/influxdata/telegraf/pull/15903) `deps` Bump github.com/p4lang/p4runtime from 1.3.0 to 1.4.0 +- [#15905](https://github.com/influxdata/telegraf/pull/15905) `deps` Bump github.com/prometheus/client_golang from 1.20.2 to 1.20.3 +- [#15930](https://github.com/influxdata/telegraf/pull/15930) `deps` Bump github.com/prometheus/client_golang from 1.20.3 to 1.20.4 +- [#15962](https://github.com/influxdata/telegraf/pull/15962) `deps` Bump github.com/prometheus/common from 0.55.0 to 0.60.0 +- [#15860](https://github.com/influxdata/telegraf/pull/15860) `deps` Bump github.com/snowflakedb/gosnowflake from 1.10.0 to 1.11.1 +- [#15954](https://github.com/influxdata/telegraf/pull/15954) `deps` Bump github.com/srebhan/protobufquery from 0.0.0-20230803132024-ae4c0d878e55 to 1.0.1 +- [#15929](https://github.com/influxdata/telegraf/pull/15929) `deps` Bump go.mongodb.org/mongo-driver from 1.16.0 to 1.17.0 +- [#15902](https://github.com/influxdata/telegraf/pull/15902) `deps` Bump golang.org/x/mod from 0.19.0 to 0.21.0 +- [#15955](https://github.com/influxdata/telegraf/pull/15955) `deps` Bump golang.org/x/oauth2 from 0.21.0 to 0.23.0 +- [#15861](https://github.com/influxdata/telegraf/pull/15861) `deps` Bump golang.org/x/term from 0.23.0 to 0.24.0 +- [#15856](https://github.com/influxdata/telegraf/pull/15856) `deps` Bump golangci-lint from v1.60.3 to v1.61.0 +- [#15933](https://github.com/influxdata/telegraf/pull/15933) `deps` Bump k8s.io/apimachinery from 0.30.1 to 0.31.1 +- [#15901](https://github.com/influxdata/telegraf/pull/15901) `deps` Bump modernc.org/sqlite from 1.32.0 to 1.33.1 + ## v1.32.0 {date="2024-09-09"} ### Important Changes diff --git a/data/products.yml b/data/products.yml index b0b43207db..bb1b7a24ec 100644 --- a/data/products.yml +++ b/data/products.yml @@ -77,7 +77,7 @@ telegraf: versions: [v1] latest: v1.32 latest_patches: - v1: 1.32.0 + v1: 1.32.1 chronograf: name: Chronograf From 47173a9a001faa79a0f69eb4a6523300ad40913a Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Mon, 21 Oct 2024 12:29:19 -0600 Subject: [PATCH 37/45] Reorganize InfluxDB Clustered installation documentation (#5636) * WIP clustered install restructure * WIP clustered install restructure * WIP clustered install reorg * finalize clustered install reorg for preview * updates to address PR feedback * added garbage collector scaling config * Apply suggestions from code review Co-authored-by: Jason Stirnaman * removed obsolete api artifacts * remove callouts for specific dependency versions * Clustered sizing recommendations per vendor (#5652) * added vendor-specific sizing recommendations to clustered * Apply suggestions from code review Co-authored-by: Jason Stirnaman * remove medium-sized workload link --------- Co-authored-by: Jason Stirnaman --------- Co-authored-by: Jason Stirnaman --- assets/styles/layouts/article/_buttons.scss | 8 + assets/styles/layouts/article/_captions.scss | 2 +- assets/styles/layouts/article/_code.scss | 3 +- assets/styles/layouts/article/_title.scss | 5 +- .../admin/bypass-identity-provider.md | 2 - content/influxdb/clustered/admin/env-vars.md | 239 +++-- content/influxdb/clustered/admin/licensing.md | 77 +- .../influxdb/clustered/admin/scale-cluster.md | 242 ++++- content/influxdb/clustered/admin/upgrade.md | 6 +- .../influxdb/clustered/admin/users/_index.md | 6 +- content/influxdb/clustered/admin/users/add.md | 12 +- content/influxdb/clustered/install/_index.md | 27 +- content/influxdb/clustered/install/auth.md | 394 ------- .../install/configure-cluster/_index.md | 27 - .../install/configure-cluster/directly.md | 975 ------------------ .../install/customize-cluster/_index.md | 29 + .../install/customize-cluster/config.md | 148 +++ .../install/customize-cluster/scale.md | 336 ++++++ .../install/optimize-cluster/_index.md | 46 + .../install/optimize-cluster/design-schema.md | 87 ++ .../optimize-cluster/optimize-querying.md | 94 ++ .../install/optimize-cluster/simulate-load.md | 36 + .../install/optimize-cluster/write-methods.md | 125 +++ .../clustered/install/prerequisites.md | 208 ---- .../install/secure-cluster/_index.md | 27 + .../clustered/install/secure-cluster/auth.md | 793 ++++++++++++++ .../clustered/install/secure-cluster/tls.md | 309 ++++++ .../install/set-up-cluster/_index.md | 28 + .../configure-cluster/_index.md | 28 + .../configure-cluster/directly.md | 741 +++++++++++++ .../configure-cluster/use-helm.md | 458 ++------ .../install/{ => set-up-cluster}/deploy.md | 10 +- .../install/{ => set-up-cluster}/licensing.md | 85 +- .../install/set-up-cluster/prerequisites.md | 405 ++++++++ .../install/set-up-cluster/test-cluster.md | 176 ++++ .../clustered/install/use-your-cluster.md | 4 +- .../reference/client-libraries/v3/python.md | 2 +- .../reference/release-notes/clustered.md | 2 +- 38 files changed, 4056 insertions(+), 2146 deletions(-) delete mode 100644 content/influxdb/clustered/install/auth.md delete mode 100644 content/influxdb/clustered/install/configure-cluster/_index.md delete mode 100644 content/influxdb/clustered/install/configure-cluster/directly.md create mode 100644 content/influxdb/clustered/install/customize-cluster/_index.md create mode 100644 content/influxdb/clustered/install/customize-cluster/config.md create mode 100644 content/influxdb/clustered/install/customize-cluster/scale.md create mode 100644 content/influxdb/clustered/install/optimize-cluster/_index.md create mode 100644 content/influxdb/clustered/install/optimize-cluster/design-schema.md create mode 100644 content/influxdb/clustered/install/optimize-cluster/optimize-querying.md create mode 100644 content/influxdb/clustered/install/optimize-cluster/simulate-load.md create mode 100644 content/influxdb/clustered/install/optimize-cluster/write-methods.md delete mode 100644 content/influxdb/clustered/install/prerequisites.md create mode 100644 content/influxdb/clustered/install/secure-cluster/_index.md create mode 100644 content/influxdb/clustered/install/secure-cluster/auth.md create mode 100644 content/influxdb/clustered/install/secure-cluster/tls.md create mode 100644 content/influxdb/clustered/install/set-up-cluster/_index.md create mode 100644 content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md create mode 100644 content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md rename content/influxdb/clustered/install/{ => set-up-cluster}/configure-cluster/use-helm.md (59%) rename content/influxdb/clustered/install/{ => set-up-cluster}/deploy.md (95%) rename content/influxdb/clustered/install/{ => set-up-cluster}/licensing.md (60%) create mode 100644 content/influxdb/clustered/install/set-up-cluster/prerequisites.md create mode 100644 content/influxdb/clustered/install/set-up-cluster/test-cluster.md diff --git a/assets/styles/layouts/article/_buttons.scss b/assets/styles/layouts/article/_buttons.scss index 6807ed6162..d05d412651 100644 --- a/assets/styles/layouts/article/_buttons.scss +++ b/assets/styles/layouts/article/_buttons.scss @@ -48,6 +48,14 @@ a.btn { font-size: 1.1rem; } + &.arrow span.CaretOutlineRight { + font-size: 1.5rem; + line-height: 0; + vertical-align: sub; + display: inline-block; + margin-right: -.65rem; + } + &.small-plus { padding: .25em; line-height: .65rem; diff --git a/assets/styles/layouts/article/_captions.scss b/assets/styles/layouts/article/_captions.scss index 20dfc39766..295550a9e0 100644 --- a/assets/styles/layouts/article/_captions.scss +++ b/assets/styles/layouts/article/_captions.scss @@ -11,7 +11,7 @@ code { font-size: .9rem; } } -p, li { +p, li, ol, ul { & + .caption { padding: 0; margin: -.75rem 0 0; diff --git a/assets/styles/layouts/article/_code.scss b/assets/styles/layouts/article/_code.scss index b9e9572bc4..4d24a7f017 100644 --- a/assets/styles/layouts/article/_code.scss +++ b/assets/styles/layouts/article/_code.scss @@ -84,6 +84,7 @@ span.code-callout, .code-placeholder { &.green {color: $article-code-accent3;} &.magenta {color: $br-new-magenta;} &.orange {color: $r-curacao;} + &.delete, &.strike {text-decoration: line-through;} } /////////////// Styles for code placeholders that can be updated /////////////// @@ -157,7 +158,7 @@ span.code-callout, .code-placeholder { } } } -.code-placeholder-key code {color: $code-placeholder} +.code-placeholder-key code {color: $code-placeholder !important} //////////////////////////////////////////////////////////////////////////////// diff --git a/assets/styles/layouts/article/_title.scss b/assets/styles/layouts/article/_title.scss index f6f10a2520..19ef644bb6 100644 --- a/assets/styles/layouts/article/_title.scss +++ b/assets/styles/layouts/article/_title.scss @@ -10,12 +10,13 @@ li { margin-bottom: 0; - padding: 0 .65em 0 .75em; + padding: .45em .75em; color: $article-heading; background: rgba($article-heading, .07); font-size: .95rem; font-weight: $medium; - border-radius: 1em; + line-height: 1.1rem; + border-radius: 1.1em; display: inline-block; &.updated-in, diff --git a/content/influxdb/clustered/admin/bypass-identity-provider.md b/content/influxdb/clustered/admin/bypass-identity-provider.md index 7edd944ede..fa7ea43f99 100644 --- a/content/influxdb/clustered/admin/bypass-identity-provider.md +++ b/content/influxdb/clustered/admin/bypass-identity-provider.md @@ -101,8 +101,6 @@ In the examples above, replace the following: The name of your InfluxDB namespace. - {{% code-placeholder-key %}}`KEY_GEN_JOB`{{% /code-placeholder-key %}}: The name of the key-gen job pod. -- {{% code-placeholder-key %}}`001`{{% /code-placeholder-key %}}: - A unique number used to increment the key-gen job. {{% note %}} To create a new admin token after revoking the existing one, rerun the diff --git a/content/influxdb/clustered/admin/env-vars.md b/content/influxdb/clustered/admin/env-vars.md index a17bd82019..f742117559 100644 --- a/content/influxdb/clustered/admin/env-vars.md +++ b/content/influxdb/clustered/admin/env-vars.md @@ -32,8 +32,9 @@ potential unintended consequences. ## AppInstance component schema In your `AppInstance` resource, configure individual component settings in the -`spec.package.spec.components` property. This property supports the following -InfluxDB Clustered component keys: +`spec.package.spec.components` property if configuring your `AppInstance` resource +directly or, if using Helm, use the `components` property in your `values.yaml`. +This property supports the following InfluxDB Clustered component keys: - `ingester` - `querier` @@ -41,6 +42,12 @@ InfluxDB Clustered component keys: - `compactor` - `garbage-collector` +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yaml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -63,6 +70,24 @@ spec: garbage-collector: # Garbage collector settings ... ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +components: + ingester: + # Ingester settings ... + querier: + # Querier settings ... + router: + # Router settings. ... + compactor: + # Compactor settings ... + garbage-collector: + # Garbage collector settings ... +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} _For more information about components in the InfluxDB v3 storage engine, see the [InfluxDB v3 storage engine architecture](/influxdb/clustered/reference/internals/storage-engine/)._ @@ -72,39 +97,81 @@ the [InfluxDB v3 storage engine architecture](/influxdb/clustered/reference/inte 1. Under the specific component property, use the `.template.containers.iox.env` property to define environment variables. -2. In the `env` property, structure each environment variable as a key-value pair. +2. In the `env` property, structure each environment variable as a key-value + pair where the key is the environment variable name and the value is the + environment variable value (string-formatted). For example, to configure environment variables for the Garbage collector: - ```yaml - apiVersion: kubecfg.dev/v1alpha1 - kind: AppInstance - metadata: - name: influxdb - namespace: influxdb + {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... spec: - package: - # ... - spec: - components: - garbage-collector: - template: - containers: - iox: - env: - INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' - INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' - ``` - -3. Use `kubectl apply` to apply the configuration changes to your cluster and - add or update environment variables in each component. - - - - ```bash - kubectl apply \ - --filename myinfluxdb.yml \ - --namespace influxdb - ``` + components: + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +components: + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +3. Apply the configuration changes to your cluster and add or update + environment variables in each component. + + {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + {{% note %}} #### Update environment variables instead of removing them @@ -124,6 +191,12 @@ the `env` property, the cutoff reverts to its default setting of `30d`. {{< expand-wrapper >}} {{% expand "View example of environment variables in all components" %}} +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yaml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -135,37 +208,77 @@ spec: # ... spec: components: - ingester: - template: - containers: - iox: - env: - INFLUXDB_IOX_WAL_ROTATION_PERIOD_SECONDS: '360' - querier: - template: - containers: - iox: - env: - INFLUXDB_IOX_EXEC_MEM_POOL_BYTES: '10737418240' # 10GiB - router: - template: - containers: - iox: - env: - INFLUXDB_IOX_MAX_HTTP_REQUESTS: '5000' - compactor: - template: - containers: - iox: - env: - INFLUXDB_IOX_EXEC_MEM_POOL_PERCENT: '80' - garbage-collector: - template: - containers: - iox: - env: - INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' - INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_WAL_ROTATION_PERIOD_SECONDS: '360' + querier: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_BYTES: '10737418240' # 10GiB + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '5000' + compactor: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_PERCENT: '80' + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +components: + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_WAL_ROTATION_PERIOD_SECONDS: '360' + querier: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_BYTES: '10737418240' # 10GiB + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '5000' + compactor: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_PERCENT: '80' + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + {{% /expand %}} {{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/admin/licensing.md b/content/influxdb/clustered/admin/licensing.md index bda66025d6..174ec49114 100644 --- a/content/influxdb/clustered/admin/licensing.md +++ b/content/influxdb/clustered/admin/licensing.md @@ -10,7 +10,7 @@ menu: weight: 101 influxdb/clustered/tags: [licensing] related: - - /influxdb/clustered/install/licensing/ + - /influxdb/clustered/install/set-up-cluster/licensing/ - /influxdb/clustered/admin/upgrade/ --- @@ -18,6 +18,10 @@ Install and manage your InfluxDB Clustered license to authorize the use of the InfluxDB Clustered software. - [Install your InfluxDB license](#install-your-influxdb-license) +- [Verify your license](#verify-your-license) + - [Verify database components](#verify-database-components) + - [Verify the Secret exists ](#verify-the-secret-exists) + - [View license controller logs](#view-license-controller-logs) - [Recover from a license misconfiguration](#recover-from-a-license-misconfiguration) - [Renew your license](#renew-your-license) - [License enforcement](#license-enforcement) @@ -31,9 +35,9 @@ the InfluxDB Clustered software. {{% note %}} If setting up an InfluxDB Clustered deployment for the first time, first -[set up the prerequisites](/influxdb/clustered/install/licensing/) and -[configure your cluster](/influxdb/clustered/install/configure-cluster/). -After your InfluxDB namespace is created and prepared, you will be able to +[set up the prerequisites](/influxdb/clustered/install/set-up-cluster/licensing/) and +[configure your cluster](/influxdb/clustered/install/set-up-cluster/configure-cluster/). +After your InfluxDB namespace is created and prepared, you can install your license. {{% /note %}} @@ -55,9 +59,72 @@ into a secret required by InfluxDB Clustered Kubernetes pods. Pods validate the license secret both at startup and periodically (roughly once per hour) while running. +## Verify your license + +After you have activated your license, use the following signals to verify the +license is active and functioning. + +In your commands, replace the following: + +- {{% code-placeholder-key %}}`NAMESPACE`{{% /code-placeholder-key %}}: + your [InfluxDB namespace](/influxdb/clustered/install/set-up-cluster/configure-cluster/#create-a-namespace-for-influxdb) +- {{% code-placeholder-key %}}`POD_NAME`{{% /code-placeholder-key %}}: + your [InfluxDB Kubernetes pod](/influxdb/clustered/install/set-up-cluster/deploy/#inspect-cluster-pods) + +### Verify database components + +After you [install your license](#install-your-influxdb-license), +run the following command to check that database pods start up and are in the +`Running` state: + + + +```bash +kubectl get pods -l app=iox --namespace influxdb +``` + +If a `Pod` fails to start, run the following command to view pod information: + + + +{{% code-placeholders "POD_NAME" %}} + +```sh +kubectl describe pod POD_NAME --namespace influxdb +``` + +{{% /code-placeholders %}} + +### Verify the `Secret` exists + +Run the following command to verify that the licensing activation created a +`iox-license` secret: + + + +```sh +kubectl get secret iox-license --namespace influxdb +``` + +If the secret doesn't exist, +[view `license-controller` logs](#view-license-controller-logs) for more +information or errors. + +### View `license controller` logs + +The `license controller` component creates a `Secret` named `iox-license` from +your `License`. To view `license controller` logs for troubleshooting, run the +following command: + + + +```sh +kubectl logs deployment/license-controller --namespace influxdb +``` + ## Recover from a license misconfiguration -If you deploy a licensed release of InfluxDB Clustered with an invalid or +If you deploy a licensed release of {{% product-name %}} with an invalid or expired license, many of the pods in your cluster will crash on startup and will likely enter a `CrashLoopBackoff` state without ever running or becoming healthy. Because InfluxDB stores the license in a volume-mounted Kubernetes secret, invalid diff --git a/content/influxdb/clustered/admin/scale-cluster.md b/content/influxdb/clustered/admin/scale-cluster.md index 31aa9042fa..3607b6c671 100644 --- a/content/influxdb/clustered/admin/scale-cluster.md +++ b/content/influxdb/clustered/admin/scale-cluster.md @@ -32,6 +32,7 @@ resources available to each component. - [Querier](#querier) - [Router](#router) - [Compactor](#compactor) + - [Garbage collector](#garbage-collector) - [Catalog](#catalog) - [Object store](#object-store) @@ -67,6 +68,7 @@ properties in your `AppInstance` resource: - Querier - Compactor - Router +- Garbage collector {{% note %}} #### Scale your Catalog and Object store @@ -77,6 +79,16 @@ are managed outside of your `AppInstance` resource. Scaling mechanisms for these components depend on the technology and underlying provider used for each. {{% /note %}} +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + Use the `spec.package.spec.resources` property in your `AppInstance` resource defined in your `influxdb.yml` to define system resource minimums and limits for each pod and the number of replicas per component. @@ -119,11 +131,18 @@ resource minimums and limits per pod and replicas per component: - `limits` - `cpu`: Maximum CPU Resource units to assign to routers - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector {{< expand-wrapper >}} {{% expand "View example `AppInstance` with resource requests and limits" %}} -{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} ```yml apiVersion: kubecfg.dev/v1alpha1 @@ -168,6 +187,13 @@ spec: limits: cpu: ROUTER_CPU_MAX memory: ROUTER_MEMORY_MAX + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX ``` {{% /code-placeholders %}} @@ -175,6 +201,121 @@ spec: {{% /expand %}} {{< /expand-wrapper >}} + + +{{% /tab-content %}} +{{% tab-content %}} + + + +Use the `resources` property in your `values.yaml` to define system resource +minimums and limits for each pod and the number of replicas per component. +`requests` are the minimum that the Kubernetes scheduler should reserve for a pod. +`limits` are the maximum that a pod should be allowed to use. + +Use the following properties to define resource minimums and limits per pod and +replicas per component: + +- `resources` + - `ingester` + - `requests` + - `cpu`: Minimum CPU resource units to assign to ingesters + - `memory`: Minimum memory resource units to assign to ingesters + - `replicas`: Number of ingester replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to ingesters + - `memory`: Maximum memory resource units to assign to ingesters + - `compactor` + - `requests` + - `cpu`: Minimum CPU resource units to assign to compactors + - `memory`: Minimum memory resource units to assign to compactors + - `replicas`: Number of compactor replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to compactors + - `memory`: Maximum memory resource units to assign to compactors + - `querier` + - `requests` + - `cpu`: Minimum CPU resource units to assign to queriers + - `memory`: Minimum memory resource units to assign to queriers + - `replicas`: Number of querier replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to queriers + - `memory`: Maximum memory resource units to assign to queriers + - `router` + - `requests` + - `cpu`: Minimum CPU resource units to assign to routers + - `memory`: Minimum memory resource units to assign to routers + - `replicas`: Number of router replicas to provision + - `limits` + - `cpu`: Maximum CPU Resource units to assign to routers + - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector + +{{< expand-wrapper >}} +{{% expand "View example `values.yaml` with resource requests and limits" %}} + +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} + +```yml +# ... + resources: + ingester: + requests: + cpu: INGESTER_CPU_MIN + memory: INGESTER_MEMORY_MIN + replicas: INGESTER_REPLICAS # Default is 3 + limits: + cpu: INGESTER_CPU_MAX + memory: INGESTER_MEMORY_MAX + compactor: + requests: + cpu: COMPACTOR_CPU_MIN + memory: COMPACTOR_MEMORY_MIN + replicas: COMPACTOR_REPLICAS # Default is 1 + limits: + cpu: COMPACTOR_CPU_MAX + memory: COMPACTOR_MEMORY_MAX + querier: + requests: + cpu: QUERIER_CPU_MIN + memory: QUERIER_MEMORY_MIN + replicas: QUERIER_REPLICAS # Default is 1 + limits: + cpu: QUERIER_CPU_MAX + memory: QUERIER_MEMORY_MAX + router: + requests: + cpu: ROUTER_CPU_MIN + memory: ROUTER_MEMORY_MIN + replicas: ROUTER_REPLICAS # Default is 1 + limits: + cpu: ROUTER_CPU_MAX + memory: ROUTER_MEMORY_MAX + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + {{% note %}} Applying resource limits to pods is optional, but provides better resource isolation and protects against pods using more resources than intended. For @@ -189,8 +330,7 @@ information, see [Kubernetes resource requests and limits](https://kubernetes.io ### Horizontally scale a component To horizontally scale a component in your InfluxDB cluster, increase or decrease -the number of replicas for the component in the `spec.package.spec.resources` -property in your `AppInstance` resource and [apply the change](#apply-your-changes). +the number of replicas for the component and [apply the change](#apply-your-changes). {{% warn %}} #### Only use the AppInstance to scale component replicas @@ -202,6 +342,12 @@ Manually scaling replicas may cause errors. For example--to horizontally scale your [Ingester](/influxdb/clustered/reference/internals/storage-engine/#ingester): +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yaml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -215,14 +361,31 @@ spec: # ... replicas: 6 ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +resources: + ingester: + requests: + # ... + replicas: 6 +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} ### Vertically scale a component To vertically scale a component in your InfluxDB cluster, increase or decrease -the CPU and memory resource units to assign to component pods in the -`spec.package.spec.resources` property in your `AppInstance` resource and +the CPU and memory resource units to assign to component pods and [apply the change](#apply-your-changes). +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yaml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -240,17 +403,53 @@ spec: cpu: "1000m" memory: "1024MiB" ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +resources: + ingester: + requests: + cpu: "500m" + memory: "512MiB" + # ... + limits: + cpu: "1000m" + memory: "1024MiB" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} ### Apply your changes After modifying the `AppInstance` resource, use `kubectl apply` to apply the configuration changes to your cluster and scale the updated components. -```sh +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash kubectl apply \ --filename myinfluxdb.yml \ --namespace influxdb ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} ## Scale your cluster as a whole @@ -266,6 +465,7 @@ to automatically scale your cluster as needed. - [Ingester](#ingester) - [Querier](#querier) - [Compactor](#compactor) +- [Garbage collector](#garbage-collector) - [Catalog](#catalog) - [Object store](#object-store) @@ -294,13 +494,20 @@ improves query performance and reduces pressure on the Compactor. Storage speed also helps with query performance. Configure the storage volume attached to Ingester pods in the -`spec.package.spec.ingesterStorage` property of your `AppInstance` resource. +`spec.package.spec.ingesterStorage` property of your `AppInstance` resource or, +if using Helm, the `ingesterStorage` property of your `values.yaml`. {{< expand-wrapper >}} {{% expand "View example Ingester storage configuration" %}} {{% code-placeholders "STORAGE_(CLASS|SIZE)" %}} +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -317,6 +524,20 @@ spec: # Set the storage size (minimum 2Gi recommended) storage: STORAGE_SIZE ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yml +# ... +ingesterStorage: + # (Optional) Set the storage class. This will differ based on the K8s + #environment and desired storage characteristics. + # If not set, the default storage class is used. + storageClassName: STORAGE_CLASS + # Set the storage size (minimum 2Gi recommended) + storage: STORAGE_SIZE +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} {{% /code-placeholders %}} @@ -340,6 +561,13 @@ increasing the available CPU) is the most effective scaling strategy for the Compactor. Horizontal scaling increases compaction throughput, but not as efficiently as vertical scaling. +### Garbage collector + +The Garbage collector can be scaled [vertically](#vertical-scaling). It is a +light-weight process that typically doesn't require many system resources, but +if you begin to see high resource consumption on the garbage collector, you can +scale it vertically to address the added workload. + ### Catalog Scaling strategies available for the Catalog depend on the PostgreSQL-compatible diff --git a/content/influxdb/clustered/admin/upgrade.md b/content/influxdb/clustered/admin/upgrade.md index 16c3cb587d..6c38f19595 100644 --- a/content/influxdb/clustered/admin/upgrade.md +++ b/content/influxdb/clustered/admin/upgrade.md @@ -11,14 +11,14 @@ weight: 206 influxdb/clustered/tags: [upgrade] related: - /influxdb/clustered/install/ - - /influxdb/clustered/install/configure-cluster/ - - /influxdb/clustered/install/deploy/ + - /influxdb/clustered/install/set-up-cluster/configure-cluster/ + - /influxdb/clustered/install/set-up-cluster/deploy/ --- Use Kubernetes to upgrade your InfluxDB Clustered version. InfluxDB Clustered versioning is defined in the `AppInstance` `CustomResourceDefinition` (CRD) in your -[`myinfluxdb.yml`](/influxdb/clustered/install/configure-cluster/). +[`myinfluxdb.yml`](/influxdb/clustered/install/set-up-cluster/configure-cluster/). - [Version format](#version-format) - [Upgrade your InfluxDB Clustered version](#upgrade-your-influxdb-clustered-version) diff --git a/content/influxdb/clustered/admin/users/_index.md b/content/influxdb/clustered/admin/users/_index.md index f08e5ae989..6c16b57d47 100644 --- a/content/influxdb/clustered/admin/users/_index.md +++ b/content/influxdb/clustered/admin/users/_index.md @@ -10,12 +10,12 @@ menu: weight: 102 cascade: related: - - /influxdb/clustered/install/auth/ - - /influxdb/clustered/install/configure-cluster/ + - /influxdb/clustered/install/secure-cluster/auth/ + - /influxdb/clustered/install/set-up-cluster/configure-cluster/ --- Manage users with administrative access to your InfluxDB cluster through your -[identity provider](/influxdb/clustered/install/auth/) and your InfluxDB +[identity provider](/influxdb/clustered/install/secure-cluster/auth/) and your InfluxDB `AppInstance` resource. Administrative access lets users perform actions like creating databases and tokens. diff --git a/content/influxdb/clustered/admin/users/add.md b/content/influxdb/clustered/admin/users/add.md index 04c92d9f98..6cbefa63c3 100644 --- a/content/influxdb/clustered/admin/users/add.md +++ b/content/influxdb/clustered/admin/users/add.md @@ -12,7 +12,7 @@ weight: 201 --- Add a user with administrative access to your InfluxDB cluster through your -[identity provider](/influxdb/clustered/install/auth/) and your InfluxDB +[identity provider](/influxdb/clustered/install/secure-cluster/auth/) and your InfluxDB `AppInstance` resource: 1. Use your identity provider to create an OAuth2 account for the user that @@ -97,7 +97,7 @@ Replace the following: Keycloak realm - {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: Keycloak user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Keycloak](/influxdb/clustered/install/auth/#find-user-ids-with-keycloak))_ + _(See [Find user IDs with Keycloak](/influxdb/clustered/install/secure-cluster/auth/#find-user-ids-with-keycloak))_ --- @@ -174,7 +174,7 @@ Replace the following: Microsoft Entra tenant ID - {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ --- @@ -312,7 +312,7 @@ Replace the following: Microsoft Entra tenant ID - {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ --- @@ -323,7 +323,7 @@ Replace the following: {{% /tab-content %}} {{< /tabs-wrapper >}} -3. Apply the change to your InfluxDB cluster. +3. Apply the change to your InfluxDB cluster. - If updating the `AppInstance` resource directly, use `kubectl` to apply the change. @@ -362,6 +362,6 @@ helm upgrade \ Once applied, the added user is granted administrative access to your InfluxDB cluster and can use `influxctl` to perform administrative actions. -See [Set up Authorization--Configure influxctl](/influxdb/clustered/install/auth/#configure-influxctl) +See [Set up Authorization--Configure influxctl](/influxdb/clustered/install/secure-cluster/auth/#configure-influxctl) for information about configuring the new user's `influxctl` client to communicate and authenticate with your InfluxDB cluster's identity provider. diff --git a/content/influxdb/clustered/install/_index.md b/content/influxdb/clustered/install/_index.md index 8fe1cac7ff..edcf2708f4 100644 --- a/content/influxdb/clustered/install/_index.md +++ b/content/influxdb/clustered/install/_index.md @@ -7,11 +7,30 @@ weight: 2 --- InfluxDB Clustered is deployed and managed using Kubernetes. -This multi-page guide walks through setting up prerequisites and configuring -your InfluxDB cluster deployment. +This installation guide walks you through the following four installation phases and +the goal of each phase. +This process helps you set up and run your cluster and ensure it +performs well with your expected production workload. + +1. **[Set up your cluster](/influxdb/clustered/install/set-up-cluster/)**: + Get a basic InfluxDB cluster up and running with as few external + dependencies as possible and confirm you can write and query data. +2. **[Customize your cluster](/influxdb/clustered/install/customize-cluster/)**: + Review and customize the available configuration options specific to your workload. +3. **[Optimize your cluster](/influxdb/clustered/install/optimize-cluster/)**: + Scale and load test your InfluxDB cluster to confirm that it will satisfy + your scalability and performance needs. Work with InfluxData to review your + schema and determine how best to organize your data and develop queries + representative of your workload to ensure queries meet performance requirements. +4. **[Secure your cluster](/influxdb/clustered/install/secure-cluster/)**: + Integrate InfluxDB with your identity provider to manage access to your + cluster. Install TLS certificates and enable TLS access. + Prepare your cluster for production use. + +## InfluxDB Clustered license InfluxDB Clustered is a commercial product offered by InfluxData, the creators -of InfluxDB. Please contact InfluxData Sales to obtain a license before +of InfluxDB. Please contact InfluxData Sales to obtain a license _before_ installing InfluxDB Clustered. Contact InfluxData Sales @@ -47,4 +66,4 @@ The Catalog and Object store contain all of the important state for Influxdb 3.0 After recovering the catalog and object store, you will need to update the dsn in myinfluxdb.yml and re-apply. --> -{{< page-nav next="/influxdb/clustered/install/prerequisites/" >}} +{{< page-nav next="/influxdb/clustered/install/set-up-cluster/prerequisites/" >}} diff --git a/content/influxdb/clustered/install/auth.md b/content/influxdb/clustered/install/auth.md deleted file mode 100644 index d45f457203..0000000000 --- a/content/influxdb/clustered/install/auth.md +++ /dev/null @@ -1,394 +0,0 @@ ---- -title: Set up administrative authentication -description: > - Manage administrative access to your InfluxDB cluster through your identity provider. -menu: - influxdb_clustered: - name: Set up authentication - parent: Install InfluxDB Clustered -weight: 120 ---- - -Administrative access to your InfluxDB cluster is managed through your identity -provider. Use your identity provider to create OAuth2 accounts for all users -who need administrative access to your InfluxDB cluster. Administrative access -lets user perform actions like creating databases and tokens. - -{{% note %}} -Identity providers can be deployed with your InfluxDB cluster or run externally. -If you choose to deploy your provider with your InfluxDB cluster, the process -outlined below should be done _after_ your initial InfluxDB cluster deployment. -{{% /note %}} - -{{% note %}} -#### Bypass your identity provider for development and testing - -If running in a development or testing environment and you do not want to -authorize with an OAuth2 identity provider, {{< product-name >}} provides an -_admin token_ in your cluster's namespace that can be used to bypass your -identity provider. - -For more information, see -[Bypass your identity provider](/influxdb/clustered/admin/bypass-identity-provider/). -{{% /note %}} - -InfluxDB Clustered requires that your OAuth2 identity provider supports -[Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow). -InfluxData has tested with the following identity providers: - -- [Keycloak](https://www.keycloak.org/) -- [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra) -- [Auth0](https://auth0.com/) - -Setup instructions are provided for the following: - -{{< tabs-wrapper >}} -{{% tabs %}} -[Keycloak](#) -[Microsoft Entra ID](#) - - - -{{% /tabs %}} - -{{% tab-content %}} - - - -## Keycloak - -To use Keycloak as your identity provider: - -1. [Create a Keycloak realm](#create-a-keycloak-realm) -2. [Create a Keycloak client with device flow enabled](#create-a-keycloak-client-with-device-flow-enabled) -3. [Create users that need administrative access to your InfluxDB cluster](#create-users) -4. [Configure InfluxDB Clustered to use Keycloak](#configure-influxdb-clustered-to-use-keycloak) - -### Create a Keycloak realm - -See [Creating a realm](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-a-realm_server_administration_guide) -in the Keycloak documentation. - -### Create a Keycloak client with device flow enabled - -1. In the **Keycloak Admin Console**, navigate to **Clients** and then click - **Create Client**. -2. In the **General Settings** configuration step: - - 1. Set the **Client type** to **OpenID Connect**. - 2. Enter a **Client ID**, Save your client ID to be used later. - 3. _Optional:_ Enter a **Name** and **Description** for the client. - 4. Click **Next**. - -3. In the **Capability** configuration step, enable the - **OAuth 2.0 Device Authorization Grant** authentication flow, and then click - **Next**. -4. In the **Login settings** step, you don’t need to change anything. - Click **Save**. - -### Create users - -See [Creating users](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-user_server_administration_guide) -in the Keycloak documentation. - -#### Find user IDs with Keycloak - -To find the user IDs with Keycloak, use the Keycloak Admin Console or the Keycloak REST API. - -##### Keycloak Admin Console - -1. In the Keycloak Admin Console, navigate to your realm -2. Select **Users** in the left navigation. -3. Select the user you want to find the ID for. -4. Select the **Details** tab. The user ID is listed here. - -##### Keycloak REST API - -Send a GET request to the Keycloak REST API `/users` endpoint to fetch -the ID of a specific user. Provide the following: - -- **Query parameters** - - **username**: Username to retrieve information about - -{{% code-placeholders "KEYCLOAK_(HOST|REALM|USERNAME)" %}} - -```sh -curl https://KEYCLOAK_HOST/auth/admin/realms/KEYCLOAK_REALM/users?username=KEYCLOAK_USERNAME -``` - -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: - the Keycloak host and port (`host:port`) -- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: - the Keycloak realm -- {{% code-placeholder-key %}}`KEYCLOAK_USERNAME`{{% /code-placeholder-key %}}: - the Keycloak username to retrieve - ---- - -### Configure InfluxDB Clustered to use Keycloak - -Run the following command to retrieve a JSON object that contains the OpenID configuration -of your Keycloak realm: - -{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} - -```sh -curl https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/.well-known/openid-configuration -``` - -{{% /code-placeholders %}} - -{{< expand-wrapper >}} -{{% expand "View example response body" %}} - -{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} - -```json -{ - "issuer": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM", - "authorization_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/auth", - "token_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/token", - "device_authorization_endpoint": "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device", - "userinfo_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/userinfo", - "end_session_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/logout", - "jwks_uri": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs", - "grant_types_supported": ["authorization_code", "refresh_token", "password"], - "response_types_supported": ["code"], - "subject_types_supported": ["public"], - "id_token_signing_alg_values_supported": ["RS256"], - "response_modes_supported": ["query"] -} -``` - -{{% /code-placeholders %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -The following are important fields in the JSON object that are necessary to -connect your InfluxDB cluster and administrative tools to Keycloak: - -- **jwks_uri**: Used in your InfluxDB cluster configuration file. - _See [Configure your cluster--Configure your OAuth2 provider](/influxdb/clustered/install/configure-cluster/#configure-your-oauth2-provider)_. -- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) -- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) - - - -{{% /tab-content %}} -{{% tab-content %}} - - - -## Microsoft Entra ID - -To use Microsoft Entra ID as your identity provider: - -1. [Create a new tenant in Microsoft Entra ID](#create-a-new-tenant-in-microsoft-entra-id) -2. [Add users that need administrative access to your InfluxDB cluster](#add-users-that-need-administrative-access-to-your-influxdb-cluster) -3. [Register a new application with device code flow enabled](#register-a-new-application-with-device-code-flow-enabled) -4. Configure InfluxDB Clustered to use Microsoft Entra ID - -### Create a new tenant in Microsoft Entra ID - -See [Create a new tenant in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/create-new-tenant) -in the Microsoft Azure documentation. -_Copy and store your **Microsoft Entra Tenant ID**_. - -### Add users that need administrative access to your InfluxDB cluster - -See [Add or delete users](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/add-users) -in the Microsoft Azure documentation. - -#### Find user IDs with Microsoft Entra ID - -For Microsoft Entra ID, the unique user ID is the Microsoft ObjectId (OID). -To download a list of user OIDs: - -1. In the **Microsoft Azure Portal**, select **Users** in the left navigation. -2. Select users you want OIDs for and click **Download Users**. - -In the downloaded CSV file, user OIDs are provided in the `id` column. - -### Register a new application with device code flow enabled - -1. In the **Microsoft Azure Portal**, select **App Registrations** in the left navigation. -2. Click **New Registration** and enter a name for a new application to handle - authentication requests. -3. Click **Register Application**. _Copy and store your **Application (Client) ID**_. -4. In your registered application, click **Authentication** in the left navigation. -5. Under **Advanced Settings**, set **Allow public client flows** to **Yes**. - This enables the use of the [device code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code) - for logging in to your InfluxDB cluster. - -### Configure InfluxDB Clustered to use Microsoft Entra ID - -Use the following command to retrieve a JSON object that contains the OpenID configuration -of your Microsoft Entra tenant: - -{{% code-placeholders "AZURE_TENANT_ID" %}} - -```sh -curl https://login.microsoftonline.com/AZURE_TENANT_ID/v2.0/.well-known/openid-configuration -``` - -{{% /code-placeholders %}} - -Replace {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}} -with your [Microsoft Entra tenant ID](#create-a-new-tenant-in-microsoft-entra-id). - -{{< expand-wrapper >}} -{{% expand "View example response body" %}} - -{{% code-placeholders "AZURE_TENANT_ID" %}} - -```js -{ - "issuer": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/", - "authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/authorize", - "token_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token", - "device_authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode", - "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo", - "jwks_uri": "https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys", - "grant_types_supported": [ - "authorization_code", - "refresh_token", - "password" - ], - "response_types_supported": [ - "code" - ], - "subject_types_supported": [ - "public" - ], - "id_token_signing_alg_values_supported": [ - "RS256" - ], - "response_modes_supported": [ - "query" - ] -} -``` - -{{% /code-placeholders %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -The following are important fields in the JSON object that are necessary to -connect your InfluxDB cluster and administrative tools to Keycloak: - -- **jwks_uri**: Used in your InfluxDB cluster configuration file. - _See [Configure your cluster--Configure your OAuth2 provider](/influxdb/clustered/install/configure-cluster/?t=Microsoft+Entra+ID#configure-your-oauth2-provider)_. -- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) -- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) - - - -{{% /tab-content %}} - - - - - - - -{{< /tabs-wrapper >}} - -## Configure influxctl - -The [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) is used to -perform administrative actions such as creating databases or database tokens. -All `influxctl` commands are first authorized using your identity provider. -Update your [`influxctl` configuration file](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) -to connect to your identity provider. - -The following examples show how to configure `influxctl` for various identity providers: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Keycloak](#) -[Auth0](#) -[Microsoft Entra ID](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - - - -{{% code-placeholders "KEYCLOAK_(CLIENT_ID|PORT|REALM)" %}} - -```toml -[[profile]] - name = "default" - product = "clustered" - host = "{{< influxdb/host >}}" # InfluxDB cluster host - port = "8086" # InfluxDB cluster port - - [profile.auth.oauth2] - client_id = "KEYCLOAK_CLIENT_ID" - device_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device" - token_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/token" -``` - -{{% /code-placeholders %}} - - - -{{% /code-tab-content %}} -{{% code-tab-content %}} - - - -{{% code-placeholders "AUTH0_(CLIENT_)*(ID|SECRET|HOST)" %}} - -```toml -[[profile]] - name = "default" - product = "clustered" - host = "{{< influxdb/host >}}" # InfluxDB cluster host - port = "8086" # InfluxDB cluster port - - [profile.auth.oauth2] - client_id = "AUTH0_CLIENT_ID" - client_secret = "AUTH0_CLIENT_SECRET" - device_url = "https://AUTH0_HOST/oauth/device/code" - token_url = "https://AUTH0_HOST/oauth/token" -``` - -{{% /code-placeholders %}} - - - -{{% /code-tab-content %}} -{{% code-tab-content %}} - - - -{{% code-placeholders "AZURE_(CLIENT|TENANT)_ID" %}} - -```toml -[[profile]] - name = "default" - product = "clustered" - host = "{{< influxdb/host >}}" # InfluxDB cluster host - port = "8086" # InfluxDB cluster port - - [profile.auth.oauth2] - client_id = "AZURE_CLIENT_ID" - scopes = ["AZURE_CLIENT_ID/.default"] - device_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode" - token_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token" -``` - -{{% /code-placeholders %}} - - - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -{{< page-nav prev="/influxdb/clustered/install/prerequisites/" next="/influxdb/clustered/install/configure-cluster/" nextText="Configure your cluster" >}} diff --git a/content/influxdb/clustered/install/configure-cluster/_index.md b/content/influxdb/clustered/install/configure-cluster/_index.md deleted file mode 100644 index f36a260ece..0000000000 --- a/content/influxdb/clustered/install/configure-cluster/_index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Configure your InfluxDB cluster -description: > - InfluxDB Clustered deployments are managed using Kubernetes and configured using - a YAML configuration file. -menu: - influxdb_clustered: - name: Configure your cluster - parent: Install InfluxDB Clustered -weight: 130 -related: - - /influxdb/clustered/admin/upgrade/ ---- - -InfluxDB Clustered deployments are managed using Kubernetes and configured using -a YAML configuration file. -Apply configuration settings to your cluster by editing and applying a -Kubernetes custom resource (CRD) called `AppInstance`. -The AppInstance CRD is defined in a YAML file (use example-customer.yml as a -template) or, if using the InfluxDB Clustered Helm chart, is provided by the -chart and configured in a `values.yaml` file. - -Use one of the following methods to configure your InfluxDB cluster: - -{{< children type="anchored-list" >}} - -{{< children >}} diff --git a/content/influxdb/clustered/install/configure-cluster/directly.md b/content/influxdb/clustered/install/configure-cluster/directly.md deleted file mode 100644 index 28630d24b5..0000000000 --- a/content/influxdb/clustered/install/configure-cluster/directly.md +++ /dev/null @@ -1,975 +0,0 @@ ---- -title: Use the InfluxDB AppInstance resource configuration -list_title: Configure your InfluxDB AppInstance resource directly -description: > - Configure your InfluxDB cluster by editing configuration options in - the provided `AppInstance` resource. -menu: -menu: - influxdb_clustered: - name: Configure AppInstance - parent: Configure your cluster -weight: 220 ---- - -Manage your InfluxDB Clustered deployments using Kubernetes and apply configuration settings using -a YAML configuration file. - -- **`influxdb-docker-config.json`**: an authenticated Docker configuration file. - The InfluxDB Clustered software is in a secure container registry. - This file grants access to the collection of container images required to - install InfluxDB Clustered. -- **A tarball that contains the following files**: - - - **`app-instance-schema.json`**: Defines the schema for `example-customer.yml` - to be used with [Visual Studio Code (VS Code)](https://code.visualstudio.com/). - - **`example-customer.yml`**: Configuration for your InfluxDB cluster that includes - information about [prerequisites](/influxdb/clustered/install/prerequisites/). - - {{% note %}} - -This documentation refers to a `myinfluxdb.yml` file that you copy from -`example-customer.yml` and edit for your InfluxDB cluster. - - {{% /note %}} - -## Configuration data - -When ready to install InfluxDB, have the following information available: - -- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB API endpoints -- **PostgreSQL-style data source name (DSN)**: used to access your - PostgreSQL-compatible database that stores the InfluxDB Catalog. -- **Object store credentials** _(AWS S3 or S3-compatible)_ - - Endpoint URL - - Access key - - Bucket name - - Region (required for S3, may not be required for other object stores) -- **Local storage information** _(for ingester pods)_ - - Storage class - - Storage size -- **OAuth2 provider credentials** - - Client ID - - JWKS endpoint - - Device authorization endpoint - - Token endpoint - -InfluxDB is deployed to a Kubernetes namespace which, throughout the following -installation procedure, is referred to as the _target_ namespace. -For simplicity, we assume this namespace is `influxdb`, however -you may use any name you like. - -The InfluxDB installation, update, and upgrade processes are driven by editing -and applying a [Kubernetes custom resource (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) -called `AppInstance`. -The `AppInstance` CRD is defined in a YAML file (use `example-customer.yml` as a -template). - -The `AppInstance` resource contains key information, such as: - -- Name of the target namespace -- Version of the InfluxDB package -- Reference to the InfluxDB container registry pull secrets -- Hostname where the InfluxDB API is exposed -- Parameters to connect to [external prerequisites](/influxdb/clustered/install/prerequisites/) - -## Configure your cluster - -1. [Create a cluster configuration file](#create-a-cluster-configuration-file) -2. [Create a namespace for InfluxDB](#create-a-namespace-for-influxdb) -3. [Install kubecfg kubit operator](#install-kubecfg-kubit-operator) -4. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) -5. [Set up cluster ingress](#set-up-cluster-ingress) -6. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) -7. [Provide a custom certificate authority bundle](#provide-a-custom-certificate-authority-bundle) - (Optional) - -### Create a cluster configuration file - -Copy the provided `example-customer.yml` file to create a new configuration file -specific to your InfluxDB cluster. For example, `myinfluxdb.yml`. - - - -```sh -cp example-customer.yml myinfluxdb.yml -``` - -{{% note %}} - -#### Use VS Code to edit your configuration file - -We recommend using [Visual Studio Code (VS Code)](https://code.visualstudio.com/) to edit your `myinfluxdb.yml` configuration file due -to its JSON Schema support, autocompletion, and validation features that ensure the best experience when editing your InfluxDB configuration. -InfluxData provides an `app-instance-schema.json` JSON schema file that VS Code can use to validate your configuration settings. -{{% /note %}} - -### Create a namespace for InfluxDB - -Create a namespace for InfluxDB--for example, enter the following `kubectl` command in your terminal: - - - -```sh -kubectl create namespace influxdb -``` - -If you use a namespace name other than `influxdb`, update the `.metadata.namespace` -field in your `myinfluxdb.yml` to use your custom namespace name. - -### Install kubecfg kubit operator - -The [`kubecfg kubit` operator](https://github.com/kubecfg/kubit) (maintained by InfluxData) -simplifies the installation and management of the InfluxDB Clustered package. -It manages the application of the jsonnet templates used to install, manage, and -update an InfluxDB cluster. - -Use `kubectl` to install the [kubecfg kubit](https://github.com/kubecfg/kubit) operator. - - - -```sh -kubectl apply -k 'https://github.com/kubecfg/kubit//kustomize/global?ref=v0.0.19' -``` - -### Configure access to the InfluxDB container registry - -The provided `influxdb-docker-config.json` grants access to a collection of -container images required to run InfluxDB Clustered. -Your Kubernetes Cluster needs access to the container registry to pull down and -install InfluxDB. - -When pulling InfluxDB Clustered images, there are two main scenarios: - -- You have a Kubernetes cluster that can pull from the InfluxData container registry. -- You run in an environment with no network interfaces ("air-gapped") and you - can only access a private container registry. - -In both scenarios, you need a valid _pull secret_. - -{{< tabs-wrapper >}} -{{% tabs %}} -[Public registry (non-air-gapped)](#) -[Private registry (air-gapped)](#) -{{% /tabs %}} - -{{% tab-content %}} - - - -#### Public registry (non-air-gapped) - -To pull from the InfluxData registry, you need to create a Kubernetes secret in the target namespace. - -```sh -kubectl create secret docker-registry gar-docker-secret \ - --from-file=.dockerconfigjson=influxdb-docker-config.json \ - --namespace influxdb -``` - -If successful, the output is the following: - -```text -secret/gar-docker-secret created -``` - -By default, this secret is named `gar-docker-secret`. -If you change the name of this secret, you must also change the value of the -`imagePullSecret` field in the `AppInstance` custom resource to match. - - - -{{% /tab-content %}} -{{% tab-content %}} - - - -#### Private registry (air-gapped) - -If your Kubernetes cluster can't use a public network to download container images -from our container registry, do the following: - -1. Copy the images from the InfluxDB registry to your own private registry. -2. Configure your `AppInstance` resource with a reference to your private - registry name. -3. Provide credentials to your private registry. - -##### Copy the images - -We recommend using [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) to copy images into your private registry. - -1. [Install crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane#installation) for your system. -2. Use the following command to create a container registry secret file and - retrieve the necessary secrets: - -{{% code-placeholders "PACKAGE_VERSION" %}} - - - -```sh -mkdir /tmp/influxdbsecret -cp influxdb-docker-config.json /tmp/influxdbsecret/config.json -DOCKER_CONFIG=/tmp/influxdbsecret \ - crane manifest \ - us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION -``` - -{{% /code-placeholders %}} - ---- - -Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} -with your InfluxDB Clustered package version. - ---- - -If your Docker configuration is valid and you’re able to connect to the container -registry, the command succeeds and the output is the JSON manifest for the Docker -image, similar to the following: - -{{< expand-wrapper >}} -{{% expand "View JSON manifest" %}} - -```json -{ - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.kubecfg.bundle.config.v1+json", - "digest": "sha256:6900d2f248e678176c68f3768e7e48958bb96a59232070ff31b3b018cf299aa7", - "size": 8598 - }, - "layers": [ - { - "mediaType": "application/vnd.kubecfg.bundle.tar+gzip", - "digest": "sha256:7c1d62e76287035a9b22b2c155f328fae9beff2c6aa7a09a2dd2697539f41d98", - "size": 404059 - } - ], - "annotations": { - "org.opencontainers.image.created": "1970-01-01T00:00:00Z", - "org.opencontainers.image.revision": "unknown", - "org.opencontainers.image.source": "kubecfg pack" - } -} -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -If there’s a problem with the Docker configuration, crane won't retrieve the manifest and the output is similar to the following error: - -```sh -Error: fetching manifest us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:: GET https://us-docker.pkg.dev/v2/token?scope=repository%3Ainfluxdb2-artifacts%2Fclustered%2Finfluxdb%3Apull&service=: DENIED: Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/influxdb2-artifacts/locations/us/repositories/clustered" (or it may not exist) -``` - -The list of images that you need to copy is included in the package metadata. -You can obtain it with any standard OCI image inspection tool--for example: - -{{% code-placeholders "PACKAGE_VERSION" %}} - - - -```sh -DOCKER_CONFIG=/tmp/influxdbsecret \ -crane config \ - us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION \ - | jq -r '.metadata["oci.image.list"].images[]' \ - > /tmp/images.txt -``` - -{{% /code-placeholders %}} - -The output is a list of image names, similar to the following: - -``` -us-docker.pkg.dev/influxdb2-artifacts/idpe/idpe-cd-ioxauth@sha256:5f015a7f28a816df706b66d59cb9d6f087d24614f485610619f0e3a808a73864 -us-docker.pkg.dev/influxdb2-artifacts/iox/iox@sha256:b59d80add235f29b806badf7410239a3176bc77cf2dc335a1b07ab68615b870c -... -``` - -Use `crane` to copy the images to your private registry: - -{{% code-placeholders "REGISTRY_HOSTNAME" %}} - - - -```sh - - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -### Set up cluster ingress - -{{% note %}} -InfluxDB Clustered components use gRPC/HTTP2 protocols. If using an external load balancer, -you may need to explicitly enable these protocols on your load balancers. -{{% /note %}} - -[Kubernetes ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) routes HTTP/S requests to services within the cluster and requires deploying an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). - -You can provide your own ingress or you can install [Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx) to use the InfluxDB-defined ingress. - -If using the InfluxDB-defined ingress, add a valid TLS Certificate to the -cluster as a secret. Provide the paths to the TLS certificate file and key file: - -{{% code-placeholders "TLS_(CERT|KEY)_PATH" %}} - - - -```sh -kubectl create secret tls ingress-tls \ - --namespace influxdb \ - --cert TLS_CERT_PATH \ - --key TLS_KEY_PATH -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- _{{% code-placeholder-key %}}`TLS_CERT_PATH`{{% /code-placeholder-key %}}: - Path to the certificate file on your local machine._ -- _{{% code-placeholder-key %}}`TLS_KEY_PATH`{{% /code-placeholder-key %}}: - Path to the certificate secret key file on your local machine._ - ---- - -Provide the TLS certificate secret to the InfluxDB configuration in the -[Configure ingress step](#configure-ingress). - -### Modify the configuration file to point to prerequisites - -Update your `myinfluxdb.yml` configuration file with credentials necessary to -connect your cluster to your prerequisites. - -- [Configure ingress](#configure-ingress) -- [Configure the object store](#configure-the-object-store) -- [Configure the catalog database](#configure-the-catalog-database) -- [Configure local storage for ingesters](#configure-local-storage-for-ingesters) -- [Configure your OAuth2 provider](#configure-your-oauth2-provider) -- [Configure the size of your cluster](#configure-the-size-of-your-cluster) - -#### Configure ingress - -To configure ingress, provide values for the following fields in your -`myinfluxdb.yml` configuration file: - -- **`spec.package.spec.ingress.hosts`: Cluster hostnames** - - Provide the hostnames that Kubernetes should - use to expose the InfluxDB API endpoints. - For example: `{{< influxdb/host >}}`. - - _You can provide multiple hostnames. The ingress layer accepts incoming - requests for all listed hostnames. This can be useful if you want to have - distinct paths for your internal and external traffic._ - - {{% note %}} - You are responsible for configuring and managing DNS. Options include: - -- Manually managing DNS records -- Using [external-dns](https://github.com/kubernetes-sigs/external-dns) to - synchronize exposed Kubernetes services and ingresses with DNS providers. - {{% /note %}} - -- **`spec.package.spec.ingress.tlsSecretName`: TLS certificate secret name** - - Provide the name of the secret that - [contains your TLS certificate and key](#set-up-cluster-ingress). - The examples in this guide use the name `ingress-tls`. - - _The `tlsSecretName` field is optional. You may want to use it if you already have a TLS certificate for your DNS name._ - - {{< expand-wrapper >}} - {{% expand "Use cert-manager and Let's Encrypt to manage TLS certificates" %}} - -If you instead want to automatically create an [ACME](https://datatracker.ietf.org/doc/html/rfc8555) -certificate (for example, using [Let's Encrypt](https://letsencrypt.org/)), refer -to the [cert-manager documentation](https://cert-manager.io/docs/usage/ingress/) -for more details on how to annotate the `Ingress` resource produced by the -InfluxDB installer operator. The operator lets you to add annotations -(with `kubectl annotate`) and preserves them as it operates on resources. - -{{% note %}} -If you choose to use cert-manager, it's your responsibility to install and configure it. -{{% /note %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: -# ... -ingress: - hosts: - - {{< influxdb/host >}} - tlsSecretName: ingress-tls -``` - -{{% /code-callout %}} - -#### Configure the object store - -To connect your InfluxDB cluster to your object store, provide values for the -following fields in your `myinfluxdb.yml` configuration file: - -- `spec.package.spec.objectStore` - - `.endpoint`: Object storage endpoint URL - - `.allowHttp`: _Set to `true` to allow unencrypted HTTP connections_ - - `.accessKey.value`: Object storage access key - - `.secretKey.value`: Object storage secret key - - `.bucket`: Object storage bucket name - - `.region`: Object storage region - -{{% code-placeholders "S3_(URL|ACCESS_KEY|SECRET_KEY|BUCKET_NAME|REGION)" %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - objectStore: - # URL for S3 Compatible object store - endpoint: S3_URL - - # Set to true to allow communication over HTTP (instead of HTTPS) - allowHttp: 'false' - - # S3 Access Key - # This can also be provided as a valueFrom: secretKeyRef: - accessKey: - value: S3_ACCESS_KEY - - # S3 Secret Key - # This can also be provided as a valueFrom: secretKeyRef: - secretKey: - value: S3_SECRET_KEY - - # Bucket that the Parquet files will be stored in - bucket: S3_BUCKET_NAME - - # This value is required for AWS S3, it may or may not be required for other providers. - region: S3_REGION -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`S3_URL`{{% /code-placeholder-key %}}: Object storage endpoint URL -- {{% code-placeholder-key %}}`S3_ACCESS_KEY`{{% /code-placeholder-key %}}: Object storage access key -- {{% code-placeholder-key %}}`S3_SECRET_KEY`{{% /code-placeholder-key %}}: Object storage secret key -- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Object storage bucket name -- {{% code-placeholder-key %}}`S3_REGION`{{% /code-placeholder-key %}}: Object storage region - ---- - -#### Configure the catalog database - -The InfluxDB catalog is a PostgreSQL-compatible relational database that stores -metadata about your time series data. -To connect your InfluxDB cluster to your PostgreSQL-compatible database, -provide values for the following fields in your `myinfluxdb.yml` configuration file: - -{{% note %}} -We recommend storing sensitive credentials, such as your PostgreSQL-compatible DSN, -as secrets in your Kubernetes cluster. -{{% /note %}} - -{{% warn %}} -#### Percent-encode special symbols in PostgreSQL DSNs - -Special symbols in PostgreSQL DSNs should be percent-encoded to ensure they -are parsed correctly by InfluxDB Clustered. This is important to consider when -using DSNs containing auto-generated passwords which may include special -symbols to make passwords more secure. - -For example, the following DSN used in InfluxDB Clustered: - -```txt -postgresql://postgres:meow#meow@my-fancy.cloud-database.party:5432/postgres -``` - -Would result in an error similar to: - -```txt -Catalog DSN error: A catalog error occurred: unhandled external error: error with configuration: invalid port number -``` - -To fix this, percent-encode special symbols in the connection string: - -```txt -postgresql://postgres:meow%23meow@my-fancy.cloud-database.party:5432/postgres -``` - -For more information, see the [PostgreSQL Connection URI -docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS). -{{% /warn %}} - -- [ ] `spec.package.spec.catalog.dsn.valueFrom.secretKeyRef` - - [ ] `.name`: Secret name - - [ ] `.key`: Key in the secret that contains the DSN - -{{% code-placeholders "SECRET_(NAME|KEY)" %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - catalog: - # A postgresql style DSN that points to a postgresql compatible database. - # postgres://[user[:password]@][netloc][:port][/dbname][?param1=value1&...] - dsn: - valueFrom: - secretKeyRef: - name: SECRET_NAME - key: SECRET_KEY -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`SECRET_NAME`{{% /code-placeholder-key %}}: - Name of the secret containing your PostgreSQL-compatible DSN -- {{% code-placeholder-key %}}`SECRET_KEY`{{% /code-placeholder-key %}}: - Key in the secret that references your PostgreSQL-compatible DSN - ---- - -{{% note %}} - -##### PostgreSQL instances without TLS or SSL - -If your PostgreSQL-compatible instance runs without TLS or SSL, you must include -the `sslmode=disable` parameter in the DSN. For example: - -{{% code-callout "sslmode=disable" %}} - -``` -postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable -``` - -{{% /code-callout %}} -{{% /note %}} - -#### Configure local storage for ingesters - -InfluxDB ingesters require local storage to store the Write Ahead Log (WAL) for -incoming data. -To connect your InfluxDB cluster to local storage, provide values for the -following fields in your `myinfluxdb.yml` configuration file: - -- `spec.package.spec.ingesterStorage` - - `.storageClassName`: [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). - This differs based on the Kubernetes environment and desired storage characteristics. - - `storage`: Storage size. We recommend a minimum of 2 gibibytes (`2Gi`). - -{{% code-placeholders "STORAGE_(CLASS|SIZE)" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - ingesterStorage: - storageClassName: STORAGE_CLASS - storage: STORAGE_SIZE -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`STORAGE_CLASS`{{% /code-placeholder-key %}}: - [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) -- {{% code-placeholder-key %}}`STORAGE_SIZE`{{% /code-placeholder-key %}}: - Storage size (example: `2Gi`) - ---- - -#### Configure your OAuth2 provider - -InfluxDB Clustered uses OAuth2 to authenticate administrative access to your cluster. -To connect your InfluxDB cluster to your OAuth2 provide, provide values for the -following fields in your `myinfluxdb.yml` configuration file: - -- `spec.package.spec.admin` - - `identityProvider`: Identity provider name. - _If using Microsoft Entra ID (formerly Azure Active Directory), set the name - to `azure`_. - - `jwksEndpoint`: JWKS endpoint provide by your identity provider. - - `users`: List of OAuth2 users to grant administrative access to your - InfluxDB cluster. IDs are provided by your identity provider. - -Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but -other OAuth2 providers should work as well: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Keycloak](#) -[Auth0](#) -[Microsoft Entra ID](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -{{% code-callout "keycloak" "green" %}} -{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - admin: - identityProvider: keycloak - jwksEndpoint: |- - https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Keycloak. - - id: KEYCLOAK_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: - Host and port of your Keycloak server -- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: - Keycloak realm -- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: - Keycloak user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "auth0" "green" %}} -{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - admin: - identityProvider: auth0 - jwksEndpoint: |- - https://AUTH0_HOST/.well-known/openid-configuration - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Auth0. - - id: AUTH0_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: - Host and port of your Auth0 server -- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: - Auth0 user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "azure" "green" %}} -{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - admin: - identityProvider: azure - jwksEndpoint: |- - https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Azure. - - id: AZURE_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: - Microsoft Entra tenant ID -- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: - Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ - ---- - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -##### Add users - -Finally, to give users access to use `influxctl`, add the list of users to the -`spec.package.spec.admin.users` field. -See [Manage users](/influxdb/clustered/admin/users/) for more details. - -#### Configure the size of your cluster - -##### Default scale settings - -- **3 ingesters**: - Ensures redundancy on the write path. -- **1 compactor**: - While you can have multiple compactors, it is more efficient to scale the - compactor vertically (assign more CPU and memory) rather than horizontally - (increase the number of compactors). -- **1 querier**: - The optimal number of queriers depends on the number of concurrent queries you are - likely to have and how long they take to execute. - -The default values provide a good starting point for testing. -Once you have your cluster up and running and are looking for scaling recommendations -for your anticipated workload, -please [contact the InfluxData Support team](https://support.influxdata.com). - -##### Customize scale settings - -**To use custom scale settings for your InfluxDB cluster**, edit values for the following fields -in your `myinfluxdb.yml`. If omitted, your cluster uses the default scale settings. - -- `spec.package.spec.resources` - - `ingester.requests` - - `cpu`: CPU resource units to assign to ingesters - - `memory`: Memory resource units to assign to ingesters - - `replicas`: Number of ingester replicas to provision - - `compactor.requests` - - `cpu`: CPU resource units to assign to compactors - - `memory`: Memory resource units to assign to compactors - - `replicas`: Number of compactor replicas to provision - - `querier.requests` - - `cpu`: CPU resource units to assign to queriers - - `memory`: Memory resource units to assign to queriers - - `replicas`: Number of querier replicas to provision - - `router.requests` - - `cpu`: CPU resource units to assign to routers - - `memory`: Memory resource units to assign to routers - - `replicas`: Number of router replicas to provision - -###### Related Kubernetes documentation - -- [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) -- [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) - -{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(CPU|MEMORY|REPLICAS)" %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - # The following settings tune the various pods for their cpu/memory/replicas - # based on workload needs. Only uncomment the specific resources you want - # to change. Anything left commented will use the package default. - resources: - # The ingester handles data being written - ingester: - requests: - cpu: INGESTER_CPU - memory: INGESTER_MEMORY - replicas: INGESTER_REPLICAS # Default is 3 - - # The compactor reorganizes old data to improve query and storage efficiency. - compactor: - requests: - cpu: COMPACTOR_CPU - memory: COMPACTOR_MEMORY - replicas: COMPACTOR_REPLICAS # Default is 1 - - # The querier handles querying data. - querier: - requests: - cpu: QUERIER_CPU - memory: QUERIER_MEMORY - replicas: QUERIER_REPLICAS # Default is 1 - - # The router performs some api routing. - router: - requests: - cpu: ROUTER_CPU - memory: ROUTER_MEMORY - replicas: ROUTER_REPLICAS # Default is 1 -``` - -{{% /code-placeholders %}} - -### Provide a custom certificate authority bundle {note="Optional"} - -InfluxDB attempts to make TLS connections to the services it depends on--notably, -the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) -and the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). -InfluxDB validates certificates for all connections. - -_If you host dependent services yourself and you use a private or otherwise not -well-known certificate authority to issue certificates to them, -InfluxDB won't recognize the issuer and can't validate the certificates._ -To allow InfluxDB to validate the certificates from your custom CA, -configure the `AppInstance` resource to use a **PEM certificate -bundle** that contains your custom certificate authority chain. - -1. Use `kubectl` to create a config map that contains your PEM-formatted - certificate bundle file. - Your certificate authority administrator should provide you with a - PEM-formatted bundle file. - - {{% note %}} -This PEM bundle file establishes a chain of trust for the -external services that InfluxDB depends on. -It's *not* the certificate that InfluxDB uses to -host its own TLS endpoints. - {{% /note %}} - - In the example, replace `/path/to/private_ca.pem` with the path to your PEM-formatted certificate bundle file: - - - - ```sh - kubectl --namespace influxdb create configmap custom-ca --from-file=certs.pem=/path/to/private_ca.pem - ``` - - {{% note %}} -#### Bundle multiple certificates - -You can append multiple certificates into the same bundle. -This approach helps when you need to include intermediate certificates or explicitly include leaf certificates. - -Include certificates in the bundle in the following order: - -1. Leaf certificates -2. Intermediate certificates required by leaf certificates -3. Root certificate - {{% /note %}} - -2. In `myinfluxdb.yml`, update the `.spec.package.spec.egress` field to refer - to the config map that you generated in the preceding step--for example: - - ```yml - spec: - package: - spec: - egress: - customCertificates: - valueFrom: - configMapKeyRef: - key: ca.pem - name: custom-ca - ``` - -{{< page-nav prev="/influxdb/clustered/install/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/licensing/" nextText="Install your license" >}} diff --git a/content/influxdb/clustered/install/customize-cluster/_index.md b/content/influxdb/clustered/install/customize-cluster/_index.md new file mode 100644 index 0000000000..1a9f92e45d --- /dev/null +++ b/content/influxdb/clustered/install/customize-cluster/_index.md @@ -0,0 +1,29 @@ +--- +title: Customize your InfluxDB cluster +description: > + Customize the scale and configuration of your cluster to best suit your workload. +menu: + influxdb_clustered: + name: Customize your cluster + parent: Install InfluxDB Clustered +weight: 102 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 2: Customize your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 2 +related: + - /influxdb/clustered/admin/scale-cluster/ + - /influxdb/clustered/admin/env-vars/ +--- + +This phase of the installation process customizes the scale and configuration of +your InfluxDB cluster to meet the needs of your specific workload. + +## Phase 2 steps + +{{< children type="ordered-list" >}} + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/test-cluster/" prevText="Test your cluster" next="/influxdb/clustered/install/customize-cluster/scale/" nextText="Customize cluster scale" >}} diff --git a/content/influxdb/clustered/install/customize-cluster/config.md b/content/influxdb/clustered/install/customize-cluster/config.md new file mode 100644 index 0000000000..9d5f37cee9 --- /dev/null +++ b/content/influxdb/clustered/install/customize-cluster/config.md @@ -0,0 +1,148 @@ +--- +title: Customize your cluster configuration +seotitle: Customize the configuration of your InfluxDB cluster +description: > + Customize the configuration of your InfluxDB cluster to best suit your workload. +menu: + influxdb_clustered: + name: Customize cluster configuration + parent: Customize your cluster +weight: 202 +related: + - /influxdb/clustered/admin/env-vars/ +--- + +Use environment variables to customize configuration options for components in +your InfluxDB cluster. + +{{< tabs-wrapper >}} +{{% tabs "medium" %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +In your `AppInstance` resource, configure environment variables for individual +components in the +`spec.package.spec.components..template.containers.iox.env` property. +The following InfluxDB Clustered components are configurable: + +- `ingester` +- `querier` +- `router` +- `compactor` +- `garbage-collector` + +In the `env` property, structure each environment variable as a key-value pair +where the key is the environment variable name and the value is the environment +variable value (string-formatted)--for example: + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '4500' + INFLUXDB_IOX_MAX_HTTP_REQUEST_SIZE: '52428800' +``` + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +In your `values.yaml`, configure environment variables for individual components +in the `components..template.containers.iox.env` property. +The following InfluxDB Clustered components are configurable: + +- `ingester` +- `querier` +- `router` +- `compactor` +- `garbage-collector` + +In the `env` property, structure each environment variable as a key-value pair +where the key is the environment variable name and the value is the environment +variable value (string-formatted)--for example: + +```yaml +components: + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '4500' + INFLUXDB_IOX_MAX_HTTP_REQUEST_SIZE: '52428800' +``` + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +For more information, see +[Manage environment variables in your InfluxDB Cluster](/influxdb/clustered/admin/env-vars/). + +{{% note %}} +#### Configurable settings + +For information about what settings are configurable and their associated +environment variables, [contact InfluxData Support](https://support.influxdata.com). +{{% /note %}} + + + +## Apply the changes to your cluster + +Use `kubectl` or `helm` (if using the InfluxDB Clustered Helm chart), to apply +the changes to your cluster: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{< page-nav prev="content/influxdb/clustered/install/customize-cluster/scale/" prevText="Customize cluster scale" next="/influxdb/clustered/install/optimize-cluster/" nextText="Phase 3: Optimize your cluster" >}} diff --git a/content/influxdb/clustered/install/customize-cluster/scale.md b/content/influxdb/clustered/install/customize-cluster/scale.md new file mode 100644 index 0000000000..06ae79a5b4 --- /dev/null +++ b/content/influxdb/clustered/install/customize-cluster/scale.md @@ -0,0 +1,336 @@ +--- +title: Customize your cluster scale +seotitle: Customize the scale of your InfluxDB cluster +description: > + Customize the scale of your cluster to best suit your workload. +menu: + influxdb_clustered: + name: Customize cluster scale + parent: Customize your cluster +weight: 201 +related: + - /influxdb/clustered/admin/scale-cluster/ +--- + +InfluxDB Clustered lets you scale each component in your cluster individually, +so you can customize your cluster's scale to address the specific the specific +needs of your workload. +For example, if you have a heavy write workload, but not a heavy query workload, +you can scale your Router and Ingester both [vertically](/influxdb/clustered/admin/scale-cluster/#vertical-scaling) +and [horizontally](/influxdb/clustered/admin/scale-cluster/#horizontal-scaling) +to increase your write throughput and latency. + +## Default scale settings + +- **1 router**: + Additional routers increase your cluster's ability to handle concurrent write + requests. +- **3 ingesters**: + Ensures redundancy on the write path. +- **1 querier**: + The optimal number of queriers depends on the number of concurrent queries you + are likely to have and how long they take to execute. +- **1 compactor**: + While you can have multiple compactors, it is more efficient to scale the + compactor vertically (assign more CPU and memory) rather than horizontally + (increase the number of compactors). +- **1 garbage collector**: + The garbage collector is a light-weight process that only needs to be scaled + vertically when you observe high resource usage by the garbage collector. + _The garbage collector cannot be scaled horizontally._ + +The default values provide a good starting point for testing. +Once you have your cluster up and running and are looking for scaling +recommendations for your anticipated workload, please +[contact the InfluxData Support team](https://support.influxdata.com) to help you +identify appropriate scale settings based on +your anticipated workload. + +## Customize scale settings + +Your `AppInstance` resource controls the scale of components in your InfluxDB +cluster. You can edit the `AppInstance` resource directly or, if using the +[InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered) +to manage your deployment, you can edit resource settings in your `values.yaml`. + +{{% note %}} +_For specific scaling recommendations and guidelines, see +[Scale your cluster](/influxdb/clustered/admin/scale-cluster/)._ +{{% /note %}} + +With Kubernetes, you can define the minimum resources and the resource limits for each component. + +{{< tabs-wrapper >}} +{{% tabs "medium" %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +**To use custom scale settings for your InfluxDB cluster**, edit values for the +following fields in your `myinfluxdb.yml`. +If omitted, your cluster uses the default scale settings. + +- `spec.package.spec.resources` + - `ingester` + - `requests` + - `cpu`: Minimum CPU resource units to assign to ingesters + - `memory`: Minimum memory resource units to assign to ingesters + - `replicas`: Number of ingester replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to ingesters + - `memory`: Maximum memory resource units to assign to ingesters + - `compactor` + - `requests` + - `cpu`: Minimum CPU resource units to assign to compactors + - `memory`: Minimum memory resource units to assign to compactors + - `replicas`: Number of compactor replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to compactors + - `memory`: Maximum memory resource units to assign to compactors + - `querier` + - `requests` + - `cpu`: Minimum CPU resource units to assign to queriers + - `memory`: Minimum memory resource units to assign to queriers + - `replicas`: Number of querier replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to queriers + - `memory`: Maximum memory resource units to assign to queriers + - `router` + - `requests` + - `cpu`: Minimum CPU resource units to assign to routers + - `memory`: Minimum memory resource units to assign to routers + - `replicas`: Number of router replicas to provision + - `limits` + - `cpu`: Maximum CPU Resource units to assign to routers + - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector + +{{< expand-wrapper >}} +{{% expand "View example `AppInstance` with resource requests and limits" %}} + +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + # The following settings tune the various pods for their cpu/memory/replicas + # based on workload needs. Only uncomment the specific resources you want + # to change. Anything left commented will use the package default. + resources: + ingester: + requests: + cpu: INGESTER_CPU_MIN + memory: INGESTER_MEMORY_MIN + replicas: INGESTER_REPLICAS # Default is 3 + limits: + cpu: INGESTER_CPU_MAX + memory: INGESTER_MEMORY_MAX + compactor: + requests: + cpu: COMPACTOR_CPU_MIN + memory: COMPACTOR_MEMORY_MIN + replicas: COMPACTOR_REPLICAS # Default is 1 + limits: + cpu: COMPACTOR_CPU_MAX + memory: COMPACTOR_MEMORY_MAX + querier: + requests: + cpu: QUERIER_CPU_MIN + memory: QUERIER_MEMORY_MIN + replicas: QUERIER_REPLICAS # Default is 1 + limits: + cpu: QUERIER_CPU_MAX + memory: QUERIER_MEMORY_MAX + router: + requests: + cpu: ROUTER_CPU_MIN + memory: ROUTER_MEMORY_MIN + replicas: ROUTER_REPLICAS # Default is 1 + limits: + cpu: ROUTER_CPU_MAX + memory: ROUTER_MEMORY_MAX + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +**To use custom scale settings for your InfluxDB cluster**, modify the following fields +in your `values.yaml`. If omitted, your cluster will use the default scale settings. + +- `resources` + - `ingester` + - `requests` + - `cpu`: Minimum CPU resource units to assign to ingesters + - `memory`: Minimum memory resource units to assign to ingesters + - `replicas`: Number of ingester replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to ingesters + - `memory`: Maximum memory resource units to assign to ingesters + - `compactor` + - `requests` + - `cpu`: Minimum CPU resource units to assign to compactors + - `memory`: Minimum memory resource units to assign to compactors + - `replicas`: Number of compactor replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to compactors + - `memory`: Maximum memory resource units to assign to compactors + - `querier` + - `requests` + - `cpu`: Minimum CPU resource units to assign to queriers + - `memory`: Minimum memory resource units to assign to queriers + - `replicas`: Number of querier replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to queriers + - `memory`: Maximum memory resource units to assign to queriers + - `router` + - `requests` + - `cpu`: Minimum CPU resource units to assign to routers + - `memory`: Minimum memory resource units to assign to routers + - `replicas`: Number of router replicas to provision + - `limits` + - `cpu`: Maximum CPU Resource units to assign to routers + - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector + +{{< expand-wrapper >}} +{{% expand "View example `values.yaml` with resource requests and limits" %}} + +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} + +```yml +# The following settings tune the various pods for their cpu/memory/replicas +# based on workload needs. Only uncomment the specific resources you want +# to change. Anything left commented will use the package default. +resources: + # The ingester handles data being written + ingester: + requests: + cpu: INGESTER_CPU_MIN + memory: INGESTER_MEMORY_MIN + replicas: INGESTER_REPLICAS # Default is 3 + limits: + cpu: INGESTER_CPU_MAX + memory: INGESTER_MEMORY_MAX + + # The compactor reorganizes old data to improve query and storage efficiency. + compactor: + requests: + cpu: COMPACTOR_CPU_MIN + memory: COMPACTOR_MEMORY_MIN + replicas: COMPACTOR_REPLICAS # Default is 1 + limits: + cpu: COMPACTOR_CPU_MAX + memory: COMPACTOR_MEMORY_MAX + + # The querier handles querying data. + querier: + requests: + cpu: QUERIER_CPU_MIN + memory: QUERIER_MEMORY_MIN + replicas: QUERIER_REPLICAS # Default is 1 + limits: + cpu: QUERIER_CPU_MAX + memory: QUERIER_MEMORY_MAX + + # The router performs some API routing. + router: + requests: + cpu: ROUTER_CPU_MIN + memory: ROUTER_MEMORY_MIN + replicas: ROUTER_REPLICAS # Default is 1 + limits: + cpu: ROUTER_CPU_MAX + memory: ROUTER_MEMORY_MAX + + # The garbage collector evicts obsolete data and files + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +##### Related Kubernetes documentation + +- [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) +- [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) + +## Apply the changes to your cluster + +Use `kubectl` or `helm` (if using the InfluxDB Clustered Helm chart), to apply +the changes to your cluster: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{< page-nav prev="content/influxdb/clustered/install/customize-cluster/" prevText="Customize your cluster" next="/influxdb/clustered/install/customize-cluster/config/" nextText="Customize cluster configuration" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/_index.md b/content/influxdb/clustered/install/optimize-cluster/_index.md new file mode 100644 index 0000000000..1011202a8d --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/_index.md @@ -0,0 +1,46 @@ +--- +title: Optimize your InfluxDB cluster +description: > + Test your cluster with a production-like workload and optimize your cluster + for your workload. +menu: + influxdb_clustered: + name: Optimize your cluster + parent: Install InfluxDB Clustered +weight: 103 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 3: Optimize your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 3 +--- + +The goal of this phase of the installation process is to simulate a +production-like workload against your InfluxDB cluster and make changes to +optimize your cluster for your workload. + +{{% note %}} +Depending on your requirements, this phase is likely to take the longest of all +the installation phases. +{{% /note %}} + +## Identify performance requirements {note="Recommended"} + +Before beginning this process, we recommend identifying performance requirements +and goals--for example: + +- Writes per second +- Query concurrency +- Query response time + +This gives specific metrics to test for and make adjustments towards. +Consult with [InfluxData support](https://support.influxdata.com) as you make +changes to meet these requirements and goals. + +## Phase 3 process + +{{< children type="ordered-list" >}} + +{{< page-nav prev="/influxdb/clustered/install/customize-cluster/config/" prevText="Customize cluster configuration" next="/influxdb/clustered/install/optimize-cluster/design-schema/" nextText="Design your schema" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/design-schema.md b/content/influxdb/clustered/install/optimize-cluster/design-schema.md new file mode 100644 index 0000000000..89c9ecf01b --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/design-schema.md @@ -0,0 +1,87 @@ +--- +title: Design your schema +description: > + Use schema design guidelines to improve write and query performance in your + InfluxDB cluster. +menu: + influxdb_clustered: + name: Design your schema + parent: Optimize your cluster +weight: 201 +related: + - /influxdb/clustered/write-data/best-practices/schema-design/ +--- + +Schema design can have a significant impact on both write and query performance +in your InfluxDB cluster. The items below cover high-level considerations and +recommendation. For detailed recommendations, see +[Schema design recommendations](/influxdb/clustered/write-data/best-practices/schema-design/). + +## Understand the difference between tags and fields + +In the [InfluxDB data structure](/influxdb/clustered/write-data/best-practices/schema-design/#influxdb-data-structure), +there are three main "categories" of information--timestamps, tags, and fields. +Understanding the difference between what should be a tag and what should be a +field is important when designing your schema. + +Use the following guidelines to determine what should be tags versus fields: + +- Use tags to store metadata that provides information about the source or + context of the data. +- Use fields to store measured values. +- Field values typically change over time. Tag values do not. +- Tag values can only be strings. +- Field values can be any of the following data types: + - Integer + - Unsigned integer + - Float + - String + - Boolean + +For more information, see [Tags versus fields](/influxdb/clustered/write-data/best-practices/schema-design/#tags-versus-fields). + +## Schema restrictions + +InfluxDB enforces the following schema restrictions: + +- You cannot use the same name for a tag and a field in the same table. +- By default, a table can have up to 250 columns. + +For more information, see [InfluxDB schema restrictions](/influxdb/clustered/write-data/best-practices/schema-design/#schema-restrictions). + +## Design for performance + +The following guidelines help to ensure write and query performance: + +{{% caption %}} +Follow the links below for more detailed information. +{{% /caption %}} + +- [Avoid wide schemas](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-wide-schemas): + A wide schema is one with a large number of columns (tags and fields). +- [Avoid sparse schemas](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-sparse-schemas): + A sparse schema is one where, for many rows, columns contain null values. +- [Keep table schemas homogenous](/influxdb/clustered/write-data/best-practices/schema-design/#table-schemas-should-be-homogenous): + A homogenous table schema is one where every row has values for all tags and fields. +- [Use the best data type for your data](/influxdb/clustered/write-data/best-practices/schema-design/#use-the-best-data-type-for-your-data): + Write integers as integers, decimals as floats, and booleans as booleans. + Queries against a field that stores integers outperforms a query against string data. + +## Design for query simplicity + +The following guidelines help to ensure that, when querying data, the schema +makes it easy to write queries: + +{{% caption %}} +Follow the links below for more detailed information. +{{% /caption %}} + +- [Keep table names, tags, and fields simple](/influxdb/clustered/write-data/best-practices/schema-design/#keep-table-names-tags-and-fields-simple): + Use one tag or one field for each data attribute. + If your source data contains multiple data attributes in a single parameter, + split each attribute into its own tag or field. +- [Avoid keywords and special characters](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-keywords-and-special-characters): + Reserved keywords or special characters in table names, tag keys, and field + keys makes writing queries more complex. + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/" prevText="Optimize your cluster" next="/influxdb/clustered/install/optimize-cluster/write-methods/" nextText="Identify write methods" >}} \ No newline at end of file diff --git a/content/influxdb/clustered/install/optimize-cluster/optimize-querying.md b/content/influxdb/clustered/install/optimize-cluster/optimize-querying.md new file mode 100644 index 0000000000..bd077c75a2 --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/optimize-querying.md @@ -0,0 +1,94 @@ +--- +title: Optimize querying +seotitle: Optimize querying in your InfluxDB cluster +description: > + Define your typical query patterns and employ optimizations to ensure query + performance. +menu: + influxdb_clustered: + name: Optimize querying + parent: Optimize your cluster +weight: 204 +related: + - /influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/ + - /influxdb/clustered/admin/custom-partitions/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/ +--- + +With data written to your cluster, you can now begin to define and test your +typical query patterns and employ optimizations to ensure query performance. + +## Define your query patterns + +Understanding your typical query patterns helps prioritize optimizations to meet your query performance requirements. + +For example, consider the following questions: + +- **Do you typically query data by a specific tag values?** + [Apply custom partitioning](/influxdb/clustered/admin/custom-partitions/) to + your target database or table to partition by those tags. Partitioning by + commonly queried tags helps InfluxDB to quickly identify where the relevant + data is in storage and improves query performance. +- **Do you query tables with [wide schemas](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-wide-schemas)?** + Avoid using wildcards (`*`) in your `SELECT` statement. Select specific + columns you want returned in your query results. The more columns queried, the + less performant the query. +- **Do you query large, historical time ranges?** + Use [time-based aggregation methods to downsample your data](/influxdb/clustered/query-data/sql/aggregate-select/#downsample-data-by-applying-interval-based-aggregates) and return aggregate + values per interval of time instead of all the data. + +## Decide on your query language + +InfluxDB Clustered supports both [SQL](/influxdb/clustered/reference/sql/) and +[InfluxQL](/influxdb/clustered/reference/influxql/)--a SQL-like query language +designed for InfluxDB v1 and specifically querying time series data. + +### SQL + +The InfluxDB SQL implementation is a full-featured SQL query engine powered by +[Apache DataFusion](https://datafusion.apache.org/). It benefits from a robust +upstream community that is constantly improving the features and performance +of the engine. Some time series-specific queries (such as time-based aggregates) +are more verbose in SQL than in InfluxQL, but they are still possible. + +### InfluxQL + +InfluxQL is designed specifically for time series data and simplifies many +time series-related operations like aggregating based on time, technical +analysis, and forecasting. It isn't as full-featured as SQL and requires some +understanding of the InfluxDB v1 data model. + +## Optimize your queries + +View the [query optimization and troubleshooting documentation](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/) +for guidance and information on how to troubleshoot and optimize queries that do +not perform as expected. + +### Analyze queries + +Both SQL and InfluxQL support the `EXPLAIN` and `EXPLAIN ANALYZE` statements +that return detailed information about your query's planning and execution. +This can provide insight into possible optimizations you can make for a specific +query. For more information, see +[Analyze a query plan](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/). + +## Custom-partition data + +InfluxDB Clustered lets you define how data is stored to ensure queries are +performant. [Custom partitioning](/influxdb/clustered/admin/custom-partitions/) +lets you define how InfluxDB partitions data and can be used to structure your +data so it's easier for InfluxDB to identify where the data you typically query +is in storage. For more information, see +[Manage data partitioning](/influxdb/clustered/admin/custom-partitions/). + +## Report query performance issues + +If you have a query that isn't meeting your performance requirements despite +implementing query optimizations, please following the process described in +[Report query performance issues](/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/) +to gather information for InfluxData engineers so they can help identify any +potential solutions. + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/simulate-load/" prevText="Simulate load" next="/influxdb/clustered/install/secure-cluster/" nextText="Phase 4: Secure your cluster" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/simulate-load.md b/content/influxdb/clustered/install/optimize-cluster/simulate-load.md new file mode 100644 index 0000000000..bb3fb19d39 --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/simulate-load.md @@ -0,0 +1,36 @@ +--- +title: Simulate a production-like load +description: > + Simulate a production-like load that writes data to your InfluxDB cluster. +menu: + influxdb_clustered: + name: Simulate load + parent: Optimize your cluster +weight: 203 +--- + +With your schema defined you can begin to simulate a production-like load that +writes data to your InfluxDB cluster. This process helps to ensure that your +schema works as designed and that both your cluster's scale and configuration +are able to meet your cluster's write requirements. + +{{% warn %}} +We do not recommend writing production data to your InfluxDB cluster at this point. +{{% /warn %}} + +## Load testing tools + +Contact your [InfluxData sales representative](https://influxdata.com/contact-sales) +for information about load testing tools. +These tools can simulate your schema and +desired write concurrency to ensure your cluster performs under production-like load. + + + +## Use your own tools + +You can also build and use your own tools to load test a production-like workload. +Use Telegraf, client libraries, or the InfluxDB API to build out tests that +simulate writes to your cluster. + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/write-methods/" prevText="Identify write methods" next="/influxdb/clustered/install/optimize-cluster/optimize-querying/" nextText="Optimize querying" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/write-methods.md b/content/influxdb/clustered/install/optimize-cluster/write-methods.md new file mode 100644 index 0000000000..3120c0a3bb --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/write-methods.md @@ -0,0 +1,125 @@ +--- +title: Identify write methods +seotitle: Identify methods for writing to your InfluxDB cluster +description: + Identify the most appropriate and useful tools and methods for writing data to + your InfluxDB cluster. +menu: + influxdb_clustered: + name: Identify write methods + parent: Optimize your cluster +weight: 202 +related: + - /telegraf/v1/ + - /telegraf/v1/plugins/ + - /influxdb/clustered/write-data/use-telegraf/configure/ + - /influxdb/clustered/reference/client-libraries/ + - /influxdb/clustered/write-data/best-practices/optimize-writes/ +--- + +Many different tools are available for writing data into your InfluxDB cluster. +Based on your use case, you should identify the most appropriate tools and +methods to use. Below is a summary of some of the tools that are available +(this list is not exhaustive). + +## Telegraf + +[Telegraf](/telegraf/v1/) is a data collection agent that collects data from +various sources, parses the data into +[line protocol](/influxdb/clustered/reference/syntax/line-protocol/), and then +writes the data to InfluxDB. +Telegraf is plugin-based and provides hundreds of +[plugins that collect, aggregate, process, and write data](/telegraf/v1/plugins/). + +If you need to collect data from well-established systems and technologies, +Telegraf likely already supports a plugin for collecting that data. +Some of the most common use cases are: + +- Monitoring system metrics (memory, CPU, disk usage, etc.) +- Monitoring Docker containers +- Monitoring network devices via SNMP +- Collecting data from a Kafka queue +- Collecting data from an MQTT broker +- Collecting data from HTTP endpoints +- Scraping data from a Prometheus exporter +- Parsing logs + +For more information about using Telegraf with InfluxDB Clustered, see +[Use Telegraf to write data to InfluxDB Clustered](/influxdb/clustered/write-data/use-telegraf/configure/). + +## InfluxDB client libraries + +[InfluxDB client libraries](/influxdb/clustered/reference/client-libraries/) are +language-specific packages that integrate with InfluxDB APIs. They simplify +integrating InfluxDB with your own custom application and standardize +interactions between your application and your InfluxDB cluster. +With client libraries, you can collect and write whatever time series data is +useful for your application. + +InfluxDB Clustered includes backwards compatible write APIs, so if you are +currently using an InfluxDB v1 or v2 client library, you can continue to use the +same client library to write data to your cluster. + +{{< expand-wrapper >}} +{{% expand "View available InfluxDB client libraries" %}} + + + +- [InfluxDB v3 client libraries](/influxdb/clustered/reference/client-libraries/v3/) + - [C# .NET](/influxdb/clustered/reference/client-libraries/v3/csharp/) + - [Go](/influxdb/clustered/reference/client-libraries/v3/go/) + - [Java](/influxdb/clustered/reference/client-libraries/v3/java/) + - [JavaScript](/influxdb/clustered/reference/client-libraries/v3/javascript/) + - [Python](/influxdb/clustered/reference/client-libraries/v3/python/) +- [InfluxDB v2 client libraries](/influxdb/clustered/reference/client-libraries/v2/) + - [Arduino](/influxdb/clustered/reference/client-libraries/v2/arduino/) + - [C#](/influxdb/clustered/reference/client-libraries/v2/csharp/) + - [Dart](/influxdb/clustered/reference/client-libraries/v2/dart/) + - [Go](/influxdb/clustered/reference/client-libraries/v2/go/) + - [Java](/influxdb/clustered/reference/client-libraries/v2/java/) + - [JavaScript](/influxdb/clustered/reference/client-libraries/v2/javascript/) + - [Kotlin](/influxdb/clustered/reference/client-libraries/v2/kotlin/) + - [PHP](/influxdb/clustered/reference/client-libraries/v2/php/) + - [Python](/influxdb/clustered/reference/client-libraries/v2/python/) + - [R](/influxdb/clustered/reference/client-libraries/v2/r/) + - [Ruby](/influxdb/clustered/reference/client-libraries/v2/ruby/) + - [Scala](/influxdb/clustered/reference/client-libraries/v2/scala/) + - [Swift](/influxdb/clustered/reference/client-libraries/v2/swift/) +- [InfluxDB v1 client libraries](/influxdb/clustered/reference/client-libraries/v1/) + +{{% /expand %}} +{{< /expand-wrapper >}} + +## InfluxDB HTTP write APIs + +InfluxDB Clustered provides backwards-compatible HTTP write APIs for writing +data to your cluster. The [InfluxDB client libraries](#influxdb-client-libraries) +use these APIs, but if you choose not to use a client library, you can integrate +directly with the API. Because these APIs are backwards compatible, you can use +existing InfluxDB API integrations with your InfluxDB cluster. + +- [InfluxDB v2 API for InfluxDB Clustered](/influxdb/clustered/api/v2/) +- [InfluxDB v1 API for InfluxDB Clustered](/influxdb/clustered/api/v1/) + +## Write optimizations + +As you decide on and integrate tooling to write data to your InfluxDB cluster, +there are things you can do to ensure your write pipeline is as performant as +possible. The list below provides links to more detailed descriptions of these +optimizations in the [Optimize writes](/influxdb/clustered/write-data/best-practices/optimize-writes/) +documentation: + +- [Batch writes](/influxdb/clustered/write-data/best-practices/optimize-writes/#batch-writes) +- [Sort tags by key](/influxdb/clustered/write-data/best-practices/optimize-writes/#sort-tags-by-key) +- [Use the coarsest time precision possible](/influxdb/clustered/write-data/best-practices/optimize-writes/#use-the-coarsest-time-precision-possible) +- [Use gzip compression](/influxdb/clustered/write-data/best-practices/optimize-writes/#use-gzip-compression) +- [Synchronize hosts with NTP](/influxdb/clustered/write-data/best-practices/optimize-writes/#synchronize-hosts-with-ntp) +- [Write multiple data points in one request](/influxdb/clustered/write-data/best-practices/optimize-writes/#write-multiple-data-points-in-one-request) +- [Pre-process data before writing](/influxdb/clustered/write-data/best-practices/optimize-writes/#pre-process-data-before-writing) + +{{% note %}} +[Telegraf](#telegraf) and [InfluxDB client libraries](#influxdb-client-libraries) +leverage many of these optimizations by default. +{{% /note %}} + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/design-schema" prevText="Design your schema" next="/influxdb/clustered/install/optimize-cluster/simulate-load/" nextText="Simulate load" >}} diff --git a/content/influxdb/clustered/install/prerequisites.md b/content/influxdb/clustered/install/prerequisites.md deleted file mode 100644 index 5cd4b0a9cc..0000000000 --- a/content/influxdb/clustered/install/prerequisites.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Set up prerequisites -description: > - InfluxDB Clustered requires prerequisites such as a Kubernetes cluster, object storage, - a PostgreSQL-compatitble database and more. Learn how to set up and configure the - necessary prerequisites. -menu: - influxdb_clustered: - name: Prerequisites - parent: Install InfluxDB Clustered -weight: 110 ---- - -InfluxDB Clustered requires the following prerequisites: - -- **Kubernetes cluster**: version 1.25 or higher -- **Object storage**: AWS S3 or S3-compatible storage used to store the InfluxDB Parquet files. - - {{% note %}} -We **strongly** recommend that you enable object versioning in your object store. - {{% /note %}} - -- **PostgreSQL-compatible database** _(AWS Aurora, hosted Postgres, etc.)_: - Used to store the InfluxDB catalog - - Supported PostgreSQL versions: **13.8–14.6** - - Ensure that the PostgreSQL-compatible instance is dedicated exclusively to InfluxDB. This avoids conflicts and prevents issues caused by shared usage with other applications. - -- **OAuth 2.0 provider**: - - Must support [Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow) - - Tested and supported providers: - - [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra) - - [Keycloak](https://www.keycloak.org/) - - [Auth0](https://auth0.com/) -- **TLS certificate**: for ingress to the cluster - -## Set up a Kubernetes cluster - -1. Deploy a Kubernetes cluster. Kubernetes v1.25 or later is required. -2. Create two namespaces--`influxdb` and `kubit`. -3. Install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) in the cluster and a mechanism to obtain a - valid TLS certificate (for example: [cert-manager](https://cert-manager.io/) - or provide the certificate PEM manually out of band). - To use the InfluxDB-specific ingress controller, install [Ingress NGINX](https://github.com/kubernetes/ingress-nginx). -4. Ensure your Kubernetes cluster can access the InfluxDB container registry, - or, if running in an air-gapped environment, a local container registry to - which you can copy the InfluxDB images. - -{{% note %}} -It is strongly recommended that you run the PostgreSQL-compatible database -(that stores the InfluxDB Catalog) and the Object Store (that stores InfluxDB Parquet files) -in a separate namespace from InfluxDB or external to Kubernetes entirely. - -Running the Catalog database and Object Store in a separate namespace or outside -of Kubernetes makes management of the InfluxDB instance easier and helps to -prevents accidental data loss. - -While deploying everything in the same namespace is possible for testing or initial setup, it is not recommended for production environments. -{{% /note %}} - -### Cluster sizing recommendation - -For a [medium-size workload](https://www.influxdata.com/resources/influxdb-3-0-vs-oss/), -InfluxData has tested InfluxDB Clustered using the following AWS products -and sizing: - -- S3 for the object store (size is determined by how much data you write) -- Aurora Postgresql - serverless v2 scaling configuration (2-64 ACUs) -- EC2 instances - primarily m6i.2xlarge (8 CPU, 32GB RAM) - - 3 m6i.2xlarge instances for ingesters and routers (with minimum of 2Gi of local storage) - - 3 m6i.2xlarge instances for queriers - - 1 m6i.2xlarge instance for compactors - - 1 t3.large for the Kubernetes control plane - -Your sizing may need to be different based on your environment and workload, -but this is a reasonable starting size for your initial testing. - -## Set up local storage - -The InfluxDB ingester pods need local storage to store the Write-Ahead Log (WAL). -The recommended minimum size of the local storage is 2 gibibytes (`2Gi`). - -## Set up an OAuth2 provider - -InfluxDB requires access to an OAuth2 authentication service to authenticate user access. -InfluxDB Clustered requires that the OAuth2 service supports -[Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow). -InfluxData has tested with [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra), [Keycloak](https://www.keycloak.org/), and -[Auth0](https://auth0.com/), but any OAuth2 provider should work. -To access the OAuth2 server, InfluxDB requires the following OAuth2 connection credentials: - - - Client ID - - JWKS endpoint - - Device authorization endpoint - - Token endpoint. - -## Set up client Software - -On the system used to configure the cluster (not the cluster itself), install -the following: - -- [kubectl _(v1.27)_](https://kubernetes.io/docs/reference/kubectl/kubectl/) -- [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) - -## Configure object storage permissions - -Ensure the identity you use to connect to your S3-compatible object store has the correct -permissions to allow InfluxDB to perform all the actions it needs to. - -{{< expand-wrapper >}} -{{% expand "View example AWS S3 access policy" %}} - -The IAM role that you use to access AWS S3 should have the following policy: - -{{% code-placeholders "S3_BUCKET_NAME" %}} -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "", - "Effect": "Allow", - "Action": [ - "s3:PutObjectAcl", - "s3:PutObject", - "s3:ListMultipartUploadParts", - "s3:GetObjectAcl", - "s3:GetObject", - "s3:DeleteObject", - "s3:AbortMultipartUpload" - ], - "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*", - }, - { - "Sid": "", - "Effect": "Allow", - "Action": [ - "s3:ListBucket", - "s3:GetBucketLocation" - ], - "Resource": "arn:aws:s3:::S3_BUCKET_NAME", - }, - { - "Sid": "", - "Effect": "Allow", - "Action": "s3:ListAllMyBuckets", - "Resource": "*", - } - ] -} -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Name of your AWS S3 bucket - -{{% /expand %}} - -{{% expand "View the requirements for Google Cloud Storage" %}} - -To use Google Cloud Storage (GCS) as your object store, your [IAM principal](https://cloud.google.com/iam/docs/overview) should be granted the `roles/storage.objectUser` role. -For example, if using [Google Service Accounts](https://cloud.google.com/iam/docs/service-account-overview): - -{{% code-placeholders "GCP_SERVICE_ACCOUNT|GCP_BUCKET" %}} -```bash -gcloud storage buckets add-iam-policy-binding \ - gs://GCP_BUCKET \ - --member="serviceAccount:GCP_SERVICE_ACCOUNT" \ - --role="roles/storage.objectUser" -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`GCP_SERVICE_ACCOUNT`{{% /code-placeholder-key %}}: Google Service Account name -- {{% code-placeholder-key %}}`GCP_BUCKET`{{% /code-placeholder-key %}}: GCS bucket name - -{{% /expand %}} - -{{% expand "View the requirements for Azure Blob Storage" %}} - -To use Azure Blob Storage as your object store, your [service principal](https://learn.microsoft.com/en-us/entra/architecture/service-accounts-principal) -should be granted the `Storage Blob Data Contributor` role. -This is a built-in role for Azure which encompasses common permissions. -You can assign it using the following command: - -{{% code-placeholders "PRINCIPAL|AZURE_SUBSCRIPTION|AZURE_RESOURCE_GROUP|AZURE_STORAGE_ACCOUNT|AZURE_STORAGE_CONTAINER" %}} -```bash -az role assignment create \ - --role "Storage Blob Data Contributor" \ - --assignee PRINCIPAL \ - --scope "/subscriptions/AZURE_SUBSCRIPTION/resourceGroups/AZURE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/AZURE_STORAGE_ACCOUNT/blobServices/default/containers/AZURE_STORAGE_CONTAINER" -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`PRINCIPAL`{{% /code-placeholder-key %}}: A user, group, or service principal that the role should be assigned to -- {{% code-placeholder-key %}}`AZURE_SUBSCRIPTION`{{% /code-placeholder-key %}}: Your Azure subscription -- {{% code-placeholder-key %}}`AZURE_RESOURCE_GROUP`{{% /code-placeholder-key %}}: The resource group that your Azure Blob storage account belongs to -- {{% code-placeholder-key %}}`AZURE_STORAGE_ACCOUNT`{{% /code-placeholder-key %}}: Azure Blob storage account name -- {{% code-placeholder-key %}}`AZURE_STORAGE_CONTAINER`{{% /code-placeholder-key %}}: Container name in your Azure Blob storage account - -{{% /expand %}} - -{{< /expand-wrapper >}} - -{{< page-nav next="/influxdb/clustered/install/auth/" nextText="Set up authentication" >}} diff --git a/content/influxdb/clustered/install/secure-cluster/_index.md b/content/influxdb/clustered/install/secure-cluster/_index.md new file mode 100644 index 0000000000..924795c7e3 --- /dev/null +++ b/content/influxdb/clustered/install/secure-cluster/_index.md @@ -0,0 +1,27 @@ +--- +title: Secure your InfluxDB cluster +description: > + Prepare your InfluxDB cluster for production use by enabling TLS and + authentication to ensure your cluster is secure. +menu: + influxdb_clustered: + name: Secure your cluster + parent: Install InfluxDB Clustered +weight: 104 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 4: Secure your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 4 +--- + +This phase of the installation process prepares your InfluxDB cluster for +production use by enabling security options to ensure your cluster is secured. + +## Phase 4 process + +{{< children type="ordered-list" >}} + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/optimize-querying/" prevText="Optimize querying" next="/influxdb/clustered/install/secure-cluster/tls/" nextText="Set up TLS" >}} diff --git a/content/influxdb/clustered/install/secure-cluster/auth.md b/content/influxdb/clustered/install/secure-cluster/auth.md new file mode 100644 index 0000000000..1b5e62f778 --- /dev/null +++ b/content/influxdb/clustered/install/secure-cluster/auth.md @@ -0,0 +1,793 @@ +--- +title: Set up administrative authentication +description: > + Set up an OAuth 2.0 identity provider to manage administrative access to your + InfluxDB cluster. +menu: + influxdb_clustered: + name: Set up authentication + parent: Secure your cluster +weight: 220 +aliases: + - /influxdb/clustered/install/auth/ +related: + - /influxdb/clustered/admin/users/ + - /influxdb/clustered/admin/bypass-identity-provider/ +--- + +To manage administrative access to your InfluxDB cluster, integrate your cluster +with an OAuth 2.0 identity provider. Use your identity provider to create OAuth2 +accounts for all users who need administrative access to your InfluxDB cluster. +Administrative access lets users perform actions like creating databases and +database tokens (which provide read and write access to databases). + +- [Identity provider requirements](#identity-provider-requirements) +- [Identity provider credentials](#identity-provider-credentials) +- [Set up your identity provider](#set-up-your-identity-provider) +- [Configure your cluster to connect to your identity provider](#configure-your-cluster-to-connect-to-your-identity-provider) +- [Apply your configuration changes](#apply-your-configuration-changes) +- [Configure influxctl](#configure-influxctl) +- [Test your authorization flow](#test-your-authorization-flow) + +InfluxData has tested with the following identity providers, but any provider +that [meets the requirements](#identity-provider-requirements) +should work: + +- [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra) +- [Keycloak](https://www.keycloak.org/) +- [Auth0](https://auth0.com/) + +{{% note %}} +Identity providers can be deployed with your InfluxDB cluster or run externally. +If you choose to deploy your provider with your InfluxDB cluster, the process +outlined below should be done _after_ your initial InfluxDB cluster deployment. +{{% /note %}} + +## Identity provider requirements + +To integrate an identity provider with your InfluxDB Cluster, it must meet the +following requirements: + +- Supports OAuth 2.0 +- Supports [Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow) + +## Identity provider credentials + +To access the OAuth2 server, InfluxDB requires the following OAuth2 connection +credentials: + +- Client ID +- JWKS endpoint +- Device authorization endpoint +- Token endpoint + +## Set up your identity provider + +Setup instructions are provided for the following: + +{{< tabs-wrapper >}} +{{% tabs %}} +[Keycloak](#) +[Microsoft Entra ID](#) + + + +{{% /tabs %}} + +{{% tab-content %}} + + + +### Keycloak + +To use Keycloak as your identity provider: + +1. [Create a Keycloak realm](#create-a-keycloak-realm) +2. [Create a Keycloak client with device flow enabled](#create-a-keycloak-client-with-device-flow-enabled) +3. [Create users that need administrative access to your InfluxDB cluster](#create-users) +4. [Configure InfluxDB Clustered to use Keycloak](#configure-influxdb-clustered-to-use-keycloak) + +#### Create a Keycloak realm + +See [Creating a realm](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-a-realm_server_administration_guide) +in the Keycloak documentation. + +#### Create a Keycloak client with device flow enabled + +1. In the **Keycloak Admin Console**, navigate to **Clients** and then click + **Create Client**. +2. In the **General Settings** configuration step: + + 1. Set the **Client type** to **OpenID Connect**. + 2. Enter a **Client ID**, Save your client ID to be used later. + 3. _Optional:_ Enter a **Name** and **Description** for the client. + 4. Click **Next**. + +3. In the **Capability** configuration step, enable the + **OAuth 2.0 Device Authorization Grant** authentication flow, and then click + **Next**. +4. In the **Login settings** step, you don’t need to change anything. + Click **Save**. + +#### Create users + +See [Creating users](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-user_server_administration_guide) +in the Keycloak documentation. + +##### Find user IDs with Keycloak + +To find the user IDs with Keycloak, use the Keycloak Admin Console or the Keycloak REST API. + +###### Keycloak Admin Console + +1. In the Keycloak Admin Console, navigate to your realm +2. Select **Users** in the left navigation. +3. Select the user you want to find the ID for. +4. Select the **Details** tab. The user ID is listed here. + +###### Keycloak REST API + +Send a GET request to the Keycloak REST API `/users` endpoint to fetch +the ID of a specific user. Provide the following: + +- **Query parameters** + - **username**: Username to retrieve information about + +{{% code-placeholders "KEYCLOAK_(HOST|REALM|USERNAME)" %}} + +```sh +curl https://KEYCLOAK_HOST/auth/admin/realms/KEYCLOAK_REALM/users?username=KEYCLOAK_USERNAME +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: + the Keycloak host and port (`host:port`) +- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: + the Keycloak realm +- {{% code-placeholder-key %}}`KEYCLOAK_USERNAME`{{% /code-placeholder-key %}}: + the Keycloak username to retrieve + +--- + +#### Configure InfluxDB Clustered to use Keycloak + +Run the following command to retrieve a JSON object that contains the OpenID configuration +of your Keycloak realm: + +{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} + +```sh +curl https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/.well-known/openid-configuration +``` + +{{% /code-placeholders %}} + +{{< expand-wrapper >}} +{{% expand "View example response body" %}} + +{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} + +```json +{ + "issuer": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM", + "authorization_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/auth", + "token_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/token", + "device_authorization_endpoint": "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device", + "userinfo_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/userinfo", + "end_session_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/logout", + "jwks_uri": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs", + "grant_types_supported": ["authorization_code", "refresh_token", "password"], + "response_types_supported": ["code"], + "subject_types_supported": ["public"], + "id_token_signing_alg_values_supported": ["RS256"], + "response_modes_supported": ["query"] +} +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +The following are important fields in the JSON object that are necessary to +connect your InfluxDB cluster and administrative tools to Keycloak: + +- **jwks_uri**: Used in your InfluxDB cluster configuration file. + _See [Configure your cluster to connect to your identity provider](#configure-your-cluster-to-connect-to-your-identity-provider)_. +- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) +- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +### Microsoft Entra ID + +To use Microsoft Entra ID as your identity provider: + +1. [Create a new tenant in Microsoft Entra ID](#create-a-new-tenant-in-microsoft-entra-id) +2. [Add users that need administrative access to your InfluxDB cluster](#add-users-that-need-administrative-access-to-your-influxdb-cluster) +3. [Register a new application with device code flow enabled](#register-a-new-application-with-device-code-flow-enabled) +4. Configure InfluxDB Clustered to use Microsoft Entra ID + +#### Create a new tenant in Microsoft Entra ID + +See [Create a new tenant in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/create-new-tenant) +in the Microsoft Azure documentation. +_Copy and store your **Microsoft Entra Tenant ID**_. + +#### Add users that need administrative access to your InfluxDB cluster + +See [Add or delete users](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/add-users) +in the Microsoft Azure documentation. + +##### Find user IDs with Microsoft Entra ID + +For Microsoft Entra ID, the unique user ID is the Microsoft ObjectId (OID). +To download a list of user OIDs: + +1. In the **Microsoft Azure Portal**, select **Users** in the left navigation. +2. Select users you want OIDs for and click **Download Users**. + +In the downloaded CSV file, user OIDs are provided in the `id` column. + +#### Register a new application with device code flow enabled + +1. In the **Microsoft Azure Portal**, select **App Registrations** in the left navigation. +2. Click **New Registration** and enter a name for a new application to handle + authentication requests. +3. Click **Register Application**. _Copy and store your **Application (Client) ID**_. +4. In your registered application, click **Authentication** in the left navigation. +5. Under **Advanced Settings**, set **Allow public client flows** to **Yes**. + This enables the use of the [device code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code) + for logging in to your InfluxDB cluster. + +#### Configure InfluxDB Clustered to use Microsoft Entra ID + +Use the following command to retrieve a JSON object that contains the OpenID configuration +of your Microsoft Entra tenant: + +{{% code-placeholders "AZURE_TENANT_ID" %}} + +```sh +curl https://login.microsoftonline.com/AZURE_TENANT_ID/v2.0/.well-known/openid-configuration +``` + +{{% /code-placeholders %}} + +Replace {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}} +with your [Microsoft Entra tenant ID](#create-a-new-tenant-in-microsoft-entra-id). + +{{< expand-wrapper >}} +{{% expand "View example response body" %}} + +{{% code-placeholders "AZURE_TENANT_ID" %}} + +```js +{ + "issuer": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/", + "authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/authorize", + "token_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token", + "device_authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode", + "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo", + "jwks_uri": "https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys", + "grant_types_supported": [ + "authorization_code", + "refresh_token", + "password" + ], + "response_types_supported": [ + "code" + ], + "subject_types_supported": [ + "public" + ], + "id_token_signing_alg_values_supported": [ + "RS256" + ], + "response_modes_supported": [ + "query" + ] +} +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +The following are important fields in the JSON object that are necessary to +connect your InfluxDB cluster and administrative tools to Keycloak: + +- **jwks_uri**: Used in your InfluxDB cluster configuration file. + _See [Configure your cluster to connect to your identity provider](#configure-your-cluster-to-connect-to-your-identity-provider)_. +- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) +- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) + + + +{{% /tab-content %}} + + + + + + + +{{< /tabs-wrapper >}} + +## Configure your cluster to connect to your identity provider + +To connect your InfluxDB cluster to your OAuth2 provider, update your +`AppInstance` resource with the required credentials. Modify your `AppInstance` +resource directly or, if using the +[InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered), +update your `values.yaml`. + +{{< tabs-wrapper >}} +{{% tabs %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +Provide values for the following fields in your `AppInstance` resource: + +- `spec.package.spec.admin` + - `identityProvider`: Identity provider name. + _If using Microsoft Entra ID (formerly Azure Active Directory), set the name + to `azure`_. + - `jwksEndpoint`: JWKS endpoint provide by your identity provider. + - `users`: List of OAuth2 users to grant administrative access to your + InfluxDB cluster. IDs are provided by your identity provider. + +Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but +other OAuth2 providers should work as well: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Keycloak](#) +[Auth0](#) +[Microsoft Entra ID](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-callout "keycloak" "green" %}} +{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + admin: + identityProvider: keycloak + jwksEndpoint: |- + https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Keycloak. + - id: KEYCLOAK_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: + Host and port of your Keycloak server +- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: + Keycloak realm +- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: + Keycloak user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "auth0" "green" %}} +{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + admin: + identityProvider: auth0 + jwksEndpoint: |- + https://AUTH0_HOST/.well-known/openid-configuration + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: + Host and port of your Auth0 server +- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: + Auth0 user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "azure" "green" %}} +{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + admin: + identityProvider: azure + jwksEndpoint: |- + https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: + Microsoft Entra tenant ID +- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: + Microsoft Entra user ID to grant InfluxDB administrative access to + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + +--- + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +Provide values for the following fields in your `values.yaml`: + +- `admin` + - `identityProvider`: Identity provider name. + _If using Microsoft Entra ID (formerly Azure Active Directory), set the name + to `azure`_. + - `jwksEndpoint`: JWKS endpoint provide by your identity provider. + - `users`: List of OAuth2 users to grant administrative access to your + InfluxDB cluster. IDs are provided by your identity provider. + +Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but +other OAuth2 providers should work as well: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Keycloak](#) +[Auth0](#) +[Microsoft Entra ID](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-callout "keycloak" "green" %}} +{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} + +```yaml +admin: + # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc + # Note for Azure Active Directory it must be exactly "azure" + identityProvider: keycloak + # The JWKS endpoint provided by the Identity Provider + jwksEndpoint: |- + https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs + # The list of users to grant access to Clustered via influxctl + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Keycloak. + - id: KEYCLOAK_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: + Host and port of your Keycloak server +- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: + Keycloak realm +- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: + Keycloak user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "auth0" "green" %}} +{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} + +```yaml +admin: + # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc + # Note for Azure Active Directory it must be exactly "azure" + identityProvider: auth0 + # The JWKS endpoint provided by the Identity Provider + jwksEndpoint: |- + https://AUTH0_HOST/.well-known/openid-configuration + # The list of users to grant access to Clustered via influxctl + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: + Host and port of your Auth0 server +- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: + Auth0 user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "azure" "green" %}} +{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} + +```yaml +admin: + # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc + # Note for Azure Active Directory it must be exactly "azure" + identityProvider: azure + # The JWKS endpoint provided by the Identity Provider + jwksEndpoint: |- + https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys + # The list of users to grant access to Clustered via influxctl + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: + Microsoft Entra tenant ID +- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: + Microsoft Entra user ID to grant InfluxDB administrative access to + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + +--- + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% note %}} +For more information about managing users in your InfluxDB Cluster, see +[Manage users](/influxdb/clustered/admin/users/). +{{% /note %}} + +## Apply your configuration changes + +Use `kubectl` or `helm` to apply your configuration changes and connect your +InfluxDB cluster to your identity provider. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Configure influxctl + +The [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) lets you +perform administrative actions such as creating databases or database tokens. +All `influxctl` commands are first authorized using your identity provider. +Update your [`influxctl` configuration file](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) +to connect to your identity provider. + +The following examples show how to configure `influxctl` for various identity providers: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Keycloak](#) +[Auth0](#) +[Microsoft Entra ID](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + + +{{% code-placeholders "KEYCLOAK_(CLIENT_ID|PORT|REALM)" %}} + +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" # InfluxDB cluster host + port = "8086" # InfluxDB cluster port + + [profile.auth.oauth2] + client_id = "KEYCLOAK_CLIENT_ID" + device_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device" + token_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/token" +``` + +{{% /code-placeholders %}} + + + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + + +{{% code-placeholders "AUTH0_(CLIENT_)*(ID|SECRET|HOST)" %}} + +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" # InfluxDB cluster host + port = "8086" # InfluxDB cluster port + + [profile.auth.oauth2] + client_id = "AUTH0_CLIENT_ID" + client_secret = "AUTH0_CLIENT_SECRET" + device_url = "https://AUTH0_HOST/oauth/device/code" + token_url = "https://AUTH0_HOST/oauth/token" +``` + +{{% /code-placeholders %}} + + + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + + +{{% code-placeholders "AZURE_(CLIENT|TENANT)_ID" %}} + +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" # InfluxDB cluster host + port = "8086" # InfluxDB cluster port + + [profile.auth.oauth2] + client_id = "AZURE_CLIENT_ID" + scopes = ["AZURE_CLIENT_ID/.default"] + device_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode" + token_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token" +``` + +{{% /code-placeholders %}} + + + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% warn %}} +### Refresh your admin token {note="Recommended"} + +In preparation for moving into production, we strongly recommend revoking your +cluster's _admin_ token used to authorize with your cluster in the earlier phases +of the InfluxDB Clustered installation process and generate a new admin token. + +For detailed instructions, see +[Revoke an admin token](/influxdb/clustered/admin/bypass-identity-provider/#revoke-an-admin-token). +{{% /warn %}} + +## Test your authorization flow + +To test your identity provider integration and ensure administrative access is +correctly authorized, run any `influxctl` command that +_requires administrative authentication_--for example: + + + +```bash +influxctl token list +``` + +Before executing, the command directs you to authorize with +your identity provider. +After you authorize successfully, the command runs and returns results. +successfully. + +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/tls/" prevText="Set up TLS" >}} diff --git a/content/influxdb/clustered/install/secure-cluster/tls.md b/content/influxdb/clustered/install/secure-cluster/tls.md new file mode 100644 index 0000000000..8c12ad819f --- /dev/null +++ b/content/influxdb/clustered/install/secure-cluster/tls.md @@ -0,0 +1,309 @@ +--- +title: Set up TLS in your InfluxDB cluster +description: > + Set up TLS in your InfluxDB to ensure both incoming and outgoing data is + encrypted and secure. +menu: + influxdb_clustered: + name: Set up TLS + parent: Secure your cluster +weight: 210 +--- + +Set up TLS in your InfluxDB cluster to ensure both incoming and outgoing data is +encrypted and secure. +We recommend using TLS to encrypt communication for the +following: + +- Ingress to your cluster +- Connection to your Object store +- Connection to your Catalog (PostgreSQL-compatible) database + +{{% note %}} +If using self-signed certs, +[provide a custom certificate authority (CA) bundle](#provide-a-custom-certificate-authority-bundle). +{{% /note %}} + +- [Set up ingress TLS](#set-up-ingress-tls) +- [Require HTTPS on the object store](#require-https-on-the-object-store) +- [Require TLS on your catalog database](#require-tls-on-your-catalog-database) +- [Provide a custom certificate authority bundle](#provide-a-custom-certificate-authority-bundle) +- [Apply the changes to your cluster](#apply-the-changes-to-your-cluster) + +## Set up ingress TLS + +Kubernetes support many different ingress controllers, some of which provide +simple mechanisms for creating and managing TLS certificates. +If using the [InfluxDB-defined ingress and the Nginx Ingress Controller](/influxdb/clustered/install/set-up-cluster/prerequisites/#set-up-a-kubernetes-ingress-controller), +add a valid TLS Certificate to the cluster as a secret. +Provide the paths to the TLS certificate file and key file: + +{{% code-placeholders "TLS_(CERT|KEY)_PATH" %}} + + + +```bash +kubectl create secret tls ingress-tls \ + --namespace influxdb \ + --cert TLS_CERT_PATH \ + --key TLS_KEY_PATH +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- _{{% code-placeholder-key %}}`TLS_CERT_PATH`{{% /code-placeholder-key %}}: + Path to the certificate file on your local machine._ +- _{{% code-placeholder-key %}}`TLS_KEY_PATH`{{% /code-placeholder-key %}}: + Path to the certificate secret key file on your local machine._ + +--- + +Provide the TLS certificate secret to the InfluxDB configuration in the +[Configure ingress step](#configure-ingress). + +### Configure ingress + +Update your `AppInstance` resource to reference the secret that +[contains your TLS certificate and key](#set-up-ingress-tls). +The examples below use the name `ingress-tls`. + +- **If modifying the `AppInstance` resource directly**, reference the TLS secret + in the `spec.package.spec.ingress.tlsSecretName` property. +- **If using the InfluxDB Clustered Helm chart**, reference the TLS secret in + the `ingress.tlsSecretName` property in your `values.yaml`. + +_The `tlsSecretName` field is optional. You may want to use it if you already have a TLS certificate for your DNS name._ + +{{< expand-wrapper >}} +{{% expand "Use cert-manager and Let's Encrypt to manage TLS certificates" %}} + +If you instead want to automatically create an [ACME](https://datatracker.ietf.org/doc/html/rfc8555) +certificate (for example, using [Let's Encrypt](https://letsencrypt.org/)), refer +to the [cert-manager documentation](https://cert-manager.io/docs/usage/ingress/) +for more details on how to annotate the `Ingress` resource produced by the +InfluxDB installer operator. The operator lets you to add annotations +(with `kubectl annotate`) and preserves them as it operates on resources. + +{{% note %}} +If you choose to use cert-manager, it's your responsibility to install and configure it. +{{% /note %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + # ... + ingress: + hosts: + - {{< influxdb/host >}} + tlsSecretName: ingress-tls +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +ingress: + hosts: + - {{< influxdb/host >}} + tlsSecretName: ingress-tls +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-callout %}} + +## Require HTTPS on the object store + +Some object store providers allow unsecure connections when accessing the object +store. Refer to your object store provider's documentation for information about +installing TLS certificates and ensuring all connections are secure. + +If using **AWS S3 or an S3-compatible** object store, set following property +in your `AppInstance` resources to `false` to disallow unsecure connections to +your object store: + +- **If modifying the `AppIsntance` resource directly**: + `spec.package.spec.objectStore.s3.allowHttp` +- **If using the InfluxDB Clustered Helm chart**: + `objectStore.s3.allowHttp` in your `values.yaml` + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + s3: + # ... + allowHttp: 'false' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yml +objectStore: + s3: + # ... + allowHttp: 'false' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Require TLS on your catalog database + +Refer to your PostreSQL-compatible database provider's documentation for +installing TLS certificates and ensuring secure connections. + +If currently using an unsecure connection to your Catalog database, update your +Catalog data source name (DSN) to **remove the `sslmode=disable` query parameter**: + +{{% code-callout "\?sslmode=disable" "magenta delete" %}} +```txt +postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable +``` +{{% /code-callout %}} + +## Provide a custom certificate authority bundle {note="Optional"} + +InfluxDB attempts to make TLS connections to the services it depends on--notably, +the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) +and the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). +InfluxDB validates certificates for all connections. + +_If you host dependent services yourself and you use a private or otherwise not +well-known certificate authority to issue certificates to them, +InfluxDB won't recognize the issuer and can't validate the certificates._ +To allow InfluxDB to validate the certificates from your custom CA, +configure the `AppInstance` resource to use a **PEM certificate +bundle** that contains your custom certificate authority chain. + +1. Use `kubectl` to create a config map that contains your PEM-formatted + certificate bundle file. + Your certificate authority administrator should provide you with a + PEM-formatted bundle file. + + {{% note %}} +This PEM bundle file establishes a chain of trust for the +external services that InfluxDB depends on. +It's _not_ the certificate that InfluxDB uses to +host its own TLS endpoints. + {{% /note %}} + + In the example, replace `/path/to/private_ca.pem` with the path to your PEM-formatted certificate bundle file: + + + + ```bash + kubectl --namespace influxdb create configmap custom-ca --from-file=certs.pem=/path/to/private_ca.pem + ``` + + {{% note %}} +#### Bundle multiple certificates + +You can append multiple certificates into the same bundle. +This approach helps when you need to include intermediate certificates or explicitly include leaf certificates. + +Include certificates in the bundle in the following order: + +1. Leaf certificates +2. Intermediate certificates required by leaf certificates +3. Root certificate + {{% /note %}} + +2. Update your `AppInstance` resource to refer to the `custom-ca` config map. + + - **If modifying the `AppInstance` resource directly**: + Add the config map to the `.spec.package.spec.egress` property. + - **If using the InfluxDB Clustered Helm chart**: + Set `useCustomEgress` to `true` and update the `egress` property to refer + to the config map. + + {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + egress: + customCertificates: + valueFrom: + configMapKeyRef: + key: ca.pem + name: custom-ca +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yml +useCustomEgress: true +egress: + customCertificates: + valueFrom: + configMapKeyRef: + key: ca.pem + name: custom-ca +``` +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +## Apply the changes to your cluster + +Use `kubectl` or `helm` (if using the InfluxDB Clustered Helm chart), to apply +the configuration changes to your cluster: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/" prevText="Secure your cluster" next="/influxdb/clustered/install/secure-cluster/auth/" nextText="Set up authentication" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/_index.md b/content/influxdb/clustered/install/set-up-cluster/_index.md new file mode 100644 index 0000000000..6ed86b7c61 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/_index.md @@ -0,0 +1,28 @@ +--- +title: Set up your InfluxDB cluster +description: > + Get a basic InfluxDB cluster up and running with as few external + dependencies as possible and confirm you can write and query data. +menu: + influxdb_clustered: + name: Set up your cluster + parent: Install InfluxDB Clustered +weight: 101 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 1: Set up your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 1 +--- + +The first phase of installing InfluxDB Clustered is to get a basic InfluxDB +cluster up and running with as few external dependencies as possible and confirm +you can write and query data. + +## Phase 1 steps + +{{< children type="ordered-list" >}} + +{{< page-nav next="/influxdb/clustered/install/set-up-cluster/prerequisites/" nextText="Set up prerequisites" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md new file mode 100644 index 0000000000..d774ef5a4c --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md @@ -0,0 +1,28 @@ +--- +title: Configure your InfluxDB cluster +description: > + InfluxDB Clustered deployments are managed using Kubernetes and configured using + a YAML configuration file. +menu: + influxdb_clustered: + name: Configure your cluster + parent: Set up your cluster +weight: 220 +aliases: + - /influxdb/clustered/install/configure-cluster/ +--- + +InfluxDB Clustered deployments are managed using Kubernetes and configured using +a YAML configuration file. +Apply configuration settings to your cluster by editing and applying a +Kubernetes custom resource (CRD) called `AppInstance`. +The AppInstance CRD is defined in a YAML file (use the `example-customer.yml` +provided by InfluxData as a template). + +We recommend editing the `AppInstance` resource directly as the primary method +for configuring and managing your InfluxDB cluster. If you are required to use +[Helm](https://helm.sh/), there is a InfluxDB Clustered Helm chart available +that acts as a wrapper for the `AppInstance` resource and lets you use Helm to +manage configuration changes in your InfluxDB cluster. + +{{< children >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md new file mode 100644 index 0000000000..6e455ba742 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md @@ -0,0 +1,741 @@ +--- +title: Use the InfluxDB AppInstance resource configuration +list_title: Configure your InfluxDB AppInstance resource directly +description: > + Configure your InfluxDB cluster by editing configuration options in + the provided `AppInstance` resource. +menu: +menu: + influxdb_clustered: + name: Configure AppInstance + parent: Configure your cluster +weight: 220 +list_code_example: | + Configure AppInstance directly Recommended +aliases: + - /influxdb/clustered/install/configure-cluster/directly/ +--- + +Configure your InfluxDB cluster by editing configuration options in +the `AppInstance` resource provided by InfluxData. +Resource configuration for your cluster includes the following: + +- **`influxdb-docker-config.json`**: an authenticated Docker configuration file. + The InfluxDB Clustered software is in a secure container registry. + This file grants access to the collection of container images required to + install InfluxDB Clustered. +- **A tarball that contains the following files**: + + - **`app-instance-schema.json`**: Defines the schema + that you can use to validate `example-customer.yml` and your cluster configuration in tools like [Visual Studio Code (VS Code)](https://code.visualstudio.com/). + - **`example-customer.yml`**: Configuration for your InfluxDB cluster that includes + information about [prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/). + + {{% note %}} + +The following sections refer to a `myinfluxdb.yml` file that you copy from +`example-customer.yml` and edit for your InfluxDB cluster. + + {{% /note %}} + +## Configuration data + +When ready to configure your InfluxDB cluster, have the following information +available: + +- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB + API endpoints +- **PostgreSQL-style data source name (DSN)**: used to access your + PostgreSQL-compatible database that stores the InfluxDB Catalog. +- **Object store credentials** _(AWS S3 or S3-compatible)_ + - Endpoint URL + - Access key + - Bucket name + - Region (required for S3, might not be required for other object stores) +- **Local or attached storage information** _(for ingester pods)_ + - Storage class + - Storage size + +You deploy {{% product-name %}} to a Kubernetes namespace, referred to as the +_target_ namespace in the following procedures. +For simplicity, we assume this namespace is `influxdb`--you can use any name you like. + +To manage {{% product-name %}} installation, updates, and upgrades, you edit +and apply a [Kubernetes custom resource (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +(`AppInstance`), which you define in a YAML file that conforms to the `app-instance-schema.json` schema. + +{{% product-name %}} includes `example-customer.yml` as a configuration template. + +The `AppInstance` resource contains key information, such as: + +- Name of the target namespace +- Version of the InfluxDB package +- Reference to the InfluxDB container registry pull secrets +- Hostname of your cluster's InfluxDB API +- Parameters to connect to [external prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/) + +{{% note %}} +#### Update your namespace if using a namespace other than influxdb + +If you use a namespace name other than `influxdb`, update the +`metadata.namespace` property in your `myinfluxdb.yml` to use your custom +namespace name. +{{% /note %}} + +## Configure your cluster + +1. [Create a cluster configuration file](#create-a-cluster-configuration-file) +2. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) +3. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) + +### Create a cluster configuration file + +Copy the provided `example-customer.yml` file to create a new configuration file +specific to your InfluxDB cluster. For example, `myinfluxdb.yml`. + + + +```bash +cp example-customer.yml myinfluxdb.yml +``` + +{{% note %}} + +#### Use VS Code to edit your configuration file + +We recommend using [Visual Studio Code (VS Code)](https://code.visualstudio.com/) +to edit your `myinfluxdb.yml` configuration file due to its JSON Schema support, +including autocompletion and validation features that help when +editing your InfluxDB configuration. InfluxData provides an +`app-instance-schema.json` JSON schema file that VS Code can use to validate +your configuration settings. +{{% /note %}} + +### Configure access to the InfluxDB container registry + +The provided `influxdb-docker-config.json` grants access to a collection of +container images required to run {{% product-name %}}. +Your Kubernetes Cluster needs access to the container registry to pull and +install InfluxDB. + +When pulling the {{% product-name %}} image, you're likely in one of two scenarios: + +- Your Kubernetes cluster can pull from the InfluxData container registry. +- Your cluster runs in an environment without network interfaces ("air-gapped") and + can only access a private container registry. + +In both scenarios, you need a valid _pull secret_. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Public registry (non-air-gapped)](#) +[Private registry (air-gapped)](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +#### Public registry (non-air-gapped) + +To pull from the InfluxData registry, you need to create a Kubernetes secret in the target namespace. + +```bash +kubectl create secret docker-registry gar-docker-secret \ + --from-file=.dockerconfigjson=influxdb-docker-config.json \ + --namespace influxdb +``` + +If successful, the output is the following: + +```text +secret/gar-docker-secret created +``` + +By default, the name of the secret is `gar-docker-secret`. +If you change the name of the secret, you must also change the value of the +`imagePullSecret` field in the `AppInstance` custom resource to match. + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +#### Private registry (air-gapped) + +If your Kubernetes cluster can't use a public network to download container images +from the InfluxData container registry, do the following: + +1. Copy the images from the InfluxData registry to your own private registry. +2. Configure your `AppInstance` resource with a reference to your private + registry name. +3. Provide credentials to your private registry. + +##### Copy the images + +We recommend using [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) +to copy images into your private registry. + +1. [Install crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane#installation) + for your system. +2. Use the following command to create a container registry secret file and + retrieve the necessary secrets: + +{{% code-placeholders "PACKAGE_VERSION" %}} + + + +```bash +mkdir /tmp/influxdbsecret +cp influxdb-docker-config.json /tmp/influxdbsecret/config.json +DOCKER_CONFIG=/tmp/influxdbsecret \ + crane manifest \ + us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION +``` + +{{% /code-placeholders %}} + +--- + +Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} +with your InfluxDB Clustered package version. + +--- + +If your Docker configuration is valid and you’re able to connect to the container +registry, the command succeeds and the output is the JSON manifest for the Docker +image, similar to the following: + +{{< expand-wrapper >}} +{{% expand "View JSON manifest" %}} + +```json +{ + "schemaVersion": 2, + "config": { + "mediaType": "application/vnd.kubecfg.bundle.config.v1+json", + "digest": "sha256:6900d2f248e678176c68f3768e7e48958bb96a59232070ff31b3b018cf299aa7", + "size": 8598 + }, + "layers": [ + { + "mediaType": "application/vnd.kubecfg.bundle.tar+gzip", + "digest": "sha256:7c1d62e76287035a9b22b2c155f328fae9beff2c6aa7a09a2dd2697539f41d98", + "size": 404059 + } + ], + "annotations": { + "org.opencontainers.image.created": "1970-01-01T00:00:00Z", + "org.opencontainers.image.revision": "unknown", + "org.opencontainers.image.source": "kubecfg pack" + } +} +``` + +{{% /expand %}} +{{< /expand-wrapper >}} + +If there’s a problem with the Docker configuration, crane won't retrieve the +manifest and the output is similar to the following error: + +```bash +Error: fetching manifest us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:: GET https://us-docker.pkg.dev/v2/token?scope=repository%3Ainfluxdb2-artifacts%2Fclustered%2Finfluxdb%3Apull&service=: DENIED: Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/influxdb2-artifacts/locations/us/repositories/clustered" (or it may not exist) +``` + +The list of images that you need to copy is included in the package metadata. +You can obtain it with any standard OCI image inspection tool--for example: + +{{% code-placeholders "PACKAGE_VERSION" %}} + + + +```bash +DOCKER_CONFIG=/tmp/influxdbsecret \ +crane config \ + us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION \ + | jq -r '.metadata["oci.image.list"].images[]' \ + > /tmp/images.txt +``` + +{{% /code-placeholders %}} + +The output is a list of image names, similar to the following: + +``` +us-docker.pkg.dev/influxdb2-artifacts/idpe/idpe-cd-ioxauth@sha256:5f015a7f28a816df706b66d59cb9d6f087d24614f485610619f0e3a808a73864 +us-docker.pkg.dev/influxdb2-artifacts/iox/iox@sha256:b59d80add235f29b806badf7410239a3176bc77cf2dc335a1b07ab68615b870c +... +``` + +Use `crane` to copy the images to your private registry: + +{{% code-placeholders "REGISTRY_HOSTNAME" %}} + + + +```bash + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Modify the configuration file to point to prerequisites + +Update your `myinfluxdb.yml` configuration file with credentials necessary to +connect your cluster to your prerequisites. + +- [Configure ingress](#configure-ingress) +- [Configure the object store](#configure-the-object-store) +- [Configure the catalog database](#configure-the-catalog-database) +- [Configure local storage for ingesters](#configure-local-storage-for-ingesters) + +#### Configure ingress + +To configure ingress, provide values for the following fields in your +`myinfluxdb.yml` configuration file: + +- **`spec.package.spec.ingress.hosts`: Cluster hostnames** + + Provide the hostnames that Kubernetes should + use to expose the InfluxDB API endpoints. + For example: `{{< influxdb/host >}}`. + + _You can provide multiple hostnames. The ingress layer accepts incoming + requests for all listed hostnames. This can be useful if you want to have + distinct paths for your internal and external traffic._ + + {{% note %}} +You are responsible for configuring and managing DNS. Options include: + +- Manually managing DNS records +- Using [external-dns](https://github.com/kubernetes-sigs/external-dns) to + synchronize exposed Kubernetes services and ingresses with DNS providers. + {{% /note %}} + +- **`spec.package.spec.ingress.tlsSecretName`: TLS certificate secret name** + + (Optional): Provide the name of the secret that contains your TLS certificate + and key. The examples in this guide use the name `ingress-tls`. + + {{% note %}} +Writing to and querying data from InfluxDB does not require TLS. +For simplicity, you can wait to enable TLS before moving into production. +For more information, see Phase 4 of the InfluxDB Clustered installation +process, [Secure your cluster](/influxdb/clustered/install/secure-cluster/). + {{% /note %}} + +{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: +# ... +ingress: + hosts: + - {{< influxdb/host >}} + tlsSecretName: ingress-tls +``` + +{{% /code-callout %}} + +#### Configure the object store + +To connect your InfluxDB cluster to your object store, provide the required +credentials in your `myinfluxdb.yml`. The credentials required depend on your +object storage provider. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Amazon S3 or S3-compatible](#) +[Azure Blob Storage](#) +[Google Cloud Storage](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +If using Amazon S3 or an S3-compatible object store, provide values for the +following fields in your `myinfluxdb.yml`: + +- `spec.package.spec.objectStore` + - `bucket`: Object storage bucket name + - `s3` + - `endpoint`: Object storage endpoint URL + - `allowHttp`: _Set to `true` to allow unencrypted HTTP connections_ + - `accessKey.value`: Object storage access key + - `secretKey.value`: Object storage secret key + - `region`: Object storage region + +{{% code-placeholders "S3_(URL|ACCESS_KEY|SECRET_KEY|BUCKET_NAME|REGION)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + s3: + # URL for S3 Compatible object store + endpoint: S3_URL + + # Set to true to allow communication over HTTP (instead of HTTPS) + allowHttp: 'true' + + # S3 Access Key + # This can also be provided as a valueFrom: secretKeyRef: + accessKey: + value: S3_ACCESS_KEY + + # S3 Secret Key + # This can also be provided as a valueFrom: secretKeyRef: + secretKey: + value: S3_SECRET_KEY + + # Bucket that the Parquet files will be stored in + bucket: S3_BUCKET_NAME + + # This value is required for AWS S3, it may or may not be required for other providers. + region: S3_REGION +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`S3_URL`{{% /code-placeholder-key %}}: Object storage endpoint URL +- {{% code-placeholder-key %}}`S3_ACCESS_KEY`{{% /code-placeholder-key %}}: Object storage access key +- {{% code-placeholder-key %}}`S3_SECRET_KEY`{{% /code-placeholder-key %}}: Object storage secret key +- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Object storage bucket name +- {{% code-placeholder-key %}}`S3_REGION`{{% /code-placeholder-key %}}: Object storage region + +--- + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +If using Azure Blob Storage as your object store, provide values for the +following fields in your `myinfluxdb.yml`: + +- `spec.package.spec.objectStore` + - `bucket`: Azure Blob Storage bucket name + - `azure`: + - `accessKey.value`: Azure Blob Storage access key + _(can use a `value` literal or `valueFrom` to retrieve the value from a secret)_ + - `account.value`: Azure Blob Storage account ID + _(can use a `value` literal or `valueFrom` to retrieve the value from a secret)_ + +{{% code-placeholders "AZURE_(BUCKET_NAME|ACCESS_KEY|STORAGE_ACCOUNT)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + # Bucket that the Parquet files will be stored in + bucket: AZURE_BUCKET_NAME + + azure: + # Azure Blob Storage Access Key + # This can also be provided as a valueFrom: + accessKey: + value: AZURE_ACCESS_KEY + + # Azure Blob Storage Account + # This can also be provided as a valueFrom: secretKeyRef: + account: + value: AZURE_STORAGE_ACCOUNT +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AZURE_BUCKET_NAME`{{% /code-placeholder-key %}}: Object storage bucket name +- {{% code-placeholder-key %}}`AZURE_ACCESS_KEY`{{% /code-placeholder-key %}}: Azure Blob Storage access key +- {{% code-placeholder-key %}}`AZURE_STORAGE_ACCOUNT`{{% /code-placeholder-key %}}: Azure Blob Storage account ID + +--- + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +If using Google Cloud Storage as your object store, provide values for the +following fields in your `myinfluxdb.yml`: + +- `spec.package.spec.objectStore` + - `bucket`: Google Cloud Storage bucket name + - `google`: + - `serviceAccountSecret.name`: the Kubernetes Secret name that contains your + Google IAM service account credentials + - `serviceAccountSecret.key`: the key inside of your Google IAM secret that + contains your Google IAM account credentials + +{{% code-placeholders "GOOGLE_(BUCKET_NAME|IAM_SECRET|CREDENTIALS_KEY)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + # Bucket that the Parquet files will be stored in + bucket: GOOGLE_BUCKET_NAME + + google: + # This section is not needed if you are using GKE Workload Identity. + # It is only required to use explicit service account secrets (JSON files) + serviceAccountSecret: + # Kubernetes Secret name containing the credentials for a Google IAM + # Service Account. + name: GOOGLE_IAM_SECRET + # The key within the Secret containing the credentials. + key: GOOGLE_CREDENTIALS_KEY +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`GOOGLE_BUCKET_NAME`{{% /code-placeholder-key %}}: + Google Cloud Storage bucket name +- {{% code-placeholder-key %}}`GOOGLE_IAM_SECRET`{{% /code-placeholder-key %}}: + the Kubernetes Secret name that contains your Google IAM service account + credentials +- {{% code-placeholder-key %}}`GOOGLE_CREDENTIALS_KEY`{{% /code-placeholder-key %}}: + the key inside of your Google IAM secret that contains your Google IAM account + credentials + +--- + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +#### Configure the catalog database + +The InfluxDB catalog is a PostgreSQL-compatible relational database that stores +metadata about your time series data. +To connect your InfluxDB cluster to your PostgreSQL-compatible database, +provide values for the following fields in your `myinfluxdb.yml` configuration file: + +{{% note %}} +We recommend storing sensitive credentials, such as your PostgreSQL-compatible DSN, +as secrets in your Kubernetes cluster. +{{% /note %}} + +- `spec.package.spec.catalog.dsn.valueFrom.secretKeyRef` + - `.name`: Secret name + - `.key`: Key in the secret that contains the DSN + +{{% code-placeholders "SECRET_(NAME|KEY)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + catalog: + # A postgresql style DSN that points to a postgresql compatible database. + # postgres://[user[:password]@][netloc][:port][/dbname][?param1=value1&...] + dsn: + valueFrom: + secretKeyRef: + name: SECRET_NAME + key: SECRET_KEY +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`SECRET_NAME`{{% /code-placeholder-key %}}: + Name of the secret containing your PostgreSQL-compatible DSN +- {{% code-placeholder-key %}}`SECRET_KEY`{{% /code-placeholder-key %}}: + Key in the secret that references your PostgreSQL-compatible DSN + +--- + +{{% warn %}} +##### Percent-encode special symbols in PostgreSQL DSNs + +Percent-encode special symbols in PostgreSQL DSNs to ensure +{{% product-name %}} parses them correctly. +Consider this when using DSNs with auto-generated passwords that include special +symbols for added security. + +If a DSN contains special characters that aren't percent-encoded, +you might encounter an error similar to the following: + +```txt +Catalog DSN error: A catalog error occurred: unhandled external error: error with configuration: invalid port number +``` + +{{< expand-wrapper >}} +{{% expand "View percent-encoded DSN example" %}} +To use the following DSN containing special characters: + +{{% code-callout "#" %}} +```txt +postgresql://postgres:meow#meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +You must percent-encode the special characters in the connection string: + +{{% code-callout "%23" %}} +```txt +postgresql://postgres:meow%23meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information, see the [PostgreSQL Connection URI +docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS). +{{% /warn %}} + +{{% note %}} + +##### PostgreSQL instances without TLS or SSL + +If your PostgreSQL-compatible instance runs without TLS or SSL, you must include +the `sslmode=disable` parameter in the DSN. For example: + +{{% code-callout "sslmode=disable" %}} + +``` +postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable +``` + +{{% /code-callout %}} +{{% /note %}} + +#### Configure local storage for ingesters + +InfluxDB ingesters require local storage to store the Write Ahead Log (WAL) for +incoming data. +To connect your InfluxDB cluster to local storage, provide values for the +following fields in your `myinfluxdb.yml` configuration file: + +- `spec.package.spec.ingesterStorage` + - `.storageClassName`: [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). + This differs based on the Kubernetes environment and desired storage characteristics. + - `storage`: Storage size. We recommend a minimum of 2 gibibytes (`2Gi`). + +{{% code-placeholders "STORAGE_(CLASS|SIZE)" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + ingesterStorage: + storageClassName: STORAGE_CLASS + storage: STORAGE_SIZE +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`STORAGE_CLASS`{{% /code-placeholder-key %}}: + [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) +- {{% code-placeholder-key %}}`STORAGE_SIZE`{{% /code-placeholder-key %}}: + Storage size (example: `2Gi`) + +--- + +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/set-up-cluster/licensing/" nextText="Install your license" >}} diff --git a/content/influxdb/clustered/install/configure-cluster/use-helm.md b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md similarity index 59% rename from content/influxdb/clustered/install/configure-cluster/use-helm.md rename to content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md index 7ecf852a81..1ac916240d 100644 --- a/content/influxdb/clustered/install/configure-cluster/use-helm.md +++ b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md @@ -7,8 +7,12 @@ menu: name: Use Helm parent: Configure your cluster weight: 230 +list_code_example: | + Use Helm to configure AppInstance related: - /influxdb/clustered/admin/users/ +aliases: + - /influxdb/clustered/install/configure-cluster/use-helm/ --- Manage your InfluxDB Clustered deployments using Kubernetes and apply configuration settings using a YAML configuration file. @@ -29,9 +33,11 @@ a `values.yaml` on your local machine. ## Configuration data -When ready to install InfluxDB, have the following information available: +When ready to configure your InfluxDB cluster, have the following information +available: -- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB API endpoints +- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB + API endpoints - **PostgreSQL-style data source name (DSN)**: used to access your PostgreSQL-compatible database that stores the InfluxDB Catalog. - **Object store credentials** _(AWS S3 or S3-compatible)_ @@ -42,17 +48,19 @@ When ready to install InfluxDB, have the following information available: - **Local storage information** _(for ingester pods)_ - Storage class - Storage size -- **OAuth2 provider credentials** - - Client ID - - JWKS endpoint - - Device authorization endpoint - - Token endpoint InfluxDB is deployed to a Kubernetes namespace which, throughout the following installation procedure, is referred to as the _target_ namespace. For simplicity, we assume this namespace is `influxdb`, however you may use any name you like. +{{% note %}} +#### Set namespaceOverride if using a namespace other than influxdb + +If you use a namespace name other than `influxdb`, update the `namespaceOverride` +field in your `values.yaml` to use your custom namespace name. +{{% /note %}} + ### AppInstance resource The InfluxDB installation, update, and upgrade processes are driven by editing @@ -68,9 +76,9 @@ The `AppInstance` resource contains key information, such as: - Version of the InfluxDB package - Reference to the InfluxDB container registry pull secrets - Hostname where the InfluxDB API is exposed -- Parameters to connect to [external prerequisites](/influxdb/clustered/install/prerequisites/) +- Parameters to connect to [external prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/) -### Kubit operator +### kubecfg kubit operator The InfluxDB Clustered Helm chart also includes the [`kubecfg kubit` operator](https://github.com/kubecfg/kubit) (maintained by InfluxData) @@ -78,16 +86,22 @@ which simplifies the installation and management of the InfluxDB Clustered packa It manages the application of the jsonnet templates used to install, manage, and update an InfluxDB cluster. +{{% note %}} +If you already installed the `kubecfg kubit` operator separately when +[setting up prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/#install-the-kubecfg-kubit-operator) +for your cluster, in your `values.yaml`, set `skipOperator` to `true`. + +```yaml +skipOperator: true +``` +{{% /note %}} + ## Configure your cluster 1. [Install Helm](#install-helm) 2. [Create a values.yaml file](#create-a-valuesyaml-file) -3. [Create a namespace for InfluxDB](#create-a-namespace-for-influxdb) -4. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) -5. [Set up cluster ingress](#set-up-cluster-ingress) -6. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) -7. [Provide a custom certificate authority bundle](#provide-a-custom-certificate-authority-bundle) - (Optional) +3. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) +4. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) ### Install Helm @@ -107,17 +121,6 @@ Or you can copy the default `values.yaml` from GitHub: View values.yaml on GitHub -### Create a namespace for InfluxDB - -Create a namespace for InfluxDB. For example, using `kubectl`: - -```sh -kubectl create namespace influxdb -``` - -If you use a namespace name other than `influxdb`, update the `namespaceOverride` -field in your `values.yaml` to use your custom namespace name. - ### Configure access to the InfluxDB container registry The provided `influxdb-docker-config.json` grants access to a collection of @@ -307,43 +310,6 @@ images: {{% /tab-content %}} {{< /tabs-wrapper >}} -### Set up cluster ingress - -{{% note %}} -InfluxDB Clustered components use gRPC/HTTP2 protocols. If using an external load balancer, -you may need to explicitly enable these protocols on your load balancers. -{{% /note %}} - -The InfluxDB Clustered Helm chart includes the -[Kubernetes Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx). -Add a valid TLS Certificate to the cluster as a secret. -Provide the paths to the TLS certificate file and key file: - -{{% code-placeholders "TLS_(CERT|KEY)_PATH" %}} - -```sh -kubectl create secret tls ingress-tls \ - --namespace influxdb \ - --cert TLS_CERT_PATH \ - --key TLS_KEY_PATH -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- _{{% code-placeholder-key %}}`TLS_CERT_PATH`{{% /code-placeholder-key %}}: - Path to the certificate file on your local machine._ -- _{{% code-placeholder-key %}}`TLS_KEY_PATH`{{% /code-placeholder-key %}}: - Path to the certificate secret key file on your local machine._ - ---- - -Provide the TLS certificate secret to the InfluxDB configuration in the -[Configure ingress step](#configure-ingress). - ### Modify the configuration file to point to prerequisites Update your `values.yaml` file with credentials necessary to connect your @@ -353,8 +319,6 @@ cluster to your prerequisites. - [Configure the object store](#configure-the-object-store) - [Configure the catalog database](#configure-the-catalog-database) - [Configure local storage for ingesters](#configure-local-storage-for-ingesters) -- [Configure your OAuth2 provider](#configure-your-oauth2-provider) -- [Configure the size of your cluster](#configure-the-size-of-your-cluster) #### Configure ingress @@ -371,7 +335,7 @@ To configure ingress, provide values for the following fields in your distinct paths for your internal and external traffic._ {{% note %}} - You are responsible for configuring and managing DNS. Options include: +You are responsible for configuring and managing DNS. Options include: - Manually managing DNS records - Using [external-dns](https://github.com/kubernetes-sigs/external-dns) to @@ -380,28 +344,20 @@ To configure ingress, provide values for the following fields in your - **`ingress.tlsSecretName`: TLS certificate secret name** - Provide the name of the secret that - [contains your TLS certificate and key](#set-up-cluster-ingress). - The examples in this guide use the name `ingress-tls`. + (Optional): Provide the name of the secret that contains your TLS certificate + and key. The examples in this guide use the name `ingress-tls`. _The `tlsSecretName` field is optional. You may want to use it if you already have a TLS certificate for your DNS name._ - {{< expand-wrapper >}} - {{% expand "Use cert-manager and Let's Encrypt to manage TLS certificates" %}} - -If you instead want to automatically create an [ACME](https://datatracker.ietf.org/doc/html/rfc8555) -certificate (for example, using [Let's Encrypt](https://letsencrypt.org/)), refer -to the [cert-manager documentation](https://cert-manager.io/docs/usage/ingress/). -In `ingress.tlsSecretName`, provide a name for the secret it should create. - -{{% note %}} -If you choose to use cert-manager, it's your responsibility to install and configure it. -{{% /note %}} -{{% /expand %}} -{{< /expand-wrapper >}} + {{% note %}} +Writing to and querying data from InfluxDB does not require TLS. +For simplicity, you can wait to enable TLS before moving into production. +For more information, see Phase 4 of the InfluxDB Clustered installation +process, [Secure your cluster](/influxdb/clustered/install/secure-cluster/). + {{% /note %}} -{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} + {{% code-callout "ingress-tls|cluster-host\.com" "green" %}} ```yaml ingress: @@ -414,8 +370,9 @@ ingress: #### Configure the object store -To connect your InfluxDB cluster to your object store. The information required -to connect to your object store depends on your object storage provider. +To connect your InfluxDB cluster to your object store, provide the required +credentials in your `values.yaml`. The credentials required depend on your +object storage provider. {{< tabs-wrapper >}} {{% tabs %}} @@ -454,7 +411,7 @@ objectStore: endpoint: S3_URL # Set to true to allow communication over HTTP (instead of HTTPS) - allowHttp: 'false' + allowHttp: 'true' # S3 Access Key # This can also be provided as a valueFrom: secretKeyRef: @@ -633,6 +590,46 @@ Replace the following: --- +{{% warn %}} +##### Percent-encode special symbols in PostgreSQL DSNs + +Special symbols in PostgreSQL DSNs should be percent-encoded to ensure they +are parsed correctly by InfluxDB Clustered. This is important to consider when +using DSNs containing auto-generated passwords which may include special +symbols to make passwords more secure. + +A DSN with special characters that are not percent-encoded result in an error +similar to: + +```txt +Catalog DSN error: A catalog error occurred: unhandled external error: error with configuration: invalid port number +``` + +{{< expand-wrapper >}} +{{% expand "View percent-encoded DSN example" %}} +To use the following DSN containing special characters: + +{{% code-callout "#" %}} +```txt +postgresql://postgres:meow#meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +You must percent-encode the special characters in the connection string: + +{{% code-callout "%23" %}} +```txt +postgresql://postgres:meow%23meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information, see the [PostgreSQL Connection URI +docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS). +{{% /warn %}} + {{% note %}} ##### PostgreSQL instances without TLS or SSL @@ -686,291 +683,4 @@ Replace the following: --- -#### Configure your OAuth2 provider - -InfluxDB Clustered uses OAuth2 to authenticate administrative access to your cluster. -To connect your InfluxDB cluster to your OAuth2 provide, provide values for the -following fields in your `values.yaml`: - -- `admin` - - `identityProvider`: Identity provider name. - _If using Microsoft Entra ID (formerly Azure Active Directory), set the name - to `azure`_. - - `jwksEndpoint`: JWKS endpoint provide by your identity provider. - - `users`: List of OAuth2 users to grant administrative access to your - InfluxDB cluster. IDs are provided by your identity provider. - -Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but -other OAuth2 providers should work as well: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Keycloak](#) -[Auth0](#) -[Microsoft Entra ID](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -{{% code-callout "keycloak" "green" %}} -{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} - -```yaml -admin: - # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc - # Note for Azure Active Directory it must be exactly "azure" - identityProvider: keycloak - # The JWKS endpoint provided by the Identity Provider - jwksEndpoint: |- - https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs - # The list of users to grant access to Clustered via influxctl - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Keycloak. - - id: KEYCLOAK_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: - Host and port of your Keycloak server -- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: - Keycloak realm -- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: - Keycloak user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "auth0" "green" %}} -{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} - -```yaml -admin: - # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc - # Note for Azure Active Directory it must be exactly "azure" - identityProvider: auth0 - # The JWKS endpoint provided by the Identity Provider - jwksEndpoint: |- - https://AUTH0_HOST/.well-known/openid-configuration - # The list of users to grant access to Clustered via influxctl - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Auth0. - - id: AUTH0_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: - Host and port of your Auth0 server -- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: - Auth0 user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "azure" "green" %}} -{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} - -```yaml -admin: - # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc - # Note for Azure Active Directory it must be exactly "azure" - identityProvider: azure - # The JWKS endpoint provided by the Identity Provider - jwksEndpoint: |- - https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys - # The list of users to grant access to Clustered via influxctl - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Azure. - - id: AZURE_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: - Microsoft Entra tenant ID -- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: - Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ - ---- - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -##### Add users - -Finally, add the users you wish to have access to use `influxctl`. -Update the `admin.users` field with a list of the users. -See [Manage users](/influxdb/clustered/admin/users/) for more details. - -#### Configure the size of your cluster - -By default, an InfluxDB cluster is configured with the following: - -- **3 ingesters**: - Ensures redundancy on the write path. -- **1 compactor**: - While you can have multiple compactors, it is more efficient to scale the - compactor vertically (assign more CPU and memory) rather than horizontally - (increase the number of compactors). -- **1 querier**: - The optimal number of queriers depends on the number of concurrent queries you are - likely to have and how long they take to execute. - -The default values provide a good starting point for testing. -Once you have your cluster up and running and are looking for scaling recommendations, -please [contact the InfluxData Support team](https://support.influxdata.com). -We are happy to work with you to identify appropriate scale settings based on -your anticipated workload. - -**To use custom scale settings for your InfluxDB cluster**, modify the following fields -in your values.yaml`. If omitted, your cluster will use the default scale settings. - -- `resources` - - `ingester.requests` - - `cpu`: CPU resource units to assign to ingesters - - `memory`: Memory resource units to assign to ingesters - - `replicas`: Number of ingester replicas to provision - - `compactor.requests` - - `cpu`: CPU resource units to assign to compactors - - `memory`: Memory resource units to assign to compactors - - `replicas`: Number of compactor replicas to provision - - `querier.requests` - - `cpu`: CPU resource units to assign to queriers - - `memory`: Memory resource units to assign to queriers - - `replicas`: Number of querier replicas to provision - - `router.requests` - - `cpu`: CPU resource units to assign to routers - - `memory`: Memory resource units to assign to routers - - `replicas`: Number of router replicas to provision - -###### Related Kubernetes documentation - -- [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) -- [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) - -{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(CPU|MEMORY|REPLICAS)" %}} - -```yml -# The following settings tune the various pods for their cpu/memory/replicas -# based on workload needs. Only uncomment the specific resources you want -# to change. Anything left commented will use the package default. -resources: - # The ingester handles data being written - ingester: - requests: - cpu: INGESTER_CPU - memory: INGESTER_MEMORY - replicas: INGESTER_REPLICAS # Default is 3 - - # The compactor reorganizes old data to improve query and storage efficiency. - compactor: - requests: - cpu: COMPACTOR_CPU - memory: COMPACTOR_MEMORY - replicas: COMPACTOR_REPLICAS # Default is 1 - - # The querier handles querying data. - querier: - requests: - cpu: QUERIER_CPU - memory: QUERIER_MEMORY - replicas: QUERIER_REPLICAS # Default is 1 - - # The router performs some api routing. - router: - requests: - cpu: ROUTER_CPU - memory: ROUTER_MEMORY - replicas: ROUTER_REPLICAS # Default is 1 -``` - -{{% /code-placeholders %}} - -### Provide a custom certificate authority bundle {note="Optional"} - -InfluxDB attempts to make TLS connections to the services it depends on; notably -the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog), -and the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). -InfluxDB validates the certificates for all of the connections it makes. - -**If you host these services yourself and you use a private or otherwise not -well-known certificate authority to issue certificates to theses services**, -InfluxDB will not recognize the issuer and will be unable to validate the certificates. -To allow InfluxDB to validate these certificates, provide a PEM certificate -bundle containing your custom certificate authority chain. - -1. Use `kubectl` to create a config map containing your PEM bundle. - Your certificate authority administrator should provide you with a - PEM-formatted certificate bundle file. - - {{% note %}} -This PEM-formatted bundle file is *not* the certificate that InfluxDB uses to -host its own TLS endpoints. This bundle establishes a chain of trust for the -external services that InfluxDB depends on. - {{% /note %}} - - In the example below, `private_ca.pem` is the certificate bundle file. - - ```sh - kubectl --namespace influxdb create configmap custom-ca --from-file=certs.pem=/path/to/private_ca.pem - ``` - - {{% note %}} -It's possible to append multiple certificates into the same bundle. -This can help if you need to include intermediate certificates or explicitly -include leaf certificates. Leaf certificates should be included before any -intermediate certificates they depend on. The root certificate should -be last in the bundle. - {{% /note %}} - -2. Update your `values.yaml` to enable custom egress and refer to your - certificate authority config map. Set `useCustomEgress` to `true` and update - the `egress` property to refer to that config map. For example: - - ```yml - useCustomEgress: true - egress: - # # If you're using a custom CA you will need to specify the full custom CA bundle here. - # # - # # NOTE: the custom CA is currently only honoured for outbound requests used to obtain - # # the JWT public keys from your identiy provider (see `jwksEndpoint`). - customCertificates: - valueFrom: - configMapKeyRef: - key: ca.pem - name: custom-ca - ``` - -{{< page-nav prev="/influxdb/clustered/install/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/licensing" nextText="Install your license" tab="Helm" >}} +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/set-up-cluster/licensing" nextText="Install your license" tab="Helm" >}} diff --git a/content/influxdb/clustered/install/deploy.md b/content/influxdb/clustered/install/set-up-cluster/deploy.md similarity index 95% rename from content/influxdb/clustered/install/deploy.md rename to content/influxdb/clustered/install/set-up-cluster/deploy.md index 67903c2528..f9ae3707ea 100644 --- a/content/influxdb/clustered/install/deploy.md +++ b/content/influxdb/clustered/install/set-up-cluster/deploy.md @@ -5,11 +5,13 @@ description: > menu: influxdb_clustered: name: Deploy your cluster - parent: Install InfluxDB Clustered -weight: 140 + parent: Set up your cluster +weight: 240 related: - /influxdb/clustered/admin/upgrade/ - - /influxdb/clustered/install/licensing/ + - /influxdb/clustered/install/set-up-cluster/licensing/ +aliases: + - /influxdb/clustered/install/deploy/ --- Use Kubernetes and related tools to deploy your InfluxDB cluster. @@ -202,4 +204,4 @@ influxdb iox-shared-querier-7f5998b9b-fpt62 4/4 Running 1 (6 influxdb kubit-apply-influxdb-g6qpx 0/1 Completed 0 8s ``` -{{< page-nav prev="/influxdb/clustered/install/licensing/" prevText="Install your license" next="/influxdb/clustered/install/use-your-cluster/" nextText="Use your cluster" >}} +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/licensing/" prevText="Install your license" next="/influxdb/clustered/install/set-up-cluster/test-cluster/" nextText="Test your cluster" >}} diff --git a/content/influxdb/clustered/install/licensing.md b/content/influxdb/clustered/install/set-up-cluster/licensing.md similarity index 60% rename from content/influxdb/clustered/install/licensing.md rename to content/influxdb/clustered/install/set-up-cluster/licensing.md index a15b6ea0cb..0baecba07d 100644 --- a/content/influxdb/clustered/install/licensing.md +++ b/content/influxdb/clustered/install/set-up-cluster/licensing.md @@ -6,12 +6,14 @@ description: > menu: influxdb_clustered: name: Install your license - parent: Install InfluxDB Clustered -weight: 135 + parent: Set up your cluster +weight: 235 influxdb/clustered/tags: [licensing] related: - /influxdb/clustered/admin/licensing/ - /influxdb/clustered/admin/upgrade/ +aliases: + - /influxdb/clustered/install/licensing/ --- Install your InfluxDB Clustered license in your cluster to authorize the use @@ -28,7 +30,7 @@ of the InfluxDB Clustered software. - ```sh + ```bash kubectl apply --filename license.yml --namespace influxdb ``` @@ -43,10 +45,9 @@ If you are currently using a non-licensed preview release of InfluxDB Clustered and want to upgrade to a licensed release, do the following: 1. [Install an InfluxDB license](#install-your-influxdb-license) -2. If you [use the `AppInstance` resource configuration](/influxdb/clustered/install/configure-cluster/directly/) - to configure your cluster, in your `myinfluxdb.yml`, - update the package version defined in `spec.package.image` to use a licensed - release. +2. If you [use the `AppInstance` resource configuration](/influxdb/clustered/install/set-up-cluster/configure-cluster/directly/) + to configure your cluster, in your `myinfluxdb.yml`, update the package + version defined in `spec.package.image` to use a licensed release. If using the InfluxDB Clustered Helm chart, update the `image.tag` property in your `values.yaml`to use a licensed release. @@ -98,46 +99,10 @@ image: Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} with the version number to upgrade to. -## Troubleshoot licensing +## Verify your license -After you have activated licensing, use the following signals to verify licensing -and troubleshoot issues with your {{< product-name omit="Clustered" >}} -cluster. - -In your commands, replace the following: - -- {{% code-placeholder-key %}}`NAMESPACE`{{% /code-placeholder-key %}}: - your [InfluxDB namespace](/influxdb/clustered/install/configure-cluster/#create-a-namespace-for-influxdb) -- {{% code-placeholder-key %}}`POD_NAME`{{% /code-placeholder-key %}}: - your [InfluxDB Kubernetes pod](/influxdb/clustered/install/deploy/#inspect-cluster-pods) - -### Verify database components - -After you [install your license](#install-your-influxdb-license), -run the following command to check that database pods start up and are in the -`Running` state: - - - -{{% code-placeholders "NAMESPACE" %}} - -```sh -kubectl get pods -l app=iox --namespace NAMESPACE -``` - -{{% /code-placeholders %}} - -If a `Pod` fails to start, run the following command to view pod information: - - - -{{% code-placeholders "POD_NAME|NAMESPACE" %}} - -```sh -kubectl describe pod POD_NAME --namespace NAMESPACE -``` - -{{% /code-placeholders %}} +After you have activated your license, use the following signals to verify the +license is active and functioning. ### Verify the `Secret` exists @@ -146,35 +111,27 @@ Run the following command to verify that the licensing activation created a -{{% code-placeholders "NAMESPACE" %}} - ```sh -kubectl get secret iox-license --namespace NAMESPACE +kubectl get secret iox-license --namespace influxdb ``` If the secret doesn't exist, -[view `license-controller` logs](#view-license-controller-logs) for -more information or errors. - -{{% /code-placeholders %}} +[view `license-controller` logs](#view-license-controller-logs) for more +information or errors. ### View `license controller` logs -The `license controller` component creates a `Secret` named `iox-license` from your -`License`. - -To view `license controller` logs for troubleshooting, run the following -command: +The `license controller` component creates a `Secret` named `iox-license` from +your `License`. To view `license controller` logs for troubleshooting, run the +following command: -{{% code-placeholders "NAMESPACE" %}} - ```sh -kubectl logs deployment/license-controller --namespace NAMESPACE +kubectl logs deployment/license-controller --namespace influxdb ``` -{{% /code-placeholders %}} - +For more information about InfluxDB Clustered licensing, see +[Manage your InfluxDB Clustered license](/influxdb/clustered/admin/licensing/) -{{< page-nav prev="/influxdb/clustered/install/configure-cluster/" prevText="Configure your cluster" next="/influxdb/clustered/install/deploy/" nextText="Deploy your cluster" keepTab=true >}} +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/configure-cluster/" prevText="Configure your cluster" next="/influxdb/clustered/install/set-up-cluster/deploy/" nextText="Deploy your cluster" keepTab=true >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/prerequisites.md b/content/influxdb/clustered/install/set-up-cluster/prerequisites.md new file mode 100644 index 0000000000..83d000b196 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/prerequisites.md @@ -0,0 +1,405 @@ +--- +title: Set up prerequisites +description: > + InfluxDB Clustered requires prerequisites such as a Kubernetes cluster, object storage, + a PostgreSQL-compatitble database and more. Learn how to set up and configure the + necessary prerequisites. +menu: + influxdb_clustered: + name: Prerequisites + parent: Set up your cluster +weight: 201 +aliases: + - /influxdb/clustered/install/prerequisites/ +--- + +InfluxDB Clustered requires the following prerequisite external dependencies: + +- **kubectl command line tool** +- **Kubernetes cluster** +- **kubecfg kubit operator** +- **Kubernetes ingress controller** +- **Object storage**: AWS S3 or S3-compatible storage (including Google Cloud Storage + or Azure Blob Storage) to store the InfluxDB Parquet files. +- **PostgreSQL-compatible database** _(AWS Aurora, hosted PostgreSQL, etc.)_: + Stores the [InfluxDB Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog). +- **Local or attached storage**: + Stores the Write-Ahead Log (WAL) for + [InfluxDB Ingesters](/influxdb/clustered/reference/internals/storage-engine/#ingester). + +The following walks through preparing these prerequisites. + +- [Install kubectl](#install-kubectl) +- [Set up your Kubernetes cluster](#set-up-your-kubernetes-cluster) +- [Install the kubecfg kubit operator](#install-the-kubecfg-kubit-operator) +- [Set up a Kubernetes ingress controller](#set-up-a-kubernetes-ingress-controller) +- [Set up your object store](#set-up-your-object-store) +- [Set up your PostgreSQL-compatible database](#set-up-your-postgresql-compatible-database) +- [Set up local or attached storage](#set-up-local-or-attached-storage) + +## Install kubectl + +Kubernetes provides the `kubectl` command line tool for communicating with a +Kubernetes cluster's control plane. `kubectl` is used to manage your InfluxDB +cluster. + +Follow instructions to install `kubectl` on your local machine: + +{{% note %}} +InfluxDB Clustered Kubernetes deployments require `kubectl` 1.27 or higher. +{{% /note %}} + +- [Install kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) +- [Install kubectl on macOS](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) +- [Install kubectl on Windows](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/) + +## Set up your Kubernetes cluster + +1. Deploy a Kubernetes cluster. The deployment process depends on your + Kubernetes environment or Kubernetes cloud provider. Refer to the + [Kubernetes documentation](https://kubernetes.io/docs/home/) or your cloud + provider's documentation for information about deploying a Kubernetes cluster. + +2. Ensure `kubectl` can connect to your Kubernetes cluster. + Your Manage [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) + defines cluster connection credentials. + +3. Create two namespaces--`influxdb` and `kubit`. Use + [`kubectl create namespace`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_namespace/) to create the + namespaces: + + + + ```bash + kubectl create namespace influxdb && \ + kubectl create namespace kubit + ``` + +4. Install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) + in the cluster and a mechanism to obtain a valid TLS certificate + (for example: [cert-manager](https://cert-manager.io/) or provide the + certificate PEM manually out of band). + To use the InfluxDB-specific ingress controller, install [Ingress NGINX](https://github.com/kubernetes/ingress-nginx). + +5. Ensure your Kubernetes cluster can access the InfluxDB container registry, + or, if running in an air-gapped environment, a local container registry to + which you can copy the InfluxDB images. + +### Cluster sizing recommendation + +As a starting point for a production workload, InfluxData recommends the +following sizing for {{% product-name %}} components: + +{{< tabs-wrapper >}} +{{% tabs %}} +[AWS](#) +[Google Cloud Platform](#) +[Microsoft Azure](#) +[On-Prem](#) +{{% /tabs %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - _[See below](#postgresql-compatible-database-requirements)_ +- **Ingesters and Routers (x3):** + - EC2 m6i.2xlarge (8 CPU, 32 GB RAM) + - Local storage: mimumum of 2 GB (high-speed SSD) +- **Queriers (x3):** + - EC2 m6i.2xlarge (8 CPU, 32 GB RAM) +- **Compactors (x1):** + - EC2 m6i.2xlarge (8 CPU, 32 GB RAM) +- **Kubernetes Control Plane (x1):** + - EC2 t3.large (2 CPU, 8 GB RAM) + + +{{% /tab-content %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - _[See below](#postgresql-compatible-database-requirements)_ +- **Ingesters and Routers (x3):** + - GCE c2-standard-8 (8 CPU, 32 GB RAM) + - Local storage: mimumum of 2 GB (high-speed SSD) +- **Queriers (x3):** + - GCE c2-standard-8 (8 CPU, 32 GB RAM) +- **Compactors (x1):** + - GCE c2-standard-8 (8 CPU, 32 GB RAM) +- **Kubernetes Control Plane (x1):** + - GCE c2d-standard-2 (2 CPU, 8 GB RAM) + + +{{% /tab-content %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - _[See below](#postgresql-compatible-database-requirements)_ +- **Ingesters and Routers (x3):** + - Standard_D8s_v3 (8 CPU, 32 GB RAM) + - Local storage: mimumum of 2 GB (high-speed SSD) +- **Queriers (x3):** + - Standard_D8s_v3 (8 CPU, 32 GB RAM) +- **Compactors (x1):** + - Standard_D8s_v3 (8 CPU, 32 GB RAM) +- **Kubernetes Control Plane (x1):** + - Standard_B2ms (2 CPU, 8 GB RAM) + + +{{% /tab-content %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - CPU: 4-8 cores + - RAM: 16-32 GB +- **Ingesters and Routers (x3):** + - CPU: 8 cores + - RAM: 32 GB + - Local storage: 2 GB (high-speed SSD) +- **Queriers (x3):** + - CPU: 8 cores + - RAM: 32 GB +- **Compactors (x1):** + - CPU: 8 cores + - RAM: 32 GB +- **Kubernetes Control Plane (x1):** + - CPU: 2 cores + - RAM: 8 GB + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +Your sizing may need to be different based on your environment, cloud provider, +and workload, but this is a reasonable starting size for your initial testing. + +## Install the kubecfg kubit operator + +The [`kubecfg kubit` operator](https://github.com/kubecfg/kubit) (maintained by InfluxData) +simplifies the installation and management of the InfluxDB Clustered package. +It manages the application of the jsonnet templates used to install, manage, and +update an InfluxDB cluster. + +{{% note %}} +#### The InfluxDB Clustered Helm chart includes the kubit operator + +If using the [InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered) +to deploy your InfluxDB cluster, you do not need to install the kubit operator +separately. The Helm chart installs the kubit operator. +{{% /note %}} + +Use `kubectl` to install the [kubecfg kubit](https://github.com/kubecfg/kubit) +operator **v0.0.18 or later**. + + + +```bash +kubectl apply -k 'https://github.com/kubecfg/kubit//kustomize/global?ref=v0.0.19' +``` + +## Set up a Kubernetes ingress controller + +[Kubernetes ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) +routes HTTP/S requests to services within the cluster and requires deploying an +[ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). +You can provide your own ingress or you can install +[Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx) to use +the InfluxDB-defined ingress. + +{{% note %}} +InfluxDB Clustered components use gRPC/HTTP2 protocols. If using an external +load balancer, you may need to explicitly enable these protocols on your load +balancers. +{{% /note %}} + +## Set up your object store + +InfluxDB Clustered supports AWS S3 or S3-compatible storage (including Google +Cloud Storage, Azure Blob Storage, and MinIO) for storing +[InfluxDB Parquet files](/influxdb/clustered/reference/internals/storage-engine/#object-store). +Refer to your object storage provider's documentation for information about +setting up an object store: + +- [Create an AWS S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) +- [Create a Google Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets) +- [Create an Azure Blog Storage container](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container) +- [Create a MinIO bucket](https://min.io/docs/minio/linux/reference/minio-mc/mc-mb.html) + +{{% caption %}} +\* This list does not represent all S3-compatible object stores +that work with InfluxDB Clustered. Other S3-compatible object stores should work +as well. +{{% /caption %}} + +{{% note %}} +#### Object storage recommendations + +We **strongly** recommend the following: + +- ##### Enable object versioning + + Enable object versioning in your object store. + Refer to your object storage provider's documentation for information about + enabling object versioning. + +- ##### Run the object store in a separate namespace or outside of Kubernetes + + Run the Object store in a separate namespace from InfluxDB or external to + Kubernetes entirely. Doing so makes management of the InfluxDB cluster easier + and helps to prevent accidental data loss. While deploying everything in the + same namespace is possible, we do not recommend it for production environments. +{{% /note %}} + +### Configure object storage permissions + +Ensure the identity you use to connect to your S3-compatible object store has +the correct permissions to allow InfluxDB to perform all the actions it needs to. + +{{< expand-wrapper >}} +{{% expand "View example AWS S3 access policy" %}} + +The IAM role that you use to access AWS S3 should have the following policy: + +{{% code-placeholders "S3_BUCKET_NAME" %}} +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "", + "Effect": "Allow", + "Action": [ + "s3:PutObjectAcl", + "s3:PutObject", + "s3:ListMultipartUploadParts", + "s3:GetObjectAcl", + "s3:GetObject", + "s3:DeleteObject", + "s3:AbortMultipartUpload" + ], + "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*", + }, + { + "Sid": "", + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": "arn:aws:s3:::S3_BUCKET_NAME", + }, + { + "Sid": "", + "Effect": "Allow", + "Action": "s3:ListAllMyBuckets", + "Resource": "*", + } + ] +} +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Name of your AWS S3 bucket + +{{% /expand %}} + +{{% expand "View the requirements for Google Cloud Storage" %}} + +To use Google Cloud Storage (GCS) as your object store, your [IAM principal](https://cloud.google.com/iam/docs/overview) should be granted the `roles/storage.objectUser` role. +For example, if using [Google Service Accounts](https://cloud.google.com/iam/docs/service-account-overview): + +{{% code-placeholders "GCP_SERVICE_ACCOUNT|GCP_BUCKET" %}} +```bash +gcloud storage buckets add-iam-policy-binding \ + gs://GCP_BUCKET \ + --member="serviceAccount:GCP_SERVICE_ACCOUNT" \ + --role="roles/storage.objectUser" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`GCP_SERVICE_ACCOUNT`{{% /code-placeholder-key %}}: Google Service Account name +- {{% code-placeholder-key %}}`GCP_BUCKET`{{% /code-placeholder-key %}}: GCS bucket name + +{{% /expand %}} + +{{% expand "View the requirements for Azure Blob Storage" %}} + +To use Azure Blob Storage as your object store, your [service principal](https://learn.microsoft.com/en-us/entra/architecture/service-accounts-principal) +should be granted the `Storage Blob Data Contributor` role. +This is a built-in role for Azure which encompasses common permissions. +You can assign it using the following command: + +{{% code-placeholders "PRINCIPAL|AZURE_SUBSCRIPTION|AZURE_RESOURCE_GROUP|AZURE_STORAGE_ACCOUNT|AZURE_STORAGE_CONTAINER" %}} +```bash +az role assignment create \ + --role "Storage Blob Data Contributor" \ + --assignee PRINCIPAL \ + --scope "/subscriptions/AZURE_SUBSCRIPTION/resourceGroups/AZURE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/AZURE_STORAGE_ACCOUNT/blobServices/default/containers/AZURE_STORAGE_CONTAINER" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`PRINCIPAL`{{% /code-placeholder-key %}}: A user, group, or service principal that the role should be assigned to +- {{% code-placeholder-key %}}`AZURE_SUBSCRIPTION`{{% /code-placeholder-key %}}: Your Azure subscription +- {{% code-placeholder-key %}}`AZURE_RESOURCE_GROUP`{{% /code-placeholder-key %}}: The resource group that your Azure Blob storage account belongs to +- {{% code-placeholder-key %}}`AZURE_STORAGE_ACCOUNT`{{% /code-placeholder-key %}}: Azure Blob storage account name +- {{% code-placeholder-key %}}`AZURE_STORAGE_CONTAINER`{{% /code-placeholder-key %}}: Container name in your Azure Blob storage account + +{{% /expand %}} + +{{< /expand-wrapper >}} + +{{% note %}} +To configure permissions with MinIO, use the +[example AWS access policy](#view-example-aws-s3-access-policy). +{{% /note %}} + +## Set up your PostgreSQL-compatible database + +The [InfluxDB Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) +that stores metadata related to your time series data requires a PostgreSQL or +PostgreSQL-compatible database _(AWS Aurora, hosted PostgreSQL, etc.)_. +The process for installing and setting up your PostgreSQL-compatible database +depends on the database and database provider you use. +Refer to your database's or provider's documentation for setting up your +PostgreSQL-compatible database. + +### PostgreSQL-compatible database requirements + +- PostgreSQL versions **13.8–14.6**. +- **Minimum of 4 GB of memory** or equivalent provider-specific units. +- To avoid conflicts and prevent issues caused by shared usage with other + applications, ensure that your PostgreSQL-compatible instance is dedicated + exclusively to InfluxDB. + +{{% note %}} +We **strongly** recommended running the PostgreSQL-compatible database +in a separate namespace from InfluxDB or external to Kubernetes entirely. +Doing so makes management of the InfluxDB cluster easier and helps to prevent +accidental data loss. + +While deploying everything in the same namespace is possible, we do not +recommend it for production environments. +{{% /note %}} + +## Set up local or attached storage + +The [InfluxDB Ingester](/influxdb/clustered/reference/internals/storage-engine/#ingester) +needs local or attached storage to store the Write-Ahead Log (WAL). +The read and write speed of the attached storage affects the write performance +of the Ingester, so the faster the storage device, the better your write +performance will be. +The recommended minimum size of the local storage is 2 gibibytes (`2Gi`). + +Installation and setup of local or attached storage depends on your underlying +hardware or cloud provider. Refer to your provider's documentation for +information about installing and configuring local storage. + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/" prevText="Back" next="/influxdb/clustered/install/set-up-cluster/configure-cluster" nextText="Configure your cluster" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/test-cluster.md b/content/influxdb/clustered/install/set-up-cluster/test-cluster.md new file mode 100644 index 0000000000..0bda6c511f --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/test-cluster.md @@ -0,0 +1,176 @@ +--- +title: Test your InfluxDB Cluster +description: > + Test to ensure your InfluxDB cluster can write and query data successfully. +menu: + influxdb_clustered: + name: Test your cluster + parent: Set up your cluster +weight: 250 +--- + +With your InfluxDB cluster deployed and running, test to ensure you can +successfully write and query data from InfluxDB. + +1. [Download and install influxctl](#download-and-install-influxctl) +1. [Retrieve your cluster's admin token](#retrieve-your-clusters-admin-token) +1. [Configure influxctl to connect to your cluster](#configure-influxctl-to-connect-to-your-cluster) +1. [Create a new database](#create-a-new-database) +1. [Write test data to the new database](#write-test-data-to-the-new-database) +1. [Query the test data from your database](#query-the-test-data-from-your-database) + +## Download and install influxctl + +[`influxctl`](/influxdb/clustered/reference/cli/influxctl/) is a command line tool +that lets you manage, write data to, and query data from your InfluxDB cluster +from your local machine. + +Download and install influxctl + +## Retrieve your cluster's admin token + +InfluxDB Clustered generates a valid access token (known as the _admin token_) +and stores it as a secret in your cluster's `influxdb` namespace. +During this phase of the installation process, use the admin token with +`influxctl` in lieu of configuring and using an identity provider. + +Use `kubectl` to retrieve the admin token from your `influxdb` namespace secret +store and copy it to a file: + +```sh +kubectl get secrets/admin-token \ + --template={{.data.token}} \ + --namespace influxdb | base64 -d > token.json +``` + +## Configure influxctl to connect to your cluster + +Create an [`influxctl` connection profile](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) +for your InfluxDB cluster. Connection profiles are stored in a `config.toml` +file on your local machine and contain the credentials necessary to connect to +and authorize with your InfluxDB cluster. + +1. Create a file named `config.toml` with the following contents: + + {{< code-placeholders "INFLUXDB_(HOST|PORT)|DIRECTORY_PATH" >}} +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" + port = "INFLUXDB_PORT" + + [profile.auth.token] + token_file = "/DIRECTORY_PATH/token.json" +``` + {{< /code-placeholders >}} + + In the example above, replace the following: + + - {{% code-placeholder-key %}}`INFLUXDB_PORT`{{% /code-placeholder-key %}}: + The port to use to connect to your InfluxDB cluster. + - {{% code-placeholder-key %}}`DIRECTORY_PATH`{{% /code-placeholder-key %}}: + The directory path to your admin token file, `token.json`. + + {{% note %}} +To set your InfluxDB cluster host, click +**{{< icon "cog" "v2" >}} Set InfluxDB cluster URL** below the codeblock above +and provide your cluster's host. This will update your cluster's host in all +code examples. + {{% /note %}} + +2. Make this configuration file available to `influxctl` in one of the following + ways: + + - Include the `--config` flag with all `influxctl` commands to specify the + filepath of your `config.toml`. + - Store the `config.toml` file at the + [default location](/influxdb/clustered/reference/cli/influxctl/#default-connection-profile-store-location) + that `influxctl` expects to find connection profiles based on your + operating system. If your connection profile is in the default location, + you do not need to include the `--config` flag with your `influxctl` commands. + +{{% note %}} +#### Connection configuration examples + +In the examples below, replace {{% code-placeholder-key %}}`CONFIG_PATH`{{% /code-placeholder-key %}} +with the directory path to your connection configuration file. If you placed +your configuration file in the default location for your operating system, remove +`--config /CONFIG_PATH/config.toml` from the example commands before running them. +{{% /note %}} + +## Create a new database + +Use [`influxctl database create`](/influxdb/clustered/reference/cli/influxctl/database/create/) +to create a new database named `testdb`. Include the following: + +- _(Optional)_ The path to your connection profile configuration file. +- The database name--`testdb`. + +{{% code-placeholders "CONFIG_PATH" %}} +```sh +influxctl --config /CONFIG_PATH/config.toml database create testdb +``` +{{% /code-placeholders %}} + +## Write test data to the new database + +Use [`influxctl write`](/influxdb/clustered/reference/cli/influxctl/write/) to +write the following test data to your `testdb` database. Provide the following: + +- _(Optional)_ The path to your connection profile configuration file. +- The database name--`testdb`. +- [Line protocol](/influxdb/clustered/reference/syntax/line-protocol/) to write + to InfluxDB. + +{{% influxdb/custom-timestamps %}} + +{{% code-placeholders "CONFIG_PATH" %}} +```bash +influxctl --config /CONFIG_PATH/config.toml write \ + --database testdb \ + "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000000000000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000000000000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600000000000 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600000000000 +" +``` +{{% /code-placeholders %}} + +{{% /influxdb/custom-timestamps %}} + +## Query the test data from your database + +Use [`influxctl query`](/influxdb/clustered/reference/cli/influxctl/query/) to +query the test data from your `testdb` database. Provide the following: + +- _(Optional)_ The path to your connection profile configuration file. +- The database name--`testdb`. +- The SQL query to execute. + +{{% code-placeholders "CONFIG_PATH" %}} +```bash +influxctl --config /CONFIG_PATH/config.toml query \ + --database testdb \ + "SELECT * FROM home" +``` +{{% /code-placeholders %}} + + +This should return results similar to: + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | +| 0 | 21.4 | Living Room | 21.4 | 2022-01-01T09:00:00Z | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | + +{{% /influxdb/custom-timestamps %}} + +If the query successfully returns data, your InfluxDB cluster is set up and functional. + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/test-cluster/" prevText="Test your cluster" next="/influxdb/clustered/install/customize-cluster/" nextText="Phase 2: Customize your cluster">}} + diff --git a/content/influxdb/clustered/install/use-your-cluster.md b/content/influxdb/clustered/install/use-your-cluster.md index 9e7debdbe7..ae7e5bf3e9 100644 --- a/content/influxdb/clustered/install/use-your-cluster.md +++ b/content/influxdb/clustered/install/use-your-cluster.md @@ -7,9 +7,11 @@ menu: name: Use your cluster parent: Install InfluxDB Clustered weight: 150 +draft: true --- -Now that your InfluxDB cluster is deployed, you can use and test it. +Now that you have deployed your InfluxDB cluster, it's ready for you to use +and test. Use the [Get started with InfluxDB clustered guide](/influxdb/clustered/get-started/setup/) to test your new InfluxDB cluster. diff --git a/content/influxdb/clustered/reference/client-libraries/v3/python.md b/content/influxdb/clustered/reference/client-libraries/v3/python.md index dca98614a5..b9070c1fe9 100644 --- a/content/influxdb/clustered/reference/client-libraries/v3/python.md +++ b/content/influxdb/clustered/reference/client-libraries/v3/python.md @@ -14,7 +14,7 @@ aliases: - /influxdb/clustered/reference/client-libraries/v3/pyinflux3/ related: - /influxdb/clustered/query-data/execute-queries/troubleshoot/ -list_code_example: > +list_code_example: |