Terraform Vault Provider 4.X Upgrade Guide

Version 4.X of the Vault provider for Terraform is a major release and includes some changes that you will need to consider when upgrading. This guide is intended to help with that process and focuses only on the changes necessary to upgrade from version 3.X to 4.X.

Most of the changes outlined in this guide have been previously marked as deprecated in the Terraform plan/apply output throughout previous provider releases, up to and including 3.25.0. These changes, such as deprecation notices, can always be found in the CHANGELOG.

Why version 4.X?

We introduced version 4.X of the Vault provider in order to make performance improvements for deployments that manage many Vault secret or auth engine mounts. This improvement required changes to the underlying Vault API calls, which in turn would require policy adjustments in environments where permissions are least privilege.

The change was deemed significant enough to warrant the major version bump. In addition to the aforementioned performance improvements, all previously deprecated fields and resources have been removed.

While you may see some small changes in your configurations as a result of these changes, we don't expect you'll need to make any major refactorings. However, please pay special attention to the changes noted in the Provider Policy Changes section.

What performance improvements should we expect to see?

Version 4.X changed the READ operations across many resources to call Vault API's to only fetch mount metadata necessary for the resource. Previously, these resources were calling a Vault API which returned mount metadata for all enabled mounts. This would result in a substantially higher CPU and memory footprint for the provider in cases where a given Vault server has a large number of secret/auth mounts.

The following is the list of resources that should see performance improvements when many mounts are enabled in Vault:

Data sources

Resources

What Vault server versions are supported in version 4.X?

The Vault provider will be dropping Vault version support for Vault <= 1.10.x. This means that only Vault server version 1.11.x and greater will be supported.

What is the impact of these changes?

With this change, Vault will require read policies to be set at the path level. For example, instead of permissions at sys/auth you must set permissions at the sys/mounts/auth/:path level. Please refer to the details in the Provider Policy Changes section.

The changes in this case are blocking but not destructive. That is, deployments will fail until the required Vault policy adjustments have been made.

Which Terraform versions are supported?

Terraform versions 1.0.x and greater are fully supported.

Please see the Terraform Upgrade Guide for more info about upgrading Terraform.

I accidentally upgraded to 4.X, how do I downgrade to 3.X?

If you've inadvertently upgraded to 4.X, first see the Provider Version Configuration Guide to lock your provider version; if you've constrained the provider to a lower version such as shown in the previous version example in that guide, Terraform will pull in a 3.X series release on terraform init.

If you've only run terraform init or terraform plan, your state will not have been modified and downgrading your provider is sufficient.

If you've run terraform refresh or terraform apply, Terraform may have made state changes in the meantime.

Upgrade Topics

Provider Version Configuration

It is recommended to use version constraints when configuring Terraform providers. If you are following that recommendation, update the version constraints in your Terraform configuration and run terraform init to download the new version.

If you aren't using version constraints, you can use terraform init -upgrade in order to upgrade your provider to the latest released version.

For example, given this previous configuration:

provider "vault" {
  # ... other configuration ...

  version = "~> 3.25.0"
}

An updated configuration:

provider "vault" {
  # ... other configuration ...

  version = "~> 4.0.0"
}

Provider Policy Changes

Version 4.X of the Vault provider made changes to the underlying Vault API calls, which in turn may require policy adjustments in environments where permissions are least privilege.

Please see the Capabilities section of the Vault Policies documentation for more information on Vault policies.

Auth method resource changes

The below table specifies what changed between version 3.X and 4.X for the following resources:

Data sources

Resources

3.X 4.X
Method Path Method Path
GET sys/auth GET sys/mounts/auth/:path

For example, in version 3.X the vault_gcp_auth_backend resource retrieves mount metadata with the GET sys/auth HTTP operation which corresponds to the following policy in Vault:

path "sys/auth"
{
    capabilities = ["read"]
}

In version 4.X the vault_gcp_auth_backend resource retrieves mount metadata with the GET sys/mounts/auth/:path HTTP operation which corresponds to the following policy in Vault:

path "sys/mounts/auth/gcp"
{
    capabilities = ["read"]
}

Secret engine resource changes

The below table specifies what changed between version 3.X and 4.X for the following resources:

Resources

3.X 4.X
Method Path Method Path
GET sys/mounts GET sys/mounts/:path

For example, in version 3.X the vault_gcp_secret_backend resource retrieves mount metadata with the GET sys/mounts HTTP operation which corresponds to the following policy in Vault:

path "sys/mounts"
{
    capabilities = ["read"]
}

In version 4.X the vault_gcp_secret_backend resource retrieves mount metadata with the GET sys/mounts/:path HTTP operation which corresponds to the following policy in Vault:

path "sys/mounts/gcp"
{
  capabilities = ["read"]
}

The below table specifies what changed between version 3.X and 4.X for the following resources:

Resources

3.X 4.X
Method Path Method Path
GET sys/mounts/:path/tune GET sys/mounts/:path

For example, in version 3.X the vault_nomad_secret_backend resource retrieves mount tune metadata with the GET sys/mounts/:path/tune HTTP operation which corresponds to the following policy in Vault:

path "sys/mounts/nomad/tune"
{
    capabilities = ["read"]
}

In version 4.X the vault_nomad_secret_backend resource retrieves mount metadata with the GET sys/mounts/:path HTTP operation which corresponds to the following policy in Vault:

path "sys/mounts/nomad"
{
  capabilities = ["read"]
}

Deprecated Field Removals

The following deprecated fields have been removed:

AD Secret Backend

Cert Auth Backend Role

Consul Backend Role

Identity Group Member Entities

LDAP Secret Backend

PKI Root Cert

PKI Root Sign Intermediate

PKI Root Sign

SSH Backend Role

Transit Secret Backend Key