kube-agents: Skill for Claude Code

Upgrade Kubernetes Agentic Harness (kube-agents)

Use this skill when asked to upgrade the kube-agents Platform Agent or operator on an active GKE cluster.

One-Liner Execution Mode (Non-Interactive)

Upgrade an install with the upgrade.sh published for the release you are moving to, substituting <RELEASE_VERSION> with a release tag from GitHub Releases. The release-pinned script carries its own version, so no image tag is passed:

curl -fsSL https://raw.githubusercontent.com/gke-labs/kube-agents/<RELEASE_VERSION>/upgrade.sh | bash -s -- \
  --upgrade-mode="full" \
  --non-interactive \
  --gcp-project-id="<PROJECT_ID>" \
  --gke-cluster-name="<CLUSTER_NAME>" \
  --gcp-region="<REGION>"

A full upgrade re-renders the whole install (the PlatformAgent CR included) from the install's install.env, and refuses to proceed without it. KUBE_AGENTS_INSTALL_ENV names one outright, which is how an ephemeral CI runner supplies it. The order the script searches when it is not set is given on the site's upgrade page.

The release bundle is the other supported source, and the one to use when the machine has no install checkout. A bundle carries sources and no configuration, so give the run the install's install.env:

curl -fsSLO https://github.com/gke-labs/kube-agents/releases/download/<RELEASE_VERSION>/kube-agents-<RELEASE_VERSION>.tar.gz
tar -xzf kube-agents-<RELEASE_VERSION>.tar.gz
cd kube-agents-<RELEASE_VERSION>
cp /path/to/the/install/install.env .
./upgrade.sh --upgrade-mode="full" --non-interactive --gcp-project-id="<PROJECT_ID>"

Run the bundle's own ./upgrade.sh, not a newer one piped into a bundle directory: the sources applied would be the unpacked release's while the images came from the piped script's. A bundle that is not the release being asked for is refused by name.

Upgrade Modes

• --upgrade-mode=harness: one helm upgrade --reset-values over the release's recorded values re-tagging the Platform Agent image (platformAgent.deployment.image.tag), the shell sandbox image (agentSandbox.image.tag) and every plugin image tag the release's values record (plugins.pubsubPlatform.image.tag, plugins.stockoutInvestigator.image.tag), followed by a read-back of the gateway Deployment's release images against the tag. Requires jq.
• --upgrade-mode=operator: applies the chart's CRDs with kubectl first (Helm never touches crds/ on upgrade), then the same helm upgrade re-tagging only the operator image. Both modes stop before any of the new release is applied, naming each recorded key the chart's values.schema.json refuses as undeclared; on an upgrade that is a renamed or removed setting, so use --upgrade-mode=full. --drop-undeclared-values drops and names those keys instead, for a rollback to a release that predates them; a later release that declares a dropped key renders it from that chart's default until a full-mode run there.
• --upgrade-mode=full (Default): applies the CRDs, then runs a full terraform apply at the new --image-tag through the install engine — both image tags move and every setting in install.env is re-rendered. This mode additionally requires the terraform CLI.