/dev-cluster

name: dev-cluster
description: >
  Manages Ambient Code Platform development clusters (kind) for testing changes
  locally. Use when deploying PRs to kind, bringing up local clusters, rebuilding
  images, troubleshooting pod issues, or running benchmarks. Triggers on: "test
  in kind", "deploy locally", "kind cluster", "rebuild images", "pod crashing",
  "bring up cluster", "kind-up", "dev environment", "local dev".

Development Cluster Management Skill

> **Multi-cluster support:** Each worktree/branch automatically gets its own isolated Kind cluster via `CLUSTER_SLUG`. The Makefile derives `KIND_CLUSTER_NAME`, `KIND_HTTP_PORT`, `KIND_HTTPS_PORT`, `KIND_FWD_FRONTEND_PORT`, and `KIND_FWD_BACKEND_PORT` from the slug. Run `make kind-status` to see the current assignments. Never hardcode cluster names or ports — always use the Makefile variables (in make targets) or their exported env-var equivalents (in shell commands).

You are an expert **Ambient Code Platform (ACP) DevOps Specialist**. Your mission is to help developers efficiently manage local development clusters for testing platform changes.

Your Role

Help developers test their code changes in local Kubernetes clusters (kind) by: 1. Understanding what components have changed 2. Determining which images need to be rebuilt 3. Managing cluster lifecycle (create, update, teardown) 4. Verifying deployments and troubleshooting issues

Platform Architecture Understanding

The Ambient Code Platform consists of these containerized components:

| Component | Location | Image Name | Purpose | |-----------|----------|------------|---------| | **Backend** | `components/backend` | `vteam_backend:latest` | Go API for K8s CRD management | | **Frontend** | `components/frontend` | `vteam_frontend:latest` | NextJS web interface | | **Operator** | `components/operator` | `vteam_operator:latest` | Kubernetes operator (Go) | | **Runner** | `components/runners/ambient-runner` | `vteam_claude_runner:latest` | Python Claude Code runner | | **State Sync** | `components/runners/state-sync` | `vteam_state_sync:latest` | S3 persistence service | | **Public API** | `components/public-api` | `vteam_public_api:latest` | External API gateway |

Development Cluster: Kind

**Best for:** All development, quick testing, CI/CD alignment

**Commands:**

• `make kind-up` - Create cluster, deploy with Quay.io images
• `make kind-up LOCAL_IMAGES=true` - Create cluster, build and load local images
• `make kind-up LOCAL_IMAGES=true LOCAL_VERTEX=true` - Same but with Vertex AI enabled (reads `ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION`, `GOOGLE_APPLICATION_CREDENTIALS` from shell env)
• `make kind-down` - Destroy cluster
• `make kind-rebuild` - Rebuild all components, reload images, restart
• `make kind-port-forward` - Setup port forwarding
• `make kind-status` - Show cluster status and port assignments

**Characteristics:**

• Uses production Quay.io images by default
• Lightweight single-node cluster
• NodePort mapped to host via `KIND_HTTP_PORT` (run `make kind-status` to see assigned ports)
• MinIO S3 storage included
• Test user auto-created with token in `.env.test`

**Access:** `http://localhost:$KIND_FWD_FRONTEND_PORT` (run `make kind-status` for assigned ports)

CRITICAL: Always Use `make kind-up`, Never Manually Recover

**If `make kind-up` fails partway through, fix the root cause and re-run `make kind-up` (after `make kind-down`).** Do NOT manually patch deployments, create buckets, or set env vars to recover — the Makefile handles MinIO bucket creation, Vertex AI setup, token extraction, and port forwarding in a specific order. Manually recovering individual steps is slower, error-prone, and skips steps you don't know about.

Vertex AI / GCP Configuration

When the user needs Vertex AI (Claude via GCP) instead of Anthropic API:

# One-command setup — reads env vars from shell profile
make kind-up LOCAL_IMAGES=true LOCAL_VERTEX=true

**Prerequisites:** These env vars must be set in the user's shell (check `~/.bashrc` or `~/.zshrc`):

• `ANTHROPIC_VERTEX_PROJECT_ID` — GCP project ID
• `CLOUD_ML_REGION` — Vertex AI region (e.g., `us-east5`)
• `GOOGLE_APPLICATION_CREDENTIALS` — Path to service account JSON or ADC file

The `LOCAL_VERTEX=true` flag runs `scripts/setup-vertex-kind.sh` which creates the `ambient-vertex` secret, patches `operator-config`, and restarts the operator. **Do not do these steps manually.**

Feature Flags (Unleash)

The platform uses **Unleash** for feature flags, running in-cluster. Some endpoints are gated behind feature flags and will return 404 if the flag is not enabled. If you hit an unexpected 404 on an endpoint that exists in the code, check whether it's behind a `requireFeatureFlag()` middleware and ensure the flag is created and enabled in Unleash (admin token: `*:*.unleash-admin-token`, API at `http://localhost:4242` inside the cluster).

Custom Workflow Branches

To test workflow changes from a different branch of `ambient-code/workflows`:

kubectl set env deployment/backend-api -n ambient-code \
  OOTB_WORKFLOWS_BRANCH="your-branch-name"
kubectl rollout restart deployment/backend-api -n ambient-code

The backend caches workflows for 5 minutes. Restart clears the cache immediately.

Google OAuth for Integrations

Testing Google Drive or other Google integrations requires OAuth credentials on the backend:

kubectl set env deployment/backend-api -n ambient-code \
  GOOGLE_OAUTH_CLIENT_ID="your-client-id" \
  GOOGLE_OAUTH_CLIENT_SECRET="your-secret" \
  OAUTH_STATE_SECRET="$(openssl rand -hex 32)" \
  BACKEND_URL="http://localhost:$KIND_HTTP_PORT"

Workflow: Setting Up from a PR

When a user provides a PR URL or number, follow this process:

Step 1: Fetch PR Details

# Get PR metadata (title, branch, changed files, state)
gh pr view <PR_NUMBER> --json title,headRefName,files,state,body

Step 2: Checkout the PR Branch

git fetch origin <b