Kubernetes Secret References

Fuzzball CRD fields that accept credentials — passwords, API keys, TLS certificates, and image pull secrets — support references to Kubernetes Secrets as an alternative to inline plaintext values. Using Secret references keeps credentials out of the CRD and is recommended for production deployments.

When the operator reconciles a FuzzballOrchestrate or FuzzballFederate CR that contains inline plaintext credentials, it automatically migrates them to Secret references:

1. The operator detects inline credential fields that do not already have a corresponding *Ref set.
2. It creates (or updates) a Kubernetes Secret named fuzzball-credentials-{cr-name} in the fuzzball-system namespace containing all the plaintext values.
3. It patches the CR to replace each inline value with a *Ref pointing to that Secret and clears the plaintext value from the CR.

Existing deployments with inline credentials are migrated automatically on the next reconcile after upgrading — no manual action is required.

Some SecretKeyReference (*Ref) fields are auto-migrated. TLS secrets (secretName) and image pull secrets (credentialsSecretName) are never auto-migrated because they require a specific Secret type — see the per-field table below for per-field behavior.

Used for individual credential values: passwords, API keys, SSH keys. Points to a specific key within a generic Kubernetes Secret.

keycloak:
  create:
    passwordRef:
      name: my-secret
      key: keycloak-password
      namespace: fuzzball-system  # optional — defaults to fuzzball-system

Create the Secret:

$ kubectl create secret generic my-secret \
    --from-literal=keycloak-password=my-secure-password \
    -n fuzzball-system

Used for TLS certificate/key pairs. Points to a kubernetes.io/tls Secret containing tls.crt and tls.key.

keycloak:
  create:
    ingress:
      tls:
        secretName: keycloak-tls

Create the Secret:

$ kubectl create secret tls keycloak-tls \
    --cert=path/to/tls.crt \
    --key=path/to/tls.key \
    -n fuzzball-system

Used for container registry credentials. Points to a kubernetes.io/dockerconfigjson Secret.

image:
  credentialsSecretName: depot-pull-secret

Create the Secret:

$ kubectl create secret docker-registry depot-pull-secret \
    --docker-server=depot.ciq.com \
    --docker-username=my-depot-user \
    --docker-password=my-depot-token \
    -n fuzzball-system

By default the operator looks for Secrets in fuzzball-system. To use a Secret from another namespace, set the optional namespace field:

keycloak:
  create:
    passwordRef:
      name: my-secret
      key: keycloak-password
      namespace: my-secrets-namespace

Storing credentials inline in a CRD means they appear in:

• kubectl get / kubectl describe output
• Kubernetes audit logs
• Any etcd backup

Keeping credentials in Secrets limits their exposure to workloads and users that have explicit RBAC access to those Secrets. The operator’s auto-migration ensures that even deployments that started with inline credentials are moved to this safer pattern automatically.