For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Configuration reference

This page explains how to configure Physical Tenants in Camunda 8.10 for Self-Managed deployments.

In 8.10, configuration is static. You define Physical Tenants in application configuration, then apply changes with a rolling restart.

Configuration model​

At startup, Camunda resolves tenant configuration using this model:

  1. Root-level camunda.* acts as the implicit base configuration.
  2. The default Physical Tenant is always present.
  3. Optional camunda.physical-tenants.default.* overrides the root-level values for the default Physical Tenant.
  4. Additional tenants are configured under camunda.physical-tenants.<tenant-key>.*.

Section structure​

Use this structure for Physical Tenants:

camunda:
  # Root-level defaults (implicit default tenant base)
  data:
    secondary-storage:
      rdbms:
        url: jdbc:postgresql://db/shared
  security:
    authentication:
      method: oidc
      providers:
        # Cluster-level provider definitions
        my-idp:
          type: oidc

  physical-tenants:
    # Optional overrides for the always-present default tenant
    default:
      cluster:
        # Required when you override default-tenant values
        partitions-count: 3
      data:
        secondary-storage:
          rdbms:
            url: jdbc:postgresql://db/default_tenant
      security:
        authentication:
          providers:
            assigned:
              - my-idp

    # Additional Physical Tenant
    tenanta:
      cluster:
        partitions-count: 3
      data:
        secondary-storage:
          rdbms:
            url: jdbc:postgresql://db/tenanta
      security:
        authentication:
          providers:
            assigned:
              - my-idp

Required and optional properties per tenant​

Each configured tenant under camunda.physical-tenants.<tenant-key> must assign at least one cluster-defined identity provider through security.authentication.providers.assigned. All other tenant-level properties are optional overrides of the root-level defaults.

Identity providers are defined at the cluster level, then assigned per tenant. Physical Tenants do not define tenant-local provider objects.

For the full list of available properties, see the Orchestration Cluster configuration properties reference.

Cluster-wide defaults and per-tenant overrides​

Use root-level camunda.* for shared defaults across all tenants.

Use camunda.physical-tenants.<tenant-key>.* only for tenant-specific differences.

Some properties are cluster-scoped and cannot be overridden per tenant. Per-tenant override behavior is indicated in the Orchestration Cluster configuration properties reference.

Default tenant behavior and compatibility​

The default Physical Tenant is always present in 8.10 and is immutable.

For backward compatibility:

  • Existing root-level single-tenant configuration maps to the default Physical Tenant.
  • If you upgrade from 8.9 to 8.10, no manual migration step is required for this mapping.
  • camunda.physical-tenants.default.* is interpreted as overrides for the existing default tenant, not as creation of a new tenant.

Validation and constraints​

At startup, configuration validation enforces tenant-level constraints.

Known constraints and behavior for 8.10:

  • Tenant keys in camunda.physical-tenants.<tenant-key> must be lowercase alphanumeric ([a-z0-9]+) with a maximum length of 64 characters.
  • Validation rejects unsupported or colliding storage configurations across tenants.
  • For RDBMS-backed secondary storage, the combination of camunda.data.secondary-storage.rdbms.url and the effective table prefix must be unique per tenant.
  • For Elasticsearch and OpenSearch, the effective index prefix must be unique per tenant.
  • For object stores, backend-specific location combinations must be unique per tenant:
    • AWS S3: Bucket name and bucket path.
    • GCP: Bucket name and prefix.
    • Azure: Container name, container path, and endpoint.
    • Local filesystem: Path.
  • Validation failures are startup failures, not runtime warnings.
  • Document store: non-default tenants must declare document.assigned. Startup also fails if two tenants resolve to the same provider, bucket or container, and path. The error names the conflicting tenants.

Configuration examples​

application.yaml​

camunda:
  data:
    secondary-storage:
      rdbms:
        url: jdbc:postgresql://db/default
  document:
    default-store-id: shared-s3
    aws:
      shared-s3:
        bucket-name: company-docs-bucket
        bucket-path: default/

  database:
    url: jdbc:postgresql://db/default

  security:
    authentication:
      method: oidc
      providers:
        corp-idp:
          type: oidc

  physical-tenants:
    default:
      cluster:
        partitions-count: 3
      document:
        default-store-id: shared-s3
        assigned:
          - shared-s3
        # inherits bucket-path: default/ from root
      security:
        authentication:
          providers:
            assigned:
              - corp-idp

    riskprod:
      cluster:
        partitions-count: 3
      data:
        secondary-storage:
          rdbms:
            url: jdbc:postgresql://db/riskprod
      database:
        url: jdbc:postgresql://db/riskprod
      document:
        default-store-id: shared-s3
        assigned:
          - shared-s3
        aws:
          shared-s3:
            bucket-path: riskprod/ # distinct path — no collision with default
      security:
        authentication:
          providers:
            assigned:
              - corp-idp

Environment variables​

Spring environment variable mapping follows canonical property conversion. For example, a root-level property and its per-tenant override:

CAMUNDA_DATA_SECONDARYSTORAGE_RDBMS_URL=jdbc:postgresql://db/default
CAMUNDA_PHYSICALTENANTS_RISKPROD_DATA_SECONDARYSTORAGE_RDBMS_URL=jdbc:postgresql://db/riskprod

If YAML and environment variables are used together, use the same normalized tenant key in both forms.