Mastering KCC Operations with Google Antigravity

1. Introduction

In this codelab, you will learn about Google Antigravity (referred to as Antigravity for the rest of the document), an agentic development platform, evolving the IDE into the agent-first era.

Unlike standard coding assistants that just autocomplete lines, Antigravity provides a "Mission Control" for managing autonomous agents that can plan, code, and even browse the web to help you build.

Antigravity is designed as an agent-first platform. It presupposes that the AI is not just a tool for writing code but an autonomous actor capable of planning, executing, validating, and iterating on complex engineering tasks with minimal human intervention.

What you'll learn

Installing and configuring Antigravity.
Exploring key concepts of Antigravity like Agent Manager, Editor, Browser and more.
Building a production-grade KCC Ops Skill from scratch to manage Google Cloud resources with safety and compliance.

What you'll need

Currently Antigravity is available as a preview for personal Gmail accounts. It comes with a free quota to use premier models.

Antigravity needs to be locally installed on your system. The product is available on Mac, Windows and specific Linux distributions. In addition to your own machine, you will need the following:

A Gmail account (Personal Gmail account).
A Google Cloud Account and Google Cloud Project
A web browser such as Chrome supporting Google Cloud console and Cloud Shell

2. Setup and Requirements

Project setup

Create a Google Cloud Project

In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

This codelab, designed for users and developers of all levels (including beginners).

3. Installation

If you don't have Antigravity installed already, let's begin with installing Antigravity. Currently the product is available for preview and you can use your personal Gmail account to get started with it.

Go to the downloads page and click on the appropriate operating system version that is applicable to your case. Launch the application installer and install the same on your machine. Once you have completed the installation, launch the Antigravity application.

Key steps during setup:

Choose setup flow: We recommend a fresh start for this codelab.
Review-driven development (recommended): Choose this option. It allows the agent to make a decision and come back to the user for approval, which is critical for infrastructure operations.

Next, Configure your Editor and Sign in to Google. Finally, accept the Terms of Use.

4. Infrastructure Setup: GKE & Config Connector

Before you can build the skill, you need a Google Cloud environment with Config Connector (KCC) installed manually and configured in Namespaced Mode. This allows you to manage GCP resources as Kubernetes objects.

Step 0: Prepare your Environment

1. Cluster Prerequisites

Create a new GKE cluster with the necessary features enabled:

# Set your variables
export PROJECT_ID=$(gcloud config get-value project)
export CLUSTER_NAME="kcc-ops-cluster"
export REGION="us-central1"

# Create the cluster
gcloud container clusters create ${CLUSTER_NAME} \
    --region ${REGION} \
    --release-channel "regular" \
    --workload-pool=${PROJECT_ID}.svc.id.goog \
    --logging=SYSTEM \
    --monitoring=SYSTEM

# Get cluster credentials
gcloud container clusters get-credentials ${CLUSTER_NAME} --region ${REGION}

2. Install the Config Connector Operator

The operator keeps your installation up to date.

# Download the latest Config Connector operator
gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz

# Extract the bundle
tar zxvf release-bundle.tar.gz

# Install the operator (Standard Cluster)
kubectl apply -f operator-system/configconnector-operator.yaml

3. Configure Namespaced Mode

Create a ConfigConnector resource to specify the operating mode.

# configconnector.yaml
apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnector
metadata:
  name: configconnector.core.cnrm.cloud.google.com
spec:
  mode: namespaced
  stateIntoSpec: Absent

kubectl apply -f configconnector.yaml

4. Create an Identity and Namespace

For this lab, we will use the default namespace and a dedicated Google Service Account (GSA).

# Set your variables
export PROJECT_ID=$(gcloud config get-value project)
export NAMESPACE="default"

# Create the Google Service Account
gcloud iam service-accounts create kcc-identity --project ${PROJECT_ID}

# Grant permissions on the project
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:kcc-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/owner"

# Grant Metric Writer permissions
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:kcc-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/monitoring.metricWriter"

# Bind GSA to KSA via Workload Identity
gcloud iam service-accounts add-iam-policy-binding \
    kcc-identity@${PROJECT_ID}.iam.gserviceaccount.com \
    --member="serviceAccount:${PROJECT_ID}.svc.id.goog[cnrm-system/cnrm-controller-manager-${NAMESPACE}]" \
    --role="roles/iam.workloadIdentityUser"

5. Configure the Namespace

Create a ConfigConnectorContext to watch the namespace.

# configconnectorcontext.yaml
apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnectorContext
metadata:
  name: configconnectorcontext.core.cnrm.cloud.google.com
  namespace: default
spec:
  googleServiceAccount: "kcc-identity@${PROJECT_ID}.iam.gserviceaccount.com"
  stateIntoSpec: Absent

kubectl apply -f configconnectorcontext.yaml

6. Verify Installation

Wait for the controller to be ready for the default namespace.

kubectl wait -n cnrm-system \
    --for=condition=Ready pod \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -l cnrm.cloud.google.com/scoped-namespace=default

5. Agent Manager: Mission Control

Antigravity forks the open-source Visual Studio Code (VS Code) foundation but radically alters the user experience to prioritize agent management over text editing. The interface is bifurcated into two distinct primary windows: the Editor and the Agent Manager.

Agent Manager

Upon launching Antigravity, the user is typically greeted by the Agent Manager. This interface acts as a Mission Control dashboard. It is designed for high-level orchestration, allowing developers to spawn, monitor, and interact with multiple agents operating asynchronously across different workspaces or tasks.

In this view, the developer acts as an architect. They define high-level objectives. Each of these requests spawns a dedicated agent instance. The UI provides a visualization of these parallel work streams, displaying the status of each agent, the Artifacts they have produced (plans, results, diffs), and any pending requests for human approval.

6. Antigravity Browser & Artifacts

Antigravity creates Artifacts as it plans and gets its work done. These are rich markdown files, architecture diagrams, images, browser recordings, and code diffs.

Artifacts solve the "Trust Gap"

When an agent claims, "I have fixed the bug," the developer previously had to read the code to verify. In Antigravity, the agent produces an artifact to prove it.

Artifacts

These are the main artifacts produced by Antigravity:

Task Lists: A structured plan generated before writing code.
Implementation Plan: Architected changes with technical details.
Walkthrough: A summary of changes and how to test them.
Browser Recordings: Video records of browser sessions for UI verification.

Antigravity Browser

When the agent needs to interact with the web, it invokes a browser subagent. This subagent can click, scroll, type, and read console logs. It uses a specialized model to operate on the pages that are open within the Antigravity-managed browser.

7. Editor experience

The editor retains the familiarity of VS Code. It includes the standard file explorer, syntax highlighting, and extensions ecosystem.

Key Editor features:

Auto-complete: Smart suggestions accepted by pressing Tab.
Tab to import: Suggests adding missing dependencies.
Commands (Cmd + I): Trigger inline completions using natural language.
Agent Side Panel (Cmd + L): Toggle the agent panel to ask questions or refer to files using @.

8. Providing Feedback

At the heart of Antigravity is its ability to effortlessly gather your feedback. These artifacts are a way for you to provide feedback to the agent in Google docs style comments.

Whenever you add a comment to a plan or task, make sure you remember to submit the comment. This steers the agent in the direction you want.

9. Building the KCC Ops Skill

Now that you understand the platform, let's build the KCC Ops Skill.

Kubernetes Config Connector (KCC) allows you to manage GCP resources as K8s objects. However, it requires safety rails to prevent configuration drift, compliance violations, and accidental resource recreation.

Step 1: Structure the Skill

In your workspace root, create the directory structure for your skill:

mkdir -p .agents/skills/kcc-ops/scripts
mkdir -p .agents/skills/kcc-ops/resources/policies/templates
mkdir -p .agents/skills/kcc-ops/resources/policies/constraints

Step 2: Author the SKILL.md (The Brains)

The SKILL.md defines the metadata and the core "Golden Rule" for the agent. Create .agents/skills/kcc-ops/SKILL.md:

---
name: kcc-ops
description: Assists with Config Connector (KCC) configuration, resource generation, and troubleshooting on Google Cloud.
---

# Config Connector (KCC) Operations Skill

Use this skill to manage Google Cloud resources using Kubernetes-style configuration (Config Connector).

## 🛑 GOLDEN RULE: Separate Generation from Application

**NEVER generate and apply a manifest in a single autonomous step.**

1. **Craft:** Write the generated manifest to a local file.
2. **Analyze:** Present the manifest to the user. Perform Impact Analysis and Dry Runs. Explain the consequences of the change (e.g., "If this topic is deleted, the attached subscription becomes orphaned").
3. **Wait:** Pause execution and explicitly wait for user permission to proceed.
4. **Apply:** Only run `kubectl apply` *after* the user has reviewed the manifest and the impact analysis, and then unequivocally confirmed you should proceed.

## Core Responsibilities

0. **Context Verification**: Verify the execution context (cluster, namespace, GCP project, user account) with the user before performing any operations.
1. **Installation & Health**: Verify KCC is properly installed and healthy on the target cluster.
2. **Resource Inventory**: Query and summarize existing KCC resources within a namespace.
3. **Brownfield Bulk Export (Adoption)**: Export existing GCP project resources into valid KCC YAML manifests.
4. **Manifest Generation**: Generate valid YAML manifests for GCP resources using KCC CRDs.
5. **Impact Analysis**: Identify ancillary services and resources (e.g., Cloud Run, Apps) that depend on a resource being modified.
6. **Change Differentiation**: Generate diff summaries for resource edits to support change control.
7. **Policy Compliance**: Vet KCC manifests against OPA/Gatekeeper policies.
8. **Troubleshooting**: Analyze resource status, and consult the troubleshooting guide to resolve reconciliation issues.

## Guidelines for Operations

### 0. Context Verification

Before performing **any operations or executing commands** (including health checks), you **MUST** verify the current execution context and obtain explicit user confirmation.

1. **Read Context:** Use commands like `kubectl config current-context`, `kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}'`, `gcloud config get-value project`, and `gcloud config get-value account` to determine the active environment.
2. **Present & Ask:** Show this information to the user clearly (e.g., "I see my context is X, namespace is Y, project is Z, and account is A. Is this correct?").
3. **Wait:** Do not proceed with any other steps or scripts until the user has confirmed or provided corrections.

### 1. Installation & Health Check

Before performing operations, ensure the environment is ready:

- **Automation**: You MUST use `./scripts/check-health.sh` to verify namespaces, controllers, and CRDs. Do not use manual kubectl commands for health checks, as the script enforces standard formatting and context verification.

### 2. Resource Inventory & Discovery

To understand the current state of infrastructure:

- **Automation**: You MUST use `./scripts/inventory.sh` to get a summary table of all KCC resources. Do not use manual kubectl queries, as the script is optimized to securely discover all CRDs with context validation.

### 3. Manifest Structure

- All KCC resources belong to the `cnrm.cloud.google.com` API group.
- Use the `cnrm.cloud.google.com/project-id` annotation for cross-project resource management if not using Namespaced Mode.
- Always include `apiVersion`, `kind`, `metadata`, and `spec`.

### 4. Official Resource Reference (Agent Action)

When generating or troubleshooting manifests, you **must not guess** the API schema. Always consult the [Official Config Connector Reference](https://cloud.google.com/config-connector/docs/reference/overview) for the exact API version, kind, and required fields for the specific resource and cross reference with the official [github repository](https://github.com/GoogleCloudPlatform/k8s-config-connector/tree/master/config/crds/resources).

### 5. Troubleshooting Checklist

When a resource is not reconciling (check `kubectl get <kind> <name> -o yaml`):

- **Ready Condition**: Look for `status.conditions` where `type: Ready` and `status: "False"`.
- **Reason/Message**: Check the `reason` and `message` fields in the status conditions.
- **Consult the Guide**: Immediately check `./resources/troubleshooting-guide.md` for definitions of the error reason (e.g. `DependencyInvalid`, `ManagementConflict`) and follow its resolution steps.
- **Common Issues**:
  - Permissions: The KCC service account lacks IAM roles.
  - Quotas: GCP project quota exceeded.
  - Conflicts: Resource already exists or is managed by another tool.
  - Immutable Fields: Attempting to change a field that requires resource recreation. Look for "Update failed" errors related to immutable fields.
  - Reference Resolution: Check if the resource is waiting for a dependency (e.g., `referenced project not found`).

### 6. Impact Analysis (Ancillary Services)

Before modifying a resource (e.g., GCS Bucket, Pub/Sub Topic), verify whatElse depends on it:

- **Reference Search (Cluster-wide)**: Search for other KCC resources that reference the item.

  ```bash
  # Example: Find resources referencing a bucket named 'my-data-bucket'
  kubectl get-all -n <namespace> -o yaml | grep -C 5 "my-data-bucket"
  ```

- **IAM-based Analysis**: Check for IAM Service Accounts that have roles on the specific resource. A Cloud Run job or GKE Workload Identity might be using those permissions.
- **Common Ancillary Dependencies**:
  - **Storage Buckets**: Look for Cloud Run/GKE mounts (CSI), Cloud Functions triggers, or Dataflow jobs.
  - **Networks**: Check for Firewall rules, Forwarding rules, and GKE cluster assignments.
  - **IAM Policies**: Changing a policy might break access for external applications not managed by KCC.
- **Resource Graph**: Use `gcloud asset search-all-resources` to find resources that might have implicit links.

### 3. Policy Compliance & Best Practices

Evaluate KCC manifests against security and governance policies. The vetting tool supports three source modes:

- **Built-in Mode (Default)**: Uses the skill's high-fidelity `v1beta1` library (300+ Anthos constraints).
  - `Usage: ./scripts/vet-policy.sh <manifest-path>`
- **Remote Mode**: Clones and vets against an external Git repository.
  - `Usage: ./scripts/vet-policy.sh <manifest-path> <repo-url> [git-ref]`
  - ⚠️ **Note**: External libraries like the legacy GCP Policy Library may be out-of-date and cause schema validation errors with modern `gator`.
- **Local Mode**: Vets against a local directory of policies.
  - `Usage: ./scripts/vet-policy.sh <manifest-path> /path/to/local/policies`

**Interaction Model:**

1. Call `./scripts/vet-policy.sh` with the appropriate arguments.
2. Interpret the `=== KCC Best Practices ===` and `=== OPA/Gatekeeper ===` reports.
3. Supplement automated findings with manual review for specific security features not yet covered by OPA (e.g., `publicAccessPrevention: enforced`, `versioning: {enabled: true}`).

  ```bash
  # Run the skill's helper script (repo URL and branch are optional)
  ./scripts/vet-policy.sh manifest.yaml [policy-repo-url] [policy-ref]
  ```

## Skill Assets

This skill includes additional resources to streamline operations:

- **`scripts/`**: Automation scripts (e.g., `vet-policy.sh`, `bulk-export.sh`).
- **`examples/`**: Reference KCC manifests (e.g., `restricted-bucket.yaml`).
- **`resources/`**: Common templates, documentation snippets, and troubleshooting guides (e.g., `troubleshooting-guide.md`).

### 4. Safety Rails for Applying Manifests

Before applying any KCC manifest update to an existing resource, you MUST:

- **Verify Immutable Fields**: Call `./scripts/verify-immutable.sh <manifest-path>` to detect updates to fields (like `location`, `name`, `project-id`) that trigger destructive resource recreation.
- **Explain Impact**: If destructive changes are detected, you MUST warn the user and explain the downtime/data loss implications before requesting approval.

### 5. Emergency Recovery & Troubleshooting

If a resource is stuck in a "Deletion" or "Error" state:

- **Check for Abondon Flag**: Check if the resource has the `cnrm.cloud.google.com/deletion-policy: abandon` annotation. If it does, you will need to remove the annotation and then force delete the resource.
- **Force Delete**: Call `./scripts/force-delete.sh <kind> <name> [namespace]` to bypass Kubernetes finalizers and remove the resource from the cluster.
- **Orphan Warning**: Inform the user that force-deleting a KCC object may leave an orphaned resource in Google Cloud that requires manual cleanup.

### 6. Change Differentiation

When editing an existing resource, always generate a diff to summarize the change for reviewers or Git history:

- **Local Diff**:

  ```bash
  # Diff a local file against the cluster state
  kubectl diff -f modified-resource.yaml
  ```

- **Commit Summary Template**:

  ```text
  [KCC Change] Update <ResourceName> (<Kind>)
  - Field 'spec.foo' changed from 'X' to 'Y'
  - Impact: Ancillary service <ServiceName> will see updated <Config>
  ```

### 9. Best Practices

- **Namespaced Mode**: Prefer namespaced mode for better isolation.
- **Sensitive Data**: Use `spec.credential.secretRef` or similar for sensitive fields.
- **Resource Naming**: Use consistent naming conventions that match your Kubernetes/GCP standards.
- **Annotations**:
  - `cnrm.cloud.google.com/deletion-policy: abandon`: Keep GCP resource on KCC deletion.
  - `cnrm.cloud.google.com/state-into-spec: absent`: Prevents KCC from syncing GCP state back into the Kubernetes object (useful for avoiding reconciliation loops on fields like node counts).

## Common Resource Examples

### Compute Instance

```yaml
apiVersion: compute.cnrm.cloud.google.com/v1beta1
kind: ComputeInstance
metadata:
  name: instance-sample
  annotations:
    cnrm.cloud.google.com/project-id: "my-project-id"
spec:
  machineType: n1-standard-1
  zone: us-central1-a
  bootDisk:
    initializeParams:
      sourceImage: projects/debian-cloud/global/images/family/debian-11
  networkInterface:
    - networkRef:
        name: default
```

### Storage Bucket

```yaml
apiVersion: storage.cnrm.cloud.google.com/v1beta1
kind: StorageBucket
metadata:
  name: bucket-sample
spec:
  location: US
```

### Pub/Sub Topic & Subscription

```yaml
apiVersion: pubsub.cnrm.cloud.google.com/v1beta1
kind: PubSubTopic
metadata:
  name: order-events-topic
---
apiVersion: pubsub.cnrm.cloud.google.com/v1beta1
kind: PubSubSubscription
metadata:
  name: order-processor-sub
spec:
  topicRef:
    name: order-events-topic
  ackDeadlineSeconds: 30
```

Step 3: Implement the Inventory Tool

Create .agents/skills/kcc-ops/scripts/inventory.sh to discover KCC resources:

#!/bin/bash
# List all resources in the cnrm.cloud.google.com group
KCC_KINDS=$(kubectl api-resources --no-headers | awk '/\.cnrm\.cloud\.google\.com/ {print $1}')
KCC_KINDS_CSV=$(echo "$KCC_KINDS" | paste -sd, -)

printf "%-40s %-30s %-10s %s\n" "KIND" "NAME" "READY" "STATUS/MESSAGE"
kubectl get "$KCC_KINDS_CSV" -A -o custom-columns="KIND:.kind,NAME:.metadata.name,READY:.status.conditions[?(@.type=='Ready')].status,MSG:.status.conditions[?(@.type=='Ready')].message" --ignore-not-found --no-headers

Step 4: Add the Policy Vetting Logic

Create .agents/skills/kcc-ops/scripts/vet-policy.sh. This script will use gator to vet manifests against OPA policies:

#!/bin/bash
MANIFEST=$1
SKILL_ROOT=$(dirname "$(dirname "$0")")
POLICY_SRC="$SKILL_ROOT/resources/policies"

echo "=== OPA/Gatekeeper Policy Vetting ==="
if command -v gator >/dev/null 2>&1; then
    gator test -f "$MANIFEST" -f "$POLICY_SRC/templates" -f "$POLICY_SRC/constraints"
else
    echo "Gator not found. Skipping OPA audit."
fi

Step 5: Implement Immutable Field Protection

This is a critical safety rail. Create .agents/skills/kcc-ops/scripts/verify-immutable.sh:

#!/bin/bash
MANIFEST=$1
KIND=$(grep "^kind:" "$MANIFEST" | awk '{print $2}')
NAME=$(grep "name:" "$MANIFEST" | head -n 1 | awk '{print $2}')

# Check for changes in common immutable fields
IMMUTABLE_FIELDS=("location" "project-id" "name" "zone" "region")
TEMP_FILE=$(mktemp)
kubectl get "$KIND" "$NAME" -o yaml > "$TEMP_FILE" 2>/dev/null

for field in "${IMMUTABLE_FIELDS[@]}"; do
    NEW=$(grep "$field:" "$MANIFEST" | awk '{print $2}')
    OLD=$(grep "$field:" "$TEMP_FILE" | awk '{print $2}')
    if [ -n "$NEW" ] && [ -n "$OLD" ] && [ "$NEW" != "$OLD" ]; then
        echo "🚨 WARNING: Immutable field '$field' is changing! Potential resource recreation."
    fi
done
rm "$TEMP_FILE"

Step 6: Emergency Recovery (Force Delete)

Create .agents/skills/kcc-ops/scripts/force-delete.sh:

#!/bin/bash
KIND=$1; NAME=$2; NS=${3:-default}
echo "Removing finalizers for $KIND/$NAME in $NS..."
kubectl patch "$KIND" "$NAME" -n "$NS" -p '{"metadata":{"finalizers":null}}' --type=merge
kubectl delete "$KIND" "$NAME" -n "$NS" --wait=false

Step 7: Finalize Resources

Make all scripts executable:

chmod +x .agents/skills/kcc-ops/scripts/*.sh

10. Testing your new Skill

Now, start a new conversation and put your skill to the test:

Discovery: @kcc-ops Show me all KCC resources in my cluster.
Compliance: Create a file bucket.yaml with a StorageBucket. Ask: @kcc-ops Vet my bucket.yaml manifest.
Safety: Try to update the location of an existing bucket in bucket.yaml. Ask: @kcc-ops Verify my bucket.yaml for immutable changes.

Notice how the agent intelligently picks the correct script and follows the "Golden Rule" from your SKILL.md.

11. Securing the Agent

Giving an AI agent access to your terminal is powerful but requires controls.

Go to Antigravity - Settings - Terminal and explore the Allow List and Deny List.

Allow List: Add ls, kubectl get, and your skill scripts here.
Deny List: Add sudo, rm -rf, or other destructive commands to ensure the agent ALWAYS asks for permission.

12. Conclusion

Congratulations! You've gone from installing Antigravity to building a high-fidelity KCC Operations Skill.

You've learned:

How to extend the agent with custom bash tools.
How to encode operational "Golden Rules" into a SKILL.md.
How to provide safety rails for complex infrastructure management.

What's Next?

Expand your resources/policies folder with more OPA constraints, or add a check-health.sh script to automate cluster readiness checks!