Primeiros passos na infraestrutura

TLDR: Instale as ferramentas, obtenha a chave do ward, e aplique as camadas na ordem — plataforma, compartilhado, stateful, stateless. Todo comando de Terraform passa por ward exec; não existe .env com secret.

Pré-requisitos

Ferramentas

As versões são fixadas em .tool-versions e geridas por asdf:

bash asdf plugin add terraform asdf plugin add kubectl asdf plugin add golang asdf install

Ferramenta Para quê
terraform toda a infraestrutura
make ponto de entrada de todo comando
ward gestão de secret (obrigatório)
kubectl operar o cluster
aws CLI assumir a TerraformRole e gerar token do EKS
bash >= 4.0 os scripts em bin/

Confira o que está instalado com:

bash bash bin/helpers/setup/check-tools.sh

Setup de máquina

Dois targets, com papéis distintos:

bash make bootstrap # nível de máquina: instala o CLI wehive, ferramentas e asdf (idempotente) make setup # nível de projeto: configura este repo na máquina

make bootstrap pode ser rodado de qualquer projeto WeHive e é seguro repetir.

Credenciais

Não existe .env com secret neste repo. Todo secret vive em vaults criptografados do ward, commitados no repo — ver o guia do vault ward.

O que você precisa é apenas a chave para decriptá-los:

Onde Como
local o arquivo .ward/.key (nunca commitado)
CI o GitHub Secret WARD_KEY

Peça a chave a alguém da lista devops em config/access.yml.

Passos

1. Aplicar as camadas na ordem

As camadas têm dependência entre si — aplique de cima para baixo:

mermaid graph TD P["platform<br/>VPC + registry"] --> S["shared<br/>rede AWS, kubernetes, messagebroker, github, registry"] S --> SF["stateful<br/>bancos e caches por projeto"] SF --> SL["stateless<br/>aplicações"]

bash make platform.apply # VPC + registry de plataforma make shared.apply # kubernetes + messagebroker + github make stateful.apply # bancos e caches make stateless.apply # aplicações

Não existe make deploy nem make destroy global — por decisão de segurança, para evitar mudança acidental de raio amplo. Use sempre o target da camada.

2. Planejar antes de aplicar

Todo componente tem o par plan/apply:

bash make platform.plan make shared.plan make shared.kubernetes.plan make shared.messagebroker.plan

3. Conjunto de targets por componente

Todo componente de Terraform expõe o mesmo conjunto:

Target O que faz
apply aplica
plan mostra o que vai mudar
status estado atual (outputs do Terraform)
outputs outputs formatados
health checagem de saúde via API
taint marca recurso para recriação
destroy destrói (com confirmação)
init inicializa o Terraform

Nomenclatura: <camada>.<componente>.<ação> — por exemplo shared.messagebroker.health.

4. Escolher o provider do Kubernetes

O stack de Kubernetes aceita um switch PROVIDER (default aws):

bash make shared.kubernetes.plan # EKS (default) make shared.kubernetes.plan PROVIDER=do # cluster legado, se ainda existir

5. Acesso ao cluster

bash make k8s.init

Isso cria o seu contexto kubectl. Detalhes de perfil e permissão no guia de acesso.

6. Bootstrap de conta AWS

Só na criação de uma conta nova da Organization. O apply é manual e local por decisão de arquitetura — ele usa backend local, assume a OrganizationAccountAccessRole e é o passo que cria a TerraformRole da qual todo o CI depende. Rodá-lo no CI seria circular.

bash ACCOUNT_NAME=shared--production ACCOUNT_EMAIL=aws+shared@wehive.tech make aws.account.create

O CI cobre src/bootstrap/** apenas com validação estática (fmt -check e validate), nunca com apply.

Troubleshooting

O Terraform trava esperando entrada

Alguma variável não está sendo injetada pelo ward. Confira o que o vault expõe:

bash ward envs | grep TF_VAR_

Se a variável faltar, adicione-a ao vault (ver guia do vault ward). Causa comum: divergência de caixa entre o nome da variável no Terraform e a chave no vault.

“Resource already exists”

O recurso foi criado à mão ou por um deploy anterior. Vários scripts de apply já fazem auto-import; se falhar, importe manualmente:

bash cd <diretorio-do-terraform> ward exec -- terraform import '<endereco.do.recurso>' <id-do-recurso>

Erro de lock de state

Uma operação anterior não terminou. O ID do lock aparece na mensagem de erro:

bash cd <diretorio-do-terraform> ward exec -- terraform force-unlock <lock-id>

Cluster inalcançável

bash aws eks update-kubeconfig --name <cluster> --profile wehive-shared kubectl cluster-info

terraform init falha

Credencial do backend de state não resolvida. Confirme que ela sai do vault e reinicialize:

bash ward exec -- terraform init -reconfigure

DNS não resolve

Propagação, ou registro errado no Cloudflare. Confira o registro no painel e teste com dig. Pode levar alguns minutos.

403 do provider do GitHub

Escopo do PAT, não problema de CI ou de secret manager — ver stack github precisa de token com admin:org.

Próximos passos