0.5.0

OpenBao Operator 0.5.0 documents the compatibility commitment selected for
parts of the openbao.org/v1alpha1 API. The API remains alpha; this is a
release-planning boundary, not a declaration that all of v1alpha1 is stable.
The release also makes restore and upgrade execution safer when the controller
restarts or loses track of a Kubernetes Job.

The release adds OpenBao 2.6 integration, validates Kubernetes 1.36 as the
primary target, and improves voter sizing, tenant cleanup, Gateway readiness,
and validation-hook security. This release does not introduce v1beta1.

What 0.5.0 changes

A defined compatibility boundary within v1alpha1

The project now records which selected fields are intended to retain their
current behavior, what omission means, which updates are allowed, and which
conditions clients can rely on. A generated field inventory and CRD comparison
make that boundary reviewable. Newer feature groups remain outside the selected
contract and can still change before a beta API release.

Durable recovery and upgrade operations

Restore execution now records durable receipts for preparation, Job creation,
terminal observation, and post-restore recovery. If a committed restore Job
disappears, the operator reports the unknown outcome instead of repeating a
potentially destructive restore. After snapshot application, it restarts voters
and restores the declared read-replica state before marking the operation
complete.

BlueGreen validation hooks now have an identity tied to a specific upgrade
attempt. A Job from an earlier attempt cannot satisfy a later upgrade, and a
recorded terminal hook is not replayed after its Job disappears. Rolling
upgrades also preserve leader ordering across revisioned workloads.

Backup cleanup preserves unrelated Secret owners. Scheduled backup observation
no longer treats a pre-upgrade snapshot Job as the scheduled backup Job.

OpenBao 2.6 integration

OpenBao 2.6.2 is the primary OpenBao validation target. The release adds:

• plugin-backed key management service (KMS) seal configuration through
  spec.unseal.type: kms;
• multi-value headers and conditional when expressions for self-init requests;
• idle strategy changes between RollingUpdate and BlueGreen, without
  replacing the active StatefulSet or its persistent volume claims (PVCs); and
• independent resource configuration for voter OpenBao containers through
  spec.resources.

Plugin-backed KMS support configures OpenBao but does not install a plugin
binary or vendor libraries. Supply the plugin through spec.plugins, mount
sensitive runtime data through spec.unseal.credentialsSecretRef, and keep
secrets out of spec.unseal.kms.config.

Kubernetes and multi-tenant operation

Kubernetes 1.36.1 is the primary Kubernetes validation target. Release gates
also cover the Kubernetes 1.34.x and 1.35.x compatibility lines. The release
adds an operator-upgrade test from 0.4.2 across Development, Transit, and
three-voter Hardened clusters.

Gateway readiness now follows the managed Route Accepted and ResolvedRefs
conditions. External certificates must contain every configured extraSANs
value. Custom BlueGreen validation-hook images use
spec.operatorImageVerification and run with a restricted Job security
context.

OpenBaoTenant now reports a generation-aware Provisioned condition. The
provisioner keeps shared namespace resources while another tenant claim exists
and removes its role-based access control (RBAC), ResourceQuota, and
LimitRange resources after the last claim ends. Single-tenant Helm
installations now derive the controller watch namespace consistently from
tenancy.targetNamespace.

Before you upgrade

Upgrade 0.4.0 or 0.4.1 installations to 0.4.2 first. Finish any active OpenBao
version upgrade, backup, or restore, then take and verify a current backup. Keep
the 0.4.2 controller and custom resource definitions (CRDs) installed while you
update stored manifests, Hardened credentials, and restore authorization.
Kubernetes can prune fields that do not exist in the new structural schema, so
do not apply the 0.5.0 CRDs before you complete these changes.

The 0.4.2-to-0.5.0 CRD comparison reports eight removed paths and five tightened
validation groups. The following sections cover the required actions.

Update restore authorization

OpenBao Operator 0.5.0 uses the seal-validating
sys/storage/raft/snapshot endpoint when spec.force is omitted or false.
Earlier releases always used sys/storage/raft/snapshot-force.

Existing restore identities must grant the normal endpoint before you upgrade
the controller. Self-init does not rewrite policies after initialization. Add:

path "sys/storage/raft/snapshot" {
  capabilities = ["update"]
}

Keep a separate update grant on sys/storage/raft/snapshot-force only when
the identity must support spec.force: true. Clusters initialized by 0.5.0
receive both grants in the generated restore policy.

Migrate Hardened unseal credentials

The 0.5.0 admission policy rejects prohibited inline credentials in every
submitted Hardened OpenBaoCluster, including an update to an existing object.
Create the replacement Secret or workload identity first. While 0.4.2 is still
installed, submit one update that adds spec.unseal.credentialsSecretRef or the
workload identity and removes the prohibited inline fields:

Provider	Remove	Replacement
AWS KMS	spec.unseal.awskms.secretKey and sessionToken	Workload identity or Secret keys AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optional AWS_SESSION_TOKEN
Azure Key Vault	spec.unseal.azureKeyVault.clientSecret	Managed or workload identity, or Secret keys AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET
Transit	spec.unseal.transit.token	Secret key token
PKCS#11	spec.unseal.pkcs11.pin	Secret key BAO_HSM_PIN

After the 0.5.0 admission policy is installed, the API server rejects later
updates while any prohibited inline field remains. Hardened plugin-backed KMS
configuration must also keep spec.unseal.kms.config empty and provide secrets
through external identity or files mounted from credentialsSecretRef.

Update stored manifests

Complete these changes while the 0.4.2 CRDs remain installed:

1. Move each Automatic Certificate Management Environment (ACME)
   spec.tls.acme.domain value into the spec.tls.acme.domains list.
2. Move spec.maintenance.restartAt to spec.runtime.restartAt. Keep
   spec.maintenance.enabled if you still use maintenance mode.
3. Add the provider block selected by each non-static spec.unseal.type.
   Remove all unselected provider blocks.
4. Remove gcs and azure blocks from S3 backup and restore targets.
5. Remove roleArn from backup and restore targets that do not use S3.
6. Set an explicit endpoint for every S3 backup and restore target.
7. Remove spec.upgrade.tokenSecretRef, including null placeholders.
   Configure spec.upgrade.jwtAuthRole when the self-init OpenID Connect (OIDC)
   bootstrap role is not available.
8. Replace image-tag aliases or partial OpenBao versions with a complete
   semantic version such as 2.6.2.

For example, migrate this 0.4.2 configuration:

spec:
  tls:
    acme:
      domain: bao.example.com
  maintenance:
    enabled: true
    restartAt: "2026-08-01T12:00:00Z"
  unseal:
    type: transit
    transit: {address: https://transit.example.com, keyName: autounseal, mountPath: transit}
    awskms: {region: eu-west-1, kmsKeyID: alias/unused}

Use this 0.5.0 configuration:

spec:
  tls:
    acme:
      domains:
        - bao.example.com
  maintenance:
    enabled: true
  runtime:
    restartAt: "2026-08-01T12:00:00Z"
  unseal:
    type: transit
    transit: {address: https://transit.example.com, keyName: autounseal, mountPath: transit}

The operator owns the removed status aliases. status.backup.lastBackupTime
replaces status.lastBackupTime. The structured status.upgrade.failure
fields reason, message, and at replace lastErrorReason,
lastErrorMessage, and lastErrorAt. The 0.4.2 controller writes both forms,
so the upgrade preserves backup and upgrade failure state.

Check affected integrations

Review these configurations before you resume their operations:

• Scheduled backups and pre-upgrade snapshots without an effective JSON Web
  Token (JWT) role must set spec.backup.tokenSecretRef. The operator no longer
  falls back to a <cluster>-root-token Secret.
• Hardened clusters with backups or either pre-upgrade snapshot setting must
  define non-empty, port-scoped spec.network.egressRules. The backup target
  must also use credentialsSecretRef, workloadIdentity, or S3 roleArn
  instead of ambient storage credentials.
• Hardened clusters with custom BlueGreen validation hooks need a blocking
  spec.operatorImageVerification policy that trusts the hook publisher.
• External TLS certificates must contain every configured extraSANs value.
• Gateway users must wait for Route Accepted=True and ResolvedRefs=True
  before expecting GatewayIntegrationReady=True.
• A cross-cluster restore to a target with different ServiceAccount subjects
  needs those subjects in the source OpenBao JWT roles before the snapshot is
  taken. Configure spec.selfInit.oidc.additionalSubjects before source
  self-initialization, or update the roles directly. A different Kubernetes
  control plane also requires separate JWT issuer and signature trust.

Upgrade from 0.4.2

After you update authorization and stored manifests, apply the 0.5.0 CRDs:

kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/0.5.0/crds.yaml

Then upgrade the Helm release:

helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
  --version 0.5.0 \
  --namespace openbao-operator-system \
  --reuse-values

The Helm provisioner now requests 64Mi of memory and sets a 128Mi memory
limit by default. Preserve higher existing overrides.

Before you continue production changes:

1. Check that the operator rollout completed.
2. Check the admission-policy health and installed CRD version.
3. Check managed cluster conditions and status.acceptedUpgradeStrategy.
4. Review lifecycle events from the upgrade period for errors.
5. Check backup and restore readiness.

The operator accepts an upgrade-strategy change only when the cluster and its
workloads are initialized and idle. Check
status.acceptedUpgradeStrategy before starting another upgrade.

Do not use BlueGreen to upgrade OpenBao from a version before 2.6 to 2.6.x.
The OpenBao request-forwarding gRPC service-name change prevents mixed-version
Autopilot health checks. Change the strategy to RollingUpdate, wait for
status.acceptedUpgradeStrategy=RollingUpdate, and then request the OpenBao
upgrade.

Compatibility and scope

OpenBao Operator requires Kubernetes 1.33 or newer. Release gates test
Kubernetes 1.34, 1.35, and 1.36, with Kubernetes 1.36 as the primary target.

OpenBao 2.6.2 is the primary OpenBao target. Configuration compatibility checks
also cover OpenBao 2.4.4 and 2.5.5. The new KMS seal and self-init request
controls require OpenBao 2.6 or newer.

The served and storage API remains openbao.org/v1alpha1. The compatibility
commitment selected for 0.5.0 does not include read replicas, recovery-key
bootstrap, Gateway, observability, plugins, telemetry, workload hardening, raw
audit options, audit file storage, or plugin-specific KMS data. These features
are supported, but their API can change before a beta release.

OpenBao Operator 0.5.0 does not include Claims or Service Offerings.

0.5.0 (2026-08-31)

OpenBao Operator 0.5.0 defines a selected compatibility boundary within the
openbao.org/v1alpha1 API. The API remains alpha. This release rolls up the
0.5.0-rc.1 through 0.5.0-rc.6 line.

Features

• api: document selected field, omission, update, and condition contracts within v1alpha1
• config: add plugin-backed KMS seals and OpenBao 2.6 self-init request controls
• upgrade: allow idle changes between RollingUpdate and BlueGreen
• workload: configure voter OpenBao container resources independently

Bug Fixes

• restore: persist execution receipts, prevent replay of missing committed Jobs, and recover voter and read-replica state
• upgrade: bind validation hooks to an upgrade attempt and preserve leader ordering across revisioned workloads
• backup: separate scheduled backups from pre-upgrade snapshots
• retention: preserve unrelated Secret owners when pruning retained backups
• tenancy: remove tenant governance resources after the last claim and preserve resources shared by active claims
• networking: derive Gateway readiness from Route conditions and require external TLS certificates to cover extraSANs
• controller: reduce steady-state reconciliation and bootstrap log noise

Security

• admission: reject prohibited inline unseal credentials in Hardened clusters
• lifecycle: require ownership proof for managed Jobs
• upgrade: verify custom BlueGreen validation-hook images through the configured operator image policy
• deps: remediate vulnerable Go and website dependencies

Compatibility

• Validate Kubernetes 1.34, 1.35, and 1.36, with Kubernetes 1.36.1 as the primary target.
• Use OpenBao 2.6.2 as the primary target. Configuration compatibility checks also cover OpenBao 2.4.4 and 2.5.5.

Upgrade Notes

• Upgrade 0.4.0 or 0.4.1 installations to 0.4.2 before installing 0.5.0.
• Update restore authorization, remove prohibited Hardened inline credentials, and migrate stored manifests before applying the 0.5.0 CRDs.
• Use RollingUpdate when upgrading OpenBao from a version before 2.6 to 2.6.x.
• Read the 0.5.0 release notes before upgrading.