Skip to content

Key Vault Secret

Key Vault Secret

The Key Vault Secret module writes secrets into an existing Key Vault (managed by the Key Vault module). Every secret is written through the provider's write-only value argument, so the secret value is never stored in Terraform state or the plan.

Each entry works in one of two modes:

  • Auto-generated (default): omit secret and the module seeds a random value using an ephemeral random_password. The generated value is never persisted anywhere by Terraform, retrieve it from Key Vault after apply.
  • Supplied: set secret to a key in local.secrets (fed by a TF_VAR_* environment variable) and that value is written instead.

Note: writing a secret is a Key Vault data-plane operation. The identity running terraform apply needs Key Vault Secrets Officer on the vault (subscription Contributor is not sufficient under RBAC authorization). The bootstrap script grants this to the CI apply identity. Consumers that read the secret (an app, a container's managed identity) are granted Key Vault Secrets User separately.

Basic Configuration (auto-generated)

1
2
3
4
5
key_vault_secret = {
    ansible-vault-password = {
        key_vault = "EpicKV"
    }
}

This seeds a 32-character random value into the EpicKV vault under the secret name ansible-vault-password.

Supplied Value

Point secret at a key in local.secrets to write a value supplied at runtime through a TF_VAR_* environment variable rather than generating one:

1
2
3
4
5
6
key_vault_secret = {
    smtp-password = {
        key_vault = "EpicKV"
        secret    = "smtp_password" # resolves to var.smtp_password via local.secrets
    }
}

The supplied value is still written write-only; it never enters state (and the variable itself, being an input variable, is not stored in state either).

Rotation

Both modes write through value_wo, which the provider only re-sends when value_wo_version changes. To rotate a secret, bump its value_wo_version and re-apply:

1
2
3
4
5
6
key_vault_secret = {
    ansible-vault-password = {
        key_vault        = "EpicKV"
        value_wo_version = 2 # was 1; incrementing regenerates the random value
    }
}

Configuration Parameters

Parameter Type Required Default Description
key_vault string Yes - The key of the Key Vault (in var.key_vault) to write the secret into
secret string No null The key in local.secrets whose value to write. Omit to auto-generate a random value
name string No Entry key The Key Vault secret name. Defaults to the map key. Must contain only letters, numbers, and dashes
length number No 32 Length of the auto-generated value (ignored when secret is set)
value_wo_version number No 1 Bump to force the value to be re-written (rotation)
content_type string No null Optional content-type label for the secret
not_before_date string No null Secret not usable before this UTC datetime (Y-m-d'T'H:M:S'Z')
expiration_date string No null Secret expiry UTC datetime (Y-m-d'T'H:M:S'Z')
tags map(string) No {} Tags to assign to the secret (merged with default tags)

Naming

Unlike most modules, secret names are not composed from the naming-convention prefix/suffix maps, a Key Vault secret name is its own identifier. The entry key is used as the secret name unless name is set. Key Vault secret names allow only letters, numbers, and dashes, so use ansible-vault-password, not ansible_vault_password.

Multiple Secrets

1
2
3
4
5
6
7
8
9
key_vault_secret = {
    ansible-vault-password = {
        key_vault = "EpicKV"
    }
    smtp-password = {
        key_vault = "EpicKV"
        secret    = "smtp_password"
    }
}