Terraform Vault: Gestiona tus Secretos como Código 2026

Terraform Vault es la combinación que te permite gestionar los secretos de tu infraestructura como código, de forma segura, auditable y automatizada. Con el proveedor oficial de HashiCorp Vault defines motores de secretos, políticas y métodos de autenticación en ficheros .tf, y consumes credenciales dinámicas sin exponerlas jamás en texto plano. En esta guía configurarás el proveedor, crearás un motor de secretos y aplicarás políticas de acceso con infraestructura como código.

¿Qué es Terraform Vault y por qué usarlo?

Terraform Vault es el uso del proveedor oficial de HashiCorp Vault para gestionar toda la configuración de tu gestor de secretos mediante Terraform. Vault es el estándar de facto para almacenar y distribuir secretos —contraseñas, claves de API, certificados— de forma centralizada y segura. Al combinarlo con Terraform, defines cómo se organiza y quién accede a esos secretos de manera declarativa y versionada.

Gestionar Vault con Terraform aporta ventajas decisivas para la seguridad de tu organización:

• Configuración versionada: los motores de secretos, políticas y roles quedan en Git, con historial completo.
• Reproducibilidad: replicas la misma configuración de Vault en varios entornos sin errores manuales.
• Auditoría: cada cambio en el acceso a secretos pasa por una revisión en pull request.
• Automatización: integras la gestión de secretos en tus pipelines de infraestructura.

Este enfoque encaja con el resto de tu infraestructura como código. Del mismo modo que gestionas permisos con Terraform AWS IAM, con Terraform Vault llevas la gestión de secretos al mismo terreno declarativo, unificando toda tu seguridad en código.

Requisitos previos para Terraform Vault

Antes de escribir el primer recurso de Terraform Vault, prepara tu entorno. Necesitas una instancia de Vault accesible y un token con permisos suficientes.

• Terraform 1.6 o superior (u OpenTofu) instalado.
• Una instancia de HashiCorp Vault en marcha y desellada (unsealed).
• Un token de Vault con permisos para administrar motores y políticas.
• La dirección de tu servidor Vault (por ejemplo, https://vault.tudominio.com).

Para pruebas, puedes levantar un Vault en modo desarrollo con un solo comando, aunque nunca debe usarse en producción porque guarda los datos en memoria y sin cifrar. Este modo es perfecto para seguir esta guía sin riesgo.

vault server -dev

El comando anterior arranca Vault y muestra en pantalla el token raíz y la dirección, que usaremos a continuación para configurar el proveedor.

Configurar el proveedor Terraform Vault

Empezamos definiendo el proveedor de Terraform Vault. Fijamos la versión para garantizar despliegues reproducibles y declaramos la dirección de Vault.

# provider.tf
terraform {
  required_providers {
    vault = {
      source  = "hashicorp/vault"
      version = "~> 4.4"
    }
  }
}

provider "vault" {
  address = var.vault_address
}

Nunca escribas el token de Vault en el código. Lo pasaremos mediante la variable de entorno VAULT_TOKEN, que el proveedor reconoce automáticamente, junto con la dirección. Así, ninguna credencial acaba en Git.

export VAULT_TOKEN="tu-token-de-vault"
export TF_VAR_vault_address="http://127.0.0.1:8200"

Crear un motor de secretos con Terraform Vault

El corazón de Terraform Vault es la gestión de los motores de secretos. Vamos a habilitar un motor de tipo KV versión 2, el más común para almacenar pares clave-valor con historial de versiones.

# secrets.tf
resource "vault_mount" "kv" {
  path        = "secret"
  type        = "kv"
  options     = { version = "2" }
  description = "Motor de secretos KV gestionado por Terraform"
}

Con el motor habilitado, podemos guardar secretos en él. Aunque en la práctica muchos secretos se generan de forma dinámica, este ejemplo muestra cómo declarar un secreto estático para una aplicación.

resource "vault_kv_secret_v2" "app" {
  mount = vault_mount.kv.path
  name  = "mi-app/config"
  data_json = jsonencode({
    db_user     = "app"
    db_password = var.db_password
  })
}

Aplica la configuración y comprueba el resultado. Terraform mostrará el plan antes de crear nada, permitiéndote revisar exactamente qué se va a configurar en Vault.

terraform init
terraform plan
terraform apply

Tras aplicar, el motor de secretos y el secreto existirán en tu Vault, gestionados por completo desde código. Acabas de dar el primer paso serio con Terraform Vault.

Políticas y autenticación como código con Terraform Vault

Gestionar secretos sin controlar quién accede a ellos no tiene sentido. Con Terraform Vault defines políticas que otorgan permisos concretos sobre rutas específicas, siguiendo el principio de mínimo privilegio. Esta política de ejemplo permite solo leer los secretos de una aplicación.

resource "vault_policy" "lectura_app" {
  name   = "lectura-app"
  policy = <<-EOT
    path "secret/data/mi-app/*" {
      capabilities = ["read"]
    }
  EOT
}

Además de las políticas, puedes habilitar métodos de autenticación para que aplicaciones y usuarios se identifiquen ante Vault. Por ejemplo, activar el método AppRole, muy usado para que las máquinas obtengan credenciales de forma automatizada, es un recurso más.

resource "vault_auth_backend" "approle" {
  type = "approle"
}

Con estos bloques, toda la lógica de acceso a secretos —quién puede leer qué y cómo se autentica— queda descrita en código versionado. Esta es la gran fortaleza de Terraform Vault: convierte la seguridad de tus secretos en algo revisable y reproducible, en lugar de una configuración manual opaca que solo una persona conoce.

Consumir secretos en tu infraestructura

El caso de uso más potente de Terraform Vault es leer secretos de Vault para usarlos en otros recursos de tu infraestructura, sin escribirlos nunca en el código. Un data source te permite recuperar un secreto durante la ejecución.

data "vault_kv_secret_v2" "app" {
  mount = "secret"
  name  = "mi-app/config"
}

# Uso del secreto en otro recurso, sin exponerlo en el código
output "db_user" {
  value     = data.vault_kv_secret_v2.app.data["db_user"]
  sensitive = true
}

De esta forma, tus contraseñas y claves viven únicamente en Vault, y Terraform las recupera en el momento de aplicar. Esto elimina el antipatrón de guardar secretos en variables o ficheros, mejorando enormemente la seguridad. Combinado con un flujo automatizado como el de Terraform Actions, consigues despliegues donde los secretos nunca tocan el disco ni el repositorio.

Casos de uso reales de Terraform Vault

Para apreciar el valor práctico de este enfoque, veamos escenarios habituales donde Terraform Vault marca la diferencia frente a gestionar los secretos a mano o repartidos por variables de entorno:

• Onboarding de aplicaciones: al desplegar un servicio nuevo, el mismo código crea su política y su rol de acceso a secretos.
• Rotación centralizada: cambias la estructura de acceso desde un único lugar versionado, sin tocar cada aplicación.
• Entornos idénticos: replicas exactamente la configuración de secretos entre desarrollo, staging y producción.
• Auditoría y cumplimiento: demuestras quién concedió qué acceso y cuándo, con el historial completo en Git.

En organizaciones donde varios equipos comparten un Vault, gestionar los accesos a mano se vuelve rápidamente ingobernable y propenso a errores peligrosos. Centralizarlo todo con Terraform Vault convierte la seguridad de los secretos en un proceso disciplinado y transparente. Esta coherencia es especialmente valiosa cuando la combinas con el resto de tu infraestructura, como la red que defines en Terraform AWS VPC, logrando que absolutamente toda tu plataforma viva en código.

Secretos estáticos frente a dinámicos en Terraform Vault

Una distinción fundamental que conviene dominar es la que separa los secretos estáticos de los dinámicos, porque define el nivel de seguridad de tu sistema. Un secreto estático es un valor que guardas y que permanece igual hasta que lo cambias manualmente, como la contraseña del ejemplo anterior. Es sencillo, pero tiene un riesgo: si se filtra, sigue siendo válido hasta que alguien lo detecta y lo rota.

Los secretos dinámicos son la joya de la corona de Vault. En lugar de guardar una credencial permanente, Vault la genera bajo demanda con una caducidad definida. Por ejemplo, cuando una aplicación necesita acceso a una base de datos, Vault crea un usuario temporal exclusivo para ella, que se revoca automáticamente al expirar. Así, aunque esa credencial se filtrara, dejaría de funcionar en cuestión de minutos u horas, reduciendo drásticamente la ventana de exposición. Con Terraform Vault puedes configurar estos motores de secretos dinámicos como código, dejando lista toda la maquinaria para que tus aplicaciones obtengan credenciales efímeras de forma automática. Adoptar este modelo es uno de los mayores saltos de madurez en la seguridad de una plataforma, porque elimina de raíz el problema de los secretos permanentes que nunca se rotan y que constituyen uno de los vectores de ataque más explotados.

Buenas prácticas y solución de problemas

• Protege el estado: el tfstate puede contener secretos; guárdalo siempre en un backend remoto cifrado.
• Secretos dinámicos: siempre que puedas, usa motores que generen credenciales temporales en lugar de secretos estáticos.
• Mínimo privilegio: crea políticas estrictas por aplicación y evita tokens con permisos amplios.
• Separa configuración y secretos: gestiona la estructura de Vault con Terraform, pero valora inyectar los valores más sensibles por otros medios.

Si Terraform no puede conectar con Vault, revisa la dirección y que el token sea válido y no haya expirado. La mayoría de problemas de Terraform Vault se deben a la autenticación o a que Vault está sellado (sealed). Encuentra más guías de infraestructura como código en nuestra categoría de tutoriales de Terraform.

Conclusión

Con Terraform Vault has llevado la gestión de secretos al terreno de la infraestructura como código: motores, políticas y autenticación definidos de forma declarativa, versionada y auditable. Hemos configurado el proveedor de forma segura, creado un motor KV, definido políticas de mínimo privilegio y consumido secretos sin exponerlos. A partir de aquí, adopta secretos dinámicos, protege tu estado y automatiza el flujo para conseguir una gestión de secretos de nivel profesional.

Como recorrido de aprendizaje recomendado, empieza practicando con un Vault en modo desarrollo para experimentar sin riesgo: crea motores, políticas y secretos, y destrúyelos con confianza mientras te familiarizas con cada recurso. Cuando domines esa base, monta un Vault de verdad, protégelo adecuadamente y traslada tu configuración a un backend de estado remoto y cifrado. El siguiente gran paso es sustituir progresivamente los secretos estáticos por dinámicos allá donde tus sistemas lo permitan, empezando por las bases de datos, que suelen ser el caso más común y agradecido. Con cada iteración reducirás la cantidad de credenciales permanentes en tu organización, que son precisamente las que más quebraderos de cabeza causan en las auditorías de seguridad. Este camino, recorrido con paciencia, transforma la gestión de secretos de un punto débil temido en una fortaleza de tu plataforma, gobernada por completo desde código y preparada para escalar con tu equipo durante años.

Preguntas frecuentes sobre Terraform Vault

¿Los secretos quedan expuestos en el estado de Terraform?

Algunos valores pueden almacenarse en el estado, por eso es imprescindible guardarlo en un backend remoto cifrado con acceso restringido. Siempre que sea posible, prioriza secretos dinámicos y su lectura en tiempo de ejecución.

¿Puedo gestionar toda la configuración de Vault con Terraform?

Sí. El proveedor permite gestionar motores de secretos, políticas, métodos de autenticación, roles y más. Es habitual definir toda la estructura de Vault como código y dejar la introducción de los valores más sensibles a procesos aparte.

¿Funciona con OpenTofu?

Sí. El proveedor de Vault es compatible con OpenTofu, el fork open source de Terraform. El código HCL es idéntico; solo cambia el binario que ejecutas.

¿Qué es un secreto dinámico?

Es una credencial que Vault genera bajo demanda y con caducidad, como un usuario de base de datos temporal. Reduce el riesgo porque no hay secretos permanentes que robar, y Vault los revoca automáticamente al expirar.

Recursos y documentación oficial

• Proveedor Vault — Terraform Registry
• Documentación de HashiCorp Vault
• Documentación de Terraform
• Tutoriales oficiales de Vault
• Documentación de OpenTofu