Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

WIP clustered install reorg

staging/commandbar-clustered-install
Scott Anderson 2024-10-03 13:28:42 -06:00
parent 6ec7504da8
commit 5295e62ddf
25 changed files with 1551 additions and 738 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
assets/styles/layouts/article/_buttons.scss
View File

@ -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;

3
assets/styles/layouts/article/_code.scss
View File

@ -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}
////////////////////////////////////////////////////////////////////////////////

5
assets/styles/layouts/article/_title.scss
View File

@ -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,

2
content/influxdb/clustered/admin/bypass-identity-provider.md
View File

@ -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

233
content/influxdb/clustered/admin/env-vars.md
View File

@ -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
`<component>.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'
```
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. Use `kubectl apply` to apply the configuration changes to your cluster and
add or update environment variables in each component.
3. Apply the configuration changes to your cluster and add or update
environment variables in each component.
<!-- pytest.mark.skip -->
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[AppInstance](#)
[Helm](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
helm upgrade \
influxdata/influxdb3-clustered \
-f ./values.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% 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 >}}

67
content/influxdb/clustered/admin/licensing.md
View File

@ -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)
@ -55,6 +59,69 @@ 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:
<!--pytest.mark.skip-->
```bash
kubectl get pods -l app=iox --namespace influxdb
```
If a `Pod` fails to start, run the following command to view pod information:
<!--pytest.mark.skip-->
{{% 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:
<!--pytest.mark.skip-->
```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:
<!--pytest.mark.skip-->
```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

202
content/influxdb/clustered/admin/scale-cluster.md
View File

@ -77,6 +77,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 %}}
<!----------------------------- BEGIN APPINSTANCE ----------------------------->
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.
@ -175,6 +185,107 @@ spec:
{{% /expand %}}
{{< /expand-wrapper >}}
<!------------------------------ END APPINSTANCE ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!--------------------------------- BEGIN HELM -------------------------------->
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
{{< expand-wrapper >}}
{{% expand "View example `values.yaml` with resource requests and limits" %}}
{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(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
```
{{% /code-placeholders %}}
{{% /expand %}}
{{< /expand-wrapper >}}
<!---------------------------------- END HELM --------------------------------->
{{% /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 +300,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 +312,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 +331,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 +373,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 %}}
<!-- pytest.mark.skip -->
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash
helm upgrade \
influxdata/influxdb3-clustered \
-f ./values.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
## Scale your cluster as a whole
@ -294,13 +463,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 +493,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 %}}

4
content/influxdb/clustered/admin/users/_index.md
View File

@ -10,12 +10,12 @@ menu:
weight: 102
cascade:
related:
- /influxdb/clustered/install/auth/
- /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.

12
content/influxdb/clustered/admin/users/add.md
View File

@ -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))_
---
@ -164,7 +164,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))_
---
@ -292,7 +292,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))_
---
@ -303,7 +303,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.
@ -342,6 +342,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.

194
content/influxdb/clustered/install/customize-cluster/_index.md
View File

@ -7,191 +7,21 @@ menu:
name: Customize your cluster
parent: Install InfluxDB Clustered
weight: 102
metadata: ['Install InfluxDB Clustered -- Phase 2']
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 is where you customize the scale and
configuration of your cluster to best suit your workload.
This phase of the installation process customizes the scale and configuration of
your InfluxDB cluster to meet the needs of your specific workload.
## Configure the size of your cluster
{{< children type="ordered-list" >}}
InfluxDB Clustered lets you scale ...
##### 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 %}}
<!-- HELM VERSIOn -->
#### 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 %}}
<!-- HELM VERSION -->
{{< 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" >}}

148
content/influxdb/clustered/install/customize-cluster/config.md Normal file
View File

@ -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. Environment variables are set on a per-component basis.
{{< tabs-wrapper >}}
{{% tabs "medium" %}}
[AppInstance](#)
[Helm](#)
{{% /tabs %}}
{{% tab-content %}}
<!----------------------------- BEGIN APPINSTANCE ----------------------------->
In your `AppInstance` resource, configure environment variables for individual
components in the
`spec.package.spec.components.<component>.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'
```
<!------------------------------ END APPINSTANCE ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!--------------------------------- BEGIN HELM -------------------------------->
In your `values.yaml`, configure environment variables for individual components
in the `components.<component>.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'
```
<!---------------------------------- END HELM --------------------------------->
{{% /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 %}}
<!--
TO-DO: We need to get a list of what environment variables users can modify and
what each does. This section should show examples of how to set the environment
variables, but point to the master list somewhere in the reference section.
-->
## 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 %}}
<!-- pytest.mark.skip -->
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```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" >}}

303
content/influxdb/clustered/install/customize-cluster/scale.md Normal file
View File

@ -0,0 +1,303 @@
---
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 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).
We are happy to work with you to 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 `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 both the minimum resources to request for each
component and resource limits to apply to each component.
{{< tabs-wrapper >}}
{{% tabs "medium" %}}
[AppInstance](#)
[Helm](#)
{{% /tabs %}}
{{% tab-content %}}
<!----------------------------- BEGIN APPINSTANCE ----------------------------->
**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
{{< expand-wrapper >}}
{{% expand "View example `AppInstance` with resource requests and limits" %}}
{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(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
```
{{% /code-placeholders %}}
{{% /expand %}}
{{< /expand-wrapper >}}
<!------------------------------ END APPINSTANCE ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!--------------------------------- BEGIN HELM -------------------------------->
**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
{{< expand-wrapper >}}
{{% expand "View example `values.yaml` with resource requests and limits" %}}
{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(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
```
{{% /code-placeholders %}}
{{% /expand %}}
{{< /expand-wrapper >}}
<!---------------------------------- END HELM --------------------------------->
{{% /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 %}}
<!-- pytest.mark.skip -->
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```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" >}}

17
content/influxdb/clustered/install/optimize-cluster/_index.md
View File

@ -7,4 +7,19 @@ menu:
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
---
- Simulate a production-like workload
- Define your schema
- Define your query patterns
- Optimize for your workload:
- Querying by specific tag values? Partition by those tags.
- Is your schema wide? SELECT specific columns in queries rather than wildcards.

281
content/influxdb/clustered/install/secure-cluster/_index.md
View File

@ -1,280 +1,25 @@
---
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
---
- **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
This phase of the installation process prepares your InfluxDB cluster for
production use by enabling security options to ensure your cluster is secured.
## Set up an OAuth2 provider
{{< children type="ordered-list" >}}
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.
## Ingress TLS
- Multiple ingress providers. Some provide simple mechanisms for creating and
and managing TLS certificates.
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" %}}
<!-- pytest.mark.skip -->
```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
- **`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 %}}
<!-- HELM version of TLS config -->
{{< 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 >}}
{{% code-callout "ingress-tls|cluster-host\.com" "green" %}}
```yaml
ingress:
hosts:
- {{< influxdb/host >}}
tlsSecretName: ingress-tls
```
{{% /code-callout %}}
<!-- END HELM TLS CONFIG -->
## Require HTTPS the object store
- `spec.package.spec.objectStore.allowHttp`:
_Set to `false` to disallow unencrypted HTTP connections_
```yml
apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
package:
spec:
objectStore:
allowHttp: 'false'
```
<!-- -->
### 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:
<!-- pytest.mark.skip -->
```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. 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
```
<!-- HELM VERSION -->
### 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
```
<!-- END HELM VERSION -->
{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/optimize-cluster/" prevText="Phase 3: Optimize your cluster" next="/influxdb/clustered/install/secure-cluster/tls/" nextText="Set up TLS" >}}

390
content/influxdb/clustered/install/auth.md → content/influxdb/clustered/install/secure-cluster/auth.md
View File

@ -1,25 +1,41 @@
---
title: Set up administrative authentication
description: >
Manage administrative access to your InfluxDB cluster through your identity provider.
Set up an OAuth 2.0 identity provider to manage administrative access to your
InfluxDB cluster.
menu:
influxdb_clustered:
name: Set up authentication
parent: Install InfluxDB Clustered
weight: 120
parent: Secure your cluster
weight: 220
aliases:
- /influxdb/clustered/install/auth/
related:
- /influxdb/clustered/admin/users/
- /influxdb/clustered/admin/bypass-identity-provider/
---
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.
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).
<!-- Credentials need to connect -->
- **OAuth2 provider credentials**
- Client ID
- JWKS endpoint
- Device authorization endpoint
- Token endpoint
- [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.
@ -27,25 +43,25 @@ 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
## Identity provider requirements
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.
To integrate an identity provider with your InfluxDB Cluster, it must meet the
following requirements:
For more information, see
[Bypass your identity provider](/influxdb/clustered/admin/bypass-identity-provider/).
{{% /note %}}
- Supports OAuth 2.0
- Supports [Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
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:
## Identity provider credentials
- [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/)
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:
@ -62,7 +78,7 @@ Setup instructions are provided for the following:
<!------------------------------- BEGIN Keycloak ------------------------------>
## Keycloak
### Keycloak
To use Keycloak as your identity provider:
@ -71,12 +87,12 @@ To use Keycloak as your identity provider:
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
#### 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
#### Create a Keycloak client with device flow enabled
1. In the **Keycloak Admin Console**, navigate to **Clients** and then click
**Create Client**.
@ -93,23 +109,23 @@ in the Keycloak documentation.
4. In the **Login settings** step, you don’t need to change anything.
Click **Save**.
### Create users
#### 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
##### 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
###### 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
###### 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:
@ -136,7 +152,7 @@ Replace the following:
---
### Configure InfluxDB Clustered to use Keycloak
#### Configure InfluxDB Clustered to use Keycloak
Run the following command to retrieve a JSON object that contains the OpenID configuration
of your Keycloak realm:
@ -191,7 +207,7 @@ connect your InfluxDB cluster and administrative tools to Keycloak:
<!--------------------------- BEGIN Microsoft Entra --------------------------->
## Microsoft Entra ID
### Microsoft Entra ID
To use Microsoft Entra ID as your identity provider:
@ -200,18 +216,18 @@ To use Microsoft Entra ID as your identity provider:
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
#### 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
#### 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
##### 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:
@ -221,7 +237,7 @@ To download a list of user OIDs:
In the downloaded CSV file, user OIDs are provided in the `id` column.
### Register a new application with device code flow enabled
#### 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
@ -232,7 +248,7 @@ In the downloaded CSV file, user OIDs are provided in the `id` column.
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
#### 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:
@ -306,108 +322,25 @@ connect your InfluxDB cluster and administrative tools to Keycloak:
{{< /tabs-wrapper >}}
## Configure influxctl
## Configure your cluster to connect to your identity provider
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.
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`.
The following examples show how to configure `influxctl` for various identity providers:
{{< tabs-wrapper >}}
{{% tabs %}}
[AppInstance](#)
[Helm](#)
{{% /tabs %}}
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Keycloak](#)
[Auth0](#)
[Microsoft Entra ID](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN Keycloak ------------------------------>
<!----------------------------- BEGIN APPINSTANCE ----------------------------->
{{% 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 %}}
<!-------------------------------- END Keycloak ------------------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-------------------------------- BEGIN Auth0 -------------------------------->
{{% 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 %}}
<!--------------------------------- END Auth0 --------------------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!--------------------------- BEGIN Microsoft Entra --------------------------->
{{% 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 %}}
<!---------------------------- END Microsoft Entra ---------------------------->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/prerequisites/" next="/influxdb/clustered/install/set-up-cluster/configure-cluster/" nextText="Configure your cluster" >}}
<!-- ////////////////////////////// NEW STUFF ////////////////////////////// -->
#### 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:
Provide values for the following fields in your `AppInstance` resource:
- `spec.package.spec.admin`
- `identityProvider`: Identity provider name.
@ -534,20 +467,21 @@ 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))_
---
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
<!-- HELM VERSION -->
<!------------------------------ END APPINSTANCE ------------------------------>
#### Configure your OAuth2 provider
{{% /tab-content %}}
{{% tab-content %}}
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`:
<!--------------------------------- BEGIN HELM -------------------------------->
Provide values for the following fields in your `values.yaml`:
- `admin`
- `identityProvider`: Identity provider name.
@ -668,17 +602,171 @@ 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))_
---
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
<!-- END HELM VERSIOn -->
<!--------------------------------- BEGIN HELM -------------------------------->
##### Add users
{{% /tab-content %}}
{{< /tabs-wrapper >}}
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.
{{% 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 %}}
<!-- pytest.mark.skip -->
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```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 %}}
<!------------------------------- BEGIN Keycloak ------------------------------>
{{% 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 %}}
<!-------------------------------- END Keycloak ------------------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-------------------------------- BEGIN Auth0 -------------------------------->
{{% 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 %}}
<!--------------------------------- END Auth0 --------------------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!--------------------------- BEGIN Microsoft Entra --------------------------->
{{% 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 %}}
<!---------------------------- END Microsoft Entra ---------------------------->
{{% /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:
<!-- pytest.mark.skip -->
```bash
influxctl token list
```
You are directed to authorize with your identity provider before the command
executes and returns results. If authorized correctly, the command should run
successfully.
{{< page-nav prev="/influxdb/clustered/install/secure-cluster/tls/" prevText="Set up TLS" >}}

309
content/influxdb/clustered/install/secure-cluster/tls.md Normal file
View File

@ -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 to ensure both incoming and outgoing data is
encrypted and secure. TLS should be used 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" %}}
<!-- pytest.mark.skip -->
```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-cluster-ingress).
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
information about installing TLS certificates and ensuring all connections are
secure.
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:
<!-- pytest.mark.skip -->
```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 %}}
<!-- pytest.mark.skip -->
```bash
kubectl apply \
--filename myinfluxdb.yml \
--namespace influxdb
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```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" >}}

8
content/influxdb/clustered/install/set-up-cluster/_index.md
View File

@ -8,7 +8,13 @@ menu:
name: Set up your cluster
parent: Install InfluxDB Clustered
weight: 101
metadata: ['Install InfluxDB Clustered -- Phase 1']
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

6
content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md
View File

@ -8,12 +8,8 @@ menu:
name: Configure your cluster
parent: Set up your cluster
weight: 220
related:
- /influxdb/clustered/admin/upgrade/
aliases:
- /influxdb/clustered/install/configure-cluster/
cascade:
metadata: ['Install InfluxDB Clustered -- Phase 1: Set up your Cluster']
---
InfluxDB Clustered deployments are managed using Kubernetes and configured using
@ -26,6 +22,4 @@ 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 >}}

4
content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md
View File

@ -10,6 +10,8 @@ menu:
name: Configure AppInstance
parent: Configure your cluster
weight: 220
list_code_example: |
<a class="btn arrow" href="/influxdb/clustered/install/set-up-cluster/configure-cluster/directly/">Configure AppInstance directly <span class="cf-icon CaretOutlineRight"></span></a>
aliases:
- /influxdb/clustered/install/configure-cluster/directly/
---
@ -741,4 +743,4 @@ Replace the following:
---
{{< page-nav prev="/influxdb/clustered/install/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/set-up-cluster/licensing/" nextText="Install your license" >}}
{{< 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" >}}

4
content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md
View File

@ -7,6 +7,8 @@ menu:
name: Use Helm
parent: Configure your cluster
weight: 230
list_code_example: |
<a class="btn arrow" style="margin-bottom:3rem;" href="/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm/">Use Helm to configure AppInstance <span class="cf-icon CaretOutlineRight"></span></a>
related:
- /influxdb/clustered/admin/users/
aliases:
@ -681,4 +683,4 @@ Replace the following:
---
{{< page-nav prev="/influxdb/clustered/install/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/set-up-cluster/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" >}}

1
content/influxdb/clustered/install/set-up-cluster/deploy.md
View File

@ -7,7 +7,6 @@ menu:
name: Deploy your cluster
parent: Set up your cluster
weight: 240
metadata: ['Install InfluxDB Clustered -- Phase 1: Set up your Cluster']
related:
- /influxdb/clustered/admin/upgrade/
- /influxdb/clustered/install/set-up-cluster/licensing/

35
content/influxdb/clustered/install/set-up-cluster/licensing.md
View File

@ -8,7 +8,6 @@ menu:
name: Install your license
parent: Set up your cluster
weight: 235
metadata: ['Install InfluxDB Clustered -- Phase 1: Set up your Cluster']
influxdb/clustered/tags: [licensing]
related:
- /influxdb/clustered/admin/licensing/
@ -105,37 +104,6 @@ the version number to upgrade to.
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:
<!--pytest.mark.skip-->
```bash
kubectl get pods -l app=iox --namespace influxdb
```
If a `Pod` fails to start, run the following command to view pod information:
<!--pytest.mark.skip-->
{{% 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
@ -163,4 +131,7 @@ following command:
kubectl logs deployment/license-controller --namespace influxdb
```
For more information about InfluxDB Clustered licensing, see
[Manage your InfluxDB Clustered license](/influxdb/clustered/admin/licensing/)
{{< 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 >}}

25
content/influxdb/clustered/install/set-up-cluster/prerequisites.md
View File

@ -9,7 +9,6 @@ menu:
name: Prerequisites
parent: Set up your cluster
weight: 201
metadata: ['Install InfluxDB Clustered -- Phase 1: Set up your Cluster']
aliases:
- /influxdb/clustered/install/prerequisites/
---
@ -88,22 +87,20 @@ InfluxDB Clustered requires **Kubernetes v1.25 or later**.
or, if running in an air-gapped environment, a local container registry to
which you can copy the InfluxDB images.
<!-- ### Cluster sizing recommendation
### 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
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)
- EC2 instances - primarily m6i.2xlarge (8 CPU, 32 GB 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. -->
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
@ -120,7 +117,8 @@ 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.
Use `kubectl` to install the [kubecfg kubit](https://github.com/kubecfg/kubit)
operator **v0.0.18 or later**.
<!-- pytest.mark.skip -->
@ -302,7 +300,8 @@ PostgreSQL-compatible database.
### PosgreSQL-compatible database requirements
- PostgreSQL versions **13.8–14.6**
- PostgreSQL versions **13.8–14.6**.
- Minimum of 4 GB of memory or equivalent provider-specific units.
- To avoid conflicts and prevents issues caused by shared usage with other
applications, ensure that your PostgreSQL-compatible instance is dedicated
exclusively to InfluxDB.
@ -321,9 +320,9 @@ recommend it for production environments.
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 the attached storage affects the write
performance of the Ingester, so the faster the storage device, the better your
write performance will be.
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

27
content/influxdb/clustered/install/set-up-cluster/test-cluster.md
View File

@ -7,10 +7,17 @@ menu:
name: Test your cluster
parent: Set up your cluster
weight: 250
metadata: ['Install InfluxDB Clustered -- Phase 1: Set up your Cluster']
---
- Purpose is to confirm writes and reads
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
@ -83,6 +90,15 @@ code examples.
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/)
@ -91,9 +107,11 @@ 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
@ -107,6 +125,7 @@ write the following test data to your `testdb` database. Provide the following:
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "CONFIG_PATH" %}}
```bash
influxctl --config /CONFIG_PATH/config.toml write \
--database testdb \
@ -116,6 +135,7 @@ 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 %}}
@ -128,11 +148,14 @@ query the test data from your `testdb` database. Provide the following:
- 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:

1
content/influxdb/clustered/install/use-your-cluster.md
View File

@ -7,6 +7,7 @@ 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.