Skip to main content

Operators and Sub-agents

How k8s-autopilot breaks down your requests into specialized teams of operators

When you ask k8s-autopilot something, it doesn't try to do everything inside a single monolithic model. Instead, it works like a coordinated team — a central coordinator (the Supervisor) listens to your request, determines which operational domain it belongs to, and hands it off to the right Operator. Each operator is a domain specialist: it knows its tools, its safety rules, and the exact procedures needed to get the job done safely.

Think of it like a hospital. You walk into the emergency room and describe your symptoms at triage (the Supervisor). They don't attempt to treat you immediately — they direct you to the right specialized department: cardiology, radiology, or surgery. Each department has its own dedicated doctors, specialized equipment, and clinical procedures.

How It Works​

You (chat) ──► Supervisor ──► Operator ──► MCP Server(s) ──► Kubernetes / External Systems
  1. You type a request in the chat interface.
  2. The Supervisor reads your request and decides which operator should handle it.
  3. The Operator loads the appropriate skill playbook, connects to its MCP server(s), and executes the task.
  4. The MCP Server interacts with the actual external system (your Kubernetes cluster, Helm, ArgoCD, Prometheus, etc.) and performs the live work.

For anything that modifies your system (installing software, scaling pods, configuring routes), every operator follows the same five-step safety pattern:

Discover ──► Plan ──► Confirm ──► Execute ──► Verify

Nothing gets changed without showing you a detailed plan first and asking for your explicit approval.

The Four Built-in Operators​

k8s-autopilot ships with four built-in operators. Each one is a self-contained agent with its own MCP server connections, skills, and domain safety guardrails.

🎡 Helm Operator​

What it does: Manages the full lifecycle of Helm charts on your Kubernetes cluster — discovering charts, installing them, upgrading releases, rolling back to previous versions, and removing releases. It can also generate new charts and commit them to Git.

When the Supervisor routes to it: When you mention anything about Helm charts, releases, installing software from a chart repository, upgrading a deployed release, or rolling back a failed deployment.

MCP Server: helm-mcp-server — provides 22 tools covering both Helm operations and basic Kubernetes awareness.

Skills:

SkillWhat It Handles
helm-operationInstall, upgrade, rollback, uninstall, search charts, validate values, dry-run, and plan generation

What you can ask it to do:

  • "Search for MySQL charts on Bitnami"
  • "Install nginx from bitnami in the web namespace"
  • "Upgrade the API release to version 3.0"
  • "Rollback the web release to the previous version"
  • "Show me all Helm releases in staging"
  • "What values does the Redis chart support?"
  • "Uninstall the test-app release from dev"

Safety rules:

  • Always executes a dry-run before new installations.
  • Checks if a release already exists before installing (auto-switches to upgrade if needed).
  • Preserves existing configuration on upgrades (--reuse-values by default).
  • Validates chart values against the schema before applying.
  • Uses real revision numbers from release history for rollbacks — never guesses.

What it won't do: Anything outside Helm. If you ask it to sync an ArgoCD app or configure Traefik middleware, it politely declines and refers you to the appropriate operator.

📦 App Operator​

What it does: Manages application delivery across three integrated systems — ArgoCD for GitOps deployments, Argo Rollouts for progressive delivery (canary, blue-green), and Traefik for edge traffic routing.

When the Supervisor routes to it: When you mention deploying applications, syncing GitOps repos, running canary deployments, splitting traffic, configuring middleware, or anything related to ArgoCD, Argo Rollouts, or Traefik.

MCP Servers:

ServerWhat It Connects To
argocd-mcp-serverArgoCD — application lifecycle, sync, rollback, project management
argo-rollout-mcp-serverArgo Rollouts — canary, blue-green, promote, abort, analysis
traefik-mcp-serverTraefik — IngressRoutes, traffic splitting, middleware, TLS, mirroring

Skills:

SkillWhat It Handles
argocd-gitopsApplication onboarding, sync, rollback, health monitoring, multi-environment promotion
argo-rollout-gitopsDeployment-to-Rollout migration, canary/blue-green rollouts, AnalysisTemplates, promotion control
traefik-edge-routingIngressRoute management, weighted traffic splitting, middleware, TLS, NGINX migration

What you can ask it to do:

  • "Onboard my app to ArgoCD" — sets up the project, repository, and application in one go
  • "Sync the frontend application"
  • "Promote the canary to 50%" — advances a progressive rollout
  • "Set up a blue-green deployment for the checkout service"
  • "Split traffic 80/20 between v1 and v2"
  • "Add rate limiting middleware to the API route"
  • "Migrate my NGINX ingress to Traefik"
  • "Check if there are any out-of-sync apps"

Safety rules:

  • Autonomous canary promotion only up to 50% traffic weight — anything beyond requires explicit approval.
  • Traefik routes are always generated first (generate mode), presented to you, and only applied after confirmation.
  • Never creates TCP routes without approval (no automatic rollback for TCP).
  • Traffic mirroring capped at 20% without explicit approval.
  • Never zeroes out all traffic weights — at least one backend must always receive traffic.
  • Verifies backend services exist before creating routes to them.

What it won't do: Raw Kubernetes operations (scaling pods, creating ConfigMaps) or Helm chart management. Those go to the K8s Operator or Helm Operator respectively.

☸️ K8s Operator​

What it does: Handles direct Kubernetes cluster operations — listing resources, debugging failing pods, scaling workloads, creating and updating manifests, managing secrets, inspecting events, and switching between clusters.

When the Supervisor routes to it: When you mention pods, deployments, services, ConfigMaps, secrets, scaling, logs, exec, namespaces, cluster health, RBAC, or anything that is a raw Kubernetes operation.

MCP Server: kubernetes-mcp-server — provides 32 tools for resource CRUD, pod lifecycle (logs, exec, run), workload scaling, cluster events, node diagnostics, and multi-cluster context management.

Skills:

SkillWhat It Handles
kubernetes-cluster-opsResource lifecycle, pod debugging, workload scaling, cluster events, node diagnostics, RBAC, multi-cluster context

What you can ask it to do:

  • "List all pods in the staging namespace"
  • "Why is my API pod crashing?" — investigates CrashLoopBackOff with logs, events, and resource analysis
  • "Scale the web deployment to 5 replicas"
  • "Show me the logs from the checkout pod"
  • "Exec into the frontend container"
  • "Create a ConfigMap with my app settings"
  • "Is my cluster healthy?" — runs a comprehensive multi-tool health assessment
  • "What events are happening in the production namespace?"
  • "Switch to the staging cluster context"
  • "Show me CPU and memory usage across all nodes"

Safety rules:

  • Production namespaces (prod, production, kube-system) receive elevated caution — always confirms before mutations.
  • Never displays secret values — acknowledges key names but masks all data values.
  • Reads before writing — always checks current state before scaling, updating, or creating.
  • Pod exec requires explicit confirmation of target pod, namespace, and exact command.
  • Force-delete only when you explicitly specify "force delete".
  • Multi-cluster: verifies the active context before any write operation.

What it won't do: Helm chart operations, ArgoCD syncs, or observability tasks. Those go to their respective operators.

📊 Observability Operator​

What it does: Manages the full observability stack across five pillars — Prometheus for metrics, Alertmanager for alert lifecycle, OpenTelemetry for instrumentation pipelines, Loki for log exploration, and Tempo for distributed tracing.

When the Supervisor routes to it: When you mention metrics, alerts, logs, traces, monitoring, PromQL, LogQL, TraceQL, silences, exporters, collectors, or anything related to observability.

MCP Servers:

ServerWhat It Connects To
prometheus-mcp-serverPrometheus — PromQL queries, exporters, ServiceMonitors, alerting/recording rules, cardinality
alertmanager-mcp-serverAlertmanager — alert triage, silences, routing, receiver testing
opentelemetry-mcp-serverOpenTelemetry — collector provisioning, auto-instrumentation, pipeline validation, sampling
loki-mcp-serverLoki — LogQL queries, label discovery, log patterns, trace-log correlation
tempo-mcp-serverTempo — TraceQL queries, trace summarization, RED metrics, service topology

Skills:

SkillWhat It Handles
prometheusPromQL queries, exporter onboarding, ServiceMonitors, Probes, alerting/recording rules, cardinality optimization
alertmanagerAlert triage, silence lifecycle, routing audits, receiver testing, governance compliance
opentelemetryCollector provisioning, auto-instrumentation, pipeline validation, sampling strategies, SpanMetrics
lokiLogQL queries, label discovery, log patterns, field analysis, trace-log correlation (read-only)
tempoTraceQL queries, trace search, critical path analysis, RED metrics, service topology, Tempo Operator CRDs

What you can ask it to do:

  • "What alerts are firing right now?" — summarizes all active alerts by severity
  • "Mute checkout alerts for 2 hours" — creates a targeted silence
  • "How much CPU is my service using?" — runs a PromQL query
  • "Monitor my endpoint https://api.example.com" — sets up a blackbox exporter and Probe
  • "Show logs for checkout errors" — queries Loki with LogQL
  • "Find slow checkout requests" — searches Tempo for high-latency traces
  • "Onboard my service to OpenTelemetry" — auto-instruments the deployment
  • "Why is checkout slow? Check metrics and traces" — cross-pillar investigation across Prometheus and Tempo
  • "Who gets paged when CPU is high?" — audits Alertmanager routing
  • "Deploy a collector for traces and metrics" — provisions an OTel collector

Cross-Pillar Correlation: This operator can correlate across multiple observability tools in a single investigation. For example, if you ask "Why is checkout slow?", it might:

  1. Check error rate and latency in Prometheus.
  2. Find slow trace IDs in Tempo.
  3. Look up related error logs in Loki.
  4. Check if there are active alerts in Alertmanager.

Safety rules:

  • Always previews silence blast radius before creating silences.
  • Max silence duration: 24 hours.
  • Test alerts fire real notifications — warns you before pushing test alerts.
  • OpenTelemetry state changes always run in dry_run mode first.
  • Auto-instrumentation triggers pod restarts — always warns during planning.
  • Loki is entirely read-only — no state-modifying operations.
  • PromQL counter queries always use rate() or increase() — never raw counter values.
  • Tempo CRD changes default to dry_run=true.

What it won't do: Raw Kubernetes operations, Helm chart management, or application deployment.

How Operators Connect: Just-In-Time (JIT) Lifecycle​

Each operator talks to external systems through MCP servers (Model Context Protocol). These are lightweight processes that translate the agent's tool calls into API requests to actual infrastructure.

The connection pattern is Just-In-Time (JIT): an MCP server only starts when its operator needs it, and shuts down immediately after the task completes. This keeps resource usage minimal — even though there are dozens of registered tools, only the servers actively being used consume CPU and memory.

All MCP servers default to stdio transport — running as local subprocesses communicating via stdin/stdout. For Docker Compose deployments, you can switch to HTTP transport. See MCP Servers for details.

How Requests Move Between Operators​

Sometimes your request starts in one operator but needs help from another. For example, you might ask the Observability Operator about a failing service, and it discovers the underlying pods are in CrashLoopBackOff — which is the K8s Operator's domain.

When this happens, the operator sends a structured handoff back to the Supervisor:

"This is outside my scope. Please use the appropriate operator."
User Request: <your original request>
Context: <what the first operator already discovered>

The Supervisor picks this up, preserves everything the first operator found, and routes to the correct operator with all the context intact. You don't have to repeat yourself — the second operator sees all prior findings and starts working immediately.

Concrete Example Flow​

  1. You ask: "Why is checkout timing out?"
  2. Observability Operator checks Prometheus → finds a 5xx error rate spike and high-latency traces in Tempo.
  3. It hands off to K8s Operator: "Pod health investigation needed based on telemetry findings."
  4. K8s Operator receives prior findings (error spike, latency data), checks pod status → finds 2/3 pods in CrashLoopBackOff with Out Of Memory (OOMKilled) errors.
  5. You receive a unified answer covering both the observability data and the underlying container resource issue.

How Operators Are Discovered at Startup​

Operators are discovered automatically from the built_in_subagents/ directory when k8s-autopilot starts:

built_in_subagents/{operator-name}/
├── .mcp.json          # MCP server connections for this operator
├── agents/
│   └── {operator}.md  # System prompt, capabilities, and safety rules
└── skills/
    └── {skill-name}/
        ├── SKILL.md           # Step-by-step workflow playbook
        └── references/
            └── workflows.md   # Detailed workflow examples and edge cases
  • .mcp.json — Defines which MCP servers this operator connects to and their environment variables.
  • agents/*.md — The operator's identity, mission, classification rules, decision policies, safety guardrails, and example interactions.
  • skills/*/SKILL.md — Detailed, step-by-step playbooks that the operator loads when performing complex or state-changing operations.

The SubagentsMiddleware handles injecting all discovered operators into the Supervisor's tool set at startup.

Dynamic Sub-agents from Plugins​

Beyond the 4 built-in operators, k8s-autopilot is an open framework: plugins installed from the marketplace or local directories can register dynamic sub-agents.

When an installed plugin includes an agents/ directory, the framework automatically registers a new specialist sub-agent alongside Helm, App, K8s, and Observability. This new sub-agent has its own isolated memory boundary, dedicated MCP tool servers, and specialized skills — allowing teams to create bespoke operators for Terraform, cloud providers, database migrations, or compliance audits without altering core code.

At a Glance​

OperatorDomainMCP ServersSkills LoadedExample Request
HelmHelm chart lifecyclehelm-mcp-server (22 tools)helm-operation"Install nginx from bitnami"
AppApplication deliveryargocd, argo-rollout, traefikargocd-gitops, argo-rollout-gitops, traefik-edge-routing"Deploy my app with canary"
K8sKubernetes cluster opskubernetes-mcp-server (32 tools)kubernetes-cluster-ops"Why is my pod crashing?"
ObservabilityMonitoring & tracingprometheus, alertmanager, opentelemetry, loki, tempoprometheus, alertmanager, opentelemetry, loki, tempo"What alerts are firing?"
Plugin AgentsDynamic custom domainsCustom MCP serversPlugin-defined skills"Lint my Terraform modules"

Next Steps​