Skip to content

Fix outdated Zeebe env var names in broker config docs after 8.9 rename (provide mapping table) #8962

@deng-leon

Description

@deng-leon

There is a mismatch between the Zeebe broker config environment variable documentation and the 8.9 property reference.

Affected pages:

In Camunda 8.9, the environment variables for broker/cluster settings were renamed from ZEEBE_BROKER_... to CAMUNDA_CLUSTER_... (see this task). However, the documentation pages above still reference a mix of old and new variable names and have different capitalization and word separation styles. This can cause confusion or misconfiguration for users.

Overview of environment variable naming mismatch (examples):

Property / Setting Old variable (pre-8.9, shown in Broker Config) New variable (8.9+, in Property Reference)
Network command API host ZEEBE_BROKER_NETWORK_COMMANDAPI_HOST CAMUNDA_CLUSTER_NETWORK_COMMANDAPI_HOST
Network command API port ZEEBE_BROKER_NETWORK_COMMANDAPI_PORT CAMUNDA_CLUSTER_NETWORK_COMMANDAPI_PORT
Network command API advertised host ZEEBE_BROKER_NETWORK_COMMANDAPI_ADVERTISEDHOST CAMUNDA_CLUSTER_NETWORK_COMMANDAPI_ADVERTISEDHOST
Network base host ZEEBE_BROKER_NETWORK_HOST CAMUNDA_CLUSTER_NETWORK_HOST
Network advertised host ZEEBE_BROKER_NETWORK_ADVERTISEDHOST CAMUNDA_CLUSTER_NETWORK_ADVERTISEDHOST
Network port offset ZEEBE_BROKER_NETWORK_PORTOFFSET CAMUNDA_CLUSTER_NETWORK_PORTOFFSET
... ... ...

Note: The old and new patterns follow the same segment structure but differ in their prefix and sometimes capitalization/word splitting.

Proposed fix:

  • Update the Zeebe broker config page to reference (and explain) only the new CAMUNDA_CLUSTER_... environment variable names as introduced in 8.9.
  • Ensure all examples, tables, and explanatory text use the new convention.
  • Consider adding a brief mapping or migration section to help users with legacy configs.
  • Normalize the presentation/capitalization of environment variable names and property names, and clarify their mapping if needed.

Background:

  • In Camunda 8.9, the env variable scheme for Zeebe was renamed from zeebe_broker_.../ZEEBE_BROKER_... to camunda_cluster_.../CAMUNDA_CLUSTER_....
  • Affected users may reference the wrong environment vars if following the old docs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    component:docsDocumentation improvements, including new or updated contentkind/bugIssues related with bugs in the documentation

    Type

    Urgency

    None yet

    Projects

    Status
    🆕 Inbox

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions