Um site que nunca entrou em operação

Capturado em 28/07/2026 de um CE deste deployment. sitecli/capture-manifest.json registra qual nó, e scripts/capture-sitecli.sh --check reverifica a superfície de comandos em um CE ativo.

A API não pode depurar isto

A API de depuração alcança o nó através do control plane do F5 Distributed Cloud, pelo túnel que o registro estabelece. Se o registro falhou, não existe túnel, portanto todos os comandos deste site ficam indisponíveis exatamente para essa falha. Trabalhe a partir do Site Console se o nó ainda tiver um caminho de rede, e a partir do console serial se não tiver.

1. Confirme que você está consultando o tenant correto. Isso custa um comando e vem primeiro porque errar aqui faz com que todos os passos seguintes mintam para você: uma frota saudável no tenant que você não está olhando é indistinguível de uma frota que nunca registrou.

   cd terraform
   terraform output -raw xc_tenant       # the tenant this deployment belongs to
   terraform output -raw xc_env_tenant   # the tenant your shell is exporting

   f5-sales-demo
   f5-sales-demo

   Divergentes, ou uma credencial que você acredita ser válida retornando um simples 401? Esse é o sintoma de um token emitido para outro tenant, e isso já custou a este deployment um rebuild completo (issue 696).

2. Confirme o que o tenant acredita. Estar ausente da lista de sites é um problema diferente de estar presente mas não ONLINE.

   curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
     "$XCSH_API_URL/api/config/namespaces/system/sites" | jq -r '.items[].name'

   Se o site existe e reporta ONLINE, o registro foi bem-sucedido e você está no fluxo de trabalho errado.

3. Encontre o registro do site e o seu estado. Um nó pode registrar e depois aguardar aprovação, o que parece idêntico a uma falha visto de fora.

   curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
     "$XCSH_API_URL/api/register/namespaces/system/registrations_by_site/<site>" \
     | jq -r '.items[] | "\(.name)  \(.object.status.current_state)  \(.object.spec.gc_spec.infra.hostname)"'

   r-a97e20c8-b7e1-483d-bd76-34a64ff8bc78  ONLINE  f5-xc-ce-vm-01

   Nenhum item significa que o nó ainda não registrou — vá para o console serial. Um item em um estado diferente de ONLINE significa que ele registrou e algo depois disso falhou, o que é uma investigação diferente.

   Para varrer todo o namespace em busca de qualquer coisa aguardando aprovação, listregistrationsbystate recebe o estado como um corpo POST:

   curl -sS -X POST -H "Authorization: APIToken $XCSH_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"namespace":"system","state":"PENDING"}' \
     "$XCSH_API_URL/api/register/namespaces/system/listregistrationsbystate" | jq -r '.items[].name'

   Em uma frota saudável isso não retorna nada, porque a aprovação é automatizada.

4. Confirme que a VM está realmente em execução, antes de assumir uma falha de software.

   az vm list -d -g <resource-group> --query "[].{name:name,power:powerState}" -o table

   Name              Power
   ----------------  ----------
   f5-xc-ce-vm-01    VM running
   f5-xc-ce-vm-02    VM running
   f5-xc-ce-vm-03    VM running
   mcn-ce-ha-client  VM running

5. Conecte-se ao console serial. De forma interativa isso exige um terminal real; a própria conexão pode ser automatizada via websocket — consulte console serial.

   az serial-console connect -g <resource-group> -n <vm-name>

   Se houver recusa, verifique se o boot diagnostics está habilitado na VM antes de concluir que o nó está inacessível; esse pré-requisito e seus modos de falha são abordados na página console serial.

6. Leia o que o console mostra, nesta ordem. cloud-init primeiro — um nó cujo cloud-init nunca foi concluído não tem configuração com a qual registrar. Depois as próprias tentativas de registro, então o DNS: se o nó não conseguir resolver register.ves.volterra.io, nada a jusante pode funcionar.

7. Assim que o nó estiver ONLINE, verifique com health e espere state: PROVISIONED.

Um registro é nomeado por um UUID, nunca pelo seu site

Os registros são nomeados r-<uuid>, e não existe endpoint que aceite um nome de site onde um nome de registro é esperado. GET .../registrations/<site> retorna 404, o que se lê como “este site não tem registro” e na verdade significa “esse não é um nome de registro”. O mapeamento de site para registro vem apenas de registrations_by_site/<site>, como no passo 3, ou listando registrations e correspondendo por gc_spec.passport.cluster_name.

A mesma armadilha fez parecer que uma frota saudável tinha zero registros.

As causas habituais

• Você está apontando para o tenant errado, então uma frota que está bem parece ausente. Passo 1.
• O cloud-init não foi concluído, então /etc/vpm/config.yaml está ausente ou incorreto.
• O token de registro está expirado, já consumido, ou é de outro tenant.
• Nenhuma rota de saída para register.ves.volterra.io.
• Desvio de relógio grande o suficiente para invalidar certificados — rápido de descartar depois com chronyc-sources, mas inacessível até que o nó esteja online. O banner de login do SSH reporta NTP: Synced e o status do resolver antes de você executar qualquer coisa, quando o SSH está disponível.