Skip to content

Align gateway env var examples with Helm 8.8+ default (embedded gateway) #8237

@giorgionaps

Description

@giorgionaps

From 8.8, the default Helm configuration runs the Zeebe Gateway embedded in the broker pod. Our gateway configuration docs still primarily use the standalone gateway-style env vars (ZEEBE_GATEWAY_*) in examples, even though we have a note explaining the difference between embedded vs standalone.

This can be confusing, especially for users who land on the page via search, skim, and copy the first examples they see. A recent SUPPORT ticket (SUPPORT-31886) appears to stem from this kind of confusion.

Proposed changes:

  1. Make embedded gateway the default in examples

Update examples to use:
Properties: zeebe.broker.gateway.*
Env vars: ZEEBE_BROKER_GATEWAY_*
Where relevant, add a short parenthetical in the first example, e.g.:
“For a standalone gateway, use zeebe.gateway.* / ZEEBE_GATEWAY_* instead.”
Tighten and surface the embedded vs standalone note

  1. Convert the existing note into a short, prominent callout placed immediately before the first example, something like:

“Helm defaults (Camunda 8.8+) use an embedded gateway. Use zeebe.broker.gateway.* / ZEEBE_BROKER_GATEWAY_.
If you run a standalone gateway, use zeebe.gateway.
/ ZEEBE_GATEWAY_* instead.”
(Optional) Add a tiny mapping table

For one or two key options, show side-by-side:
Embedded: zeebe.broker.gateway.network.port / ZEEBE_BROKER_GATEWAY_NETWORK_PORT
Standalone: zeebe.gateway.network.port / ZEEBE_GATEWAY_NETWORK_PORT

Reported in slack: https://camunda.slack.com/archives/C026U8GBNSW/p1773396678867559

Metadata

Metadata

Assignees

Labels

kind/enhancementIssues related with enhancing existing documentation or the documentation structure (nice to have)

Type

No type
No fields configured for issues without a type.

Projects

Status

✅ Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions