온라인 상태가 된 적 없는 사이트

이 배포의 CE 한 대에서 2026-07-28에 캡처했습니다. sitecli/capture-manifest.json에 어떤 노드인지 기록되어 있으며, scripts/capture-sitecli.sh --check는 실제 동작 중인 CE에 대해 명령 표면을 다시 검증합니다.

API로는 이 문제를 디버그할 수 없습니다

디버그 API는 등록 과정에서 수립된 터널을 통해 F5 Distributed Cloud 컨트롤 플레인을 거쳐 노드에 도달합니다. 등록이 실패했다면 터널이 없으므로, 바로 이 실패 상황에서는 이 사이트의 모든 명령을 사용할 수 없습니다. 노드에 아직 네트워크 경로가 남아 있다면 Site Console에서, 그렇지 않다면 시리얼 콘솔에서 작업하십시오.

1. 올바른 테넌트에 질의하고 있는지 확인하십시오. 명령 하나면 되고, 이것이 첫 단계인 이유는 여기서 틀리면 이후의 모든 단계가 거짓을 말하기 때문입니다. 지금 보고 있지 않은 테넌트의 정상적인 플릿은 등록된 적이 없는 플릿과 구별할 수 없습니다.

   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

   값이 일치하지 않거나, 정상이라고 믿는 자격 증명이 그냥 401을 반환합니까? 그것은 다른 테넌트용으로 발급된 토큰의 증상이며, 이 배포에서 이미 전체 재구축 한 번의 비용을 치르게 했습니다 (issue 696).

2. 테넌트가 무엇을 알고 있는지 확인하십시오. 사이트 목록에 없는 것과, 존재하지만 ONLINE이 아닌 것은 서로 다른 문제입니다.

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

   사이트가 존재하고 ONLINE으로 보고된다면 등록은 성공한 것이며, 잘못된 워크플로에 들어와 있는 것입니다.

3. 사이트의 등록과 그 상태를 찾으십시오. 노드는 등록한 뒤 승인을 기다릴 수 있는데, 외부에서 보면 실패와 완전히 똑같아 보입니다.

   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

   항목이 전혀 없다면 노드가 아직 등록하지 않은 것입니다 — 시리얼 콘솔로 가십시오. ONLINE 이외의 상태인 항목이 있다면 등록은 되었고 그 이후에 무언가가 실패한 것이며, 이는 별개의 조사 대상입니다.

   승인을 기다리는 항목이 있는지 네임스페이스 전체를 훑어보려면, listregistrationsbystate는 상태를 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'

   정상적인 플릿에서는 승인이 자동화되어 있으므로 아무것도 반환하지 않습니다.

4. 소프트웨어 결함을 가정하기 전에 VM이 실제로 실행 중인지 확인하십시오.

   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. 시리얼 콘솔에 접속하십시오. 대화형으로 사용하려면 실제 터미널이 필요합니다. 접속 자체는 대신 웹소켓을 통해 스크립트로 처리할 수 있습니다 — 시리얼 콘솔을 참조하십시오.

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

   거부된다면, 노드에 도달할 수 없다고 결론짓기 전에 VM에서 부팅 진단이 활성화되어 있는지 확인하십시오. 해당 전제 조건과 그 실패 양상은 시리얼 콘솔 페이지에서 다룹니다.

6. 콘솔에 표시되는 내용을 다음 순서로 읽으십시오. cloud-init이 먼저입니다 — cloud-init이 완료되지 않은 노드는 등록에 사용할 구성 자체가 없습니다. 그다음 등록 시도 자체, 그다음 DNS입니다. 노드가 register.ves.volterra.io를 해석하지 못하면 그 이후의 어떤 것도 동작할 수 없습니다.

7. 노드가 ONLINE이 되면, health로 확인하고 state: PROVISIONED를 기대하십시오.

등록의 이름은 UUID를 따르며, 사이트 이름을 따르지 않습니다

등록의 이름은 r-<uuid> 형식이며, 등록 이름이 필요한 자리에 사이트 이름을 받는 엔드포인트는 없습니다. GET .../registrations/<site>는 404를 반환하는데, 이는 “이 사이트에는 등록이 없다”처럼 읽히지만 실제로는 “그것은 등록 이름이 아니다”라는 의미입니다. 사이트-등록 매핑은 3단계에서처럼 registrations_by_site/<site>를 통해서만 얻을 수 있으며, 또는 registrations를 나열한 뒤 gc_spec.passport.cluster_name으로 대조해서 얻을 수 있습니다.

바로 이 함정 때문에 정상적인 플릿에 등록이 하나도 없는 것처럼 보였습니다.

흔한 원인

• 잘못된 테넌트를 가리키고 있어서, 정상인 플릿이 없는 것처럼 보입니다. 1단계.
• cloud-init이 완료되지 않아 /etc/vpm/config.yaml이 없거나 잘못되었습니다.
• 등록 토큰이 만료되었거나, 이미 사용되었거나, 다른 테넌트의 것입니다.
• register.ves.volterra.io로 나가는 이그레스 경로가 없습니다.
• 인증서를 무효화할 만큼 큰 시간 편차 — 나중에 chronyc-sources로 빠르게 배제할 수 있지만, 노드가 온라인이 되기 전에는 접근할 수 없습니다. SSH를 사용할 수 있는 경우, SSH 로그인 배너가 무엇을 실행하기도 전에 NTP: Synced와 리졸버의 상태를 보고합니다.