docs(8.8): identity-as-code page shows chart 8.9+ syntax, leaves authorizations un-imported on 8.8

[Ian-wang-liyang]

Summary

The Identity as Code page for version 8.8 shows Helm syntax that does not work on chart camunda-platform-8.8. Customers following the documented steps end up with a file written to /usr/local/camunda/config/identity-as-code.yaml inside the pod, but Spring never imports it, so no authorizations / groups / roles / tenants / users are created.

Reported via SUPPORT-33109 (Deutsche Telekom, Camunda 8.8.24, Helm chart 13.7.0).

Where the bug is

versioned_docs/version-8.8/self-managed/components/orchestration-cluster/core-settings/configuration/identity-as-code.md

Every Helm tab on the page uses:

orchestration:
  extraConfiguration:
    - file: identity-as-code.yaml
      content: |
        camunda:
          security:
            initialization:
              authorizations: [...]

Why it does not work on chart 8.8

The array form - file: … content: … and the automatic spring.config.import rendering were introduced in chart camunda-platform-8.9 (PR camunda/camunda-platform-helm#5629, commit d1c901c00 — "feat: add springImport flag to extraConfiguration entries"). They are present in 8.9 and 8.10 only.

In chart 8.8:

• orchestration.extraConfiguration is a map ({}), not an array — see charts/camunda-platform-8.8/values.yaml:3124 and values.schema.json:5534.
• The configmap (templates/orchestration/configmap-unified.yaml:33) and statefulset (templates/orchestration/statefulset.yaml:201) mount the file under /usr/local/camunda/config/, but templates/orchestration/files/_application-unified.yaml does not emit any spring.config.import block.

Spring Boot does not load arbitrary YAML files just because they are on the classpath — they must be explicitly imported. Result: the documented syntax silently fails on 8.8.

Proposed fix (docs only — no chart change for 8.8)

Rewrite the 8.8 page so the documented syntax actually works on chart 8.8. Two acceptable approaches:

Option A — recommend the chart-native path (preferred):

orchestration:
  security:
    initialization:
      authorizations:
        - ownerType: USER
          ownerId: john.doe
          resourceType: RESOURCE
          resourceId: "*"
          permissions:
            - CREATE
            - READ
      groups: [...]
      roles: [...]
      tenants: [...]
      users: [...]
      mappingRules: [...]

These paths are already templated into the main application.yaml by _application-unified.yaml (see :212-215 for authorizations, plus surrounding blocks for users / mapping-rules / default-roles). No Spring import needed. This is the customer's own confirmed workaround on SUPPORT-33109.

Option B — keep the extraConfiguration story but document the 8.8-specific steps:

orchestration:
  env:
    - name: SPRING_CONFIG_IMPORT
      value: "optional:file:/usr/local/camunda/config/identity-as-code.yaml"
  extraConfiguration:
    identity-as-code.yaml: |
      camunda:
        security:
          initialization:
            authorizations: [...]

Note the map syntax (identity-as-code.yaml: |, not - file: …) and the explicit SPRING_CONFIG_IMPORT env var — this is what chart 8.9+ generates automatically and what 8.8 requires you to wire yourself.

Either option works. Recommendation: lead with Option A, show Option B as an alternative for users who want Identity-as-Code in a separate file (the multi-stage use case the feature was designed for).

Add a one-line callout at the top of the page:

The array - file: / content: syntax requires Helm chart 8.9 or later. On chart 8.8, use one of the patterns below.

The 8.9 / 8.10 / next versions of the page are correct and should not be touched.

No chart fix planned

Backporting springImport to chart 8.8 would be a breaking schema flip (map → array) and is not planned. Docs fix is the resolution.

Affected page

• versioned_docs/version-8.8/self-managed/components/orchestration-cluster/core-settings/configuration/identity-as-code.md — all five Helm tabs (authorizations, groups, mapping rules, roles, tenants, users).

References

• SUPPORT-33109
• feat: add springImport flag to extraConfiguration entries camunda-platform-helm#5629 (feature introducing the documented syntax in chart 8.9)
• Chart 8.8 templates: charts/camunda-platform-8.8/templates/orchestration/{configmap-unified.yaml,statefulset.yaml,files/_application-unified.yaml}