feat: Add setup script for Vertex AI on kind clusters

[natifridman]

Adds a helper script to configure the Ambient Code Platform to use Google Cloud Vertex AI instead of the Anthropic API when running locally on kind.
Uses the same environment variables as Claude Code CLI (GOOGLE_APPLICATION_CREDENTIALS, ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION) for consistency.

[github-actions]

Claude Code Review - PR 555

Overall Assessment: Ready to merge with minor recommendations

Summary

This PR adds a helper script to configure Vertex AI for kind clusters. The script is well-written, secure, and follows established patterns.

Issues Found

Major Issues (1):

• Missing volume mount in operator-deployment.yaml for ambient-vertex secret (though it works via secret copying pattern)

Minor Issues (4):

1. Script always recreates secret (no checksum comparison)
2. Inconsistent error handling patterns (&>/dev/null vs >/dev/null 2>&1)
3. Missing Makefile target (no make setup-vertex-kind)
4. Not documented in kind.md

Positive Highlights

Excellent Documentation: Script header is exemplary with clear prerequisites, env vars, examples, and verification steps

Security Best Practices:

• No secrets logged (only paths)
• Proper Kubernetes Secret usage
• Follows CLAUDE.md security standards
• Secret mounted read-only in pods

Consistent Design:

• Uses same env vars as Claude Code CLI
• Follows setup-minio.sh patterns
• Correct ConfigMap patching with --type merge
• Comprehensive error handling and validation

Code Quality: 8.7/10

Category	Score
Documentation	10/10
Security	10/10
Error Handling	9/10
Consistency	9/10
Testing	7/10
Integration	7/10

Recommendations

Before merge: Add Makefile target

Follow-up PRs:

• Add docs/developer/local-development/kind.md section
• Add volume mount clarification comment in script
• Consider checksum-based idempotency

Conclusion

Recommendation: APPROVE

No blocking issues. Script demonstrates strong engineering practices. Minor improvements can be addressed in follow-ups.

---

Reviewed by Claude Sonnet 4.5 | Standards: CLAUDE.md, Security Standards, Error Handling Patterns

[adalton]

Looks like it doesn't generate such a log immediately; you can't use this (at this time) to verify that the operator started correctly. I think you'd see this only after creating a session.

[andybraren]

I'm seeing the same - no output when I run this.

[natifridman]

Not sure if you need to wait a bit or if you need to create a new session. I added sleep over there in case it takes some time for the operator

[adalton]

Should that be /app/vertex/... instead of /etc/vertex/...?

[natifridman]

Yes, fixed

[github-actions]

Claude Code Review

Summary

This PR adds a helpful script to configure Vertex AI on kind clusters. The script is well-documented, follows bash best practices, and provides a good user experience with clear validation and feedback. The implementation correctly aligns with the existing Vertex AI configuration in the operator and Makefile.

Overall Assessment: ✅ Ready to merge with minor suggestions for improvement.

Issues by Severity

🚫 Blocker Issues

None.

🔴 Critical Issues

None.

🟡 Major Issues

1. Missing Volume Mount Configuration in Operator Deployment

The script configures the ConfigMap with GOOGLE_APPLICATION_CREDENTIALS=/app/vertex/ambient-code-key.json, but the operator deployment doesn't mount the vertex secret at startup. The operator only mounts this secret to runner pods, not to the operator pod itself.

Impact: The operator's preflight validation at components/operator/internal/preflight/vertex.go:23 expects GOOGLE_APPLICATION_CREDENTIALS to point to an existing file, but this file won't exist in the operator pod - only in runner pods.

Evidence:

• Line 149: Sets GOOGLE_APPLICATION_CREDENTIALS: "/app/vertex/ambient-code-key.json"
• components/operator/base/operator-deployment.yaml:69-73 shows env vars are read from ConfigMap
• components/operator/internal/handlers/sessions.go:1213-1228 shows the secret is only mounted to runner pods, not operator
• components/operator/internal/preflight/vertex.go:20-31 validates env vars but doesn't actually use the credentials file at operator startup

Recommended Fix: This is actually a design issue in the operator's preflight validation, not this script. The preflight check should either:

1. Skip file existence checks (the file is only needed in runners), OR
2. Only validate env var presence, not file access

For this PR: Add a note in the script's comments explaining that the operator preflight warnings about the credentials file are expected and can be ignored (the file is mounted to runners, not the operator).

🔵 Minor Issues

1. Script Name Doesn't Match Pattern (Line 1)

Location: scripts/setup-vertex-kind.sh:1

Issue: Other setup scripts use different naming patterns:

• scripts/setup-minio.sh (component-specific)

This script is named setup-vertex-kind.sh (feature + platform). Consider setup-vertex.sh since it only works on kind anyway.

Recommendation: Rename to setup-vertex.sh for consistency, or keep current name if future CRC/OpenShift variants are planned.

2. Documentation Gap

Issue: The script isn't mentioned in the kind development documentation at docs/developer/local-development/kind.md.

Recommendation: Add a section to the kind.md docs:

## Vertex AI Configuration (Optional)

If you have Google Cloud Vertex AI access instead of a direct Anthropic API key:

```bash
# Export environment variables (add to ~/.zshrc)
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/your-sa-key.json"
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project-id"
export CLOUD_ML_REGION="us-east5"

# Run setup script
./scripts/setup-vertex-kind.sh

See the script header for detailed setup instructions.

**3. Hard-coded Secret Name Could Collide**

**Location:** Lines 135-138

**Issue:** The script creates `ambient-vertex` secret without checking if an operator-managed version already exists. The Makefile (`Makefile:754-757`) uses the same pattern, but this could cause issues if users run both.

**Current behavior:** `kubectl delete secret ... || true` will delete existing secrets without warning.

**Recommendation:** Add a warning if the secret already exists:

```bash
if kubectl get secret ambient-vertex -n "$NAMESPACE" &>/dev/null; then
    echo "  ⚠ Warning: Overwriting existing ambient-vertex secret"
fi
kubectl delete secret ambient-vertex -n "$NAMESPACE" 2>/dev/null || true

4. No Validation of GCP Credentials File Format

Location: Lines 92-99

Issue: Script checks if file exists but doesn't validate it's valid JSON or has required fields.

Risk: Low - invalid credentials will fail at runtime with clear errors from the GCP SDK.

Recommendation (optional): Add basic JSON validation:

elif \! jq -e '.type' "$GOOGLE_APPLICATION_CREDENTIALS" >/dev/null 2>&1; then
    echo "  [ERROR]   GOOGLE_APPLICATION_CREDENTIALS file is not valid JSON"
    missing_vars=1

Requires jq dependency, so this is optional.

5. Verification Step May Fail Silently

Location: Lines 172-178

Issue: The verification check looks for "vertex ai mode enabled" in logs, but:

• The operator may not log this exact string
• Logs may not be available yet after restart
• The 3-second sleep may not be long enough

Recommendation: Make the verification optional/informational:

echo "Verifying Vertex AI configuration (may take a few seconds)..."
sleep 5
if kubectl logs -l app=agentic-operator -n "$NAMESPACE" --tail=200 2>/dev/null | grep -qi "vertex"; then
    echo "  ✓ Vertex-related logs found in operator"
else
    echo "  ℹ  Verification skipped (operator may still be starting)"
    echo "    Manually verify: kubectl logs -l app=agentic-operator -n $NAMESPACE | grep -i vertex"
fi

Positive Highlights

1. Excellent Documentation (Lines 1-52)

The script header is exemplary:

• Clear prerequisites
• Usage examples
• Environment variable documentation aligned with Claude Code CLI
• Step-by-step setup instructions
• Verification steps

This is exactly the level of documentation scripts should have.

2. Proper Error Handling

• set -e for early exit on errors
• Clear validation of prerequisites with helpful error messages
• Graceful handling of missing namespace/cluster

3. Consistent with Existing Patterns

The script correctly mirrors the Makefile's _create-operator-config logic:

• Same environment variables
• Same ConfigMap structure
• Same secret creation approach

4. Good User Experience

• Clear progress indicators ("Step 1/3...")
• Colored output for status (OK/MISSING/ERROR)
• Helpful next steps
• Shows how to revert changes

5. Help Flag Support

Lines 56-60 provide a nice --help flag that extracts the header comments.

Recommendations

Priority 1: Documentation

1. Add to kind.md: Document this script in docs/developer/local-development/kind.md
2. Clarify preflight warnings: Add a note in the script comments that operator preflight warnings about credentials file are expected

Priority 2: Robustness

1. Improve verification step: Make it more informational and less likely to show false negatives
2. Add secret overwrite warning: Warn users if they're replacing an existing secret

Priority 3: Polish (Optional)

1. Consider renaming to setup-vertex.sh for consistency
2. Add JSON validation if jq is already a project dependency

Testing Suggestions

Before merging, verify:

1. Fresh cluster: Run on a clean make kind-up cluster
2. Missing env vars: Test with missing ANTHROPIC_VERTEX_PROJECT_ID
3. Invalid credentials path: Test with non-existent GOOGLE_APPLICATION_CREDENTIALS
4. Idempotency: Run the script twice to ensure it's safe to re-run
5. Operator logs: Check that operator starts successfully and sessions can be created
6. Revert flow: Test the revert command provided at the end

---

Code Quality Score: 8.5/10

Strong implementation with excellent documentation. The major issue is actually in the operator's preflight validation design, not this script. With documentation additions, this is ready to merge.

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.

[github-actions]

Claude Code Review

This PR adds a helper script to configure Vertex AI for kind clusters. The script is well-documented and follows established patterns.

Critical Issue Found

Operator Deployment Volume Mount Missing

The script sets GOOGLE_APPLICATION_CREDENTIALS=/app/vertex/ambient-code-key.json but components/manifests/base/operator-deployment.yaml does NOT mount the ambient-vertex secret at /app/vertex.

Impact: Vertex AI mode will fail at operator startup when preflight.ValidateVertexConfig checks if the credentials file exists.

Fix: Add volumeMounts and volumes to operator-deployment.yaml to mount the ambient-vertex secret at /app/vertex.

Positive Highlights

• Excellent documentation with comprehensive header comments
• Follows established patterns (same env vars as Claude Code CLI)
• Good error handling and validation
• Security best practices (Secret not ConfigMap)
• Clear user experience with progress indicators
• Idempotent operations

Recommendation

Approve with changes requested. The script is well-written but the missing operator volume mount must be addressed before merge. Estimated effort: 10 minutes.

Full detailed review with 7 issues and recommendations available upon request.

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.