🧭 kube-agents — The Kubernetes Agentic Harness

Stop driving your clusters. Start delegating them.

kube-agents replaces the traditional imperative DevOps presentation layer — kubectl, gcloud, the Google Cloud Console — with autonomous, proactive AI agents that manage your Kubernetes/GKE infrastructure, enforce multi-tenant governance, and continuously audit security posture. Instead of you reacting to pages and typing commands, a Platform Agent watches your fleet around the clock, opens pull requests with fixes, and reports to you in chat.

📗 Full documentation: gke-labs.github.io/kube-agents

An SRE asks for a fleet self-health check; the agent answers in the thread. An illustrative replay — the names and figures are examples. It runs live at the top of the documentation site.

💬 Five things to ask it

The list lives on the documentation site: First prompts gives the first message to send a new install, what a healthy answer looks like, and five things to ask it next.

---

⚡ Try it now

The fastest, zero-friction way to install kube-agents in Google Cloud Shell or your terminal:

curl -fsSL https://raw.githubusercontent.com/gke-labs/kube-agents//install.sh | bash

Substitute `` with the desired version tag from GitHub Releases (for example, 0.4.0; a GitLab install needs 0.9.0 or later).

This interactive installer (recommended for initial setup) guides you through GCP authentication, project selection, GKE cluster setup (Autopilot or Standard), chat integrations (Google Chat & Slack), and LLM model provider credentials. Sensible defaults are detected from your gcloud context, requiring minimal input.

🤖 AI Agent & Automation Usage

For automated environments, CI/CD pipelines, and AI Agents where no interactive TTY is available, invoke the release installer with --non-interactive and CLI flags:

curl -fsSL https://raw.githubusercontent.com/gke-labs/kube-agents//install.sh | bash -s -- \
  --non-interactive \
  --gcp-project-id="my-gcp-project" \
  --gke-cluster-name="platform-agent-host" \
  --gcp-region="us-central1" \
  --model-provider="gemini" \
  --permission-set="read-only"

Or give this prompt to an AI coding assistant. It needs no checkout of this repository, and tells the assistant to confirm the target with you and show you the --dry-run summary before it creates any cloud resources:

Install the latest official release of kube-agents (github.com/gke-labs/kube-agents) into my GCP project.
Follow INSTALL.md from that release tag — do not invent installer URLs, namespaces, or model names.
First inspect my gcloud project and existing GKE clusters and confirm the target, cluster, model provider,
and credential with me. Run install.sh with --dry-run and show me its printed summary before you change anything.
Only run the real install after I say yes.

The full procedure behind the prompt, including the credential and consent-flag checks, is in INSTALL.md. The GitOps repository can be on GitHub or on GitLab (gitlab.com or a self-managed instance); INSTALL.md gives the flags for each. An assistant working in a checkout of this repository also picks up the install-kube-agents skill, which covers the same install.

Prefer to drive the engine by hand? Unpack kube-agents-.tar.gz from GitHub Releases (recommended), or clone the repository at an official release tag if a Git checkout is needed:

curl -fsSL https://github.com/gke-labs/kube-agents/releases/download//kube-agents-.tar.gz | tar -xz
cd kube-agents-
./install.sh                                              # the interview, then one terraform apply
# or, if a Git checkout is needed instead:
# git clone --branch  https://github.com/gke-labs/kube-agents.git
# cd kube-agents && ./install.sh
# or, with your own terraform.tfvars:
cd terraform/examples/full-install && ./lifecycle.sh apply

Both paths run the same engine: terraform/examples/full-install provisions every GCP resource and installs the Helm chart that owns every Kubernetes one, end to end and idempotently. ./uninstall.sh (or lifecycle.sh destroy) reverses it. See the quick start for the walkthrough, or INSTALL.md for manual and local-development paths.

---

📖 What it is

The harness runs co-located agents in a single operator-deployed pod: the Planning Agent — the conversational front door that receives every chat message, works out what it needs, and delegates that work over a shared kanban board — the Platform Agent — the master custodian and agent architect that manages the GKE infrastructure lifecycle, establishes multi-tenancy boundaries, and enforces fleet-wide compliance — and a Cluster Agent per managed cluster, a single-cluster SRE persona the Platform Agent scaffolds from the agents/cluster/ template for runtime operations and workload debugging, with read-only access to the cluster it watches. The Platform Agent is driven by:

• 🧬 A persona — agents/platform/SOUL.md defines its identity, its Automation First rule (no manual cluster mutations; changes flow through declarative, PR-based workflows), and its Least Privilege constraint.
• 📚 Governance playbooks — SOPs in agents/platform/governance/ covering compliance and security audits, fleet consistency drift, cost analysis, stockout prevention, and security patch orchestration.
• 🛠️ Skills — task-focused SKILL.md bundles under agents/platform/skills/: cluster creation, app onboarding, cost analysis, backup & DR, and manifest generation. Single-cluster runtime skills — workload troubleshooting, observability, autoscaling, storage — belong to the Cluster Agent in agents/cluster/skills/. See the skill catalog.
• ⏰ Autonomous watchdogs — cron-driven governance jobs in agents/platform/cron/jobs.json that keep the fleet honest without human prompting. Ticking belongs to the Planning Agent’s gateway, the only running one, so a job on its roster advances the Platform Agent’s schedule once a minute. See proactive autonomy.

The runtime is built on the Hermes agent framework and wires in MCP servers for platform control and GKE’s hosted MCP endpoint, so the agent speaks to your clusters through structured tools rather than raw shell access.

For three scenarios from trigger to pull request (a scheduled audit, a crash loop alert, and a chat question), see A day with kube-agents.

---

🧰 Capabilities

The Platform Agent runs these audits on a schedule and posts each report to chat. Each skill is a procedure that the Platform Agent or a Cluster Agent loads when a request or an audit needs it. The skill catalog describes each skill, and the cron job reference lists every scheduled job.

Scheduled governance audits

Skills by area

---

🛡️ Governance & isolation

kube-agents is designed for enterprise fleets where agents must be powerful and provably contained:

• Least-privilege RBAC — the agent’s Kubernetes identity is read-only and cannot read Secrets.
• Credential isolation — model-authored code runs in a shell sandbox pod that holds no API keys or tokens; an Envoy credential broker in a pod of its own injects them at the network boundary.
• At-rest database encryption & state security — GKE etcd database encryption (CMEK) via Cloud KMS, strict state file permissions (umask 077), and mandatory encryption pre-flight gates.
• Kernel-level sandboxing — agent workloads run under a gVisor RuntimeClass (GKE Sandbox) by default; --enable-gvisor=false opts out.
• GitOps-only mutations — infrastructure changes are proposed as pull requests for human review.

Exactly what is enforced on which plane — Kubernetes RBAC, GCP IAM, and the GitOps path each answer differently — is set out in Security & IAM. Read that before granting the agent access to a production project.

---

🏗️ Architecture

flowchart TB
    subgraph agent["🧠 Control Plane — Agent Layer"]
        SOUL["SOUL.md persona+ governance SOPs"]
        SKILLS["Skills(agents/platform/skills)"]
        CRON["Scheduled watchdogs(cron/jobs.json)"]
        PA["Platform Agent workspace(agents/platform)"]
        SOUL --> PA
        SKILLS --> PA
        CRON --> PA
    end

    subgraph cluster["☸️ Cluster Plane — Kubernetes Layer"]
        OP["k8s-operator(Go / Kubebuilder)"]
        CRD["PlatformAgent CRDkubeagents.x-k8s.io/v1alpha1"]
        POD["Agent pod: gVisor sandbox+ Envoy credential proxy+ Fluent Bit + event watcher"]
        RBAC["RBAC isolation boundaries(read-only view + explorer)"]
        OP -->|reconciles| CRD
        CRD --> POD
        OP --> RBAC
    end

    subgraph integration["🔀 Integration & Routing Layer"]
        LLM["LiteLLM GatewayGemini · Vertex AI · OpenAI · Anthropic · OpenAI-compatible"]
        CHAT["Messaging bridgesGoogle Chat (Pub/Sub) · Slack (Socket Mode)"]
        GH["Minty — GitHub Apptoken minter (KMS)"]
    end

    PA -.runs inside.-> POD
    POD --> LLM
    CHAT  POD
    POD -->|PR-based changes| GH

Walkthrough: Architecture. The k8s-operator/ reconciles PlatformAgent custom resources into the sandboxed agent pod, its sidecars, per-agent ServiceAccounts with Workload Identity, read-only RBAC, and Services.

Looking for the end-state design? docs/architecture/ specifies a three-tier, fully read-only agent model that this repository is converging toward. It describes the target, not what ships today.

---

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the CLA and where the contributor workflow is documented. Repository conventions for AI coding agents are in AGENTS.md.

Bug reports and feature requests go in issues. If your GitHub account cannot open one here, use the feedback form, which files it for you.

Disclaimer

This is not an officially supported Google product.

This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.