Ir para o conteúdo
Promovaweb

Namespaces e segredos

StayCloudVPS Agêntica

Uma VPS para os seus agentes trabalharem dia e noite

Instale o SetupVibe Desktop numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. Deixe Claude Code, Codex e OpenCode rodando no tmux ou no Herdr e feche o notebook sem interromper nada.

Montar minha VPS Agêntica

Link de parceiro da Promovaweb.

Black Friday até 30/11

30%off

nos 2 primeiros meses do plano mensal da VPS

  • Backup diário grátis para sempre
  • Servidores em São Paulo no datacenter da Ascenty
  • Datacenter Tier III manutenção sem parada
  • Acesso root com disco SSD NVMe
  • Réplica do backup em Ashburn, nos EUA

Um namespace é o grupo lógico de flows que controla o acesso aos segredos, aos pares de chave e valor e às variáveis, numa hierarquia separada por pontos, como agencia.clientes.loja. Na edição open source, os segredos entram como variáveis de ambiente com o prefixo SECRET_ e chegam aos flows pela função secret().

Sumário da página

  1. Uma pasta para cada cliente
  2. O que cada namespace guarda
  3. KV Store para o estado entre execuções
  4. Segredos na edição open source
  5. Segredos na edição Enterprise
  6. A configuração do servidor fica à parte

Uma pasta para cada cliente

Uma agência com rotinas de vinte clientes precisa de ordem. Sem ela, a lista de flows vira uma coluna longa de nomes parecidos. Ninguém sabe qual backup é de qual banco. O namespace resolve a organização. A documentação define namespaces como agrupamentos lógicos de flows. Cada namespace controla o acesso aos segredos e às variáveis do grupo.

Os namespaces formam uma hierarquia separada por pontos, sem limite de profundidade. O backup e a limpeza do servidor da agência ficam em agencia.infra. A sincronização do ERP da loja fica em agencia.clientes.loja. Cada flow declara o namespace na segunda linha do arquivo. A interface agrupa os flows por essa árvore.

  • agenciaRaiz da hierarquia, com os arquivos e as chaves compartilhados por todos.
  • agencia.infraBackups, limpeza de disco e manutenção do próprio servidor.
  • agencia.clientesGrupo dos clientes, com as rotinas de aviso reaproveitadas.
  • agencia.clientes.lojaSincronização do ERP com a loja e carga de relatórios.

O que cada namespace guarda

Abra um namespace na interface e você encontra os painéis de execução, os flows, as dependências e o KV Store daquele grupo. Cada namespace também tem um editor de código próprio para arquivos compartilhados entre os flows do grupo. É ali que mora o script Python usado por três flows diferentes, ou o arquivo SQL da consulta do relatório. Os flows do namespace leem esses arquivos sem copiar o código para dentro do YAML.

A documentação marca algumas abas do namespace com um cadeado, sinal de recurso da edição Enterprise. Entre elas estão as variáveis por namespace, a edição do namespace e os segredos por namespace. O isolamento completo de ambientes, com recursos próprios, fica nos tenants, também da edição Enterprise.

KV Store para o estado entre execuções

Algumas rotinas precisam guardar um valor de uma execução para a outra. A sincronização com o ERP precisa saber a data da última atualização trazida, para buscar só o que mudou desde então. O KV Store resolve isso. A documentação descreve o recurso como um armazenamento de chave e valor que guarda e compartilha valores entre execuções e flows, com cada par vinculado a um namespace.

PeçaO que fazUso numa rotina
kv()Lê um valor dentro de uma expressão do flow, como {{ kv('ULTIMA_SYNC') }}.Montar a consulta com a data da última sincronização.
kv.SetCria ou atualiza um par. Com overwrite: false, falha se a chave já existe.Gravar a data nova no fim de uma sincronização bem-sucedida.
kv.GetDevolve o valor guardado como output para as tasks seguintes.Passar o valor adiante para um script.
kv.DeleteRemove a chave e informa se ela existia.Zerar o estado para forçar uma carga completa.
TTLTempo de vida opcional de cada par, que expira sozinho.Guardar um token temporário pelo prazo de validade dele.

Segredos na edição open source

As tasks precisam de senhas de banco, tokens de API e chaves de acesso. Escrever esses valores no YAML levaria as credenciais para o Git e para qualquer pessoa com acesso à interface. A edição open source não tem um cofre dedicado. A documentação explica que o Kestra lê as variáveis de ambiente com o prefixo SECRET_ e decodifica cada valor na inicialização.

.env do container do Kestra

Segredos lidos pelos flows

SECRET_POSTGRES_PASSWORD=
Senha do banco, codificada em base64. O flow lê com secret('POSTGRES_PASSWORD').
SECRET_DISCORD_WEBHOOK=
Endereço do webhook de aviso de falha, também em base64.
SECRET_WEBHOOK_KEY=
Chave do trigger Webhook, que a documentação manda guardar como segredo.
Os segredos da edição open source chegam como variáveis de ambiente com o prefixo SECRET_ e o valor em base64. Os nomes são exemplo. A senha em si fica fora do YAML do flow.

O valor de cada variável vai codificado em base64. A documentação mostra um script que acrescenta o prefixo e faz a codificação. No flow, o prefixo some: a variável SECRET_POSTGRES_PASSWORD vira {{ secret('POSTGRES_PASSWORD') }}. A chave passada para secret() não diferencia maiúsculas de minúsculas: secret('postgres_password') resolve o mesmo valor.

O mesmo documento é direto sobre os limites. Esse modo não tem criptografia em repouso, trilha de auditoria nem controle de acesso além do que o próprio servidor oferece. Todo flow lê todo segredo. Numa instância com rotinas de vinte clientes, isso significa que um flow de um cliente consegue ler a senha do banco de outro. A separação, nesse caso, depende de restringir o acesso à edição de flows.

Segredos na edição Enterprise

Na edição Enterprise e no Kestra Cloud, os segredos vão para um gerenciador dedicado, com AWS Secrets Manager, Azure Key Vault, HashiCorp Vault ou o armazenamento do próprio Kestra. Cada segredo pertence a um namespace ou a um tenant e tem nome, descrição e tags. As permissões por papel definem os usuários que veem e os que gerenciam cada um.

A função secret() procura a chave no namespace do flow e sobe pela hierarquia até a raiz. Se nenhum namespace tem a chave, o Kestra volta às variáveis SECRET_ do ambiente. Um flow também pode ler um segredo de outro namespace, passando o nome dele como argumento. A sintaxe no flow é a mesma nas duas edições, então uma rotina escrita na open source continua funcionando depois de uma migração.

A configuração do servidor fica à parte

Os segredos dos flows não se confundem com a configuração do próprio Kestra. A documentação explica que a configuração é um YAML. Numa instalação com Docker Compose, ela fica na variável KESTRA_CONFIGURATION do container ou num arquivo application.yaml montado. Variáveis de ambiente do tipo KESTRA_* sobrescrevem o arquivo. A senha do PostgreSQL usado pelo Kestra e o usuário e a senha da autenticação básica da interface ficam nessa configuração, longe dos flows.

O último hub coloca o Kestra ao lado da ferramenta que a maioria das agências já usa: Kestra e n8n na mesma stack.