install-kube-agents Skill

This skill provides step-by-step instructions for AI Agents to non-interactively provision Google Cloud GKE infrastructure and deploy the kube-agents Platform Agent.

What install.sh actually does

It is a front-end, not a second provisioner. It loads install.env (the install's hand-authored configuration), collects anything still missing, generates terraform/examples/full-install/terraform.tfvars from the result, and then runs the composition's lifecycle.sh apply — the Terraform root in terraform/examples/full-install/ owns every GCP resource and installs the Helm chart (charts/kube-agents) that owns every Kubernetes one. Terraform state goes to a GCS bucket (<project>-kube-agents-tfstate, versioned, prefix kube-agents/<cluster>), so uninstall.sh and upgrade.sh can find the install from a fresh clone. The installer sources scripts/installer/installer_common.sh before its first prompt, so its defaults and accepted values are the ones defined there; that file is where a default changes.

Order of operations: resolve the image/source ref → check CLI prerequisites (including terraform, which it offers to install; make is not needed) → put the repository on disk and verify it against that ref → load install.env → interview for what is missing → generate terraform.tfvars → run lifecycle.sh apply. The source check happens before the interview, so a bad ref fails in seconds rather than after a dozen answers. Two steps stay gcloud calls after the apply — the managed-OTel scope and CMEK on a pre-existing cluster — and the GitHub App PEM import runs through the Minty CLI so the key never enters Terraform state. Re-running the installer (or its --menu Day-2 panel's Save & Apply) reconciles every change through one terraform apply.

Quick Execution for AI Agents

To run the installer non-interactively in automated subagent execution, pass --non-interactive along with explicit configuration flags:

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

--image-tag accepts a SemVer release tag or a full 40-character commit SHA; mutable refs (latest, main, master, HEAD) are rejected. When the installer runs from a kube-agents checkout it defaults to that checkout's HEAD; anywhere else — including the curl | bash path — the flag is required. Pass it explicitly unless a container image exists for that exact commit: CI publishes one per main commit and per release tag, so an unmerged local commit will pass validation and then fail at image pull.

Dry-Run Inspection

To validate prerequisites and preview the install without creating GCP resources, use --dry-run. It always runs terraform validate against the generated configuration, and adds a full terraform plan when Application Default Credentials exist — on local state, so it never creates the state bucket:

./install.sh --dry-run --non-interactive \
  --project-id="YOUR_GCP_PROJECT_ID" \
  --image-tag="<SEMVER_TAG_OR_FULL_COMMIT_SHA>"

A dry run regenerates terraform.tfvars, so back that up first if a real deployment's copy is already there. It writes no install.env: a dry run provisions nothing, so it has no install to record, and an existing one is never rewritten.

Source verification

Before provisioning, the installer requires the checkout holding the Terraform configuration and chart to be at the same commit as --image-tag and to have no uncommitted changes — the install sources and the container image must come from one revision. A dirty or mismatched checkout aborts with instructions. --allow-unverified-source (or ALLOW_UNVERIFIED_SOURCE=true) downgrades that to a warning; use it when iterating on the installer itself, not for a deployment you intend to keep. --dry-run is lenient already.

GCP IAM permission sets

--permission-set chooses which GCP IAM role bundle the composition grants the agent's GSA (its permission_set variable; custom becomes a project_roles list). It does not affect Kubernetes RBAC, which is read-only in every set, and it does not gate the GitOps pull-request path, which works in every set. See the site's security and IAM reference.

Set	Grants
read-only	Viewer roles only — no GCP write capability. Default.
custom	Exactly the roles passed in --custom-roles; no built-in bundle.

Machine-Readable Results

Upon completion, install.sh generates a machine-readable JSON status report at /tmp/kube-agents-install-report.json:

{
  "status": "SUCCESS",
  "dry_run": false,
  "non_interactive": true,
  "project_id": "YOUR_GCP_PROJECT_ID",
  "cluster_name": "platform-agent-host",
  "timestamp": "2026-08-05T03:35:00Z"
}

Supported Command-Line Flags

Defaults marked "installer_common.sh" reach the installer through scripts/installer/installer_common.sh; the values themselves are listed in install.defaults.env at the repository root, not here. Run ./install.sh --help for the authoritative list.

Flag	Description	Default
-y, --non-interactive	Run without blocking on /dev/tty prompts	false
--dry-run	Output plan and terraform.tfvars without creating resources	false
--menu, --config	Launch the Day-2 control panel instead of installing	false
--project-id=ID	Target GCP Project ID	Active gcloud project
--region=REGION	Target GCP Region	installer_common.sh DEFAULT_REGION
--cluster-name=NAME	GKE Cluster Name	installer_common.sh DEFAULT_CLUSTER_NAME
--cluster-mode=MODE	Shape of a cluster this run creates: autopilot | standard. Autopilot is regional: unset at a zonal --region builds standard, explicit autopilot there is an error. No bearing on an existing cluster, whose live shape the generator probes	autopilot
--image-tag=TAG	SemVer release tag or full 40-character commit SHA	Checkout HEAD; required via curl | bash
--registry-prefix=PATH	Registry path (no URL scheme) for the four images this project builds	installer_common.sh DEFAULT_REGISTRY_PREFIX
--third-party-registry-prefix=PATH	Registry path holding the mirrored third-party images (cert-manager, LiteLLM, fluent-bit, token minter, Hindsight). Not implied by --registry-prefix	unset — upstream registries
--allow-unverified-source	Provision from a dirty or mismatched checkout	false
--model-provider=NAME	gemini | vertex_ai | anthropic | openai	installer_common.sh DEFAULT_MODEL_PROVIDER
--vertex-location=LOCATION	Vertex AI serving location, a region or global. The global endpoint gives no in-region ML processing guarantee	installer_common.sh DEFAULT_VERTEX_LOCATION
--gemini-api-key=KEY	Gemini API key	Looked up in Secret Manager
--openai-api-key=KEY	OpenAI API key	unset
--anthropic-api-key=KEY	Anthropic API key	unset
--permission-set=SET	Agent GCP IAM set: read-only | custom	read-only
--custom-roles=ROLES	Roles for --permission-set=custom (space- or comma-separated)	unset
--gitops-org=ORG	GitHub org/user for the GitOps IaC repository	unset
--gitops-repo=REPO	GitOps IaC repository name	gke-fleet-iac
--enable-google-chat	Enable the Google Chat integration	false
--gvisor=true|false	Enable GKE Sandbox (gVisor) runtime isolation	true
--enable-web-ui=true|false	Enable the Hermes Web UI on port 9119	false
--allowed-users=EMAILS	Comma-separated chat users allowed to reach the agent; empty allows everyone	unset
-h, --help, -?	Output CLI usage banner and parameter details	N/A