Compatibility

A release covers only what its release notes and this page list as tested. Everything else might work but is outside the tested matrix.

Preview.3 fresh-installation boundary

0.1.0-preview.3 requires a fresh disposable installation with a new Transit key and provider identity. In-place upgrades from earlier previews are unsupported. The provider rejects the older registry schema without rewriting its state or checkpoint. Keep an existing preview installation on its matching artifacts; do not erase its registry, checkpoint, or key material to bypass the check.

The new registry schema binds the configuration identity fingerprint, including the Transit key name and mount path. Earlier state did not record these values, so their original configuration cannot be verified retrospectively. There is no automatic adoption or migration command. KMS key_id derivation, annotations, and AAD bytes remain unchanged.

Qualification verifies that a preview.2 upgrade attempt is rejected, its state is preserved, and returning to preview.2 can still read its existing data. It does not qualify an upgrade to preview.3 or a downgrade of preview.3 state.

Preview.3 clock handling

Pending rotation now waits the full activation delay after each restart or after recovering an unconfirmed stable-observation save. Within the current state schema, retained keys and observation counts are preserved. New local event timestamps preserve ordering across backward clock corrections. OpenBao creation metadata and key IDs retain their existing meaning. Older binaries still use persisted wall time for activation, so downgrades do not retain the new delay guarantee.

Token leases and cached status cannot regain validity after an observed expiry through a backward clock correction. Forward corrections can require earlier authentication or a fresh probe. Retry and circuit-breaker cooldowns use process-local elapsed time. OAuth access tokens must satisfy both their relative endpoint lifetime and the absolute JWT expiry claim.

File JWT configuration upgrades

Existing file JWT configurations can omit auth.jwt.source when jwtFile is set and no oauth2 section is present. The provider retains file authentication for these configurations. Empty source values and mixed source settings fail validation. OAuth authentication never falls back to a file.

Preview.3 qualification scope

Preview.3 was published on 20 October 2026. The signed tag points to release merge cc11e671.

Candidate qualification passed all 13 jobs for source 62997d4, whose tree matches the release merge. The separate tagged release checks passed all 15 jobs for the exact tag. They validate the selected release artifacts through security scans, integration suites, independent rebuilds, installation checks, signatures, SBOMs, and provenance. Candidate qualification and tagged artifact checks cover different inputs and scopes.

The qualified candidate covers all eight combinations of OpenBao 2.7.0 and 2.6.3 with Kubernetes 1.34.11, 1.35.8, 1.36.4, and 1.37.0. Exact images are pinned in .ci/versions.yaml. The tagged release workflow checks both OpenBao versions and the four Kubernetes lanes with the primary OpenBao version. Those tagged checks do not repeat every cross-pair.

The separate Provider Qualification workflow also passed live generated-kit acceptance with three API servers, OAuth on all four Kubernetes lanes with the primary OpenBao version, both OpenBao suites, server upgrade, and a 30-minute soak. These results qualify that candidate and its pinned versions. They do not qualify an adopter’s platform.

Tagged installation jobs cover selected archives and native packages, including init, node-setup.sh, ownership, and reinstallation. The jobs run on Linux; Linux arm64 checks use QEMU. Linux and macOS CLI builds for amd64 and arm64 are distribution targets, not native execution qualification on every OS and architecture. The provider service runs only on Linux.

Published preview.3 matrix

This is an evaluation preview with best-effort support. Production availability, performance guarantees, a service-level objective, and long-term support are outside this scope.

Historical preview.2 matrix

The following matrix describes only 0.1.0-preview.2. It is historical release information, not the installation prerequisite for preview.3.

Auth methods

Certificate auth also needs an OpenBao listener that requests client certificates, a cert auth role bound to the provider identity, and a PKCS#11 module on the host.

Required OpenBao features

The provider relies on Transit encrypt and decrypt with an explicit key_version, associated_data, key metadata with version creation times, min_encryption_version, min_decryption_version, disable_upsert, and JWT or TLS certificate auth.

It fails closed when Transit metadata falls outside the validated profile. Each finding has an impact class:

• cryptographic_safety: the key type, exportability, plaintext backup, or derived or convergent mode would change the validated encryption contract.
• api_server_availability: deletion, unsupported operations, or version restrictions would strand reads or writes of active or historical versions.

Failing closed protects the cryptographic contract but stops API server writes until OpenBao is fixed. Check verify-key, doctor, /ready, and KMS Status before changing API server encryption.

Compatibility promises

After the first stable release, these stay backward compatible within a major version:

• key_id derivation for existing epochs, including the Unix-second normalization of Transit version creation times,
• the annotation schema and AAD canonicalization,
• the meaning of identity-bearing configuration values,
• decryption of historical key_id values,
• the JSON report shape of report-style CLI commands.

Until then, preview releases can break these surfaces. Release notes describe the impact and whether migration is supported or a fresh installation is required; see Release and support lifecycle .

Operator retirement

retire-versions --apply ends local decryption for the versions you select and changes nothing else: key_id derivation, annotations, AAD, the active key, and other historical identities stay the same.

restore-versions --apply can restore selected removed historical records while matching Transit versions remain decryptable. It advances the current state chain; automatic observation still cannot restore removed records. Both commands require the provider to be stopped and the current reviewed state hash.

Retirement adds removed records to the state file, which older binaries reject. Upgrade every provider before retiring versions, and afterwards never downgrade to such a binary or erase the records. The state directory must be owned by the provider’s OS user, and retirement must run as that user. See Operate: Rotation .

Breaking changes

Preview.3 CLI exit-code corrections

Invalid command usage now returns the documented exit code 2, and an unreadable or malformed file passed to config returns 3. These cases previously returned the unclassified error code 1. Unknown help topics and completion subcommands also return 2. Update scripts that matched the previous codes. Diagnostic failures remain 4 and runtime failures remain 5.

Preview.3 configuration cross-checks

Configuration validation now rejects a probe interval greater than or equal to the status staleness window, a renewal increment less than or equal to the token refresh lead time, and duplicate fixed health and metrics endpoints. These checks apply to the effective configuration after file, environment, and flag overrides. Defaults satisfy all three checks.

Empty listener addresses still disable their listeners, and port 0 still requests an available port. Endpoint comparisons do not resolve DNS names or detect every wildcard overlap; other bind conflicts remain runtime errors. No key identity, encryption format, or persisted state changes are required.

Preview.3 Transit key-name validation

Configuration and its JSON Schema now enforce the name pattern used by the OpenBao 2.6 Transit key-metadata endpoint. Names start and end with an ASCII letter, digit, or underscore; interior characters can also be dots or hyphens. Previously accepted names outside this pattern now fail configuration validation, including . and .., whitespace, and URL delimiters.

Valid names, key IDs, AAD, annotations, and state formats are unchanged. The provider does not rewrite names. Treat a name change as an identity change; do not rename an existing configuration to bypass validation without checking the backend key and existing encrypted data.

Preview.3 static-pod JWT mount correction

New static-pod scaffolds place file JWTs in /var/lib/openbao-kms/credentials/identity.jwt and mount the directory read-only so atomic replacement is visible. Existing file mounts need a one-time manifest and credential-path migration . The generator rejects JWT directories that overlap provider state or socket directories. Existing deployments are not changed automatically. Systemd paths and the encryption format are unchanged.

Preview.3 rotation corrections

Pending versions now decrypt as soon as their metadata is validated and saved, though they still cannot encrypt before promotion. An unknown key_id can trigger a metadata read, bounded by the request timeout and status.probeInterval, which never counts toward promotion. State transitions keep pending identities alongside active and retired ones.

These rotation corrections retain key_id derivation, AAD bytes, and annotations. The separate state-binding change requires a fresh preview.3 installation. Confirm all nodes report the same active key_id before the next rotation. Older binaries do not implement all current rotation guarantees.

What counts as breaking

Changing key_id derivation, AAD canonicalization, the default AAD mode, or provider-name handling, or dropping an annotation version or decrypt support for retained historical key_id values, is breaking. A breaking change needs a written design decision, a migration guide, updated test fixtures, and a compatibility section in the release notes.