Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      The Things Stack Enterprise

      • Overview
      • AWS
      • Kubernetes
        • Generic
          • Prerequisites
          • Preparation
          • Configuration
          • Install Charts
          • Monitoring
          • Troubleshooting
          • Database Migrations
        • Azure
      • Docker
      • The Things Join Server
      • Manage The Things Stack

      Configuration

      Updated 23 June 2026 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      The Things Stack Helm chart is configured using yaml files. This guide assumes that these fields are saved in a <deployment>.values.yaml file and used for deployment/updates.

      The following is a list of mandatory minimum fields. For a full list of possible values, check the values.yaml file at the root of the The Things Stack Helm chart. You can find it on artifacthub.io as well.

      Warning:

      Some values in this file are secrets. Make sure to check this file into a secure repository.

      Implications of choosing the domain and initial tenant

      Note:

      The global.domain, global.deployment.initialTenant.tenantID and global.tenancy.defaultID values determine how The Things Stack constructs its URLs and what your TLS certificates must cover.

      Single-tenant deployments

      For single-tenant deployments, set global.tenancy.defaultID to the tenant ID. This makes The Things Stack accessible directly at the configured domain without a tenant subdomain.

      Example configuration:

      global:
        domain: thethings.example.com
        deployment:
          initialTenant:
            tenantID: tti
            adminUserID: admin-tti
            adminPassword: ...
            adminEmail: admin@example.com
        tenancy:
          defaultID: tti
      

      With this configuration, The Things Stack is available at:

      • Console: https://thethings.example.com
      • API: https://thethings.example.com/api/v3

      The TLS certificate (referenced by global.ingress.tls.secretName) only needs to cover the base domain:

      • thethings.example.com

      Multi-tenant deployments

      Your license must support multi-tenancy to use this configuration. For multi-tenant deployments, set global.tenancy.defaultID to an empty string. Each tenant is then served on its own subdomain of the configured domain.

      Example configuration:

      global:
        domain: thethings.example.com
        deployment:
          initialTenant:
            tenantID: tti
            adminUserID: admin-tti
            adminPassword: ...
            adminEmail: admin@example.com
        tenancy:
          defaultID: ""
      

      With this configuration, the initial tenant is available at:

      • Console: https://tti.thethings.example.com
      • API: https://tti.thethings.example.com/api/v3

      When additional tenants are created, they are automatically served at https://<tenantID>.thethings.example.com. The TLS certificate must cover the base domain and a wildcard for tenant subdomains:

      • thethings.example.com
      • *.thethings.example.com

      The wildcard entry is required because each tenant is served on its own subdomain. Without it, browsers and API clients will reject the connection for any tenant-specific URL. No changes to the The Things Stack configuration or TLS certificates are needed when adding new tenants, as long as the wildcard certificate is in place.

      license:
        key: # License for The Things Stack
      global:
        domain: # Domain where The Things Stack deployment is exposed.
        deployment:
          initialTenant:
            tenantID: # ID of the initial (first) tenant.
            adminPassword: # Password for the Administrator of the tenant.
            adminUserID: # User ID for the Administrator of the tenant. Do not use `admin`.
            adminEmail: # Email of the Administrator of the tenant.
        blob:
          provider: # "aws", "azure", "gcp", "local" or empty string to disable blob usage.
          aws: # Set only if provider is "aws".
            region: # region
            accessKeyID: # AWS access key ID
            secretAccessKey: # AWS access key secret
          azure: # Set only if provider is "azure".
            accountName: # account name
          gcp: # Set only if provider is "gcp".
            # Base64 encoded GCP credentials.json file.
            # One option is to run `$ cat <credentials>.json | base64`.
            credentials:
          local: # Local Blob via a PV(C). The PVC must support the `ReadWriteMany` access mode.
            pvc: # Name of the PVC.
        cluster:
          keys: # See preparation section.
        http:
          cookie:
            blockKey: # See preparation section.
            hashKey: # See preparation section.
          metrics:
            password: # See preparation section.
          pprof:
            password: # See preparation section.
        redis:
          address: # Address of the Redis Database end point.
          password: # (Optional) Password to access Redis.
          readOnly:
            address: # (Optional) Address of the Redis Database read-only end point.
            password: # (Optional) Password to access Redis.
        console:
          oauth:
            clientSecret: # See preparation section.
        ingress:
          controller: # Ingress controller class name.
          tls:
            secretName: # Secret Name containing the TLS Certificates for the Domain.
        tenancy:
          adminKey: # See preparation section.
        interop:
          # Description: Interoperability configuration source.
          # Expected value: "blob", "directory", "url" or empty string to disable blob usage
          configSource: "blob"
          blob:
            # Description: Bucket for interoperability configuration.
            # Expected value: string
            bucket: ""
      is:
        # Postgres connection string
        # Format : postgres://<username>:<password>@<host>:<port>/<database>?<options>
        database:
          uri:
        profilePictures:
          # Description: Bucket used for storing profile pictures
          # Expected value: string
          bucket: ""
        endDevicePictures:
          # Description: Bucket used for end device pictures
          # Expected value: string
          bucket: ""
      dcs:
        edcs:
          blob:
            bucket: # End Device Claiming Server bucket from "Section 4. Blob Storage"
      

      Optional features

      Beyond the mandatory minimum above, the chart supports a number of optional features. Each is configured through additional values.yaml keys; see the full values.yaml for the complete list and defaults.

      • High availability: per-component PodDisruptionBudgets (<component>.podDisruptionBudget.*) and horizontal pod autoscaling.
      • Redis high availability: Redis Sentinel failover (global.redis.failover.*) and separate cache/events Redis endpoints (global.cache.redis.*, global.events.redis.*).
      • OpenTelemetry tracing: global.tracing.*.
      • OIDC login: is.oidcProvider.*.
      • Email delivery: is.email.provider with smtp, sendgrid or dir backends.

      Security context, scheduling and service accounts

      The Helm chart exposes a set of global values that apply to every component (as, console, dcs, gcs, gs, is, js, noc, ns, pba). Each sub-chart exposes the same keys so that the global defaults can be overridden or augmented per component.

      Field name Default Description
      global.podSecurityContext runAsUser/runAsGroup: 886, runAsNonRoot: true Pod-level security context shared by every component.
      global.containerSecurityContext allowPrivilegeEscalation: false, capabilities.drop: [ALL] Container-level security context shared by every component.
      global.nodeSelector {} Node labels used to schedule all component pods.
      global.podLabels {} Labels applied to the pod template of all components.
      global.serviceAccount.create true Whether to create ServiceAccounts for the components. Disable to bring your own pre-provisioned ServiceAccounts.
      global.serviceAccount.automountServiceAccountToken false Whether pods should mount the ServiceAccount token. The Things Stack components do not call the Kubernetes API, so this is false for hardening.
      global.serviceAccount.annotations {} Annotations applied to all component ServiceAccounts. Use this to attach cloud-provider workload-identity annotations.

      The override semantics differ per value type:

      • Scalar keys (for example serviceAccount.create, serviceAccount.automountServiceAccountToken): if the component value is set, it replaces the global value. Otherwise the global applies.
      • Map keys (for example podSecurityContext, containerSecurityContext, nodeSelector, serviceAccount.annotations): the component map is merged on top of the global map. Keys present in both are won by the component.

      For example, to run all pods on the lorawan node pool except the NOC Grafana pod which must land on the monitoring pool:

      global:
        nodeSelector:
          agentpool: lorawan
      noc:
        grafana:
          nodeSelector:
            agentpool: monitoring
      

      Note:

      global.serviceAccount.name has no global equivalent because each component needs a unique ServiceAccount name. Set <component>.serviceAccount.name per component to bring your own ServiceAccount.

      The Things Indoor Gateway Pro configuration

      The Helm chart does not support The Things Indoor Gateway Pro by default. To enable it in the Helm chart, The Things Gateway Controller must be enabled and the ingress controller of the Kubernetes cluster must have mTLS configured.

      To set up the gateway controller, the following fields must be filled in values.yaml:

      Field name Description
      global.ttgc.enabled The Things Gateway Controller enable flag. Set this to true.
      global.ttgc.domain Domain name of the cluster. Should be the same as global.domain.
      global.ttgc.tls.secretName Kubernetes Secret name containing the TLS. Should be the same as global.ingress.tls.secretName.
      global.ttgc.address (Optional) The URL of the gateway controller. It not specified, it defaults to gc.thethings.industries:443.

      Note:

      In case you are using the cloud-managed The Things Gateway Controller (i.e. gc.thethings.industries:443), your network must be registered on The Things Gateway Controller, otherwise connections to the gateway controller will fail. Please contact The Things Industries support for registration.

      The Things Stack verifies the identity of each connected TTIGPro gateway for security reasons, therefore mutual TLS is necessary to be configured in the ingress controller. mTLS configuration depends on the chosen ingress controller and is left to the operator of the Kubernetes cluster. The Things Stack recognizes the following client certificate header names:

      • X-Forwarded-Client-Cert
      • X-Forwarded-Tls-Client-Cert

      As an example, the steps to configure Traefik to support mTLS are the following:

      1. Create the Traefik middleware that passes the TLS client certificates in the request headers.

        • Paste the k8s middleware manifest into a yaml file (make sure to set the correct namespace):
        # traefik-passtlsclientcert.yaml
        apiVersion: traefik.io/v1alpha1
        kind: Middleware
        metadata:
          name: traefik-passtlsclientcert
          namespace: <traefik-namespace>
        spec:
          passTLSClientCert:
            pem: true
        
        • Apply the k8s manifest to the cluster:
        kubectl apply -f traefik-passtlsclientcert.yaml 
        

      For more info check the Traefik docs on the PassTLSClientCert middleware.

      1. Configure the default TLS options for Traefik.

        • Paste the k8s middleware manifest into a yaml file (make sure to set the correct namespace):
        # traefik-tlsoption.yaml
        apiVersion: traefik.io/v1alpha1
        kind: TLSOption
        metadata:
          name: default
          namespace: <traefik-namespace>
        spec:
          clientAuth:
            clientAuthType: RequestClientCert
        
        • Apply the k8s manifest to the cluster:
        kubectl apply -f traefik-tlsoption.yaml
        

      Note:

      The Things Stack Helm chart uses wildcard domains in ingress routes. This is necessary for multi-tenant deployments as we don’t know the names of the tenants in advance. Traefik does not support TLS options for wildcard domains, because it maps the TLS options based solely on the host name (the Host part of the ingress rule) and it needs a concrete domain to match (check out more in the Traefik docs). To go around this limitation, a default TLS option can be used which is the fallback for any unmatched host.

      For more info check the Traefik docs on TLS options.

      1. Set the protocol annotations for The Things Indoor Gateway Pro, middleware annotations and service annotations in values.yaml (in addition to the existing annotations):
      global:
        ingress:
          annotations:
            ttigw:
              traefik.ingress.kubernetes.io/router.entrypoints: ttigw,ttigwsecure
              traefik.ingress.kubernetes.io/router.middlewares: traefik-passtlsclientcert@kubernetescrd
              traefik.ingress.kubernetes.io/router.tls: "true"
        services:
          annotations:
            grpc:
              traefik.ingress.kubernetes.io/service.serversscheme: h2c
      
      1. Install (or upgrade) the helm chart.
      ← Preparation Install Charts →

      On this page

      • Optional features
      • Security context, scheduling and service accounts
      • The Things Indoor Gateway Pro configuration

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories