Query API Reference

8.5 Kubernetes Observability Enterprise

MeshOptixIQ can collect live node and pod data from any Kubernetes cluster and expose it through the same REST API used for network queries. Collection requires the k8s_observability feature flag (Enterprise tier); the status endpoint is open to all authenticated clients.

Installation

Install the optional Kubernetes SDK for full collection capability (recommended):

pip install kubernetes

If the SDK is not installed, MeshOptixIQ falls back to a built-in urllib-based collector that works inside a Kubernetes pod without any additional packages.

Configuration

Authentication modes

volumes:
  - ~/.kube/config:/etc/meshq/kubeconfig:ro
environment:
  K8S_KUBECONFIG: /etc/meshq/kubeconfig

kubectl create secret generic meshq-kubeconfig \
  --from-file=config=$HOME/.kube/config

# In your Pod spec:
volumes:
  - name: kubeconfig
    secret:
      secretName: meshq-kubeconfig
volumeMounts:
  - name: kubeconfig
    mountPath: /etc/meshq
    readOnly: true

Required RBAC (ServiceAccount)

Create a ClusterRole that grants read access to nodes and pods, then bind it to the ServiceAccount MeshOptixIQ runs under:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: meshoptixiq-observer
rules:
  - apiGroups: [""]
    resources: ["nodes", "pods", "endpoints", "services"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: meshoptixiq-observer
subjects:
  - kind: ServiceAccount
    name: meshoptixiq          # match your Pod's serviceAccountName
    namespace: monitoring
roleRef:
  kind: ClusterRole
  name: meshoptixiq-observer
  apiGroup: rbac.authorization.k8s.io

REST endpoints

Triggering collection

Call POST /k8s/collect to pull a fresh snapshot from Kubernetes into the store:

curl -s -X POST http://localhost:8000/k8s/collect \
  -H "X-API-Key: $API_KEY" | jq .
# {
#   "status": "ok",
#   "node_count": 12,
#   "pod_count": 148
# }

Querying the data

# All nodes
curl -s http://localhost:8000/k8s/nodes \
  -H "X-API-Key: $API_KEY" | jq '.nodes[] | {node_name, cpu_capacity, memory_gb, gpu_count, ready}'

# Pods in a namespace
curl -s "http://localhost:8000/k8s/pods?namespace=gpu-jobs" \
  -H "X-API-Key: $API_KEY" | jq '.pods[] | {pod_name, phase, gpu_request, restart_count}'

# Pods on a specific node
curl -s http://localhost:8000/k8s/node/gpu-node-01/pods \
  -H "X-API-Key: $API_KEY" | jq .

# Quick status — no Enterprise gate
curl -s http://localhost:8000/k8s/status \
  -H "X-API-Key: $API_KEY"
# {"node_count": 12, "pod_count": 148, "gpu_node_count": 4, "total_gpus": 32}

Response schemas

Node object

Pod object