API de depuración

Capturado el 2026-07-28 desde un CE de esta implementación. sitecli/capture-manifest.json registra qué nodo, y scripts/capture-sitecli.sh --check vuelve a verificar la superficie de comandos contra un CE en vivo.

La API vpm/debug ejecuta comandos de Site CLI en un nodo registrado y devuelve su salida. Todo lo que aparece a continuación se estableció contra un nodo en vivo; nada de ello está publicado en el origen.

El catálogo de comandos es autodescriptivo

Pregunte al nodo qué admite haciendo un POST a exec-user con la clave command omitida:

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 .

La respuesta es un objeto JSON indexado por nombre de comando:

{
  "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)"]
}

Cada entrada es [category, tier, exampleArgument?, scope?], y esos campos no son documentación: determinan cómo debe invocarse el comando.

Omita la clave; no envíe un valor incorrecto

El descubrimiento funciona dejando fuera command. Enviar en su lugar un valor desconocido devuelve un error, no el catálogo:

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

Ese mensaje es también lo que se obtiene para un comando real enviado al endpoint incorrecto, por lo que es fácil malinterpretarlo como «este comando no existe».

Tres transportes, elegidos por la entrada del catálogo

Condición	Método y ruta	Cuerpo	Devuelve
scope es GLOBAL	GET .../vpm/debug/global/<cmd>	ninguno	JSON
tier es ExecUser	POST .../vpm/debug/<node>/exec-user	array command	texto
tier es Exec	POST .../vpm/debug/<node>/exec	array command	texto

ExecUser — el nivel de solo lectura 31 comandos

El caso habitual. Pase el comando y sus argumentos como un array, con el nombre del comando primero:

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 ..." }

Los argumentos son elementos separados del array, no una única cadena:

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

GLOBAL — de ámbito global del sitio, y con un transporte completamente distinto 2 comandos

health y diagnosis son los dos únicos. Son solicitudes GET a una ruta global, no toman argumentos y devuelven JSON estructurado en lugar de texto de terminal.

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

Un comando GLOBAL no es accesible a través de exec-user

Esta es la trampa que cuesta más tiempo. Enviar health o diagnosis a exec-user devuelve command not supported, lo que se lee como si el comando no existiera en el nodo, cuando de hecho existe y usted usó el transporte incorrecto.

# 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 — el nivel privilegiado 1 comando en esta compilación

Un endpoint separado, y el nivel se aplica de forma estricta en lugar de ser orientativo: exec rechaza un comando ExecUser con el mismo mensaje command not supported. Cada miembro o modifica el nodo o lee un marcador de estado.

En la compilación que ejecuta este tenant, el nivel contiene únicamente ip-link-set. Las compilaciones más recientes añaden systemctl-restart-NetworkManager, systemctl-restart-crio, systemctl-restart-kubelet, systemctl-start-crio-prune y tres comandos marker-exists-*.

Nada de lo aquí descrito ejecuta un comando Exec

El arnés de captura rechaza este nivel y lee el nivel del catálogo en vivo en lugar de una lista fija, de modo que una compilación futura que promueva un comando a Exec se respeta sin que nadie tenga que editar código. Ejecute uno solo de forma deliberada, en un nodo que esté dispuesto a interrumpir.

Encontrar los nombres del sitio y del nodo

El nombre del nodo es el nombre de la VM de Azure, y list-service es una forma económica de confirmarlo junto con los servicios que se ejecutan en él:

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"]

Algunos servicios informan un nombre de nodo vacío, por lo que una cadena vacía en esa lista es un artefacto de la respuesta y no un segundo nodo. list-service tampoco está en el catálogo de 34 comandos: es un endpoint global que el catálogo no anuncia, razón por la cual se documenta aquí y no en la referencia de comandos.

Reproducir las capturas de este repositorio

Cada página de comando incrusta la salida capturada por scripts/capture-sitecli.sh, que implementa las tres reglas anteriores.

1. Apúntelo a un tenant. Lee XCSH_API_URL y XCSH_API_TOKEN, o recurre al contexto activo de xcsh.

2. Actualice el catálogo y confirme que el nodo no ha cambiado por debajo de la documentación:

   bash scripts/capture-sitecli.sh --check

   Esto compara únicamente el catálogo confirmado y la compilación de software. Informa de un cambio de compilación por separado de los comandos añadidos o eliminados.

3. Vuelva a capturar cuando quiera evidencia reciente:

   bash scripts/capture-sitecli.sh

Las capturas son evidencia, no artefactos reproducibles

Los contadores, los tiempos de actividad y las antigüedades de los contenedores cambian entre ejecuciones, por lo que volver a capturar siempre produce una diferencia. El catálogo es el contrato estable y es idéntico byte a byte entre ejecuciones cuando el nodo no ha cambiado; eso es lo que compara --check. La salida extensa se recorta y termina con un marcador explícito, de modo que una tabla truncada nunca se muestra como si estuviera completa.

Capturar desde un nodo de cliente: revise el perfil de redacción

La salida de los comandos contiene la identidad de la infraestructura —direccionamiento interno, direcciones MAC, números de AS, nombres de host— y, para un cliente, eso es información identificativa sobre la organización.

Por ello, el filtro de depuración usa por defecto un perfil strict que elimina todo eso. Este repositorio declara lab en sitecli/capture-manifest.json, lo que conserva ese detalle, y solo es correcto aquí porque estas capturas proceden de infraestructura de demostración propiedad de F5.

No traslade esa configuración a una captura de cliente. Los tokens, las claves privadas, el identificador del tenant, los UUID de objetos, las direcciones de correo electrónico y las rutas del directorio de inicio se eliminan con ambos perfiles.

Conviene conocer una limitación: una tabla de vecinos BGP imprime el AS como una columna sin etiqueta en la que anclar un patrón, por lo que los ASN se comparan por valor contra los rangos privados. Un ASN público ahí sobrevive al perfil strict y requiere una revisión manual de la salida de show-ip-bgp* antes de publicarla.