Deprecation Policy

Use this page when you need the exact contract for how APIs and behavior can change across releases.

OpenBao Operator is still pre-GA, so compatibility rules are explicit rather than implied. This page defines how deprecations are announced, how removals happen, and what migration guidance must ship with a breaking or removing change.

Reference table

Pre-GA lifecycle rules

Pre-GA lifecycle rules.

Change type	Current contract	Contributor or maintainer expectation
Minor releases (0.Y.0)	May include breaking API or behavior changes while the project remains pre-GA.	Document the break clearly and ship a migration path.
Patch releases (0.Y.Z)	Should avoid intentional breaking changes.	Use only when the change is truly compatible or required for safety and integrity.
Security or data-integrity fixes	May force urgent behavior changes earlier than the normal removal timeline.	Call the exception out explicitly in release notes and migration guidance.

Scope

This policy applies to:

• CRD API versions (openbao.org/*)
• CRD fields (spec, status)
• user-visible defaults and behavior contracts
• operator installation and upgrade workflows

Deprecation process

When a field or behavior is deprecated, the project aims to do all of the following in the same release:

1. Mark the deprecation in API comments, which feed the generated API docs.
2. Document the deprecation in API Reference and release notes.
3. Provide a migration path and a concrete replacement example.

Removal policy

For pre-1.0 releases:

• removals are expected in minor releases, not patch releases
• deprecated fields should remain available for at least one minor release when feasible
• urgent safety or security concerns may force earlier removal, but only with explicit release notes

Reference table

Migration requirements for breaking changes

Migration requirements for breaking changes.

Required output	Why it exists
A migration section in release notes or changelog	Operators need a single place to see what changed and in what order to act.
Clear before-and-after manifests	Schema changes are easier to adopt when the new target shape is concrete.
Upgrade sequencing notes	Some changes are safe only when CRDs, operator version, and workload rollout happen in the right order.

Kubernetes versioning mechanics

The project currently serves a single CRD API version, v1alpha1. When additional CRD versions are introduced, the project will use Kubernetes-native lifecycle controls such as:

• served and storage
• deprecated: true
• deprecationWarning

Related lifecycle references

Compatibility matrixOpen the validation matrix when the question is whether a target platform or version is still in scope.Upgrade compatibilityUse the upgrade-path contract when you need sequencing and rollback guidance instead of API lifecycle rules.Release managementMove to the maintainer workflow when the next step is shipping a release that contains the deprecation.