Vault Connector

1. Visión General

El componente Vault Connector (vault) permite leer o grabar secretos en un motor Key-Value (KV) de HashiCorp Vault u OpenBao.

Soporta tanto el motor KV v1 (estático) como el KV v2 (versionado), manejando las diferencias de API de forma transparente. El componente funciona solo como acción de salida, es decir, no puede usarse como disparador de entrada.

Úsalo cuando el flujo necesita recuperar credenciales sensibles (contraseñas de base de datos, claves de API) o almacenar información protegida de forma segura.

2. Prerrequisitos

• Una instancia de Vault u OpenBao accesible por la plataforma.
• Un motor de secretos del tipo Key-Value (KV) habilitado en Vault.
• Credenciales (Token o AppRole) con permisos adecuados en la ruta (path) deseada.

3. Autenticación y Conexión

El conector soporta dos métodos de autenticación: AppRole (recomendado para servicios) y Token.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
address	Sí	Texto	URL completa de la instancia de Vault/OpenBao.	"https://vault.ejemplo.com"
authMethod	No	Texto	Método de autenticación: approle o token. Por defecto: "approle".	"approle"
token	Sí*	Texto	Token de Vault. Obligatorio si authMethod es token.	"hvs.CAES..."
roleId	Sí**	Texto	Role ID del AppRole. Obligatorio si authMethod es approle.	"0a52..."
secretId	Sí**	Texto	Secret ID del AppRole. Obligatorio si authMethod es approle.	"1e2b..."
tlsSkipVerify	No	Texto	Si es "true", ignora la validación del certificado SSL (no recomendado en producción).	"false"
caCert	No	Texto	Certificado CA en formato PEM para validar conexiones HTTPS.	"-----BEGIN CERTIFICATE-----..."

Consejo: utiliza los secrets de la plataforma para almacenar tokens y credenciales del AppRole, referenciándolos en el componente con {$.secrets.nombre_del_secreto}.

4. Configuración / Operaciones Soportadas

El componente tiene dos operaciones principales: read (lectura) y write (escritura).

Parámetros Comunes

Campo	Obligatorio	Tipo	Descripción	Ejemplo
operation	No	Texto	Operación a realizar: read o write. Por defecto: "read".	"read"
mount	Sí	Texto	Punto de montaje del engine KV en Vault.	"secret"
path	Sí	Texto	Ruta del secreto dentro del mount.	"myapp/config"
kvVersion	No	Texto	Versión del motor KV: v1 o v2. Por defecto: "v2".	"v2"

Operación: Read (Lectura)

Recupera un secreto de Vault.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
key	No	Texto	Si se completa, devuelve solo el valor de esta clave. Si está vacío, devuelve todo el objeto del secreto.	"password"
cacheTtl	No	Número	Tiempo en segundos para cachear el valor leído, evitando llamadas repetitivas a Vault.	60

Operación: Write (Escritura)

Crea o actualiza claves en un secreto. Importante: la escritura en el conector es no destructiva por defecto (no elimina claves que no fueron listadas).

Campo	Obligatorio	Tipo	Descripción	Ejemplo
overwrite	No	Texto	Si es "true", actualiza claves existentes. Si es "false", falla si alguna clave listada ya existe. Por defecto: "false".	"true"
dataMode	No	Texto	Modo de envío de los datos: fields (objeto) o raw (cadena JSON). Por defecto: "fields".	"fields"
data	Sí***	Objeto	Mapa de clave/valor a grabar (usado en el modo fields).	{"api_key": "123"}
dataRaw	Sí***	Texto	Cadena JSON que representa el objeto a grabar (usado en el modo raw).	{"db_user": "admin"}

*** Obligatorio según el dataMode elegido.

5. Ejemplos Prácticos

Lectura de una contraseña de base de datos

Busca la clave password en el secreto ubicado en secret/myapp/database.

Configuración del componente:

{
  "componentName": "vault",
  "configurations": {
    "operation": "read",
    "authMethod": "approle",
    "address": "https://vault.internal:8200",
    "roleId": "{$.secrets.vaultRoleId}",
    "secretId": "{$.secrets.vaultSecretId}",
    "mount": "secret",
    "path": "myapp/database",
    "key": "password",
    "kvVersion": "v2"
  }
}

Respuesta:

{
  "data": {
    "password": "contrasena-super-segura"
  },
  "metadata": {
    "version": 3,
    "created_time": "2024-08-20T15:00:00Z"
  }
}

Escritura de múltiples campos (Upsert)

Actualiza o crea las claves token y expires_at en la ruta secret/myapp/integration, preservando otras claves que ya existan en el mismo secreto.

Configuración del componente:

{
  "componentName": "vault",
  "configurations": {
    "operation": "write",
    "overwrite": "true",
    "authMethod": "token",
    "address": "{$.env.vault_url}",
    "token": "{$.secrets.vaultToken}",
    "mount": "secret",
    "path": "myapp/integration",
    "dataMode": "fields",
    "data": {
      "token": "{$.body.newToken}",
      "expires_at": "2024-12-31"
    }
  }
}

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
Vault is sealed or unavailable	Vault está en estado "sealed" o inaccesible por red.	Verificar el estado de Vault y la conectividad.
Permission denied	El Token o AppRole no tiene capacidades (read, create, update, patch) en el path.	Revisar las políticas (policies) asociadas a la credencial. Para overwrite: true en KV v2, el permiso patch es necesario.
Key(s) [...] already exist	Intento de escritura con overwrite: false en claves ya existentes.	Cambiar overwrite a "true" o garantizar que la clave sea nueva.
Configuration 'address' is required	Falta completar uno de los parámetros obligatorios (address, mount o path).	Revisar la configuración del componente.
A write operation requires at least one key/value	Intento de escritura sin proveer datos en data o dataRaw.	Proveer los campos a grabar.