Manage Vault resources programmatically with Terraform
Use Terraform to manage policies, namespaces, and plugins in Vault.
Before you start
- You must have Terraform installed.
- You must have the Terraform Vault provider configured.
- You must have admin access to your Terraform installation. If you do not have admin access, you can still generate the relevant configuration files, but you will need to have someone else apply the changes.
- You must have a Vault server running.
Step 1: Create a resource file for namespaces
Terraform Vault provider supports a vault_namespace
resource type for
managing Vault namespaces:
To manage your Vault namespaces in Terraform:
Use the
vault namespace list
command to identify any unmanaged namespaces that you need to migrate. For example:Create a new Terraform Vault Provider resource file called
vault_namespaces.tf
that definesvault_namespace
resources for each of the new or existing namespaces resources you want to manage.For example, to migrate the
admin
namespace in the example and create a newdev
namespace:
Step 2: Create a resource file for secret engines
Terraform Vault provider supports discrete types for the different auth, secret, and database plugin types in Vault.
To migrate a secret engine, use the vault_mount
resource type:
To manage your Vault secret engines in Terraform:
Use the
vault secret list
command to identify any unmanaged secret engines that you need to migrate. For example:Use the
-namespace
flag to check for unmanaged secret engines under any namespaces you identified in the previous step. For example, to check for secret engines under theadmin
namespace:Create a new Terraform Vault Provider resource file called
vault_secrets.tf
that definesvault_mount
resources for each of the new or existing secret engines you want to manage.For example, to migrate the
transit
andadmin_keys
secret engines in the example and enable a newkv
engine under the newdev
namespace calleddev_keys
:
Step 3: Create a resource file for policies
Terraform Vault provider supports a vault_policy
resource type for
managing Vault policies:
To manage your Vault policies in Terraform:
Use the
vault policy list
command to identify any unmanaged policies that you need to migrate. For example:Create a Terraform Vault Provider resource file called
vault_policies.tf
that definesvault_mount
resources for each policy resource you want to manage in Terraform. You can use the followingbash
code to write all your existing, non-root policies to the file:Update the
vault_policies.tf
file with any new policies you want to add. For example, to create a policy for the exampledev_keys
secret engine:
Step 4: Update your Terraform configuration
Create a
vault
directory wherever you keep your deployment configuration files for Terraform.Save your new resource files to your new Vault configuration directory.
Use
terraform fmt
to adjust the formatting (if needed) of your new configuration files:Use
terraform validate
to confirm the new configuration is valid:
Step 5: Import preexisting root-level resources
Use the terraform import
command to import the preexisting root-level resources.
For example, import the admin
namespace, default
policy, and transit
plugin from the previous steps:
Step 6: Import preexisting nested resources
To import resources that belong to a previously unmanaged namespace, you must
set the TERRAFORM_VAULT_NAMESPACE_IMPORT
environment variable before importing.
For example, to import the admin_keys
secret engine from the admin
namespace:
Set
TERRAFORM_VAULT_NAMESPACE_IMPORT
to theadmin
Vault namespace:Import the
vault_mount
resourceadmin_keys
:Unset the
TERRAFORM_VAULT_NAMESPACE_IMPORT
variable when you finish importing child resources:
Step 6: Verify the import
Use the
terraform state show
command to check your Terraform state file and verify the resources imported successfully. For example, to check theadmin_keys
resource:For each of the migrated resources, compare the
accessor
value from your Terraform state to the accessor value in Vault. For example, to confirm the accessor foradmin_keys
:
Step 7: Add new Vault resources
Run
terraform plan
to confirm the new resources that Terraform will manage:Run
terraform apply
to create the new resources:Use the
terraform state show
command to check your Terraform state file and verify the new resources created successfully. For example, to check thedev_keys
resource:Confirm that your Vault instance can use the new resources. For example, to confirm the
dev_keys
resources:
Next steps
- Review the best practices for programmatic Vault management.