Vault Connector

1. Visão Geral

O componente Vault Connector (vault) permite ler ou gravar segredos em um mecanismo Key-Value (KV) do HashiCorp Vault ou OpenBao.

Ele suporta tanto o motor KV v1 (estático) quanto o KV v2 (versionado), lidando com as diferenças de API de forma transparente. O componente funciona apenas como ação de saída, ou seja, não pode ser usado como gatilho de entrada.

Use quando o fluxo precisa recuperar credenciais sensíveis (senhas de banco, chaves de API) ou armazenar informações protegidas de forma segura.

2. Pré-requisitos

• Uma instância do Vault ou OpenBao acessível pela plataforma.
• Um motor de segredos do tipo Key-Value (KV) habilitado no Vault.
• Credenciais (Token ou AppRole) com permissões adequadas no caminho (path) desejado.

3. Autenticação e Conexão

O conector suporta dois métodos de autenticação: AppRole (recomendado para serviços) e Token.

Campo	Obrigatório	Tipo	Descrição	Exemplo
address	Sim	Texto	URL completa da instância do Vault/OpenBao.	"https://vault.exemplo.com"
authMethod	Não	Texto	Método de autenticação: approle ou token. Padrão: "approle".	"approle"
token	Sim*	Texto	Token do Vault. Obrigatório se authMethod for token.	"hvs.CAES..."
roleId	Sim**	Texto	Role ID do AppRole. Obrigatório se authMethod for approle.	"0a52..."
secretId	Sim**	Texto	Secret ID do AppRole. Obrigatório se authMethod for approle.	"1e2b..."
tlsSkipVerify	Não	Texto	Se "true", ignora a validação do certificado SSL (não recomendado em produção).	"false"
caCert	Não	Texto	Certificado CA em formato PEM para validar conexões HTTPS.	"-----BEGIN CERTIFICATE-----..."

Dica: Utilize os segredos (secrets) da plataforma para armazenar tokens e credenciais do AppRole, referenciando-os no componente com {$.secrets.nome_do_segredo}.

4. Configuração / Operações Suportadas

O componente possui duas operações principais: read (leitura) e write (escrita).

Parâmetros Comuns

Campo	Obrigatório	Tipo	Descrição	Exemplo
operation	Não	Texto	Operação a realizar: read ou write. Padrão: "read".	"read"
mount	Sim	Texto	Ponto de montagem do engine KV no Vault.	"secret"
path	Sim	Texto	Caminho do segredo dentro do mount.	"myapp/config"
kvVersion	Não	Texto	Versão do motor KV: v1 ou v2. Padrão: "v2".	"v2"

Operação: Read (Leitura)

Recupera um segredo do Vault.

Campo	Obrigatório	Tipo	Descrição	Exemplo
key	Não	Texto	Se preenchido, retorna apenas o valor desta chave. Se vazio, retorna todo o objeto do segredo.	"password"
cacheTtl	Não	Número	Tempo em segundos para cachear o valor lido, evitando chamadas repetitivas ao Vault.	60

Operação: Write (Escrita)

Cria ou atualiza chaves em um segredo. Importante: A escrita no conector é não-destrutiva por padrão (não remove chaves que não foram listadas).

Campo	Obrigatório	Tipo	Descrição	Exemplo
overwrite	Não	Texto	Se "true", atualiza chaves existentes. Se "false", falha se alguma chave listada já existir. Padrão: "false".	"true"
dataMode	Não	Texto	Modo de envio dos dados: fields (objeto) ou raw (string JSON). Padrão: "fields".	"fields"
data	Sim***	Objeto	Mapa de chave/valor para gravar (usado no modo fields).	{"api_key": "123"}
dataRaw	Sim***	Texto	String JSON representando o objeto a ser gravado (usado no modo raw).	{"db_user": "admin"}

*** Obrigatório dependendo do dataMode escolhido.

5. Exemplos Práticos

Leitura de uma senha de banco de dados

Busca a chave password no segredo localizado em secret/myapp/database.

Configuração do 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"
  }
}

Resposta:

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

Escrita de múltiplos campos (Upsert)

Atualiza ou cria as chaves token e expires_at no caminho secret/myapp/integration, preservando outras chaves que já existam no mesmo segredo.

Configuração do 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. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
Vault is sealed or unavailable	O Vault está no estado "sealed" ou inacessível via rede.	Verificar o status do Vault e a conectividade.
Permission denied	O Token ou AppRole não possui capacidades (read, create, update, patch) no path.	Revisar as políticas (policies) associadas à credencial. Para overwrite: true no KV v2, a permissão patch é necessária.
Key(s) [...] already exist	Tentativa de escrita com overwrite: false em chaves já existentes.	Mudar overwrite para "true" ou garantir que a chave é nova.
Configuration 'address' is required	Falta preencher um dos parâmetros obrigatórios (address, mount ou path).	Revisar a configuração do componente.
A write operation requires at least one key/value	Tentativa de escrita sem fornecer dados em data ou dataRaw.	Fornecer os campos a serem gravados.