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.
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.
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:
vault_auth_backend
vault_auth_backend
vault_aws_secret_backend
vault_azure_secret_backend
vault_consul_secret_backend
vault_database_secrets_mount
vault_gcp_auth_backend
vault_gcp_secret_backend
vault_github_auth_backend
vault_jwt_auth_backend
vault_kubernetes_secret_backend
vault_ldap_auth_backend
vault_ldap_secret_backend
vault_mount
vault_okta_auth_backend
vault_pki_secret_backend_cert
vault_pki_secret_backend_intermediate_set_signed
vault_pki_secret_backend_root_cert
vault_pki_secret_backend_sign
vault_rabbitmq_secret_backend
vault_terraform_cloud_secret_backend
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.
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.
Terraform versions 1.0.x
and greater are fully supported.
Please see the Terraform Upgrade Guide for more info about upgrading Terraform.
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.
terraform refresh
with a downgraded
provider is likely sufficient to revert your state.terraform apply
, you'll need to either terraform import
them or delete
them by hand.length
formatter
allowed_organization_units
token_type
group_name
length
serial
serial
serial
allowed_user_key_lengths
auto_rotate_interval
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"
}
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.
The below table specifies what changed between version 3.X and 4.X for the following resources:
vault_auth_backend
vault_auth_backend
vault_gcp_auth_backend
vault_github_auth_backend
vault_jwt_auth_backend
vault_ldap_auth_backend
vault_okta_auth_backend
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"]
}
The below table specifies what changed between version 3.X and 4.X for the following resources:
vault_aws_secret_backend
vault_azure_secret_backend
vault_consul_secret_backend
vault_database_secrets_mount
vault_gcp_secret_backend
vault_kubernetes_secret_backend
vault_ldap_secret_backend
vault_mount
vault_pki_secret_backend_cert
vault_pki_secret_backend_intermediate_set_signed
vault_pki_secret_backend_root_cert
vault_pki_secret_backend_sign
vault_rabbitmq_secret_backend
vault_terraform_cloud_secret_backend
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:
vault_ad_secret_backend
vault_nomad_secret_backend
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"]
}
The following deprecated fields have been removed:
length
- removed from the vault_ad_secret_backend
resource.
formatter
- removed from the vault_ad_secret_backend
resource.
allowed_organization_units
- removed from the vault_cert_auth_backend_role
resource.token_type
- removed from the vault_consul_secret_backend_role
resource.group_name
- removed from the vault_identity_group_member_entity_ids
resource.length
- removed from the vault_ldap_secret_backend
resource.serial
- removed from the vault_pki_secret_backend_root_cert
resource. Use serial_number
instead.serial
- removed from the vault_pki_secret_backend_root_sign_intermediate
resource. Use serial_number
instead.serial
- removed from the vault_pki_secret_backend_sign
resource. Use serial_number
instead.allowed_user_key_lengths
- removed from the vault_ssh_secret_backend_role
resource. Use allowed_user_key_config
instead.auto_rotate_interval
- removed from the vault_transit_secret_backend_key
resource. Use auto_rotate_period
instead.