open-vault/website/source/guides/upgrading/upgrade-to-0.5.0.html.md

layout	page_title	sidebar_current	description
guides	Upgrading to Vault 0.5.0 - Guides	guides-upgrading-to-0.5.0	This page contains the full list of breaking changes for Vault 0.5, including actions you must take to facilitate a smooth upgrade path.

Overview

This page contains the list of breaking changes for Vault 0.5. Please read it carefully.

Please note that these are changes to Vault itself. Client libraries maintained by HashiCorp have been updated with support for these changes, but if you are using community-supported libraries, you should ensure that they are ready for Vault 0.5 before upgrading.

Rekey Requires Nonce

Vault now generates a nonce when a rekey operation is started in order to ensure that the operation cannot be hijacked. The nonce is output when the rekey operation is started and when rekey status is requested.

The nonce must be provided as part of the request parameters when providing an unseal key. The nonce can be communicated from the request initiator to unseal key holders via side channels; the unseal key holders can then verify the nonce (by providing it) when they submit their unseal key.

As a convenience, if using the CLI interactively to provide the unseal key, the nonce will be displayed for verification but the user will not be required to manually re-type it.

TTL Field in Token Lookup

Previously, the ttl field returned when calling lookup or lookup-self on the token auth method displayed the TTL set at token creation. It now displays the time remaining (in seconds) for the token's validity period. The original behavior has been moved to a field named creation_ttl.

Grace Periods Removed

Vault no longer uses grace periods internally for leases or token TTLs. Previously these were set by backends and could differ greatly from one backend to another, causing confusion. TTLs (the lease_duration field for a lease, or, for a token lookup, the ttl) are now exact.

token-renew CLI Command

If the token given for renewal is the same as the token in use by the client, the renew-self endpoint will be used in the API rather than the renew endpoint. Since the default policy contains auth/token/renew-self this makes it much more likely that the request will succeed rather than somewhat confusingly failing due to a lack of permissions on auth/token/renew.

status CLI Command

The status CLI command now returns an exit code of 0 for an unsealed Vault (as before), 2 for a sealed Vault, and 1 for an error. This keeps error return codes consistent across commands.

Transit Upsertion Behavior Uses Capabilities

Previously, attempting to encrypt with a key that did not exist would create a key with default values. This was convenient but ultimately allowed a client to potentially escape an ACL policy restriction, albeit without any dangerous access. Now that Vault supports more granular capabilities in policies, upsertion behavior is controlled by whether the client has the create capability for the request (upsertion is allowed) or only the update capability (upsertion is denied).

etcd Physical Backend Uses sync

The etcd physical backend now supports sync functionality and it is turned on by default, which maps to the upstream library's default. It can be disabled; see the configuration page for information.

S3 Physical Backend Prefers Environment Variables

The s3 physical backend now prefers environment variables over configuration file variables. This matches the behavior of the rest of the backends and of Vault generally.

Lease Default and Renewal Handling

All backends now honor system and mount-specific default and maximum lease times, except when specifically overridden by backend configuration or role parameters, or when doing so would not make sense (e.g. AWS STS tokens cannot have a lifetime of greater than 1 hour).

This allows for a much more uniform approach to managing leases on both the operational side and the user side, and removes much ambiguity and uncertainty resulting from backend-hardcoded limits.

However, also this means that the leases generated by the backends may return significantly different TTLs in 0.5 than in previous versions, unless they have been preconfigured. You can use the mount-tune CLI command or the /sys/mounts/<mount point>/tune endpoint to adjust default and max TTL behavior for any mount. This is supported in 0.4, so you can perform this tuning before upgrading.

The following list details the ways in which lease handling has changed per-backend. In all cases the "mount TTL" means the mount-specific value for default or max TTL; however, if no value is set on a given mount, the system default/max values are used. This lists only the changes; any lease-issuing or renew function not listed here behaves the same as in 0.4.

(As a refresher: the default TTL is the amount of time that the initial lease/token is valid for before it must be renewed; the maximum TTL is the amount of time a lease or token is valid for before it can no longer be renewed and must be reissued. A mount can be more restrictive with its maximum TTL, but cannot be less restrictive than the mount's maximum TTL.)

Credential (Auth) Backends

• github – The renewal function now uses the backend's configured maximum TTL, if set; otherwise, the mount maximum TTL is used.
• ldap – The renewal function now uses the mount default TTL instead of always using one hour.
• token – Tokens can no longer be renewed forever; instead, they now honor the mount default/max TTL.
• userpass – The renew function now uses the backend's configured maximum TTL, if set; otherwise the mount maximum TTL is used.

Secrets Engines

• aws – New IAM roles no longer always have a default TTL of one hour, instead honoring the configured default if available and the mount default TTL if not (renewal always used the configured values if available). STS tokens return a TTL corresponding to the lifetime of the token in AWS and cannot be renewed.
• cassandra – lease_grace_period has been removed since Vault no longer uses grace periods.
• consul – The mount default TTL is now used as the default TTL if there is no backend configuration parameter. Renewal now uses the mount default and maximum TTLs.
• mysql – The mount default TTL is now used as the default TTL if there is no backend configuration parameter.
• postgresql – The mount default TTL is now used as the default TTL if there is no backend configuration parameter. In addition, there is no longer any grace period with the time configured for password expiration within Postgres itself.