Supply-chain verification

The controller resolves configured images to digests, verifies signatures against the selected trust policy, and uses the verified digest in managed workloads. Keep the OpenBao server and operator helper images as separate trust surfaces because they have different publishers and release identities.

For legacy Cosign signatures, the signed claim must contain the resolved image digest. For Sigstore bundles, an in-toto subject must contain that digest. Verification rejects a missing or different digest even when the signature is valid.

Configure both trust surfaces

spec:
  imageVerification:
    enabled: true
    failurePolicy: Block
    issuer: https://token.actions.githubusercontent.com
    subject: "<expected OpenBao release workflow identity>"
  operatorImageVerification:
    enabled: true
    failurePolicy: Block
    issuer: https://token.actions.githubusercontent.com
    subject: "<expected operator release workflow identity>"

Use either a public key or a complete keyless issuer-and-subject pair. The operator supplies built-in keyless defaults only for recognized official repositories. A mirror, fork, or internal image needs explicit trust configuration even when it was copied from an official registry.

Helper images in ghcr.io/kubebao/openbao-{init,backup,upgrade} use KubeBao workflow identities. Historical helpers in ghcr.io/dc-tec/openbao-{init,backup,upgrade} use the original dc-tec/openbao-operator workflow identities. Each repository trusts only its corresponding publisher. The OpenBao server image trust policy is unchanged.

Hardened clusters enable both verification surfaces when the blocks are omitted and require Block. Custom public keys, issuer or subject matchers, regular-expression matchers, or ignoreTlog require useimagetrustroots on the cluster. Development permits Warn for staged adoption.

Understand failure behavior

Successful verification produces a repo@sha256:... reference. Hardened managed StatefulSets and Jobs receive a digest-enforcement label, and admission rejects any container or init-container image that is not a SHA-256 digest. This provides defense in depth against controller bypass or an accidental tag reintroduction.

ignoreTlog: false is the default. Setting it to true skips transparency-log verification and changes the trust model; use it only as part of an explicit disconnected or private signing design.

Separate pull credentials

spec.imagePullSecrets is used by kubelets. The imagePullSecrets inside each verification block is used by the controller to resolve and verify a private image. In multi-tenant mode, the controller receives name-scoped get access only to the verification Secrets referenced in active tenant resources.

Verification accepts both kubernetes.io/dockerconfigjson and kubernetes.io/dockercfg Secrets. Registry keys can include an HTTP(S) scheme, an exact port, a repository path prefix, or hostname globs. Docker Hub’s docker.io, index.docker.io, and registry-1.docker.io names share credentials, including the historical https://index.docker.io/v1/ key. Hostname globs match one DNS label. Append / to a path prefix to restrict it to that directory. Malformed credentials produce a verification error.

Before path matching, the controller removes one leading /v1/ or /v2/, following Kubernetes credential normalization. It matches the remaining path as a literal prefix. For example, registry.example/v1/team/ matches registry.example/team/image.

The longest matching repository path takes precedence. For equally scoped paths, an exact hostname takes precedence over a hostname glob. For the same normalized scope, a later Secret in the verification block overrides an earlier Secret. The controller does not retry other credentials after a registry rejects authentication.

See Use private registries before promoting images into a disconnected environment.

Verify policy approval files

Release approval files are generated from the operator’s built-in policy definitions. The release workflow checks their byte reproducibility and includes both files in its signed checksums.txt and provenance index.

Use the GitHub CLI, Cosign, and sha256sum to download and verify the selected file. Set OPERATOR_VERSION to the intended release tag, such as X.Y.Z, and select the file for your backup configuration. Run in an empty directory.

The example uses the signer for releases published under KubeBao. For releases published before the transfer, including 0.5.1 and earlier, use https://github.com/dc-tec/openbao-operator/.github/workflows/release.yml@refs/tags/$OPERATOR_VERSION as the certificate identity. Repository redirects do not change historical signing identities.

OPERATOR_VERSION='<operator-release-tag>'
APPROVAL_FILE='operator-policy-approval-with-backup.hcl'
gh release download "$OPERATOR_VERSION" --repo kubebao/openbao-operator \
  --pattern "$APPROVAL_FILE" --pattern checksums.txt --pattern checksums.txt.bundle
cosign verify-blob --new-bundle-format=true \
  --bundle checksums.txt.bundle \
  --certificate-identity "https://github.com/kubebao/openbao-operator/.github/workflows/release.yml@refs/tags/$OPERATOR_VERSION" \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' checksums.txt
awk -v name="$APPROVAL_FILE" '$2 == name' checksums.txt | sha256sum --check -

Require successful signature verification and an OK checksum result before reviewing and applying the file. Verification establishes the publisher and file integrity; an OpenBao administrator still reviews and approves the capabilities. See policy enrollment.

Know what is not verified here

The in-cluster verifier does not verify the Helm chart, CRDs, operator installation image, GitHub Actions, or other release artifacts. Verify those in the installation and release process.

Custom blue-green validation-hook images pass through operatorImageVerification before the Job is created. A successful verification is pinned by digest; Block prevents Job creation on failure and Warn retains the original reference. Hardened requires the blocking policy. The CR author also needs usecustomexecutables, and custom hook publishers normally need explicit operator-image trust roots.