Deploy na AWS ou Azure

Este guia mostra como implantar o Finnest Power com a CLI finnest numa conta AWS ou numa assinatura Azure da instituição. Um único fluxo cobre tudo: verificação de pré-requisitos, preparação do estado, infraestrutura de nuvem, runtime Kubernetes, aplicação e testes de fumaça. Não é preciso acesso ao código-fonte da plataforma.

O que você precisa

• A CLI finnest instalada. Veja Instalar a CLI.
• Um alvo de deploy: nuvem (--cloud=aws ou --cloud=azure) e ambiente (--environment=sandbox ou --environment=prod).
• Credenciais da nuvem de destino, com permissão para criar rede, cluster, identidades, segredos, DNS e o armazenamento do estado.
• A credencial de download das imagens fornecida pela Finnest.
• O domínio da instalação, com a zona pai pronta para delegar os registros NS.
• O material regulado do seu papel: certificados ICP-Brasil (BRCAC e BRSEAL), cadeias de confiança e chaves. Veja Material regulado.

Credencial de download das imagens

As imagens da plataforma ficam num registro privado. A Finnest fornece um usuário e um token somente leitura, que só permitem baixar as imagens. Grave-os em arquivos com permissão 0600:

(
  umask 077
  mkdir -p ~/.finnest/credentials
  rm -f ~/.finnest/credentials/image-pull-username ~/.finnest/credentials/image-pull-token
  printf '%s' '<usuário fornecido pela Finnest>' > ~/.finnest/credentials/image-pull-username
  printf '%s' '<token fornecido pela Finnest>' > ~/.finnest/credentials/image-pull-token
)

A CLI cria no cluster o segredo de download a partir desses arquivos. Em pipelines, as variáveis FINNEST_IMAGE_PULL_USERNAME e FINNEST_IMAGE_PULL_TOKEN substituem os arquivos.

Se a instituição espelhar as imagens num registro próprio (ECR ou ACR), configure FINNEST_RUNTIME_IMAGE_REGISTRY e FINNEST_RUNTIME_IMAGE_OWNER e dispense a credencial da Finnest.

Versão da plataforma

A versão das imagens implantadas acompanha a versão da CLI: cada versão da CLI traz o conjunto de imagens publicado e assinado junto com ela. Para mudar de versão, atualize a CLI; veja Atualização de versão. O finnest doctor confere, antes do deploy, se as imagens podem ser baixadas.

Para fixar uma versão diferente, por exemplo num pipeline, use FINNEST_RUNTIME_IMAGE_TAG. Para fixar um único serviço, use FINNEST_RUNTIME_IMAGE_TAG_<SERVIÇO> ou FINNEST_RUNTIME_IMAGE_DIGEST_<SERVIÇO>.

Requisitos na AWS

• Sessão da AWS CLI ativa na conta de destino. Com SSO, selecione o perfil antes do deploy:

  export AWS_PROFILE="<perfil sso>"
  aws sts get-caller-identity

• O principal precisa gerenciar EKS, VPC, IAM, KMS, S3, Route 53, balanceadores de carga e recursos do Kubernetes.

• A região padrão é sa-east-1. Use --region para outra região.

• Se o SSO expirar durante o trabalho, renove a sessão antes de repetir o deploy ou os testes.

Requisitos na Azure

• az login concluído, com a assinatura de destino ativa:

  az account show --query '{subscription:id, tenant:tenantId}' -o table
  export ARM_SUBSCRIPTION_ID="$(az account show --query id -o tsv)"

• O login precisa de Owner, ou de Contributor e User Access Administrator, na assinatura. finnest doctor confere esses papéis.

• O tenant do Entra ID precisa permitir registro de aplicações, service principals, credenciais federadas, grupos e atribuições de RBAC.

• Por padrão, a plataforma cria um grupo de administradores do AKS e inclui o login atual. Isso exige Groups Administrator e Application Administrator no Entra ID. Se preferir usar um grupo existente, informe o ID dele:

  export FINNEST_AZURE_AKS_ADMIN_GROUP_OBJECT_ID="<object id do grupo>"

• A região padrão é brazilsouth.

• Se o acesso ao AKS pedir login por código repetidamente, converta o kubeconfig:

  KUBECONFIG=<caminho> kubelogin convert-kubeconfig -l azurecli

Passo a passo

Rode os comandos na estação ou no pipeline que tem as credenciais da nuvem:

CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --preview
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes
finnest smoke  --cloud="$CLOUD" --environment="$ENVIRONMENT"

1. doctor confere credenciais, permissões, DNS, imagens e material regulado.
2. deploy --preview mostra o plano de mudanças sem alterar nada.
3. deploy --apply --yes aplica o plano. As migrações do banco e a configuração do Keycloak rodam automaticamente em cada deploy.
4. smoke repete os testes de fumaça depois do deploy.

Para acompanhar o andamento, finnest status mostra o estado do alvo, e finnest admin imprime o endereço do Power Admin.

O doctor roda as verificações em paralelo, mostra o progresso ao vivo e termina com o resumo. Quando algo falha, ele também mostra os próximos passos e o link para a documentação do erro:

Automação

Com --json, a CLI imprime um envelope versionado com o resultado e o caminho da evidência. Para acompanhar um deploy longo em tempo real, use NDJSON:

CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes --output=ndjson

Cada linha é um evento JSON, e a última é o envelope final.

Onde o deploy parou

A evidência e o finnest recover deploy indicam a etapa em que o deploy parou:

Etapa	O que significa
preflight	Falta um pré-requisito: login, permissão, DNS, imagens ou material regulado.
bootstrap	Falha ao preparar o armazenamento do estado ou as identidades.
platform	Falha na infraestrutura de nuvem: rede, cluster, identidades, DNS ou balanceador.
runtime / helm	Falha no Kubernetes: operadores, segredos, valores do chart ou download das imagens.
smoke	A infraestrutura está no ar, mas um teste de produto, autenticação ou jornada regulatória falhou.

Veja o que fazer em cada caso em Recuperação de deploy. A estrutura das evidências está em Solução de problemas.

Endereços da instalação

Depois de um deploy bem-sucedido, a instalação responde nos hosts do domínio escolhido:

Host	Uso
api.<domínio>	APIs públicas e administrativas
matls-api.<domínio>	APIs reguladas, com mTLS obrigatório
auth.<domínio>	Servidor de autorização
matls-auth.<domínio>	Endpoints do servidor de autorização que exigem mTLS
admin.<domínio>	Power Admin
docs.<domínio>	Portal de API da instalação (opcional)

Material regulado

O doctor e o deploy conferem o material regulado exigido pelo papel da instituição e classificam cada item como ausente, inválido, vencido, perto de vencer (30 dias ou menos) ou válido.

No certificado BRCAC do gateway regulado, a CLI confere que:

• o certificado tem uso estendido serverAuth;
• os nomes alternativos cobrem matls-auth.<domínio> e matls-api.<domínio>;
• a cadeia está em ordem (certificado final primeiro, depois cada AC emissora) e fecha na cadeia ICP-Brasil informada;
• o certificado e a chave formam um par.

O certificado de cliente da receptora precisa ter uso clientAuth e não pode ser autoassinado.

Para informar ou trocar um item, use o Configuration Workspace ou secrets write:

finnest config workspace open --goal=apply
finnest secrets write brcac-tls-cert-pem --file ./brcac.pem --pair-file ./brcac.key --yes

O próximo finnest deploy --apply --yes publica o material no cofre de segredos da nuvem. A lista de itens e o procedimento completo estão em Rotação de certificados.

Controle de custos

As chaves abaixo ficam em [profile.<id>] no finnest.toml. São política operacional, não credenciais, e podem ser versionadas. Cada chave também aceita uma variável de ambiente com o prefixo FINNEST_ (por exemplo, FINNEST_COST_MODE), usada só quando a chave não está no arquivo.

cost_mode

Define o porte da infraestrutura e se o desligamento fora do horário e a escala a zero ficam ativos.

cost_mode = "economy"   # economy | standard | compliance | production

Modo	Desligamento fora do horário	Escala a zero	Disco do sistema (Azure)
economy	ligado	ligada	64 GB
standard	ligado	ligada	64 GB
compliance	desligado	desligada	128 GB
production	não permitido	desligada	128 GB

Sem a chave, o sandbox usa standard e produção usa production. Um alvo de produção só aceita production; qualquer outro modo é recusado antes de qualquer mudança na nuvem.

Outras chaves

Chave	Valores	Padrão
cost_alert_emails	e-mails separados por vírgula	vazio — necessário para criar orçamentos e alertas
cost_monthly_budget_usd	número positivo	500 em economy/standard; 1500 em compliance/production
cost_digest_cadence	off, daily, weekly ou monthly	weekly
cost_digest_emails	e-mails separados por vírgula	usa cost_alert_emails
cost_digest_enabled	true ou false	false
cost_anomaly_threshold_usd	número positivo	max(50, 20% do orçamento) — só AWS
cost_hard_cap_enabled	só false	false; true é recusado

Sem cost_alert_emails, o deploy funciona normalmente, mas não cria orçamentos nem alertas. Na AWS, finnest cost mostra o gasto do mês por dia e por serviço.

Desligamento fora do horário

Nos modos economy e standard, o cluster do sandbox desliga à noite e religa de manhã, em dias úteis. finnest resume religa antes do horário, e finnest pause desliga na hora.

Chave	Valores	Padrão
off_hours_stop	"true" ou "false"	depende do cost_mode
off_hours_stop_hour	inteiro de 0 a 23	20 na Azure, 22 na AWS
off_hours_start_hour	inteiro de 0 a 23	8
off_hours_weekend_start	"true" ou "false"	"false" (religa só em dias úteis)
off_hours_timezone	nome de fuso horário	America/Sao_Paulo

Regras de validação (erro OFF_HOURS_STOP_INVALID):

• os horários de desligar e religar precisam ser diferentes;
• o fuso não pode ser vazio. Na AWS, use um nome IANA canônico; na Azure, nomes do Windows também são aceitos;
• na AWS, o horário de desligar não pode cair entre 11:00 e 23:00 UTC, janela reservada à consolidação de nós.

Ajuste de autoscaling

O cost_mode define o comportamento de autoscaling dos grupos de nós. Para ajustar, use autoscaling_override em [profile.<id>] com um objeto JSON:

autoscaling_override = '{"app": {"consolidateAfter": "10m", "cpuLimit": "48"}}'

Campo	Valores
Grupo	system, stateful ou app
consolidateAfter, expireAfter	duração (30s, 10m, 720h) ou Never
capacityTypes	spot e/ou on-demand
weight	inteiro de 1 a 100
cpuLimit, memoryLimit	quantidades do Kubernetes (48, 96Gi)

Um ajuste não pode colocar em spot um grupo que é só on-demand, nem encurtar o expireAfter dele. JSON inválido gera o erro AUTOSCALING_OVERRIDE_INVALID. Na Azure, o ajuste é mostrado como aviso e não é aplicado.

Remover uma instalação

• finnest undeploy remove o processamento do alvo e mantém os dados.
• finnest destroy remove o alvo inclusive os dados. Rode finnest destroy --preview antes.

Ambos exigem confirmação explícita.