Configure your InfluxDB cluster

InfluxDB Clustered deployments are managed using Kubernetes and configured using a YAML configuration file. InfluxData provides the following items:

• influxdb-docker-config.json: an authenticated Docker configuration file. The InfluxDB Clustered software is in a secure container registry. This file grants access to the collection of container images required to install InfluxDB Clustered.

• A tarball that contains the following files:

  • app-instance-schema.json: Defines the schema for example-customer.yml to be used with Visual Studio Code (VS Code).

  • example-customer.yml: Configuration for your InfluxDB cluster that includes information about prerequisites.

    This documentation refers to a myinfluxdb.yml file that you copy from example-customer.yml and edit for your InfluxDB cluster.

Configuration data

When ready to install InfluxDB, have the following information available:

• InfluxDB cluster hostname: the hostname Kubernetes uses to expose InfluxDB API endpoints
• PostgreSQL-style data source name (DSN): used to access your PostgreSQL-compatible database that stores the InfluxDB Catalog.
• Object store credentials (AWS S3 or S3-compatible)
  • Endpoint URL
  • Access key
  • Bucket name
  • Region (required for S3, may not be required for other object stores)
• Local storage information (for ingester pods)
  • Storage class
  • Storage size
• OAuth2 provider credentials
  • Client ID
  • JWKS endpoint
  • Device authorization endpoint
  • Token endpoint

InfluxDB is deployed to a Kubernetes namespace which, throughout the following installation procedure, is referred to as the target namespace. For simplicity, we assume this namespace is influxdb, however you may use any name you like.

The InfluxDB installation, update, and upgrade processes are driven by editing and applying a Kubernetes custom resource (CRD) called AppInstance. The AppInstance CRD is defined in a YAML file (use example-customer.yml as a template) that contains key information, such as:

• Name of the target namespace
• Version of the InfluxDB package
• Reference to the InfluxDB container registry pull secrets
• Hostname where the InfluxDB API is exposed
• Parameters to connect to external prerequisites

Configure your cluster

1. Create a cluster configuration file
2. Create a namespace for InfluxDB
3. Install kubecfg kubit operator
4. Configure access to the InfluxDB container registry
5. Set up cluster ingress
6. Modify the configuration file to point to prerequisites

Create a cluster configuration file

Copy the provided example-customer.yml file to create a new configuration file specific to your InfluxDB cluster. For example, myinfluxdb.yml.

cp example-customer.yml myinfluxdb.yml

Create a namespace for InfluxDB

Create a namespace for InfluxDB. For example, using kubectl::

kubectl create namespace influxdb

If you use a namespace name other than influxdb, update the .metadata.namespace field in your myinfluxdb.yml to use your custom namespace name.

Install kubecfg kubit operator

The kubecfg kubit operator (maintained by InfluxData) simplifies the installation and management of the InfluxDB Clustered package. It manages the application of the jsonnet templates used to install, manage, and update an InfluxDB cluster.

Use kubectl to install the kubecfg kubit operator.

kubectl apply -k 'https://github.com/kubecfg/kubit//kustomize/global?ref=v0.0.15'

Configure access to the InfluxDB container registry

The provided influxdb-docker-config.json grants access to a collection of container images required to run InfluxDB Clustered. Your Kubernetes Cluster needs access to the container registry to pull down and install InfluxDB.

There are two main scenarios:

• You have a kubernetes cluster that can pull from the InfluxData container registry.
• You run in an environment with no network interfaces (“air-gapped”) and you can only access a private container registry.

In both scenarios, you need a valid container registry secret file. Use crane to create a container registry secret file.

1. Install crane
2. Use the following command to create a container registry secret file and retrieve the necessary secrets:

mkdir /tmp/influxdbsecret
cp influxdb-docker-config.json /tmp/influxdbsecret/config.json
DOCKER_CONFIG=/tmp/influxdbsecret \
  crane manifest \
  us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:
PACKAGE_VERSION

Replace PACKAGE_VERSION with your InfluxDB Clustered package version.

If your Docker configuration is valid and you’re able to connect to the container registry, the command succeeds and the output is the JSON manifest for the Docker image, similar to the following:

{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.kubecfg.bundle.config.v1+json",
    "digest": "sha256:6900d2f248e678176c68f3768e7e48958bb96a59232070ff31b3b018cf299aa7",
    "size": 8598
  },
  "layers": [
    {
      "mediaType": "application/vnd.kubecfg.bundle.tar+gzip",
      "digest": "sha256:7c1d62e76287035a9b22b2c155f328fae9beff2c6aa7a09a2dd2697539f41d98",
      "size": 404059
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "1970-01-01T00:00:00Z",
    "org.opencontainers.image.revision": "unknown",
    "org.opencontainers.image.source": "kubecfg pack"
  }
}

If there’s a problem with the Docker configuration, crane won’t retrieve the manifest and the output is similar to the following error:

Error: fetching manifest us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:<package-version>: GET https://us-docker.pkg.dev/v2/token?scope=repository%3Ainfluxdb2-artifacts%2Fclustered%2Finfluxdb%3Apull&service=: DENIED: Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/influxdb2-artifacts/locations/us/repositories/clustered" (or it may not exist)

kubectl create secret docker-registry gar-docker-secret \
  --from-file=.dockerconfigjson=influxdb-docker-config.json \
  --namespace influxdb

secret/gar-docker-secret created

DOCKER_CONFIG=/tmp/influxdbsecret \
crane config \
  us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:
PACKAGE_VERSION
 \
  | jq -r '.metadata["oci.image.list"].images[]' \
  > /tmp/images.txt

us-docker.pkg.dev/influxdb2-artifacts/idpe/idpe-cd-ioxauth@sha256:5f015a7f28a816df706b66d59cb9d6f087d24614f485610619f0e3a808a73864
us-docker.pkg.dev/influxdb2-artifacts/iox/iox@sha256:b59d80add235f29b806badf7410239a3176bc77cf2dc335a1b07ab68615b870c
...

</tmp/images.txt xargs -I% crane cp % 
REGISTRY_HOSTNAME
/%

myregistry.mydomain.io

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      images:
        registryOverride: 
REGISTRY_HOSTNAME

Set up cluster ingress

Kubernetes ingress routes HTTP/S requests to services within the cluster and requires deploying an ingress controller.

You can provide your own ingress or you can install Nginx Ingress Controller to use the InfluxDB-defined ingress.

If using the InfluxDB-defined ingress, add a valid TLS Certificate to the cluster as a secret. Provide the paths to the TLS certificate file and key file:

kubectl create secret tls ingress-tls \
  --namespace influxdb \
  --cert 
TLS_CERT_PATH
 \
  --key 
TLS_KEY_PATH

Replace the following:

• TLS_CERT_PATH: Path to the certificate file on your local machine.
• TLS_KEY_PATH: 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.

Modify the configuration file to point to prerequisites

Update your myinfluxdb.yml configuration file with credentials necessary to connect your cluster to your prerequisites.

• Configure ingress
• Configure the object store
• Configure the catalog database
• Configure local storage for ingesters
• Configure your OAuth2 provider
• Configure the size of your cluster

Configure ingress

To configure ingress, provide values for the following fields in your myinfluxdb.yml configuration file:

• spec.package.spec.ingress.hosts: Cluster hostnames

  Provide the hostnames that Kubernetes should use to expose the InfluxDB API endpoints. For example: cluster-host.com.

  You can provide multiple hostnames. The ingress layer accepts incoming requests for all listed hostnames. This can be useful if you want to have distinct paths for your internal and external traffic.

  You are responsible for configuring and managing DNS. Options include:

  • Manually managing DNS records
  • Using external-dns to synchronize exposed Kubernetes services and ingresses with DNS providers.

• spec.package.spec.ingress.tlsSecretName: TLS certificate secret name

  Provide the name of the secret that contains your TLS certificate and key. The examples in this guide use the name ingress-tls.

  The tlsSecretName field is optional. You may want to use it if you already have a TLS certificate for your DNS name.

  Use cert-manager and Let’s Encrypt to manage TLS certificates

  If you instead want to automatically create an ACME certificate (for example, using Let’s Encrypt), refer to the cert-manager documentation 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.

  If you choose to use cert-manager, it’s your responsibility to install and configure it.

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
# ...
ingress:
  hosts:
    - cluster-host.com
  tlsSecretName: ingress-tls

Configure the object store

To connect your InfluxDB cluster to your object store, provide values for the following fields in your myinfluxdb.yml configuration file:

• spec.package.spec.objectStore
  • .endpoint: Object storage endpoint URL
  • .allowHttp: Set to true to allow unencrypted HTTP connections
  • .accessKey.value: Object storage access key
  • .secretKey.value: Object storage secret key
  • .bucket: Object storage bucket name
  • .region: Object storage region

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      objectStore:
        # URL for S3 Compatible object store
        endpoint: 
S3_URL

        # Set to true to allow communication over HTTP (instead of HTTPS)
        allowHttp: 'false'

        # S3 Access Key
        # This can also be provided as a valueFrom: secretKeyRef:
        accessKey:
          value: 
S3_ACCESS_KEY

        # S3 Secret Key
        # This can also be provided as a valueFrom: secretKeyRef:
        secretKey:
          value: 
S3_SECRET_KEY

        # Bucket that the Parquet files will be stored in
        bucket: 
S3_BUCKET_NAME

        # This value is required for AWS S3, it may or may not be required for other providers.
        region: 
S3_REGION

Replace the following:

• S3_URL: Object storage endpoint URL
• S3_ACCESS_KEY: Object storage access key
• S3_SECRET_KEY: Object storage secret key
• S3_BUCKET_NAME: Object storage bucket name
• S3_REGION: Object storage region

Configure the catalog database

The InfluxDB catalog is a PostgreSQL-compatible relational database that stores metadata about your time series data. To connect your InfluxDB cluster to your PostgreSQL-compatible database, provide values for the following fields in your myinfluxdb.yml configuration file:

• spec.package.spec.catalog.dsn.valueFrom.secretKeyRef
  • .name: Secret name
  • .key: Key in the secret that contains the DSN

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      catalog:
        # A postgresql style DSN that points to a postgresql compatible database.
        # postgres://[user[:password]@][netloc][:port][/dbname][?param1=value1&...]
        dsn:
          valueFrom:
            secretKeyRef:
              name: 
SECRET_NAME
              key: 
SECRET_KEY

Replace the following:

• SECRET_NAME: Name of the secret containing your PostgreSQL-compatible DSN
• SECRET_KEY: Key in the secret that references your PostgreSQL-compatible DSN

postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable

Configure local storage for ingesters

InfluxDB ingesters require local storage to store the Write Ahead Log (WAL) for incoming data. To connect your InfluxDB cluster to local storage, provide values for the following fields in your myinfluxdb.yml configuration file:

• spec.package.spec.ingesterStorage
  • .storageClassName: Kubernetes storage class. This differs based on the Kubernetes environment and desired storage characteristics.
  • storage: Storage size. We recommend a minimum of 2 gibibytes (2Gi).

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      ingesterStorage:
        storageClassName: 
STORAGE_CLASS
        storage: 
STORAGE_SIZE

Replace the following:

• STORAGE_CLASS: Kubernetes storage class
• STORAGE_SIZE: Storage size (example: 2Gi)

Configure your OAuth2 provider

InfluxDB Clustered uses OAuth2 to authenticate administrative access to your cluster. To connect your InfluxDB cluster to your OAuth2 provide, provide values for the following fields in your myinfluxdb.yml configuration file:

• spec.package.spec.admin
  • identityProvider: Identity provider name. If using Microsoft Entra ID (formerly Azure Active Directory), set the name to azure.
  • jwksEndpoint: JWKS endpoint provide by your identity provider.
  • users: List of OAuth2 user IDs to grant administrative access to your InfluxDB cluster. IDs are provided by your identity provider.

Below are examples for Keycloak, Auth0, and Microsoft Entra ID, but other OAuth2 providers should work as well:

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      admin:
        identityProvider: keycloak
        jwksEndpoint: |-
          https://
KEYCLOAK_HOST
/auth/realms/
KEYCLOAK_REALM
/protocol/openid-connect/certs          
        users:
          - 
KEYCLOAK_USER_ID

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      admin:
        identityProvider: auth0
        jwksEndpoint: |-
          https://
AUTH0_HOST
/.well-known/openid-configuration          
        users:
          - 
AUTH0_USER_ID

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      admin:
        identityProvider: azure
        jwksEndpoint: |-
          https://login.microsoftonline.com/
AZURE_TENANT_ID
/discovery/v2.0/keys          
        users:
          - 
AZURE_USER_ID

Adding users

Finally, add all the users you wish to have access to use influxctl. Update the spec.package.spec.admin.users field with a list of these users. See Adding or removing users for more details.

Configure the size of your cluster

By default, an InfluxDB cluster is configured with the following:

• 3 ingesters:
  Ensures redundancy on the write path.
• 1 compactor:
  While you can have multiple compactors, it is more efficient to scale the compactor vertically (assign more CPU and memory) rather than horizontally (increase the number of compactors).
• 1 querier:
  The optimal number of queriers depends on the number of concurrent queries you are likely to have and how long they take to execute.

The default values provide a good starting point for testing. Once you have your cluster up and running and are looking for scaling recommendations, please contact the InfluxData Support team. 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 myinfluxdb.yml. If omitted, your cluster will use 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
• Memory resource units

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