Skip to content

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.
  • 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.

  1. Informe à Finnest o id da conta AWS do deploy (aws sts get-caller-identity).

  2. Quando a Finnest confirmar a liberação, aponte o finnest.toml para o registro informado:

    toml
    [images]
    registry = "<conta>.dkr.ecr.sa-east-1.amazonaws.com/finnest"
  3. Rode finnest doctor. A verificação image-registry lê, 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é 10

Em 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:

    bash
    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:

    bash
    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:

    bash
    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:

    bash
    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:

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"
  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 --confirm=<confirmação> aplica o plano. O --confirm repete a identidade do alvo: aws:<conta>:<ambiente> na AWS ou azure:<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.
  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.

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 --email e --name ou, se omitidos, de owner.email e owner.display_name do perfil do operador.
  • Em uma sessão interativa (stdin e stdout no terminal, sem --json nem --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-interactive ou 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 admin e admin owner recusam com ADMIN_DOMAIN_INVALID quando 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.
  • create recusa quando já existe um proprietário. Para recuperar o acesso, use finnest 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=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:

EtapaO que significa
preflightFalta um pré-requisito: login, permissão, DNS, imagens ou material regulado.
bootstrapFalha ao preparar o armazenamento do estado ou as identidades.
platformFalha na infraestrutura de nuvem: rede, cluster, identidades, DNS ou balanceador.
runtime / helmFalha no Kubernetes: operadores, segredos, valores do chart ou download das imagens.
smokeA 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:

HostUso
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 -d

A 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 deploy

O 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-reconcile

Dar 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:

  1. Entre em https://grafana.<domínio> como admin.
  2. Abra Administration › Users and access › Users e crie o usuário, com nome, e-mail e uma senha inicial.
  3. 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.
  4. 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> 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:

bash
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 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
ModoDesligamento fora do horárioEscala a zeroDisco do sistema (Azure)
economyligadoligada64 GB
standardligadoligada64 GB
compliancedesligadodesligada64 GB
productionnão permitidodesligada128 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 ​

ChaveValoresPadrão
cost_alert_emailse-mails separados por vírgulavazio — necessário para criar orçamentos e alertas
cost_monthly_budget_usdnúmero positivo500 em economy/standard/compliance; 1000 em production
cost_digest_cadenceoff, daily, weekly ou monthlyweekly
cost_digest_emailse-mails separados por vírgulausa cost_alert_emails
cost_digest_enabledtrue ou falsefalse. 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_usdnúmero positivomax(50, 20% do orçamento) — só AWS
cost_hard_cap_modefreeze ou stopstop 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:

  • freeze bloqueia nova capacidade (nós, grupos de nós, bancos e caches) e mantém o que já roda no ar. Só na AWS.
  • stop também desliga a frota. Só no sandbox; um novo finnest deploy --apply restaura 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.

ChaveValoresPadrão
off_hours_stop"true" ou "false"depende do cost_mode
off_hours_stop_hourinteiro de 0 a 2320 na Azure, 22 na AWS
off_hours_start_hourinteiro de 0 a 238
off_hours_weekend_start"true" ou "false""false" (religa só em dias úteis)
off_hours_timezonenome de fuso horárioAmerica/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"}}'
CampoValores
Gruposystem, stateful, app ou mop (só AWS, só capacityTypes)
consolidateAfter, expireAfterduração (30s, 10m, 720h) ou Never
capacityTypesspot e/ou on-demand
weightinteiro de 1 a 100
cpuLimit, memoryLimitquantidades 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 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.

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br