Debug API

เก็บข้อมูลเมื่อ 2026-07-28 จาก CE หนึ่งเครื่องของการติดตั้งนี้ โดย sitecli/capture-manifest.json บันทึกว่าเป็นโหนดใด และ scripts/capture-sitecli.sh --check จะตรวจสอบพื้นผิวคำสั่ง เทียบกับ CE ที่ทำงานอยู่จริงอีกครั้ง

API vpm/debug เรียกใช้คำสั่ง Site CLI บนโหนดที่ลงทะเบียนไว้และคืนค่าผลลัพธ์ ของคำสั่งนั้น ทุกสิ่งที่อยู่ด้านล่างนี้ได้รับการยืนยันกับโหนดที่ทำงานอยู่จริง และไม่มีส่วนใด ที่เผยแพร่ไว้ในเอกสารต้นทาง

แคตตาล็อกคำสั่งอธิบายตัวเองได้

สอบถามโหนดว่ารองรับคำสั่งอะไรบ้าง โดยส่ง POST ไปที่ exec-user และ ละ คีย์ command ไว้:

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?] และฟิลด์เหล่านั้น ไม่ใช่เพียงเอกสารประกอบ — มันกำหนดว่าคำสั่งนั้นต้องถูกเรียกอย่างไร

Discovery ทำงานได้โดยการไม่ใส่ command หากส่งค่าที่ไม่รู้จักเข้าไปแทน จะได้รับ ข้อผิดพลาด ไม่ใช่แคตตาล็อก:

{"code":3,"details":[],"message":"exec command failed: command not supported"}

ข้อความนั้นก็เป็นสิ่งเดียวกับที่คุณจะได้รับเมื่อส่งคำสั่ง จริง ไปยัง endpoint ที่ผิด จึงเข้าใจผิดได้ง่ายว่า “คำสั่งนี้ไม่มีอยู่”

Transport สามแบบ เลือกตามรายการในแคตตาล็อก

เงื่อนไข	เมธอดและพาธ	Body	คืนค่า
`scope` เป็น `GLOBAL`	`GET .../vpm/debug/global/<cmd>`	ไม่มี	JSON
`tier` เป็น `ExecUser`	`POST .../vpm/debug/<node>/exec-user`	อาร์เรย์ `command`	ข้อความ
`tier` เป็น `Exec`	`POST .../vpm/debug/<node>/exec`	อาร์เรย์ `command`	ข้อความ

`ExecUser` — ระดับอ่านเท่านั้น 31 commands

กรณีที่พบทั่วไป ส่งคำสั่งและอาร์กิวเมนต์ของคำสั่งเป็นอาร์เรย์ โดยให้ชื่อคำสั่ง อยู่ลำดับแรก:

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` — ครอบคลุมทั้งไซต์ และใช้ transport ที่แตกต่างไปโดยสิ้นเชิง 2 commands

มีเพียง health และ diagnosis สองคำสั่งเท่านั้น ทั้งคู่เป็นคำขอ GET ไปยังพาธ global ไม่รับอาร์กิวเมนต์ และคืนค่าเป็น JSON ที่มีโครงสร้างแทนที่จะเป็นข้อความแบบเทอร์มินัล

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

นี่คือกับดักที่ทำให้เสียเวลามากที่สุด การส่ง health หรือ diagnosis ไปที่ exec-user จะคืนค่า command not supported ซึ่งอ่านดูเหมือนว่าคำสั่งนั้น ไม่มีอยู่บนโหนด — แต่ความจริงคือมันมีอยู่ และคุณใช้ transport ผิด

# Wrong. Returns: exec command failed: command not supported
-d '{"namespace":"system","site":"…","node":"…","command":["health"]}'   # POST exec-user

# Right.
GET .../vpm/debug/global/health

`Exec` — ระดับที่มีสิทธิ์พิเศษ 1 command on this build

เป็น endpoint แยกต่างหาก และระดับนี้ถูกบังคับใช้จริงไม่ใช่เพียงคำแนะนำ: exec จะปฏิเสธ คำสั่งระดับ ExecUser ด้วยข้อความ command not supported เดียวกัน สมาชิกทุกตัว ในระดับนี้ล้วนเปลี่ยนแปลงสถานะของโหนดหรืออ่านค่าตัวบ่งชี้สถานะ

บนบิลด์ที่เทนแนนต์นี้ใช้งาน ระดับนี้มีเพียง ip-link-set เท่านั้น บิลด์ที่ใหม่กว่า เพิ่ม systemctl-restart-NetworkManager, systemctl-restart-crio, systemctl-restart-kubelet, systemctl-start-crio-prune และคำสั่ง marker-exists-* อีกสามคำสั่ง

ชุดเครื่องมือเก็บข้อมูลปฏิเสธระดับนี้ และอ่านค่า tier จากแคตตาล็อกที่ทำงานอยู่จริง แทนที่จะใช้รายการที่ฮาร์ดโค้ดไว้ — ดังนั้นบิลด์ในอนาคตที่เลื่อนคำสั่งขึ้นเป็น Exec จะได้รับการเคารพโดยไม่ต้องมีใครแก้ไขโค้ด ให้เรียกใช้คำสั่งเหล่านี้อย่างตั้งใจเท่านั้น บนโหนดที่คุณยอมรับได้ว่าจะถูกรบกวน

การค้นหาชื่อไซต์และชื่อโหนด

ชื่อโหนดคือชื่อ Azure VM และ list-service เป็นวิธีที่ประหยัดในการยืนยันชื่อนั้น พร้อมกับบริการที่กำลังทำงานอยู่บนโหนด:

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 คำสั่ง: มันเป็น endpoint แบบ global ที่แคตตาล็อกไม่ประกาศไว้ ซึ่งเป็นเหตุผลที่มันถูกบันทึกไว้ที่นี่ ไม่ใช่ในเอกสารอ้างอิงคำสั่ง

การทำซ้ำการเก็บข้อมูลของ repository นี้

ทุกหน้าคำสั่งฝังผลลัพธ์ที่เก็บได้จาก scripts/capture-sitecli.sh ซึ่ง นำกฎทั้งสามข้อด้านบนไปใช้งาน

ชี้ให้สคริปต์ทำงานกับเทนแนนต์ สคริปต์จะอ่าน XCSH_API_URL และ XCSH_API_TOKEN หรือย้อนไปใช้คอนเท็กซ์ xcsh ที่เปิดใช้งานอยู่
รีเฟรชแคตตาล็อกและยืนยันว่าโหนดไม่ได้เปลี่ยนแปลงไปจากที่เอกสารระบุไว้:
Terminal window
```
bash scripts/capture-sitecli.sh --check
```
คำสั่งนี้เปรียบเทียบเฉพาะแคตตาล็อกที่คอมมิตไว้และบิลด์ซอฟต์แวร์เท่านั้น และจะ รายงานการเปลี่ยนแปลงของบิลด์แยกจากคำสั่งที่ถูกเพิ่มหรือถูกลบ
เก็บข้อมูลใหม่เมื่อคุณต้องการหลักฐานที่สดใหม่:
Terminal window
```
bash scripts/capture-sitecli.sh
```

ตัวนับ ระยะเวลาทำงาน และอายุของคอนเทนเนอร์เปลี่ยนแปลงไปในแต่ละรอบการทำงาน ดังนั้น การเก็บข้อมูลใหม่จะทำให้เกิด diff อยู่เสมอ แคตตาล็อกคือสัญญาที่เสถียรและเหมือนกันทุกไบต์ ในทุกรอบการทำงานเมื่อโหนดไม่ได้เปลี่ยนแปลง นั่นคือสิ่งที่ --check เปรียบเทียบ ผลลัพธ์ที่ยาว จะถูกตัดทอนและลงท้ายด้วยเครื่องหมายที่ระบุชัดเจน ดังนั้นตารางที่ถูกตัดทอนจะไม่ถูกแสดง เสมือนว่าสมบูรณ์

ผลลัพธ์ของคำสั่งพาข้อมูลอัตลักษณ์ของโครงสร้างพื้นฐานมาด้วย — การกำหนดที่อยู่ภายใน ที่อยู่ MAC หมายเลข AS ชื่อโฮสต์ — และสำหรับลูกค้า สิ่งเหล่านั้นคือข้อมูลที่ระบุตัวตน ขององค์กรได้

ดังนั้นตัวกรองล้างข้อมูลจึงตั้งค่าเริ่มต้นเป็นโปรไฟล์แบบ strict ที่ลบข้อมูลเหล่านั้นทั้งหมด Repository นี้ประกาศ lab ไว้ใน sitecli/capture-manifest.json ซึ่งเก็บรายละเอียด เหล่านั้นไว้ และมันถูกต้องเฉพาะที่นี่เท่านั้น เพราะข้อมูลที่เก็บมานี้มาจากโครงสร้างพื้นฐาน สาธิตที่ F5 เป็นเจ้าของ

อย่านำการตั้งค่านั้นไปใช้กับการเก็บข้อมูลของลูกค้า โทเค็น คีย์ส่วนตัว ตัวระบุเทนแนนต์ UUID ของอ็อบเจ็กต์ ที่อยู่อีเมล และพาธไดเรกทอรีบ้านจะถูกลบออกภายใต้ทั้งสองโปรไฟล์

มีข้อจำกัดหนึ่งที่ควรทราบ: ตารางเพื่อนบ้าน BGP พิมพ์ค่า AS เป็นคอลัมน์เปล่าโดยไม่มีป้ายกำกับ ให้ใช้ยึดเป็นแพตเทิร์นได้ ดังนั้น ASN จึงถูกจับคู่ตามค่าเทียบกับช่วงส่วนบุคคล ASN แบบ สาธารณะ ในตำแหน่งนั้นจะรอดพ้นจากโปรไฟล์ strict และจำเป็นต้องมีการตรวจทานผลลัพธ์ show-ip-bgp* ด้วยตนเองก่อนที่คุณจะเผยแพร่