Skip to main content

Secret Manager Domain

The Secret Manager domain is responsible for handling sensitive values such as client credentials and tokens. Instead of storing these values directly in custom resources, the Control Plane stores a secret reference and keeps the real value in a dedicated secret backend.

This helps reduce accidental exposure of sensitive data and provides one consistent way for domains to store, retrieve, and rotate secrets.

What problem it solves​

  • Keeps secret values out of user-facing resources
  • Provides a single API for secret onboarding, read, write, and deletion
  • Supports centralized access control and auditing
  • Allows backend choice based on environment needs

How it works​

At a high level, the flow is:

  1. A domain sends a secret value to Secret Manager
  2. Secret Manager stores the value in the configured backend
  3. Secret Manager returns a secret reference (secretId placeholder)
  4. The domain stores only that reference in its resource
  5. When needed, the domain resolves the reference and retrieves the value just in time

Backends​

Secret Manager supports multiple storage backends:

  • Kubernetes Secrets — simple and convenient for development and smaller setups
  • Conjur — recommended for production scenarios with stronger access control and auditing

Both backends are accessed through the same Secret Manager API, so domains do not need backend-specific logic.

Backend behavior guarantees​

A shared conformance suite pins both backends to the same observable behavior, so a domain sees identical results regardless of which backend is configured:

  • Empty defaults are not references. Optional values left empty (for example an application's externalSecrets or an environment's zones when nothing is provided) are neither stored nor returned as secret references. Only values that actually exist get a reference.
  • Transient write contention is retryable. Concurrent onboarding of the same environment, team, or application can briefly conflict. Both backends surface this as a retryable "too many requests" response (HTTP 429), and callers (typically a reconciler) simply requeue and retry — no data is lost.
  • Immutable values are preserved. Generated credentials are never silently regenerated on re-onboarding; only an explicitly supplied value overrides them.

Access and security model​

Access is controlled with explicit permissions:

  • secrets_read — read secrets
  • secrets_write — create or delete secrets
  • onboarding_write — manage onboarding-related secret structures (environments, teams, applications)

In addition, Kubernetes network policies can restrict which services are allowed to call Secret Manager at all.

Domain interactions​

  • Rover domain — Obfuscates secrets from Rover payloads before creating resources.
  • Organization domain — Stores and rotates team credentials (for example team tokens).
  • Application domain — Stores application client credentials, including rotated secrets during grace periods.
  • Identity domain — Resolves secret references before provisioning clients in the identity provider.
  • Admin domain — A Zone defaulting webhook onboards zone secrets (IDP admin password, Redis password, gateway admin client secret) under zones/<zone>/admin/... paths and stores references in the Zone resource. The Admin domain also provides onboarding context (environments and teams) used by secret onboarding workflows.
info

When Secret-Manager is disabled in an installation, the same zone secrets are generated inline and kept on the resource instead of being onboarded. See Admin Domain: Secret onboarding for the zone-specific behavior.