Skip to content

Installation Notes

Use the overview for configuration entry points and the README for package metadata. Unless labeled as a Kubernetes resource or resource fragment, YAML examples below are package values; in the umbrella, place them under packages.certManager.values with the v1 contract, or legacy certManager.values.

CRD ownership

The package enables CRD installation and retention by default through upstream.crds. A separate preinstall is not required with these defaults. Install cert-manager only once per cluster and coordinate ownership of existing CRDs and admission webhooks. CRDs are cluster-wide; the release namespace contains the workloads, not the CRD objects. If disabling chart-managed CRDs, arrange compatible CRDs externally before installing dependent resources.

Retained CRDs do not retain a deleted namespace’s Secrets or provide a working webhook after removal. Review upstream uninstall guidance and backup guidance before disabling, deleting, or reinstalling the package. Do not delete CRDs while other packages or certificate resources still use them.

Istio

The webhook accepts Kubernetes API-server admission callbacks on pod port 10250. Preserve these coordinated defaults:

  • traffic.sidecar.istio.io/excludeInboundPorts: "10250" bypasses sidecar inbound capture.
  • ambient.istio.io/bypass-inbound-capture: "true" bypasses ambient inbound capture.
  • A pod-selected PeerAuthentication makes only webhook port 10250 permissive for mTLS.
  • The bb-common ingress rule permits the API-server path to webhook port 10250. The umbrella supplies the kubeAPI ingress definition; standalone users must check the source ranges against their control-plane network.

Changing the upstream webhook port requires reviewing all these paths together. The startup API check opts out of sidecar and ambient enrollment. The umbrella also excludes the release namespace from ambient enrollment by default; bypass metadata is not an instruction to enroll it. Verify admission in the selected mode rather than relying on pod readiness alone.

Monitoring

The standalone package defaults its ServiceMonitor to HTTPS with Big Bang’s Prometheus mesh certificates. In contrast, the umbrella enables it with monitoring and post-renders plaintext HTTP, removing tlsConfig. Use the wiring for your Big Bang release, not standalone scrape assumptions.

For a standalone deployment without that mTLS scrape path, explicitly remove the additional endpoint properties so the upstream HTTP metrics endpoint is used:

upstream:
  prometheus:
    servicemonitor:
      endpointAdditionalProperties: null

An empty map may merge with existing Helm defaults rather than remove them. ServiceMonitor CRDs must exist when the resource is enabled. Coordinate scrape transport and the Prometheus identity/network rules in package values.

Managed issuers

The chart can manage one self-signed and one Let’s Encrypt issuer. Both are disabled by default and render on upgrade by default, after webhook readiness. The default scope is a namespaced Issuer in the release namespace; use ClusterIssuer only when cluster-wide issuance is intentional.

For a clean install, configure the desired issuer with createOnInstall: false, wait for the release and webhook to be Ready, then perform an upgrade. Use the same staged procedure on reinstall while retained resources remain. Set createOnInstall: true only when a working cert-manager webhook already exists at initial install; otherwise issuer admission can race webhook startup.

Default names are release-prefixed:

  • <release>-selfsigned
  • <release>-letsencrypt-staging
  • <release>-letsencrypt-production
  • <release>-letsencrypt-custom when server is overridden

After the managed self-signed issuer is Ready, reference its exact name and kind. For the default release, this Kubernetes Certificate resource uses the namespaced issuer. It is not a Helm values overlay:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-selfsigned
  namespace: cert-manager
spec:
  secretName: example-selfsigned-tls
  dnsNames:
    - app.example.com
  issuerRef:
    name: cert-manager-selfsigned
    kind: Issuer
    group: cert-manager.io

Adjust the issuer name for another release or an explicit name override. A namespaced Issuer serves Certificates only in its own namespace; keep the Certificate namespace aligned. This example does not establish public trust or configure an application or gateway to consume the generated TLS Secret.

Self-signed

issuers:
  selfSigned:
    enabled: true

This uses the staged lifecycle above. Only when cross-namespace issuance is intentional, create a cluster-scoped bootstrap issuer with a stable name using these package values:

issuers:
  selfSigned:
    enabled: true
    createOnInstall: false
    scope: ClusterIssuer
    name: platform-bootstrap

The corresponding Certificate resource fragment, replacing the reference in the earlier Certificate, is:

spec:
  issuerRef:
    name: platform-bootstrap
    kind: ClusterIssuer
    group: cert-manager.io

Issuer scope is a chart value; Certificate issuerRef.kind is an API field. The fragment is not a complete Certificate and is not Helm configuration. Cluster scope expands who can request issuance, so review authorization before using it; namespaced Issuer remains the safer default. Self-signed end-entity certificates are not publicly trusted. Use upstream SelfSigned guidance for PKI bootstrap and trust caveats; this chart does not create a CA issuer or distribute trust bundles.

Let’s Encrypt HTTP-01

issuers:
  letsEncrypt:
    enabled: true
    email: platform-team@example.mil
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx

Staging is the safe default. This example requires a verified ingress controller, public DNS and challenge reachability; it does not deploy nginx. Each ingress solver must select exactly one of ingressClassName, class, or name. The package rejects classless solvers and reserved acme.cert-manager.io/http-* label overrides. Consult the upstream solver reference for the API and the Big Bang routing cautions.

The wrapper adds sidecar/ambient opt-out metadata to ingress solver pod templates; explicit metadata wins. It does not add those pod-template overrides to Gateway API solvers. Solver ingress policy is environment-owned, not generated by this chart; review the network prerequisites below before issuance.

Let’s Encrypt DNS-01

Create provider credential Secrets separately and reference them from a solver; never put provider keys in chart values. The DNS-01 provider reference owns provider/workload-identity requirements. The Secret namespace must match the issuer scope. See the staging test example for a Secret reference paired with Big Bang outbound routing.

Gateway API HTTP-01

Gateway API CRDs must exist before controller startup, or the controller needs a restart after their installation. For this bundled version, enable support with upstream.config.enableGatewayAPI: true (or upstream.extraArgs containing --enable-gateway-api). Do not copy a different version’s configuration key. Use the v1.20.3 configuration source and solver API when checking version-specific support.

The solver must set parentRefs or labels and use a Gateway with an HTTP port 80 listener that permits HTTPRoutes from the challenge namespace. An Istio networking.istio.io/Gateway is not a Gateway API object. These package values enable Gateway API support and point the staging solver at an existing Gateway:

upstream:
  config:
    enableGatewayAPI: true
issuers:
  letsEncrypt:
    enabled: true
    createOnInstall: false
    environment: staging
    email: platform-team@example.com
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: public
                namespace: istio-gateway
                kind: Gateway
                group: gateway.networking.k8s.io

Replace the email and Gateway reference with the environment’s actual values. This does not create the Gateway, listener, public DNS, or network permissions. Use the staged issuer upgrade after webhook readiness. Verify the actual Gateway name, namespace, port 80 listener, allowedRoutes, public reachability, and solver-pod mesh policy before requesting a Certificate. See the test plan for route and solver-pod policy requirements.

Production and custom endpoints

Prove staging issuance before setting environment: production. Production is subject to Let’s Encrypt rate limits and needs a separate operational review. An explicit server selects a custom directory and the -letsencrypt-custom name suffix. The package accepts only HTTPS hostnames on port 443, without userinfo or fragments, matching its generated egress/ServiceEntry port.

Override name for a stable issuer identity and privateKeySecretName for a stable account Secret identity. The default Secret name is <issuer-name>-account-key; set the override if this would exceed Kubernetes’ 253-character name limit.

Authorization and approval

A ClusterIssuer expands issuance across namespaces. Restrict creation/update of Certificate and CertificateRequest resources and constrain allowed DNS names. When using the separate Approver Policy package, approval policies must allow the generated issuer reference or requests can remain unapproved. Namespaced Issuer is the safer default; this package does not configure approval policy.

Account key lifecycle

cert-manager creates the ACME account key in the named Secret; the chart never accepts or renders it. An Issuer uses its own namespace. A ClusterIssuer uses the controller’s cluster resource namespace, which defaults to the release namespace in this package.

Back up account Secrets as sensitive identity data. Preserve them through upgrades/migrations to retain account management and revocation access; deleting one can cause a replacement account to be registered. They are not Helm-rendered resources, but namespace deletion still removes them. Big Bang package removal may remove the namespace, so back up keys before disabling or uninstalling.

Network and mesh prerequisites

When ACME issuer creation is active for the current install/upgrade, the chart can add controller egress and directory registration:

  • With common NetworkPolicies and controllerEgress enabled, TCP 443 and UDP/TCP 53 to the configured CIDRs, plus a separate kube-dns allow path. HTTP-01 additionally permits TCP 80 for controller self-checks.
  • A namespace-local ACME directory ServiceEntry when sidecar mode uses REGISTRY_ONLY. Ambient mode does not render this directory ServiceEntry.

The default IPv4 CIDR is broad and excludes the link-local metadata address; tighten it where address ranges are stable. Add appropriate IPv6 CIDRs/exclusions for IPv6 destinations. controllerEgress.cidrs must be nonempty when enabled. Use objects, not the older string form. This package-values fragment shows the full nesting and an exclusion inside its parent CIDR:

issuers:
  letsEncrypt:
    networking:
      controllerEgress:
        cidrs:
          - cidr: 203.0.113.0/24
            except:
              - 203.0.113.128/25

These are documentation-only addresses illustrating syntax, not a working ACME allowlist. Replace them with reviewed ranges for the required ACME, provider, and DNS destinations. The list replaces existing CIDRs, so preserve all required paths and relevant exclusions. This fragment does not enable an issuer or NetworkPolicies. Kubernetes validates CIDR syntax and exception containment.

Add environment-owned outbound routes/ServiceEntries for provider APIs and HTTP-01 domain self-checks in sidecar mode; registration is separate from NetworkPolicy. Use the matching bb-common outbound reference under this package’s bb-common.routes.outbound. HTTP-01 may follow redirects from 80 to 443; nonstandard provider API ports need additional egress rules.

Namespace owners must permit ingress/Gateway traffic to temporary solver pods on TCP 8089 in every participating certificate namespace. This chart does not generate solver ingress policy because those pods are shared across issuers. Mesh-enrolled solvers also need compatible authorization policy. Gateway API solvers require an explicit enrollment/policy review rather than assuming the ingress solver’s opt-out metadata applies. Both mesh modes still need working network paths; do not disable Kyverno or widen cluster issuance to make tests pass.

Runtime ACME acceptance test

See the Gluon runtime script for coverage and the Let’s Encrypt test plan for the opt-in script invocation and required external evidence. Default CI does not prove ACME issuance.