ksug-stackql-demo

Talk and demo assets for KSUG.AI Australia #67, Melbourne, 2 Sep 2026.

synopsis

AI agents are starting to participate in platform engineering workflows - provisioning, de-provisioning, triage, reporting, drift detection, remediation. This session covers modeling infrastructure as a relational data source with StackQL, exposed to agents through a Model Context Protocol (MCP) server.

An agent can traverse the cloud control plane and the cluster in one session: from a GKE cluster and its node pools in Google Cloud, into the Kubernetes control plane (deployments, services, RBAC), down to running workloads - pod status, events, and logs - including joins across providers in a single query.

Includes a live demo: an agent triaging a workload issue across Google Cloud and a cluster, then performing a scoped remediation under an elevated access mode. Closes with the embedded MCP server - the same contract vendored into compiled applications (Go, Rust, Kotlin/JVM, .NET) for internal platform tooling.

setup

cp .env.example .env               # GOOGLE_CREDENTIALS, ANTHROPIC_API_KEY, stack variables
set -a; source .env; set +a        # the servers spawned below read credentials from the environment
stackql exec "REGISTRY PULL google"
stackql exec "REGISTRY PULL k8s"

Needs stackql, stackql-deploy, kubectl, python and psql on PATH.

No gcloud and no GKE auth plugin: the demo mints its own token from the service account key.

demo 1: stackql-deploy

Provisions the whole demo estate across two control planes from one manifest: the VPC, subnet and GKE cluster with the google provider, then the namespace, config map, deployments and service inside it with the k8s provider. Between the two groups a type: script resource mints a token, writes a kubeconfig and starts kubectl proxy, which is how the k8s provider reaches the API server.

# show every query that would run, resolve nothing
stackql-deploy build shop-platform demo --dry-run

# build both planes (about 8 minutes from nothing, 40 seconds when converged)
stackql-deploy build shop-platform demo --show-queries

# same manifest, bigger cluster: e2-standard-2, 2 nodes, 3 web replicas
stackql-deploy build shop-platform prd --dry-run

# tear down in reverse dependency order
stackql-deploy teardown shop-platform demo

Every run asserts against the live API: exists -> create, statecheck -> update, then exports. No state file, so a re-run also repairs whatever a human or an agent changed in between. See shop-platform/README.md for the resource map and the demo / prd switches.

demo 2: k8s provider

Demonstrates the k8s provider (v26.08) and the google provider against the estate demo 1 built:

• shell.iql - stackql shell: discovery, the cluster and its node pools, the cross-provider join, workloads, unhealthy pods, events, logs, RBAC
• exec.sh - stackql exec: output formats, queries from files, jsonnet variables, --dryrun
• srv.sh - stackql srv: the postgres wire protocol with psql and @stackql/pgwire-lite
• pystackql-app - the same queries in Python, results as pandas frames

The k8s provider needs kubectl proxy in front of the API server. Demo 1 starts one; for a demo tab you can watch, run it in the foreground:

./scripts/proxy.sh                 # second tab, leave it running
stackql shell                      # then paste from demo/k8s-provider/shell.iql

the API server is a column (cluster_addr), so a fleet of clusters is one table with a WHERE clause; and node pools from google join to nodes from k8s in a single statement.

demo 3: agentic use cases with stackql mcp

• claude-desktop-prompts.md - prompts for an interactive agent session over the StackQL MCP server, including the gated write (safe mode elicitation)
• python-agent - triage agent: Anthropic SDK + the StackQL MCP server, with a markdown policy of six controls across both planes and the three statements it may run to fix them

Break something first, then let the agent find it. Each drift scenario is one StackQL statement:

# drop DB_HOST from the config map and bounce the pod: CrashLoopBackOff
./scripts/drift.sh crash

# read_only: writes are refused whatever the model is told (about 50 s)
python demo/agentic-use-cases/python-agent/agent.py triage

# safe: the server asks a human before each write, answered at the terminal
python demo/agentic-use-cases/python-agent/agent.py remediate

# every tool call, mode, decision and statement; never result rows
tail -n 5 stackql-mcp-audit.jsonl

./scripts/drift.sh pending is the other scenario: checkout asks for 4 CPUs on a 2 vCPU node, and the agent has to compare the pod request with the node pool machine type to explain it. ./scripts/heal.sh undoes both with no model in the loop, and so does stackql-deploy build shop-platform demo.

FAQs

• "How is this different from the Terraform Kubernetes provider?" Same APIs, different model. Terraform holds desired state in HCL and actual state in a file; StackQL holds desired state in SQL and reads actual state from the API every run. No state file, no import, and the same SQL works for ad-hoc queries, CI and agents.
• "Does it replace kubectl?" No. It makes the same API queryable and joinable next to the cloud control plane, which is the part kubectl and gcloud cannot do together.
• "Is the agent writing to production?" Only through a server mode you chose. read_only by default; safe routes every write through an elicitation to a human; everything is logged as JSONL with the SQL and the decision.
• "What about secrets?" Credentials live in the server process environment; the model never sees them, including the cluster token. The demo talks to the API server through kubectl proxy, so the MCP server has no cluster credential at all.
• "Which clusters does the k8s provider work with?" Any conformant API server: GKE here, EKS, AKS, kind, k3s, OpenShift the same way. Point cluster_addr at it.

Links

• stackql
• k8s provider docs
• google provider docs
• stackql-deploy
• StackQL MCP