Diagnóstico do Customer Edge

Um Customer Edge (CE) é o nó do F5 Distributed Cloud que este repositório provisiona no Azure — terraform/modules/ce-node, criado a partir da imagem de marketplace volterraedgeservices/volterra-node.

Ele executa o plano de dados (Argo), o plano de controle (Vega), um proxy Envoy, uma pilha Kubernetes e o vpm, o agente que registra o nó e gerencia todo o resto nele.

Quando um CE apresenta problemas, a Site CLI é o instrumento. A primeira decisão é qual caminho de acesso se aplica, e errar isso desperdiça tempo de uma forma que parece um nó quebrado.

Quatro caminhos de acesso, e eles não são intercambiáveis

Debug APIFor a node that is ONLINE. Scriptable, read-only, and covers 34 commands.

Site ConsoleF5's own per-node troubleshooting UI, over an Azure Bastion tunnel. No SSH key, no jump host.

SSHThe full on-box Site CLI. Needs a key present from first boot and a host inside the VNet.

Serial consoleFor a node that never registered. The only route when the node has no network path.

A debug API alcança o nó através do plano de controle do F5 Distributed Cloud. Essa é toda a razão pela qual a distinção importa: a API só pode responder depois que o nó tenha se registrado e reporte ONLINE.

Um nó que falhou em se registrar — cloud-init incorreto, um token expirado, sem rota para register.ves.volterra.io — é exatamente o caso em que você precisa de diagnósticos, e exatamente o caso que a API não pode atender.

O Site Console é o primeiro a tentar quando você quer a própria UI de troubleshooting da F5 em vez de comandos específicos. Ele exige menos de você — sem chave, sem jump host, sem IP público no nó — porque quem pode se conectar passa a ser uma decisão de RBAC do Azure, e ele responde independentemente de o site ter se registrado ou não. Ele requer o Azure Bastion, que este deployment restringe atrás de enable_bastion e que não é implantado por padrão.

O SSH é o único caminho que alcança toda a superfície de comandos do appliance — a debug API expõe 34 comandos e o próprio nó oferece muitos mais. Duas coisas o restringem. O sshd responde apenas no endereço interno (SLI) do nó, portanto é necessário um host dentro da VNet; e a chave é escrita pelo cloud-init no primeiro boot, porque o campo ssh_key no objeto de site é inerte — o vpm ignora o usuário admin e nunca o aplica. Habilitá-lo em nós em execução, portanto, os substitui.

Então: se o site está ONLINE e 34 comandos são suficientes, use a debug API. Para uma UI, ou para um nó que nunca se registrou mas ainda tem um caminho de rede, use o Site Console. Se você precisa do restante da superfície de comandos e consegue alcançar a VNet, use SSH. Se o nó não tem nenhum caminho de rede funcional, o console serial é a única forma de entrar.

Uma única requisição informa em qual caminho você está:

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/config/namespaces/system/sites/<site>" \
  | jq -r '.spec.site_state'

ONLINE significa que a debug API funcionará. Qualquer outra coisa significa Site Console ou console serial.

Um site que não existe tem uma segunda explicação antes de “ele nunca se registrou”: você está apontando para o tenant errado. Este deployment vive em f5-sales-demo (https://<XC_TENANT>.console.ves.volterra.io), fixado por var.expected_xc_tenant — cd terraform && terraform output -raw xc_tenant informa isso sem tocar em nada. Uma credencial emitida para outro tenant retorna um 401 puro, que se parece com um token expirado.

Regras de segurança

Estas valem para todos os comandos em todas as páginas abaixo.

Somente leitura, a menos que você tenha certeza. A superfície de comandos é dividida em duas camadas de privilégio, e a camada Exec ou altera o nó ou lê um marcador de estado. Nada nestas páginas executa um comando Exec, e nem o harness de captura.
Nunca presuma que um comando é seguro pelo nome. ip-link-set parece uma consulta e derruba uma interface. systemctl-restart-crio reinicia o runtime de contêiner sob um plano de dados ativo.
Prefira o comando mais restrito que responda à pergunta. health e diagnosis resumem o nó com baixo custo; flow-l despeja todos os fluxos ativos, e flow-l-match responde à mesma pergunta sobre uma única conexão.
Um CE atende tráfego real. Estes são ambientes de demonstração compartilhados. Presuma que alguém está apresentando a partir do site que você está depurando.

O que está documentado aqui

Todos os comandos acessíveis pela debug API na build de software que este tenant executa, cada um com saída capturada de um nó real em vez de transcrita de outro lugar.

A referência de comandos lista todos eles com sua categoria, camada de privilégio e transporte; os workflows os encadeiam nas sequências que você realmente usa quando algo está errado.

As partes da Site CLI disponíveis apenas no equipamento — configure, configure-network, factory-reset, upgrade e cerca de sessenta comandos ExecCLI adicionais — não estão cobertas, porque sua saída não foi capturada de um nó real como ocorreu em todas as páginas abaixo.

Elas, no entanto, não estão mais fora de alcance. O scripts/sitecli_ssh_harvest.py conduz o próprio menu de autocompletar do appliance via SSH e registra a descrição que o appliance fornece para cada comando, de modo que a superfície possa ser medida em vez de adivinhada. Sua execução é negada por padrão — ele enumera tudo e executa apenas uma lista de permissões — porque sintaxe de comando não verificada, e efeitos de comando não verificados, são o defeito que esta documentação existe para evitar repetir.