Aparência
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
finnestinstalada. Veja Instalar a CLI. - Um alvo de deploy: nuvem (
--cloud=awsou--cloud=azure) e ambiente (--environment=sandboxou--environment=prod). - Credenciais da nuvem de destino, com permissão para criar rede, cluster, identidades, segredos, DNS e o armazenamento do estado.
- Acesso às imagens: a conta AWS liberada pela Finnest ou a credencial de download. Veja Acesso às imagens.
- 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.
Acesso às imagens
As imagens da plataforma ficam em registros privados da Finnest. Há duas formas de acesso.
Na AWS, pelo registro de distribuição (recomendado). A Finnest espelha as imagens de cada versão da CLI num registro ECR e libera o acesso pelo número da conta AWS da instalação, sem token.
Informe à Finnest o id da conta AWS do deploy (
aws sts get-caller-identity).Quando a Finnest confirmar a liberação, aponte o
finnest.tomlpara o registro informado:toml[images] registry = "<conta>.dkr.ecr.sa-east-1.amazonaws.com/finnest"Rode
finnest doctor. A verificaçãoimage-registrylê, com as credenciais da sua conta, cada imagem da versão da CLI. Se a conta ainda não foi liberada, ela falha e mostra o id da conta que a Finnest precisa liberar.
Os nós do EKS já baixam do ECR com a política AmazonEC2ContainerRegistryReadOnly, que o deploy anexa. Nenhum segredo de download é criado no cluster.
Com token (Azure, ou AWS sem o registro de distribuição). 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:
bash
(
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_RUNTIME_IMAGE_REGISTRY e FINNEST_RUNTIME_IMAGE_OWNER substituem o [images] registry, e FINNEST_IMAGE_PULL_USERNAME e FINNEST_IMAGE_PULL_TOKEN substituem os arquivos de credencial.
Destino de telemetria
Por padrão o coletor do cluster não envia telemetria para fora. Para enviar traces, logs e métricas a um destino OTLP/HTTP gerenciado, defina FINNEST_OTLP_EXPORT_ENDPOINT com a URL base https do destino e guarde o valor do cabeçalho Authorization em ~/.finnest/credentials/otlp-export-authorization (ou em FINNEST_OTLP_EXPORT_AUTHORIZATION). Cada implantação mantém o destino; sem a variável, a exportação continua desligada.
Sem destino externo, a instalação guarda a telemetria nos próprios armazenamentos e traz o Grafana. A senha do administrador do Grafana é gerada no primeiro deploy, e nenhum item novo é exigido. Se a participante preferir definir a senha, gere-a direto no arquivo de credencial antes do deploy, sem que ela passe pela linha de comando nem pelo histórico do shell:
bash
(
umask 077
mkdir -p -m 700 ~/.finnest/credentials
openssl rand -base64 33 > ~/.finnest/credentials/grafana-admin-password
)O arquivo guarda uma única linha, e a CLI descarta a quebra de linha final. A senha precisa de pelo menos 16 caracteres, sem caracteres de controle. Em pipelines, FINNEST_GRAFANA_ADMIN_PASSWORD substitui o arquivo.
Alerta de telemetria parada
Com os armazenamentos próprios, um alerta de vigia dispara sem parar dentro do cluster e manda um sinal periódico para a conta de nuvem, fora do cluster. Se os sinais param (o armazenamento de métricas caiu, deixou de receber dados ou de avaliar as regras), a nuvem envia um e-mail "Finnest telemetry watchdog heartbeat stopped" aos destinatários de telemetry_alert_emails.
Antes de implantar o runtime de um sandbox ou de produção com os armazenamentos próprios, informe telemetry_alert_emails no alvo (ou aws:telemetryAlertEmails / azure:telemetryAlertEmails na stack da plataforma) e implante a plataforma primeiro. Sem a chave, o deploy do runtime falha.
toml
telemetry_alert_emails = "plataforma@participante.example" # e-mails separados por vírgula, até 10Em pipelines, FINNEST_TELEMETRY_ALERT_EMAILS substitui a chave. Com um destino externo, não há armazenamento próprio que mande sinais: deixe a chave vazia, ou o deploy do runtime falha. Um sandbox desligado (finnest pause ou o desligamento fora do horário) também para os sinais e dispara o e-mail. O procedimento para quando o e-mail chega está no runbook telemetry-watchdog do pacote de conteúdo de observabilidade.
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:
bashexport AWS_PROFILE="<perfil sso>" aws sts get-caller-identityO 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--regionpara 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 loginconcluído, com a assinatura de destino ativa:bashaz 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 doctorconfere 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:
bashexport 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:
bashKUBECONFIG=<caminho> kubelogin convert-kubeconfig -l azurecli
Passo a passo
Rode os comandos na estação ou no pipeline que tem as credenciais da nuvem:
bash
CLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod
finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --preview
# <confirmação>: aws:<conta>:<ambiente> ou azure:<tenant>:<assinatura>:<ambiente>
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes --confirm=<confirmação>
finnest smoke --cloud="$CLOUD" --environment="$ENVIRONMENT"doctorconfere credenciais, permissões, DNS, imagens e material regulado.deploy --previewmostra o plano de mudanças sem alterar nada.deploy --apply --yes --confirm=<confirmação>aplica o plano. O--confirmrepete a identidade do alvo:aws:<conta>:<ambiente>na AWS ouazure:<tenant>:<assinatura>:<ambiente>na Azure. Sem ele, ou com uma identidade que não bate com o alvo, o deploy recusa o--apply. As migrações do banco e a configuração do Keycloak rodam automaticamente em cada deploy.smokerepete 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.
Primeiro proprietário do Power Admin
Quando o smoke passa, o deploy indica o próximo passo: criar o primeiro proprietário.
bash
finnest admin owner create --cloud="$CLOUD" --environment="$ENVIRONMENT"- O comando usa as credenciais da nuvem do alvo e não precisa de licença. A organização do proprietário é a da própria instalação, nomeada pelo identificador do deploy do alvo.
- E-mail e nome vêm de
--emaile--nameou, se omitidos, deowner.emaileowner.display_namedo perfil do operador. - Em uma sessão interativa (stdin e stdout no terminal, sem
--jsonnem--non-interactive), o comando mostra a URL do admin, o e-mail do proprietário e a senha temporária uma única vez; a senha nunca vai para o envelope, a evidência ou um arquivo. - Fora disso (
--json, stdin redirecionado,--non-interactiveou sem terminal), informe--password-file=<caminho>: a senha é gravada apenas nesse arquivo novo com permissão 0600. Sem o flag, o comando recusa antes de tocar o cluster. finnest admineadmin ownerrecusam comADMIN_DOMAIN_INVALIDquando o domínio do alvo não é um hostname puro (sem esquema, caminho ou porta); o texto configurado nunca é ecoado.- No primeiro acesso, o proprietário precisa escolher uma nova senha. Se usou arquivo, apague-o depois.
createrecusa quando já existe um proprietário. Para recuperar o acesso, usefinnest admin owner reset --email=<e-mail> --yes: ele substitui a senha e revoga as sessões do proprietário anterior.
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:
bash
CLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes --confirm=<confirmação> --output=ndjsonCada 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) |
grafana.<domínio> | Grafana, quando a telemetria fica na instalação |
finnest status mostra o endereço do Grafana, e finnest health --suite=post-deploy confere que ele responde em /api/health.
Grafana
Quando a telemetria fica na instalação (sem FINNEST_OTLP_EXPORT_ENDPOINT), o deploy instala o Grafana em https://grafana.<domínio>, com TLS do mesmo emissor dos outros hosts. Ele já vem com:
- as fontes de dados de métricas, logs e traces da instalação;
- os painéis da plataforma na pasta Finnest, entre eles Finnest — Client requests, que encontra os logs e o trace de uma requisição pelo
x-fapi-interaction-id.
O Power Admin usa esse mesmo endereço na busca de operações para abrir os logs e o trace de um id.
O Grafana vem ligado por padrão. Para manter a telemetria na instalação sem ele, declare grafana_enabled = false no alvo ([profile.<id>]) do finnest.toml: o próximo deploy remove o Grafana e o host grafana.<domínio>, o finnest status deixa de mostrá-lo e o finnest health marca a sonda do Grafana como não aplicável.
Entrar. O usuário e a senha do administrador ficam no segredo finnest-grafana-admin do cluster, no namespace finnest-power. Esse admin local é a conta de emergência do Grafana. A senha é a última que a participante informou ou, sem escolha, a que o primeiro deploy gerou; os deploys seguintes mantêm a gerada. finnest status mostra o endereço e onde ler a credencial, sem imprimi-la:
bash
kubectl -n finnest-power get secret finnest-grafana-admin -o jsonpath='{.data.admin-user}' | base64 -d
kubectl -n finnest-power get secret finnest-grafana-admin -o jsonpath='{.data.admin-password}' | base64 -dA senha não aparece nos valores do Helm nem nos logs do deploy.
A senha vem sempre do segredo. Cada vez que um pod do Grafana é criado, um contêiner de inicialização redefine a senha da conta de emergência para a do segredo finnest-grafana-admin, antes de o Grafana abrir. O pod é recriado num deploy que muda a senha ou a versão, quando o pod é apagado ou quando vai para outro nó; um deploy sem mudança não recria o pod, e o reinício do contêiner dentro do mesmo pod não repete a redefinição. Uma troca feita pela interface do Grafana dura só até a próxima recriação do pod, quando volta à do segredo.
Ao atualizar para esta versão
A senha da conta de emergência do Grafana passa a ser sempre a do segredo finnest-grafana-admin. Se ela foi trocada pela interface, volta à do segredo no primeiro deploy desta versão. Para manter a senha atual, grave-a no arquivo de credencial (ou em FINNEST_GRAFANA_ADMIN_PASSWORD) antes de atualizar.
Trocar a senha da conta de emergência. Gere a nova senha no arquivo de credencial, do mesmo modo que na primeira escolha, e rode finnest deploy:
bash
(
umask 077
mkdir -p -m 700 ~/.finnest/credentials
openssl rand -base64 33 > ~/.finnest/credentials/grafana-admin-password
)
finnest deployO deploy grava a nova senha no segredo, o pod do Grafana é recriado e o contêiner de inicialização redefine a senha antes de o Grafana abrir. Em pipelines, troque FINNEST_GRAFANA_ADMIN_PASSWORD e rode o deploy. Uma senha gerada pelo primeiro deploy só muda quando a participante passa a informar a sua.
O contêiner de inicialização só conclui quando o Grafana confirma a troca da senha: o comando do Grafana sai com sucesso em algumas falhas (por exemplo, quando o usuário admin deixou de ser administrador), e por isso a confirmação é exigida. Se a redefinição falhar ou não for confirmada, o contêiner de inicialização falha (o pod fica em Init:Error ou Init:CrashLoopBackOff), o deploy falha de forma visível e o Grafana fica indisponível até a causa ser corrigida e um novo deploy rodar: o Grafana é recriado (estratégia Recreate) e nunca abre com uma senha diferente da do segredo. O log do contêiner traz só uma linha fixa, sem valores; para vê-la:
bash
kubectl -n finnest-power logs deploy/finnest-grafana -c finnest-admin-reconcileDar acesso somente leitura. O administrador cria os demais usuários no próprio Grafana, com o papel Viewer. É assim que a participante dá à Finnest acesso de leitura aos logs e métricas:
- Entre em
https://grafana.<domínio>comoadmin. - Abra Administration › Users and access › Users e crie o usuário, com nome, e-mail e uma senha inicial.
- Confira que o papel do usuário na organização é Viewer. Ele vê os painéis e o Explore, mas não altera fontes de dados, painéis nem usuários.
- Envie o endereço e o usuário à pessoa por um canal à escolha da participante, e peça que ela troque a senha no primeiro acesso.
Para revogar o acesso, remova o usuário na mesma tela. Os usuários e papéis ficam guardados no volume do Grafana e sobrevivem às atualizações. Uma desinstalação os apaga junto com a instalação.
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 ou válido. Um certificado fica perto de vencer a partir de 60 dias do vencimento, e o aviso fica crítico com 7 dias ou menos. O aviso não bloqueia o deploy, porque é o deploy que publica o certificado novo. Um certificado vencido bloqueia. A exceção é um certificado das cadeias ICP-Brasil que não assina o certificado BRCAC: vencido, ele só gera aviso.
No certificado BRCAC do gateway regulado, a CLI confere que:
- o certificado tem uso estendido serverAuth;
- a chave do certificado é RSA de pelo menos 2048 bits, porque o gateway regulado só oferece cifras ECDHE-RSA;
- os nomes alternativos cobrem
matls-auth.<domínio>ematls-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:
bash
finnest config workspace open --goal=apply
finnest secrets write brcac-tls-cert-pem --file ./brcac.pem --pair-file ./brcac.key --yesO próximo finnest deploy --apply 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. As chaves cost_* e off_hours_* também aceitam uma variável de ambiente com o prefixo FINNEST_ (por exemplo, FINNEST_COST_MODE), usada só quando a chave não está no arquivo. O autoscaling_override só vale no arquivo.
cost_mode
Define o porte da infraestrutura e se o desligamento fora do horário e a escala a zero ficam ativos.
toml
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 | 64 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/compliance; 1000 em 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. Só vale na AWS; na Azure, a chave não tem efeito e o resumo sai quando há cost_alert_emails e cost_digest_cadence não é off |
cost_anomaly_threshold_usd | número positivo | max(50, 20% do orçamento) — só AWS |
cost_hard_cap_mode | freeze ou stop | stop no sandbox, freeze em produção |
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.
Teto de gasto
Com cost_alert_emails informado, o teto de gasto fica sempre ligado e não há chave para desligá-lo: quando o gasto real chega a 90% do orçamento mensal, ele trava o consumo na conta de nuvem. Sem cost_alert_emails, não há orçamento nem teto, e informar cost_hard_cap_mode sem ele faz o deploy falhar. cost_hard_cap_mode (ou deployment.cost.hard_cap_mode) escolhe como:
freezebloqueia nova capacidade (nós, grupos de nós, bancos e caches) e mantém o que já roda no ar. Só na AWS.stoptambém desliga a frota. Só no sandbox; um novofinnest deploy --applyrestaura o serviço.
Antes de qualquer mudança na nuvem, finnest deploy recusa stop em produção (COST_HARD_CAP_MODE_INVALID_FOR_PROD), porque desligar o plano de controle regulado é um incidente regulatório, e recusa freeze na Azure (COST_HARD_CAP_MODE_UNSUPPORTED_ON_AZURE). Por isso, um alvo de produção na Azure com cost_alert_emails informado é recusado: produção exige freeze, e a Azure só aceita stop. O resumo do deploy mostra o modo resolvido, por exemplo cost hard cap freeze at 90%.
A chave antiga cost_hard_cap_enabled (deployment.cost.hard_cap_enabled) foi removida: a validação a recusa com CONFIG_FIELD_RETIRED. Rode finnest config retire cost.hard-cap-enabled para apagá-la de todos os arquivos carregados.
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:
toml
autoscaling_override = '{"app": {"consolidateAfter": "10m", "cpuLimit": "48"}}'| Campo | Valores |
|---|---|
| Grupo | system, stateful, app ou mop (só AWS, só capacityTypes) |
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) |
O grupo stateful nunca usa spot. Um grupo que é só on-demand por padrão (app e system nos modos compliance e production, e o mop sempre) só aceita spot junto com on-demand, como em ["spot", "on-demand"]; spot puro é recusado. Também não é possível encurtar o expireAfter de um grupo só on-demand. 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 undeployremove o processamento do alvo e mantém os dados.finnest destroyremove o alvo inclusive os dados. Rodefinnest destroy --previewantes.
Ambos exigem confirmação explícita.