First-class 8.10 support and docs for Orchestration REST/gRPC TLS modes

[eamonnmoloney]

Problem

TLS configuration for the 8.10 Helm chart is not first-class enough for customers.

Today, customers must understand and manually combine several low-level settings across Orchestration, ingress, Web Modeler, Connectors, and Java trust configuration. The behavior is partly documented in separate component reference pages, but there is no clear customer-facing Helm guide or first-class values surface for the common deployment modes.

This became visible while working SUPPORT-33090 / PR #6280. The customer configuration enables TLS for the Orchestration gRPC API while leaving the Orchestration REST API plaintext:

orchestration:
  env:
    - name: CAMUNDA_API_GRPC_SSL_ENABLED
      value: "true"
    - name: SERVER_SSL_ENABLED
      value: "false"

That is a valid deployment shape, but it is hard to configure correctly because each consumer uses a different endpoint scheme convention:

• Orchestration REST remains http://...:8080/orchestration when SERVER_SSL_ENABLED=false.
• Orchestration gRPC is TLS-enabled on :26500 when CAMUNDA_API_GRPC_SSL_ENABLED=true.
• Web Modeler needs grpcs://...:26500 for the secure gRPC endpoint.
• Connectors / Camunda client needs https://...:26500 for the secure gRPC endpoint.
• Public gRPC ingress must proxy to the backend with nginx.ingress.kubernetes.io/backend-protocol: GRPCS when the in-chart Orchestration gRPC backend uses TLS.
• Trust material must be mounted/configured consistently for Web Modeler, Connectors, and any other in-cluster clients.

Customers should not need to reverse-engineer this from component internals.

Scope

Target 8.10 first. Decide separately whether to backport any part to 8.9/8.8.

Proposed outcome

Provide first-class 8.10 Helm support and documentation for Orchestration TLS modes:

• REST plaintext + gRPC TLS.
• REST TLS + gRPC plaintext, if supported.
• REST TLS + gRPC TLS.
• Plaintext REST + plaintext gRPC.

The chart should expose a clear, supported way to configure these modes without requiring users to hand-wire all internal client URLs and ingress annotations.

Acceptance criteria

• Add a customer-facing Helm guide for Orchestration REST/gRPC TLS configuration in 8.10 docs.
• The guide clearly explains that REST TLS (SERVER_SSL_ENABLED) and gRPC TLS (CAMUNDA_API_GRPC_SSL_ENABLED) are independent server settings.
• The guide shows the required endpoint schemes for in-cluster clients:
  • Web Modeler gRPC: grpc:// or grpcs://.
  • Connectors / Camunda client gRPC: http:// or https://.
  • REST: http:// or https:// based on REST server TLS.
• The guide documents the public ingress behavior, including when the gRPC ingress backend protocol must be GRPC vs GRPCS.
• The guide includes a complete 8.10 values example for REST HTTP + gRPC TLS, including trust material.
• The chart has a first-class value surface or helper behavior for this configuration, so users do not have to duplicate large webModeler.restapi.clusters and connectors.configuration blocks just to use Orchestration gRPC TLS.
• CI covers the supported TLS modes for 8.10, at least for the REST HTTP + gRPC TLS mode.
• Existing explicit user overrides remain authoritative:
  • webModeler.restapi.clusters
  • connectors.configuration

Related work

• PR fix: support Orchestration gRPC TLS endpoints #6280: fixes the immediate SUPPORT-33090 behavior and adds regression coverage for REST HTTP + gRPC TLS handling.
• Issue [TASK] support tls for rest #4814: existing narrower issue for REST TLS support.
• SUPPORT-33090: customer report that exposed the configuration gap.

[distro-ci]

🧭 Triage Assessment

Field	Value
Work type	FEATURE_REQUEST
Kind	feature-request
Severity	⚠️ Mid
Likelihood	🔥 High
Confidence	0.93

📝 Rationale

This issue is within SM Platform Distribution scope because the team-boundaries guidance assigns Helm Charts, the camunda/camunda-platform-helm repository, Self-Managed documentation, automated scenario testing/deployments, and customer issues related to Self-Managed Helm Chart configurations to Distribution. The best classification is FEATURE_REQUEST with kind feature-request, not BUG/TASK/TOIL, because the distro non-feature triage defines feature requests as new or improved behavior, while bugs are incorrect existing behavior / broken functionality and chores are maintenance work. Based on the provided issue text, the requested outcome is a first-class, customer-facing values surface and guidance for multiple Orchestration REST/gRPC TLS modes, which is broader than fixing a single defect. That interpretation is reinforced by the related narrower issue #4814, which was already triaged as a FEATURE_REQUEST for missing REST TLS support rather than a bug. PR #6280 appears to address the immediate SUPPORT-33090 behavior and adds regression coverage for the REST-http + gRPC-TLS shape, including secure client defaults, GRPCS ingress backend handling, and preservation of explicit overrides; that makes this new issue look like the broader follow-on request for a polished supported path and docs, not a duplicate of a still-broken implementation bug. I set severity=mid because the gap creates noticeable customer deployment friction, but there is a documented/manual workaround path and partial remediation is already in flight, which aligns better with a non-stop-the-world impact level than high/critical. I set likelihood=high because the affected area is a common secure-deployment path spanning Orchestration, Web Modeler, Connectors, ingress, and trust configuration, and the related REST-TLS issue was already assessed as common rather than edge-case for secure deployments. Per the task/non-feature triage guide, non-internal feature requests should be routed as kind/feature-request and handled via the feature-request path rather than normal engineer auto-triage completion.

🔍 Similar Issues

#4814, #3594, #6308

---

🤖 This issue was automatically triaged by an AI-based system.
✋ If you believe this assessment is incorrect, update the labels or add the triage:manual label for human review.