Skip to main content
Version: Development

Feature deprecation FAQ

This page provides frequently asked questions concerning decisions made about OpenBao feature deprecations. Please refer to the Overview page for up-to-date information on OpenBao feature deprecations and notices.

Q: What are the phases of deprecation?​

OpenBao implements a multi-phased approach to deprecation. The intent of this approach is to provide sufficient warning that a feature will be removed and safe handling of stored data when the associated feature has been removed.

The phases of deprecation are also known as "Deprecation Status". These statuses apply to all feature deprecations but are specially reflected in builtin auth & secrets engines, which expose this information at runtime via the /sys/auth, /sys/mounts and /sys/plugins endpoints. For more information, refer to the corresponding documentation.

The four phases of deprecation are: "Supported", "Deprecated", "Pending Removal", and "Removed".

Supported​

This is the default status and reflects a feature which is still supported. There is no unique behavior or functionality associated with this status.

Deprecated​

This status reflects a feature which has been marked for deprecation in a later release of OpenBao. This is the first phase of the deprecation process. A status of "Deprecated" has two effects:

  1. After an upgrade, "Deprecated" features already in use (enabled prior to upgrade) will log warnings when loaded, e.g., on startup or unseal.
  2. All new usage of "Deprecated" features will log warnings.
  3. HTTP endpoints associated with this feature will include a warnings field in response data.

Pending removal​

This status reflects a feature which has been officially deprecated in this release of OpenBao. This is the first phase in the process that fundamentally alters the behavior of OpenBao. The effects are two-fold:

  1. After an upgrade, any existing "Pending Removal" feature (enabled prior to upgrade) will log errors and cause an immediate shutdown of OpenBao if irrecoverable.
  2. All new usage of "Pending Removal" will fail with errors emitted as logs or in API responses as appropriate.

The "Pending Removal" behavior of builtin plugins may be overridden via the BAO_ALLOW_PENDING_REMOVAL_MOUNTS environment variable. This effectively allows all "Pending Removal" features to be treated as "Deprecated".

note

This deprecation status typically only applies to deprecations of entire builtin plugins. Other feature deprecations tend to skip this phase and go from "Deprecated" to "Removed" right away in the next major or minor release.

Removed​

This status reflects a feature which has been officially removed from OpenBao. "Removed" is the last phase of the deprecation process. Once reached, code for this feature no longer exists within OpenBao, and thus attempted use of the feature will fail.

Migration path​

In order to successfully upgrade, use of the "Removed" feature must be discontinued. To accomplish this:

  1. Downgrade OpenBao to a previous version if a premature upgrade was performed and the migration requires live access to the removed feature.
  2. Replace any "Removed" or "Pending Removal" feature with the preferred alternative feature.
  3. Upgrade to latest desired version.