Skip to main content

Configuration

The shape and lifecycle of the deployer's input. Three concept pages cover the file hierarchy and the load-bearing fields (customerId, stage); eight incident pages document specific input-validation and sanitization gaps that have bitten in production. Answers: "Where does each value in instance.yaml come from?", "Why is my deployment using the wrong namespace?", "Why did a token with a trailing newline silently break Git auth?", "What's the difference between project.yaml and instance.yaml?", "What changed in v1.14 that made MASTER_PASSWORD strict-required?".

Audience: anyone editing instance.yaml (or the underlying project.yaml / runtime-state.json), and anyone debugging input-validation or sanitization errors before the deployer even reaches step 1.

What lives here​

  • The input-side surface area: which file holds which field, and in what precedence order.
  • The two fields with the most operational consequence — customerId and stage.
  • A growing log of input-validation incidents: places where the validator was too lenient (or too strict in a way that broke an upgrade).

What does NOT live here:

  • How a field is consumed by a deployer step — that lives with the step in deployment.
  • Secret-value semantics (rotation, derivation, encryption) — see security.
  • runtime-state.json schema in detail — owned by infrastructure and cross-linked from concept-config-hierarchy.

Pages​

Concepts​

  • concept-config-hierarchy — load order and precedence: project.yaml → instance.yaml → runtime-state.json → <service>-inflight.json markers (+ the K8s deploy Lease); atomic 0600 writes with ETag/If-Match on the web PUT
  • concept-config-field-reference — previously undocumented fields: Terraform SKE/DNS/PostgreSQL/Redis sizing, ingress tuning knobs, cluster.*, storage.* (partial replacement for the nonexistent docs/CONFIG.md)
  • concept-customer-id — customerId triple-duty: directory under customers/, parent-Application name, label selector
  • concept-stage — stage enum (dev/test/qs/prod), namespace mapping, prod-only hard fails

Incidents — input sanitization (whitespace, normalization)​

  • incident-domain-not-normalized — trailing dot / mixed case in mainDomain not normalized; downstream cert mismatch
  • incident-token-whitespace — Git access token with trailing newline silently breaking HTTPS auth
  • incident-registry-cred-whitespace — registry credentials with whitespace producing imagePullBackOff
  • incident-master-password-whitespace — leading/trailing whitespace in master password breaking derivePassword reproducibility
  • incident-xwiki-license-whitespace — XWiki license string with embedded whitespace rejected at runtime
  • incident-openproject-ee-token-yaml-folded — multi-line PEM token loaded correctly, then YAML-folded to spaces by the writer at 07b_enterprise_setup.go:346; OP seeder's TokenSeeder fails; auth_providers row never persists; /auth/keycloak 404

Incidents — validation gaps and required-field changes​

  • incident-customerid-not-validated — customerId accepted with characters that break Git paths; needed strict regex
  • incident-enterprise-render-env — Enterprise render skipped because OPENDESK_ENTERPRISE env var wasn't passed to helmfile
  • incident-master-password-required — v1.14 upstream tightened env-var fallbacks to required; smoke-test must now pass MASTER_PASSWORD
  • security — MasterPassword and SecretsManager.* fields and what they unlock
  • deployment — concept-config-hierarchy is referenced by every step; the deployer reads this config
  • infrastructure — runtime-state.json is written by the infra service and read by the deployer
  • sizing — platformSizing is one of the input fields

When to add a page here​

  • A new field in instance.yaml is added or its semantics change — update or add a concept-*
  • A new input-validation or sanitization gap is discovered — incident-*
  • A field becomes required where it was optional (or vice versa) — record as incident-* if it broke an upgrade
  • A new validation rule is added to ValidateDeployer() — link or update the relevant concept-*

Anything about how the deployer consumes a field (which step uses it, what it does with it) belongs in deployment. Anything about secret values themselves belongs in security — this topic covers the input-side surface area only.