Aparência
Solução de problemas
Primeiro diagnóstico
Quando um comando falha:
Leia o código do erro e os próximos passos impressos pela CLI. Cada categoria de erro tem uma página em Erros da CLI.
Rode o diagnóstico do alvo:
bashCLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"Se a falha foi num deploy, peça o diagnóstico da execução:
bashCLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod finnest recover deploy --run=latest --cloud="$CLOUD" --environment="$ENVIRONMENT"O comando só lê as evidências. Ele indica em que etapa o deploy parou e qual o próximo comando seguro. Veja Recuperação de deploy.
Para acionar o suporte, gere o pacote de suporte e envie-o com o código do erro:
bashfinnest support bundle --run=<id-da-execução>
Evidências de execução
Cada comando grava uma evidência redigida em .finnest/runs/<comando>/<execução>/, no diretório onde foi executado:
| Arquivo | Conteúdo |
|---|---|
envelope.json | Resultado final: status, código de saída, alvo, resumo das etapas, erro e próximos passos. |
events.ndjson | Eventos do comando, em ordem. |
run.json e deploy-events.ndjson | No deploy: resumo da execução e eventos de cada etapa. |
raw/pulumi-bootstrap.log | Saída da preparação do estado da infraestrutura. |
raw/pulumi-deploy.log | Saída da criação da infraestrutura e do runtime. |
raw/pulumi-destroy.log | Saída do destroy. |
Para listar e abrir execuções anteriores:
bash
finnest runs
finnest runs show <execução>Por alvo, a CLI mantém as 25 execuções mais recentes, até 200 MiB. Mude esses limites na seção [runs] do finnest.toml, com keep (quantidade) e max_bytes (em bytes). Execuções que falharam nunca são apagadas.
Arquivos de configuração legados
Instalações antigas podiam apontar a CLI para arquivos de configuração do runtime, na seção [runtime] do finnest.toml (bootstrap_config, deploy_config) ou nas variáveis RUNTIME_CD_*_CONFIG_PATH. A CLI atual não precisa desses arquivos.
Configuração de bootstrap
Erros: BOOTSTRAP_CONFIG_FILE_MISSING, BOOTSTRAP_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.
O arquivo de bootstrap configurado não existe, não pode ser lido ou ainda tem valores __FINNEST_REQUIRED_… do modelo.
Configuração de deploy
Erros: DEPLOY_CONFIG_FILE_MISSING, DEPLOY_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.
O arquivo de deploy configurado não existe, não pode ser lido ou ainda tem valores do modelo.
Configuração de destroy
Erros: DESTROY_CONFIG_FILE_MISSING, DESTROY_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.
O arquivo usado pelo destroy não existe, não pode ser lido ou ainda tem valores do modelo.
Como corrigir
Remova a referência ao arquivo legado do
finnest.toml(ou a variávelRUNTIME_CD_*_CONFIG_PATH). Se o suporte Finnest pediu para manter o arquivo, restaure-o e preencha os valores pendentes.Atualize os metadados da estação:
bashfinnest setupRepita o comando que falhou.
Situações comuns
O deploy pede --yes
Todo --apply altera a nuvem e exige confirmação explícita:
bash
CLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yesO sandbox não responde
O sandbox pode estar pausado para economizar custo:
- Na Azure, nos modos de custo
economyestandard, o cluster desliga fora do horário comercial, a menos queoff_hours_stopdiga o contrário. - Na AWS, o sandbox pausa sozinho depois de duas horas sem atividade, quando a pausa automática está ativa; a verificação
power-automationdofinnest doctoravisa quando ela está desligada. O desligamento fora do horário só vale comoff_hours_stop = "true".
Para religar:
bash
CLOUD=aws # ou: azure
finnest resume --cloud="$CLOUD" --environment=sandbox --yesA sessão da nuvem expirou
Renove o login (AWS SSO ou az login) e rode finnest doctor de novo antes de repetir o deploy.
Falha nos testes de fumaça depois do deploy
Se o deploy parou na etapa smoke, a infraestrutura já está no ar. Corrija a causa apontada (normalmente certificado, credencial ou configuração regulatória) e rode só os testes:
bash
CLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod
finnest smoke --cloud="$CLOUD" --environment="$ENVIRONMENT"Envio real do PCM do Open Finance (pcm_live)
pcm_live = true liga o envio real ao PCM do Open Finance no próximo finnest deploy. A chave vale por alvo, num alvo nomeado ou na forma legada de alvo único:
toml
[profile.<id>]
pcm_live = true
# Forma legada:
[deployment.pcm]
live = trueEla chega ao runtime como runtime:pcm.live na AWS e na Azure e leva as três credenciais do PCM para o segredo pcm-banking-credentials do serviço de banking. Sem a chave, ou com false, o envio real fica desligado.
O deploy grava essas credenciais no cofre de segredos da nuvem a partir do ambiente da execução do finnest deploy, a única origem que a CLI lê para elas (não são material regulado, então o finnest secrets write não as aceita). Com o envio real ligado, defina as três em todo deploy:
bash
export FINNEST_PCM_SS_CLIENT_ID=<client id do software statement do PCM>
export FINNEST_PCM_TRANSPORT_CERT_PEM="$(cat <arquivo PEM do certificado de transporte do PCM>)"
export FINNEST_PCM_TRANSPORT_KEY_PEM="$(cat <arquivo PEM da chave de transporte do PCM>)"Todo relatório identifica a participante pela organização dela no Diretório do OFB, que não é segredo: declare ofb_org_id em [opin] no finnest.toml. Ele chega ao runtime como runtime:ofb.organisationId, sua única origem.
toml
[opin]
ofb_org_id = "<UUID da organização no Diretório do OFB>"Numa instalação gerida pelo configuration workspace, toda edição à mão dessas chaves pede um novo commit do workspace antes do deploy. A instalação é gerida pelo workspace quando já há um commit dele, ou quando o alvo tem um material_set: o de [profile.<alvo>] ou, se o alvo não declara um, o de [opin]. Sem ele, o finnest doctor aponta a falta (workspace-receipt) e o deploy recusa com RUNTIME_WORKSPACE_RECEIPT_INVALID:
bash
finnest config workspace open --goal=apply --json
finnest config workspace review <workspace> <revisão>
finnest config workspace commit <workspace> <revisão> reviewUse a revisão que cada resposta devolve.
Com pcm_live = true e alguma credencial ausente, ou sem ofb_org_id, a verificação ofb-pcm-live-credentials da preparação do deploy para o finnest deploy (preview e apply) com DEPLOY_PREFLIGHT_FAILED antes de qualquer alteração, nomeando o que falta. O finnest doctor mostra a mesma falta como aviso. O finnest deploy --preview mostra o plano de recursos e a contagem de mudanças das pilhas de plataforma e de runtime, não uma comparação dos valores de configuração do runtime: confira a chave em finnest config show antes de aplicar.
Encerrar a sessão de um consentimento OFB revogado
Uma implantação que serve a jornada de autorização OFB encerra a sessão do Keycloak de cada consentimento que deixa AUTHORISED. Declare em [opin] no finnest.toml:
toml
[opin]
ofb_session_revocation = trueO flag liga juntos o event runtime e o relay de eventos do banking. Gere uma vez o segredo da conta de serviço com finnest secrets write ofb-session-revoker-client-secret; finnest doctor indica esse comando enquanto ele faltar. O papel manage-users dessa conta alcança todos os usuários do realm OFB, e é o papel mais estreito que o Keycloak oferece para apagar uma sessão: só o worker de revogação e o bootstrap do Keycloak leem o segredo.
O relatório PCM do OPIN não chega ao PCM
A participante receptora reporta ao PCM (Plataforma de Coleta de Métricas) cada chamada feita a uma transmissora. Comece pelo estado:
bash
finnest opin pcm statusReal sending OFF (FINNEST_OPIN_PCM_LIVE=off)quer dizer que o envio real está desligado no serviço de seguros: os relatórios são montados e assinados, mas nada chega ao PCM. Em produção, o relatório regulatório não está sendo entregue. Enquanto isso,opin pcm approverespondeOPIN_PCM_REAL_SENDING_OFF.- As pendências listam cada relatório que o PCM descartou ou que o serviço recusou antes do envio, com a mensagem literal, o
correlationId, o endpoint e o status HTTP. A exceção é umDuplicated registerque volta depois de um POST que ficou sem resposta: o PCM já tem esse relatório, então ele conta como entregue e não aparece nas pendências. OcorrelationIdé o id do registro na trilha, não o id da chamada. Nas pendências de chamadas, ox-fapi-interaction-idaparece no campointeractionIddefinnest opin pcm status --json. - Para conferir uma chamada, use o
x-fapi-interaction-iddela:finnest opin pcm lookup --interaction-id <x-fapi-interaction-id>oufinnest opin interactions --interaction-id <x-fapi-interaction-id>. - A linha
Correlation echo today: N differing (P% of today's receipts)mostra quantos recibos de hoje (desde a meia-noite de São Paulo) voltaram com umcorrelationIddiferente do enviado. A API de ingestão (v1.0.13) atribui os itens do recibo pela posição, então o id é só uma conferência: 0% indica que o id foi ecoado (ou que nenhum recibo voltou ainda), 100% indica que o PCM responde com ids próprios (informativo), e uma taxa parcial indica um possível desalinhamento de posição. Odoctormostra a mesma taxa; uma taxa parcial é aviso, nunca falha.
Confira o kid de assinatura em três fontes: o opin_pcm_signing_kid do alvo ativo, a identidade com que o serviço implantado assina e o keystore público da organização no Diretório:
bash
finnest opin pcm doctorO PCM valida os relatórios com o certificado de assinatura (BRSEAL) cadastrado na organização. O doctor lê o JWKS público da organização (org_jwks_uri, https://keystore.sandbox.directory.opinbrasil.com.br/<org_id>/application.jwks; em produção, keystore.directory.opinbrasil.com.br) e o JWKS de chaves inativas (org_jwks_inactive_uri, .../<org_id>/inactive/application.jwks), como descreve a seção de software statement da área do desenvolvedor do OPIN. Os dois são públicos: não precisa de sessão no Diretório, BRCAC nem TOTP. O kid precisa ser uma chave de assinatura (use: "sig"; chaves enc são ignoradas), não pode estar no JWKS de inativas, e o SHA-256 do DER do seu x5c[0] precisa ser o do certificado em uso. O resultado é um só:
| Veredito | Código | Significado |
|---|---|---|
org-level | — | O kid é da organização, ativo e do certificado em uso. |
inactive | OPIN_PCM_SIGNING_KID_INACTIVE | O kid está no JWKS de chaves inativas. |
absent | OPIN_PCM_SIGNING_KID_ABSENT | O kid não é uma chave de assinatura ativa da organização. |
certificate-mismatch | OPIN_PCM_SIGNING_CERTIFICATE_MISMATCH | O kid aponta para outro certificado. |
keystore-unreachable | OPIN_PCM_KEYSTORE_UNREACHABLE | O keystore não respondeu com um JWKS. |
O doctor também falha quando o kid do alvo difere do kid implantado (OPIN_PCM_SIGNING_KID_DIVERGED) e avisa quando o envio real está desligado (real sending off: the PCM receives nothing).
A URL do keystore só é montada a partir de um id de organização que seja um UUID. Qualquer outro valor (com /, .. ou ?, por exemplo) é recusado antes de qualquer requisição: o doctor responde OPIN_PCM_ORGANISATION_ID_INVALID e a verificação opin-pcm-signing do deploy falha.
Ligar o envio real
Cadastre o BRSEAL no Diretório no nível da organização e guarde o certificado e a chave:
finnest secrets write keycloak-brseal-certificate-pem --file <pem>efinnest secrets write keycloak-brseal-private-key-pem --file <pem>.Veja o kid com
finnest opin directory certse informe-o no alvo, ainda com o envio desligado. Prepare a mudança no configuration workspace e faça o commit, usando a revisão que cada resposta devolve:bashfinnest config workspace open --goal=apply --json finnest config workspace stage <workspace> <revisão> opin.pcm-signing-kid <kid> finnest config workspace review <workspace> <revisão> finnest config workspace commit <workspace> <revisão> reviewSe a resposta listar avisos, reconheça cada um com
finnest config workspace acknowledge <workspace> <revisão> <requirement-id>antes doreview. O campo gravaopin_pcm_signing_kidno alvo ativo.Rode
finnest deploye depoisfinnest opin pcm doctor: o veredito precisa serorg-levele o kid do alvo precisa ser o implantado.Ligue o envio da mesma forma, com
opin.pcm-live true(gravaopin_pcm_live = true), e rodefinnest deploy --preview. A verificaçãoopin-pcm-signingda preparação do deploy aplica a mesma regra ao kid do alvo e ao certificado BRSEAL guardado. Se o veredito não fororg-level, o deploy para comDEPLOY_PREFLIGHT_FAILEDantes de qualquer alteração, para que o envio real nunca ligue com um kid que o PCM recusa. Com o envio desligado, não há consulta ao keystore nem bloqueio.Aplique o deploy e confirme em
finnest opin pcm statusa linhaReal sending ON.
Aprovar, reenviar e alterar o modo de envio exigem --yes e o e-mail de quem faz a operação, que o serviço registra:
bash
finnest opin pcm approve <batch-id> --operator <email> --yes
finnest opin pcm resend <batch-id> --operator <email> --yes
finnest opin pcm config --mode manual --interval 15 --operator <email> --yesresend aceita um lote com falha ou sem confirmação dentro da janela de 180 dias. Se o comando responder OPIN_PCM_SCOPE_DENIED, rode finnest deploy depois de atualizar a CLI, para que o realm conceda os escopos opin:pcm:read e opin:pcm:operate.
A declaração de recertificação OIDF responde 403 ou 503
Na vigilância de conformidade do console Power, só os donos (owner) e administradores (admin) da organização que opera o participante desta implantação declaram uma recertificação OIDF. Como qualquer pessoa pode criar a própria organização no Power, ser dono de outra organização não basta.
- 503 com
operator organization unresolved (Power IAM must hold exactly one self-hosted organization): o Power não encontrou exatamente uma organização auto-hospedada no Power IAM. A organização operadora é a organização auto-hospedada quefinnest admin owner createou o bootstrap da licença provisiona; não há nada a informar nofinnest.tomlnem no workspace de configuração. Se o dono ainda não foi criado, rodefinnest admin owner create. - 403 com
only the organization that operates this participant declares recertifications: a organização ativa da sessão não é a organização operadora. Troque a organização ativa no console ou peça a um dono ou administrador dela que faça a declaração.
Um finnest.toml que ainda informa power_operator_organization_id em um [profile.<id>] falha com CONFIG_FIELD_RETIRED; rode finnest config retire power.operator-organization-id para remover a chave e confirme de novo o workspace de configuração.
Ler a vigilância também exige que a organização ativa da sessão seja a organização operadora, com qualquer papel menos developer. Fora dela, a leitura recebe 403, e recebe o mesmo 503 descrito acima quando o Power não resolve a organização operadora. Uma sessão sem organização ativa recebe 403 com active organization required, tanto na leitura quanto na declaração. Só a declaração exige, além disso, o papel owner ou admin.