• Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.11.x (latest)
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
      • Overview
      • K/V Version 1
      • K/V Version 2
    • KMIP ENTERPRISE
    • Kubernetes
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
      • Overview
      • Setup and Usage
      • Quick Start - Root CA Setup
      • Quick Start - Intermediate CA Setup
      • Considerations
      • Rotation Primitives
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Configuration
      • Upgrading
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.11.x
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.11.0
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Automated Upgrades
    • Redundancy Zones
    • Lease Count Quotas
    • Entropy Augmentation
      • Overview
      • FIPS 140-2 Inside Vault
      • Seal Wrap for FIPS 140-2
    • Seal Wrap
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault

The Vault website is being redesigned to help you find what you are looking for more effectively.

Type '/' to Search

»Upgrading Vault Plugins

»External Plugin Upgrade Procedure

The following procedure details steps for upgrading an external plugin that has been registered to the catalog on a running server. This procedure is applicable to secret engines, auth methods, and database plugins.

Vault executes plugin binaries when they are configured and roles are established around them. The binary cannot be modified or replaced while running, so upgrades cannot be performed by simply swapping the binary and updating the hash in the plugin catalog.

Instead, you can restart or reload a plugin with the sys/plugins/reload/backend API. Follow these steps to replace or upgrade a Vault plugin binary:

  1. Register version 1 of my-db-plugin to the catalog. Skip this step if your plugin is already registered.

    $ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
        database \                  # type
        my-db-plugin
    
    $ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
        database \                  # type
        my-db-plugin
    
  2. Mount the plugin backend. Skip this step if the backend is already mounted.

    $ vault secrets enable database
    
    $ vault secrets enable database
    
  3. Register version 2 of my-db-plugin to the catalog under the same plugin name, but with updated command to run version 2 of my-db-plugin and updated sha256 of the new binary

    $ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
        database \                  # type
        my-db-plugin
    
    $ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
        database \                  # type
        my-db-plugin
    
  4. Trigger a plugin reload to reload all mounted backends using that plugin or a subset of the mounts using that plugin with either the plugin or mounts parameter respectively.

    $ vault plugin reload -plugin my-db-plugin
    
    $ vault plugin reload -plugin my-db-plugin
    

Until step 4, the mount will still use version 1 of my-db-plugin, and when the reload is triggered, Vault will kill my-db-plugin’s process and start the new plugin process for my-db-plugin version 2.

Important: Plugin reload of a new plugin binary must be performed on each Vault instance. Performing a plugin upgrade on a single instance or through a load balancer can result in mismatched plugin binaries within a cluster. On a replicated cluster this may be accomplished by setting the 'scope' parameter of the reload to 'global'.

»Overriding Built-in Plugins

»Background

Vault's auth methods and secrets engines are structured as plugins, but this design is not obvious since many of them are built into Vault.

You can see them with the Vault plugin list command, for example, the list of Secrets engines:

$ vault plugin list secret
Plugins
-------
ad
alicloud
aws
azure
cassandra
consul
gcp
gcpkms
kv
mongodb
mongodbatlas
mssql
mysql
nomad
openldap
pki
postgresql
rabbitmq
ssh
terraform
totp
transit
$ vault plugin list secret
Plugins
-------
ad
alicloud
aws
azure
cassandra
consul
gcp
gcpkms
kv
mongodb
mongodbatlas
mssql
mysql
nomad
openldap
pki
postgresql
rabbitmq
ssh
terraform
totp
transit

This will list all Secrets engines, internal (built-in) or external. To find out if a plugin is built-in, we can query its info:

$ vault plugin info secret azure
Key        Value
---        -----
args       []
builtin    true
command    n/a
name       azure
sha256     n/a
$ vault plugin info secret azure
Key        Value
---        -----
args       []
builtin    true
command    n/a
name       azure
sha256     n/a

Because these built-in engines are plugins, they can be overridden. This can be a useful way to leverage features or bug fixes in plugins that are newer than the version of Vault you're using, without updating or even restarting Vault, and while retaining the data for your existing mount.

Assume you have a new version of Azure Secrets and the binary is called "azure_new". The binary needs to be in the plugin directory and can then be registered as either a distinct plugin, or overriding the current one.

Important: do not disable (vault secrets disable ...) any mount that has data you're interested in; that would erase storage. For the in-place update, register a new plugin atop the built-in one and leave any mounts alone.

»Procedure for Overriding Built-in Plugins

The syntax is the same as an external plugin, with the difference being you name it the same as a built-in:

$ vault plugin register \
  -sha256=<SHA256 Hex value of the plugin binary> \
  -command=azure_new \
  secret \
  azure
$ vault plugin register \
  -sha256=<SHA256 Hex value of the plugin binary> \
  -command=azure_new \
  secret \
  azure

"-command=azure_new" is the name of the binary, "secret" is the plugin type, and "azure" is the name of the built-in plugin that we're overriding. We can verify that the override is in place:

$ vault plugin info secret azure
Key        Value
---        -----
args       []
builtin    false
command    azure_new
name       azure
sha256     f6f6ec45d37484c257aa9ff80444b9f244aaef1c650edf8a42a2a1d3f00db2c5
$ vault plugin info secret azure
Key        Value
---        -----
args       []
builtin    false
command    azure_new
name       azure
sha256     f6f6ec45d37484c257aa9ff80444b9f244aaef1c650edf8a42a2a1d3f00db2c5

At this point we've overridden the built-in, but it is not yet actively handling requests. For that we run:

$ vault plugin reload -plugin=azure
$ vault plugin reload -plugin=azure

»Procedure for Reverting After Overriding A Built-in Plugin

To revert the override, first deregister the plugin:

$ vault plugin deregister secret azure
$ vault plugin deregister secret azure

Next, verify the override has been reverted and we are now using the built-in plugin:

$ vault plugin info secret azure
Key        Value
---        -----
args       []
builtin    true
command    n/a
name       azure
sha256     n/a
$ vault plugin info secret azure
Key        Value
---        -----
args       []
builtin    true
command    n/a
name       azure
sha256     n/a

Finally, reload the plugin:

$ vault plugin reload -plugin=azure
$ vault plugin reload -plugin=azure

»Caveats to Overriding Built-in Plugins

  • As mentioned earlier, disabling existing mounts will wipe the existing data.
  • This type of upgrade affects all uses of the plugin. So if you have 5 different Azure Secrets mounts, they'll all change after the replacement. If you don't want that, you'll need to register the plugin under a different name and start with a fresh mount.
  • In most cases, data upgrade and downgrade is not an issue. If the "new" version introduces new data and you downgrade, the "old" version will ignore the extraneous data. In some cases upgrading changes existing data in non-backwards compatible ways, so it is good to check whether this is an issue.
github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager