Skip to content
kube-agents

Quick start (GKE)

The ./install.sh installer bootstraps everything you need for a running Platform Agent on GKE: cluster, CRDs, IAM, secrets, Chat integration, inference gateway, and the token minter. It is a front door, not a second provisioner — the engine underneath is the Terraform composition terraform/examples/full-install, which owns every GCP resource and installs the kube-agents Helm chart, which owns every Kubernetes resource.

Prefer declarative IaC over the interview? Apply the same composition by hand with your own terraform.tfvars — see the composition README for the hand-driven path. Both paths run the same Terraform, so they create the same resources.

Run the Zero-Friction One-Liner Installer

Section titled “Run the Zero-Friction One-Liner Installer”
Terminal window
curl -fsSL https://gke-labs.github.io/kube-agents/install.sh | bash

The installer asks for an immutable image/source revision. Enter a SemVer release tag or the full 40-character commit SHA behind a validated RC tag; mutable refs such as latest and main are rejected so the Terraform configuration and container images stay on the same revision.

For non-interactive AI Agent or CI/CD automated deployments:

Terminal window
curl -fsSL https://gke-labs.github.io/kube-agents/install.sh | bash -s -- \
  --non-interactive \
  --project-id="my-gcp-project" \
  --cluster-name="platform-agent-host" \
  --region="us-central1" \
  --image-tag="<SEMVER_TAG_OR_FULL_COMMIT_SHA>" \
  --permission-set="read-only"

Interactive installer workflow

Section titled “Interactive installer workflow”

  1. Clone the repo.

    Terminal window
    git clone https://github.com/gke-labs/kube-agents.git
    cd kube-agents

  2. Run the installer.

    Terminal window
    ./install.sh

    The run is interactive: it prompts for the values it needs (project ID, region, new or existing cluster, the new cluster’s shape, image tag, chat integrations, model provider and API key, GitOps repo, agent permission set, gVisor, web UI, and memory). Answers are saved to install.env (git-ignored, chmod 600), the install’s configuration; terraform/examples/full-install/terraform.tfvars is regenerated from it on every run, so the two stay in step. A re-run loads install.env first, so a flag you omit keeps the value it records instead of reverting to a default. The installer then runs the composition’s lifecycle.sh apply, and a re-run reconciles every change through one terraform apply — safe to Ctrl-C and run again.

  3. Configure Google Chat (only if you enabled the Google Chat integration). In the Chat API console, point the bot’s Pub/Sub connection at the created topic (projects/<PROJECT_ID>/topics/<CHAT_TOPIC_NAME>). The installer prints the exact topic name and step-by-step instructions when it finishes.

  4. Verify.

    Terminal window
    kubectl get platformagents -n kubeagents-system
    kubectl get pods -n kubeagents-system

    You should see one PlatformAgent resource plus pods for the operator (kubeagents-controller-manager), the Platform Agent gateway (platform-agent-gateway), and LiteLLM (litellm). The GitHub token minter (github-token-minter) also appears if you enabled the GitHub integration. When the Platform Agent gateway pod is Running and Google Chat is configured, DM your Chat app and it should reply.

    The gateway logs errors while it starts up, and they do not mean the install failed. Repeated Connection refused from the Google Chat relay, and a one-off slack connect timed out after 30s, are ordering: both relays dial the credential-proxy sidecar on loopback before it is listening. They retry until it is, and on a fresh install the messages stopped on their own within about seven minutes. Treat them as a fault only if they are still arriving well after that, and inspect the envoy-credential-proxy container rather than the relay reporting the error.

What just happened

Section titled “What just happened”

./install.sh collected your answers, wrote install.env and terraform.tfvars, and ran one terraform apply through the composition’s lifecycle.sh — GCP APIs, the GKE cluster (CMEK, Workload Identity, the host-discovery label), IAM and Workload Identity bindings, cert-manager, and the Helm chart carrying the operator, the PlatformAgent CR, the credentials Secret, and the LiteLLM gateway. Terraform state lives in a versioned GCS bucket (<project>-kube-agents-tfstate, prefix kube-agents/<cluster>), so uninstall.sh and upgrade.sh can find the install from a fresh clone.

Two steps stay gcloud calls because Terraform cannot express them: the managed OpenTelemetry collection scope, and CMEK on a cluster that already existed before the install. The one-shot GitHub App key import into KMS also runs outside Terraform, so the PEM never enters state.

Changing your mind later is the same engine: ./install.sh --menu opens a Day-2 control panel whose Save & Apply regenerates terraform.tfvars and re-applies.

Common flags and toggles

Section titled “Common flags and toggles”
  • --dry-run — always runs terraform validate, and adds a full terraform plan preview when Application Default Credentials exist; nothing is created, and state stays local. It writes no install.env: a dry run provisions nothing, so it has no install to record.
  • --cluster-mode=autopilot|standard — the shape of a cluster this run creates; autopilot unless you say otherwise, and the interactive installer asks when it is about to create one. Autopilot clusters are regional, and what a zonal --region does depends on who chose Autopilot: passing --cluster-mode=autopilot explicitly aborts at the interview, while leaving the flag unset builds Standard instead, since nothing asked for Autopilot there. An invalid mode value aborts the run whatever the target is. The chosen shape has no bearing on a cluster that already exists: the installer writes that cluster’s probed shape instead, for the reason scripts/installer/README.md gives.
  • --gvisor=false — runs the agent on the standard container runtime. The default is true: the agent executes model-authored commands, so it runs under the gvisor RuntimeClass unless you say otherwise. Autopilot, the default shape, ships that RuntimeClass and needs no node pool, from GKE 1.27.4-gke.800 onwards — the installer stops before applying anything if an Autopilot cluster it is adopting is older than that. On a Standard cluster the sandbox needs a node pool of its own, which the run provisions (the gke-cluster module’s enable_gvisor_node_pool).
  • --enable-google-chat — provisions the Google Chat Pub/Sub backend and enables the CR’s googleChat integration.
  • --memory=file|hindsight|off — the agent’s long-term memory store; hindsight deploys the Hindsight API and Postgres into the cluster.

Run ./install.sh --help for the full list.

Uninstall

Section titled “Uninstall”

Run ./uninstall.sh — it drives the same composition’s lifecycle.sh destroy against the state in GCS. See Uninstall for the full procedure and the asymmetries it handles.

Next steps

Section titled “Next steps”