cert-manager Values Source Stabilization

This page is a troubleshooting document for cert-manager source-layout confusion after the June 20, 2026 stabilization change. The broader deployment contract lives in the infrastructure networking cert-manager reference page.

Symptom

cert-manager changes are hard to reason about because the application appears to need both chart values and a separate manifest-only Git source just to create cloudflare-api-token-vss.

In the pre-fix layout, platform/cert-manager/argocd.yaml carried:

• the Jetstack chart source
• a repo source for charts/common and $values/platform/cert-manager/common-values.yaml
• another repo source for platform/cert-manager/manifests

That extra manifest source was the unstable part.

Likely Causes

• The Cloudflare token VaultStaticSecret lived in platform/cert-manager/manifests/vault-static-secret.yaml even though charts/common already had a vault-static-secrets.yaml renderer.
• platform/cert-manager/common-values.yaml still contains a clusterIssuers block that looks authoritative, but charts/common/templates/ does not render ClusterIssuer resources at all.

Fix

f9280254 moved the Cloudflare token secret into platform/cert-manager/common-values.yaml under common.vaultStaticSecrets and removed the path: platform/cert-manager/manifests source from platform/cert-manager/argocd.yaml.

The remaining layout is intentional:

• the Jetstack chart source installs cert-manager itself
• the repo-backed values source still provides charts/common and $values/platform/cert-manager/common-values.yaml
• charts/common/templates/vault-static-secrets.yaml renders common.vaultStaticSecrets

The fix removed the extra manifest source, not the repo-backed values source.

Diagnostic Path

1. Inspect platform/cert-manager/argocd.yaml and confirm there is no source with path: platform/cert-manager/manifests.
2. Inspect platform/cert-manager/common-values.yaml and confirm common.vaultStaticSecrets defines cloudflare-api-token-vss.
3. Inspect charts/common/templates/vault-static-secrets.yaml and confirm it renders .Values.common.vaultStaticSecrets.
4. For issuer behavior, inspect applications/cluster-bootstrap/manifests/cluster-issuer.yaml, not the stale clusterIssuers block in platform/cert-manager/common-values.yaml.

Prevention

• When a platform app already uses charts/common, keep namespaced VaultStaticSecret resources in that values file unless the common chart truly cannot render them.
• Do not treat common-values.yaml.clusterIssuers as the issuer source of truth. The active ClusterIssuer objects come from applications/cluster-bootstrap/manifests/cluster-issuer.yaml.

Verification

cd lumie-infra
rg -n "platform/cert-manager/manifests|path: charts/common|ref: values" \
  platform/cert-manager/argocd.yaml

rg -n "cloudflare-api-token-vss|vaultStaticSecrets|clusterIssuers" \
  platform/cert-manager/common-values.yaml \
  charts/common/templates/vault-static-secrets.yaml \
  applications/cluster-bootstrap/manifests/cluster-issuer.yaml

Success means argocd.yaml has no platform/cert-manager/manifests source, common-values.yaml defines the Cloudflare token VaultStaticSecret, and issuer ownership is still visible only in the cluster-bootstrap manifest.

Operational Detail

This was a GitOps ownership problem, not a cert-manager controller failure. The confusing part was that several files looked capable of declaring certificate-related resources, but only some of them were actually rendered.

Resource type	Active owner after stabilization	Notes
cert-manager chart	Jetstack chart source in platform/cert-manager/argocd.yaml.	Installs controller components.
Cloudflare token secret sync	common.vaultStaticSecrets rendered by charts/common.	Replaces the extra manifest source.
ClusterIssuer	applications/cluster-bootstrap/manifests/cluster-issuer.yaml.	Not rendered from common-values.yaml.clusterIssuers.

During triage, first identify which renderer owns the object. Do not assume a values block is active just because it is present.

Recovery Playbook

1. Check whether Argo CD is applying an unexpected extra source for cert-manager.
2. If a VaultStaticSecret is missing, verify the common chart values before adding a new manifest directory.
3. If a ClusterIssuer is missing or stale, inspect cluster-bootstrap manifests instead of editing clusterIssuers under cert-manager values.
4. Remove dead or misleading values only after confirming they are not consumed by a template.
5. Sync cert-manager and cluster-bootstrap separately so controller installation and issuer declaration failures are not conflated.

Verification Evidence

Record:

• Argo CD source list for cert-manager has no platform/cert-manager/manifests path,
• rendered manifests include cloudflare-api-token-vss from the common chart,
• live VaultStaticSecret exists in the namespace expected by cert-manager,
• live ClusterIssuer objects match cluster-bootstrap,
• no runbook instructs operators to edit the stale clusterIssuers block.

Anti-Patterns

• Adding another manifest source when charts/common already renders the resource type.
• Moving issuer ownership into cert-manager values without adding a renderer.
• Treating Argo CD multi-source layout as harmless when two sources appear to own the same object.
• Debugging DNS-01 failures before verifying the Cloudflare token secret is rendered and synced.