콘텐츠로 이동
멀티클라우드 네트워킹

디버그 API

2026-07-28에 이 배포의 CE 한 대에서 캡처했습니다. sitecli/capture-manifest.json은 어느 노드였는지를 기록하며, scripts/capture-sitecli.sh --check는 실제 CE를 대상으로 명령 표면을 다시 검증합니다.

vpm/debug API는 등록된 노드에서 Site CLI 명령을 실행하고 그 출력을 반환합니다. 아래 내용은 모두 실제 노드를 대상으로 확인한 것이며, 어느 것도 업스트림에 공개되어 있지 않습니다.

명령 카탈로그는 자기 기술적입니다

섹션 제목: “명령 카탈로그는 자기 기술적입니다”

command 키를 생략한 채 exec-user에 POST하여 노드가 무엇을 지원하는지 문의하십시오:

Terminal window
curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>"}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user" \
  | jq -r .output | jq .

응답은 명령 이름을 키로 하는 JSON 객체입니다:

{
  "crictl-inspect": ["System Troubleshooting", "ExecUser", " container-id"],
  "diagnosis":      ["System Troubleshooting", "ExecUser", "no argument needed", "GLOBAL"],
  "ip-link-set":    ["Network Troubleshooting", "Exec", " (<device>||<group>) (up||down)"]
}

각 항목은 [category, tier, exampleArgument?, scope?]이며, 이 필드들은 문서가 아니라 해당 명령을 어떻게 호출해야 하는지를 결정합니다.

카탈로그 항목에 따라 선택되는 세 가지 전송 방식

섹션 제목: “카탈로그 항목에 따라 선택되는 세 가지 전송 방식”
조건메서드와 경로본문반환값
scope가 GLOBALGET .../vpm/debug/global/<cmd>없음JSON
tier가 ExecUserPOST .../vpm/debug/<node>/exec-usercommand 배열텍스트
tier가 ExecPOST .../vpm/debug/<node>/execcommand 배열텍스트

ExecUser — 읽기 전용 계층 31 commands

섹션 제목: “ExecUser — 읽기 전용 계층 ”

일반적인 경우입니다. 명령과 그 인수를 배열로, 명령 이름을 먼저 두어 전달하십시오:

Terminal window
curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>","command":["crictl-ps"]}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user"
{ "return_code": 0, "output": "CONTAINER    IMAGE    CREATED    STATE ..." }

인수는 하나의 문자열이 아니라 개별 배열 요소입니다:

{ "command": ["journalctl", "-u", "vpm", "-n", "200"] }

GLOBAL — 사이트 전체 범위이며, 전송 방식이 완전히 다릅니다 2 commands

섹션 제목: “GLOBAL — 사이트 전체 범위이며, 전송 방식이 완전히 다릅니다 ”

health와 diagnosis가 유일한 두 가지입니다. 이들은 global 경로에 대한 GET 요청이며, 인수를 받지 않고, 터미널 텍스트가 아닌 구조화된 JSON을 반환합니다.

Terminal window
curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/health" | jq .

Exec — 권한이 필요한 계층 1 command on this build

섹션 제목: “Exec — 권한이 필요한 계층 ”

별도의 엔드포인트이며, 계층은 권고가 아니라 강제됩니다: exec는 ExecUser 명령을 동일한 command not supported 메시지로 거부합니다. 모든 구성원은 노드를 변경하거나 상태 마커를 읽습니다.

이 테넌트가 실행하는 빌드에서 이 계층에는 ip-link-set만 포함되어 있습니다. 더 최신 빌드에서는 systemctl-restart-NetworkManager, systemctl-restart-crio, systemctl-restart-kubelet, systemctl-start-crio-prune 및 세 개의 marker-exists-* 명령이 추가됩니다.

사이트와 노드 이름 찾기

섹션 제목: “사이트와 노드 이름 찾기”

노드 이름은 Azure VM 이름이며, list-service는 해당 노드에서 실행 중인 서비스와 함께 이를 확인하는 간단한 방법입니다:

Terminal window
curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/list-service" \
  | jq -r '[.service[].node] | unique'
["", "f5-xc-ce-vm-01"]

일부 서비스는 빈 노드 이름을 보고하므로, 이 목록의 빈 문자열은 두 번째 노드가 아니라 응답의 부산물입니다. list-service는 34개 명령 카탈로그에도 포함되어 있지 않습니다: 이는 카탈로그가 광고하지 않는 global 엔드포인트이며, 그래서 명령 참조가 아니라 여기에 문서화되어 있습니다.

이 리포지토리의 캡처 재현하기

섹션 제목: “이 리포지토리의 캡처 재현하기”

모든 명령 페이지에는 위의 세 가지 규칙을 모두 구현한 scripts/capture-sitecli.sh가 캡처한 출력이 포함되어 있습니다.

  1. 테넌트를 지정하십시오. 이 스크립트는 XCSH_API_URL과 XCSH_API_TOKEN을 읽거나, 활성 xcsh 컨텍스트로 대체합니다.

  2. 카탈로그를 새로 고치고 문서 아래의 노드가 변경되지 않았는지 확인하십시오:

    Terminal window
    bash scripts/capture-sitecli.sh --check

    이는 커밋된 카탈로그와 소프트웨어 빌드만 비교합니다. 빌드 변경은 추가되거나 제거된 명령과 별도로 보고합니다.

  3. 새로운 증거가 필요할 때 다시 캡처하십시오:

    Terminal window
    bash scripts/capture-sitecli.sh