การควบคุมการดำเนินงาน KCC ด้วย Google Antigravity

1. บทนำ

ใน Codelab นี้ คุณจะได้เรียนรู้เกี่ยวกับ Google Antigravity (ต่อไปในเอกสารนี้จะเรียกว่า Antigravity) ซึ่งเป็นแพลตฟอร์มการพัฒนาด้าน Agentic AI ที่พัฒนา IDE ไปสู่ยุค Agent-First

Antigravity ไม่เหมือนผู้ช่วยเขียนโค้ดมาตรฐานที่เพียงแค่เติมบรรทัดให้โดยอัตโนมัติ แต่มี "ศูนย์ควบคุมภารกิจ" สำหรับจัดการ Agent แบบอัตโนมัติที่สามารถวางแผน เขียนโค้ด และแม้แต่ท่องเว็บเพื่อช่วยคุณสร้าง

Antigravity ออกแบบมาให้เป็นแพลตฟอร์มที่เน้น Agent เป็นอันดับแรก ซึ่งสมมติว่า AI ไม่ใช่แค่เครื่องมือสำหรับเขียนโค้ด แต่เป็นผู้ดำเนินการแบบอัตโนมัติที่สามารถวางแผน ดำเนินการ ตรวจสอบ และทำซ้ำงานด้านวิศวกรรมที่ซับซ้อนโดยมีการแทรกแซงจากมนุษย์น้อยที่สุด

สิ่งที่คุณจะได้เรียนรู้

การติดตั้งและกำหนดค่า Antigravity
สำรวจแนวคิดหลักของ Antigravity เช่น Agent Manager, Editor, Browser และอื่นๆ
สร้างทักษะการดำเนินการ KCC ระดับการผลิตตั้งแต่ต้นเพื่อจัดการทรัพยากร Google Cloud อย่างปลอดภัยและเป็นไปตามข้อกำหนด

สิ่งที่คุณต้องมี

ปัจจุบัน Antigravity พร้อมให้บริการในเวอร์ชันตัวอย่างสำหรับบัญชี Gmail ส่วนตัว โดยจะมีโควต้าฟรีสำหรับใช้โมเดลชั้นนำ

คุณต้องติดตั้ง Antigravity ในระบบของคุณ ผลิตภัณฑ์นี้พร้อมให้บริการใน Mac, Windows และ Linux บางรุ่น นอกจากเครื่องของคุณเองแล้ว คุณจะต้องมีสิ่งต่อไปนี้ด้วย

บัญชี Gmail (บัญชี Gmail ส่วนตัว)
บัญชี Google Cloud และโปรเจ็กต์ Google Cloud
เว็บเบราว์เซอร์ เช่น Chrome ที่รองรับ คอนโซล Google Cloud และ Cloud Shell

2. การตั้งค่าและข้อกำหนด

การตั้งค่าโปรเจ็กต์

สร้างโปรเจ็กต์ Google Cloud

ในคอนโซล Google Cloud ในหน้าตัวเลือกโปรเจ็กต์ ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud
ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่

Codelab นี้ออกแบบมาสำหรับผู้ใช้และนักพัฒนาซอฟต์แวร์ทุกระดับ (รวมถึงผู้เริ่มต้น)

3. การติดตั้ง

หากยังไม่ได้ติดตั้ง Antigravity ให้เริ่มติดตั้ง Antigravity กันเลย ปัจจุบันผลิตภัณฑ์นี้พร้อมให้ใช้งานในเวอร์ชันตัวอย่าง และคุณสามารถใช้บัญชี Gmail ส่วนตัวเพื่อเริ่มต้นใช้งานได้

ไปที่หน้าดาวน์โหลด แล้วคลิกเวอร์ชันระบบปฏิบัติการที่เหมาะสมกับกรณีของคุณ เปิดตัวโปรแกรมติดตั้งแอปพลิเคชันและติดตั้งแอปพลิเคชันในเครื่อง เมื่อติดตั้งเสร็จแล้ว ให้เปิดแอปพลิเคชัน Antigravity

ขั้นตอนสำคัญระหว่างการตั้งค่ามีดังนี้

เลือกขั้นตอนการตั้งค่า: เราขอแนะนำให้เริ่มจากศูนย์สำหรับโค้ดแล็บนี้
การพัฒนาที่ขับเคลื่อนด้วยการตรวจสอบ (แนะนำ): เลือกตัวเลือกนี้ ซึ่งช่วยให้เอเจนต์ตัดสินใจและกลับมาขออนุมัติจากผู้ใช้ได้ ซึ่งเป็นสิ่งสำคัญสำหรับการดำเนินการด้านโครงสร้างพื้นฐาน

จากนั้นกำหนดค่า Editor และลงชื่อเข้าใช้ Google สุดท้าย ให้ยอมรับข้อกำหนดในการใช้งาน

4. การตั้งค่าโครงสร้างพื้นฐาน: GKE และ Config Connector

ก่อนที่จะสร้างทักษะได้ คุณต้องมีสภาพแวดล้อม Google Cloud ที่ติดตั้ง Config Connector (KCC) ด้วยตนเองและกำหนดค่าในโหมด Namespaced ซึ่งช่วยให้คุณจัดการทรัพยากร GCP เป็นออบเจ็กต์ Kubernetes ได้

ขั้นตอนที่ 0: เตรียมสภาพแวดล้อม

1. ข้อกำหนดเบื้องต้นของคลัสเตอร์

สร้างคลัสเตอร์ GKE ใหม่โดยเปิดใช้ฟีเจอร์ที่จำเป็น

# 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. ติดตั้ง Config Connector Operator

โดยผู้ให้บริการจะอัปเดตการติดตั้งให้เป็นเวอร์ชันล่าสุดอยู่เสมอ

# 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. กำหนดค่าโหมด Namespace

สร้างทรัพยากร ConfigConnector เพื่อระบุโหมดการทำงาน

# 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. สร้างข้อมูลประจำตัวและเนมสเปซ

สำหรับแล็บนี้ เราจะใช้เนมสเปซ default และบัญชีบริการของ Google (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. กำหนดค่าเนมสเปซ

สร้าง ConfigConnectorContext เพื่อดูเนมสเปซ

# 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. ยืนยันการติดตั้ง

รอให้ตัวควบคุมพร้อมสำหรับเนมสเปซ default

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 แยกจากพื้นฐานของ Visual Studio Code (VS Code) แบบโอเพนซอร์ส แต่เปลี่ยนประสบการณ์ของผู้ใช้อย่างสิ้นเชิงเพื่อจัดลำดับความสำคัญของการจัดการเอเจนต์มากกว่าการแก้ไขข้อความ อินเทอร์เฟซแบ่งออกเป็น 2 หน้าต่างหลักที่แตกต่างกัน ได้แก่ Editor และ Agent Manager

ผู้จัดการตัวแทน

เมื่อเปิดตัว Antigravity โดยปกติแล้วผู้ใช้จะได้รับการต้อนรับจาก Agent Manager อินเทอร์เฟซนี้ทำหน้าที่เป็นแดชบอร์ดศูนย์ควบคุม ออกแบบมาเพื่อการจัดการเป็นกลุ่มระดับสูง ซึ่งช่วยให้นักพัฒนาซอฟต์แวร์สามารถสร้าง ตรวจสอบ และโต้ตอบกับเอเจนต์หลายตัวที่ทำงานแบบอะซิงโครนัสในพื้นที่ทำงานหรือภารกิจต่างๆ

ในมุมมองนี้ นักพัฒนาแอปจะทำหน้าที่เป็นสถาปนิก โดยจะกำหนดวัตถุประสงค์ระดับสูง คำขอแต่ละรายการเหล่านี้จะสร้างอินสแตนซ์ของตัวแทนเฉพาะ UI จะแสดงภาพของสตรีมงานแบบคู่ขนานเหล่านี้ โดยแสดงสถานะของตัวแทนแต่ละราย Artifact ที่ตัวแทนสร้างขึ้น (แผน ผลลัพธ์ ความแตกต่าง) และคำขอที่รอดำเนินการซึ่งต้องได้รับการอนุมัติจากเจ้าหน้าที่

6. Antigravity Browser และ Artifacts

Antigravity สร้างอาร์ติแฟกต์ขณะวางแผนและทำงาน ซึ่งได้แก่ ไฟล์ Markdown แบบริช แผนภาพสถาปัตยกรรม รูปภาพ การบันทึกในเบราว์เซอร์ และส่วนต่างของโค้ด

อาร์ติแฟกต์ช่วยแก้ปัญหา "ช่องว่างด้านความน่าเชื่อถือ"

เมื่อตัวแทนกล่าวว่า "ฉันแก้ไขข้อบกพร่องแล้ว" ก่อนหน้านี้นักพัฒนาซอฟต์แวร์ต้องอ่านโค้ดเพื่อยืนยัน ใน Antigravity เอเจนต์จะสร้างอาร์ติแฟกต์เพื่อพิสูจน์

อาร์ติแฟกต์

อาร์ติแฟกต์หลักที่ Antigravity สร้างขึ้นมีดังนี้

Task Lists: แผนที่มีโครงสร้างซึ่งสร้างขึ้นก่อนเขียนโค้ด
Implementation Plan: การเปลี่ยนแปลงที่ออกแบบไว้พร้อมรายละเอียดทางเทคนิค
Walkthrough: สรุปการเปลี่ยนแปลงและวิธีทดสอบ
Browser Recordings: บันทึกวิดีโอของเซสชันเบราว์เซอร์สำหรับการยืนยัน UI

Antigravity Browser

เมื่อตัวแทนต้องการโต้ตอบกับเว็บ ตัวแทนจะเรียกใช้ตัวแทนย่อยของเบราว์เซอร์ เอเจนต์ย่อยนี้สามารถคลิก เลื่อน พิมพ์ และอ่านบันทึกคอนโซลได้ โดยใช้โมเดลเฉพาะเพื่อดำเนินการในหน้าที่เปิดภายในเบราว์เซอร์ที่ Antigravity จัดการ

7. ประสบการณ์การใช้งานของเอดิเตอร์

โดยตัวแก้ไขจะยังคงความคุ้นเคยของ VS Code ไว้ ซึ่งรวมถึง File Explorer มาตรฐาน การไฮไลต์ไวยากรณ์ และระบบนิเวศของส่วนขยาย

ฟีเจอร์หลักของตัวแก้ไขคีย์

เติมข้อความอัตโนมัติ: คำแนะนำอัจฉริยะที่ยอมรับได้โดยการกด Tab
แท็บเพื่อนำเข้า: แนะนำให้เพิ่มการอ้างอิงที่ขาดหายไป
คำสั่ง (Cmd + I): เรียกใช้การเติมข้อความในบรรทัดโดยใช้ภาษาธรรมชาติ
แผงด้านข้างของตัวแทน (Cmd + L): สลับแผงตัวแทนเพื่อถามคำถามหรืออ้างอิงไฟล์โดยใช้ @

8. การแสดงความคิดเห็น

หัวใจสำคัญของ Antigravity คือความสามารถในการรวบรวมความคิดเห็นของคุณได้อย่างง่ายดาย อาร์ติแฟกต์เหล่านี้เป็นวิธีที่คุณใช้แสดงความคิดเห็นต่อตัวแทนในความคิดเห็นสไตล์ Google เอกสาร

เมื่อใดก็ตามที่คุณเพิ่มความคิดเห็นในแผนหรือในงาน อย่าลืมส่งความคิดเห็น ซึ่งจะช่วยให้ Agent ทำงานในทิศทางที่คุณต้องการ

9. การสร้างทักษะการปฏิบัติงานของ KCC

เมื่อคุณเข้าใจแพลตฟอร์มแล้ว เรามาสร้างทักษะการปฏิบัติงานของ KCC กัน

Kubernetes Config Connector (KCC) ช่วยให้คุณจัดการทรัพยากร GCP เป็นออบเจ็กต์ K8s ได้ อย่างไรก็ตาม ต้องมีแนวทางด้านความปลอดภัยเพื่อป้องกันการกำหนดค่าที่ไม่ตรงกัน การละเมิดการปฏิบัติตามข้อกำหนด และการสร้างทรัพยากรใหม่โดยไม่ตั้งใจ

ขั้นตอนที่ 1: สร้างโครงสร้างทักษะ

สร้างโครงสร้างไดเรกทอรีสำหรับทักษะในรูทของพื้นที่ทำงาน โดยทำดังนี้

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

ขั้นตอนที่ 2: สร้าง SKILL.md (ส่วนสมอง)

SKILL.md กำหนดข้อมูลเมตาและ "กฎทอง" หลักสำหรับเอเจนต์ สร้าง .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
```

ขั้นตอนที่ 3: ติดตั้งใช้งานเครื่องมือสินค้าคงคลัง

สร้าง .agents/skills/kcc-ops/scripts/inventory.sh เพื่อค้นหาแหล่งข้อมูลของ KCC

#!/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

ขั้นตอนที่ 4: เพิ่มตรรกะการตรวจสอบนโยบาย

สร้าง .agents/skills/kcc-ops/scripts/vet-policy.sh สคริปต์นี้จะใช้ gator เพื่อตรวจสอบไฟล์ Manifest เทียบกับนโยบาย OPA

#!/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

ขั้นตอนที่ 5: ใช้การป้องกันฟิลด์ที่ไม่เปลี่ยนแปลง

นี่เป็นแนวทางด้านความปลอดภัยที่สำคัญ สร้าง .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"

ขั้นตอนที่ 6: การกู้คืนฉุกเฉิน (บังคับลบ)

สร้าง .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

ขั้นตอนที่ 7: ทรัพยากรขั้นสุดท้าย

ทำให้สคริปต์ทั้งหมดเรียกใช้งานได้

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

10. การทดสอบทักษะใหม่

ตอนนี้ให้เริ่มการสนทนาใหม่และทดสอบทักษะของคุณ

การค้นพบ: @kcc-ops Show me all KCC resources in my cluster.
การปฏิบัติตามข้อกำหนด: สร้างไฟล์ bucket.yaml ด้วย StorageBucket ถาม: @kcc-ops Vet my bucket.yaml manifest.
ความปลอดภัย: ลองอัปเดต location ของที่เก็บข้อมูลที่มีอยู่ใน bucket.yaml ถาม: @kcc-ops Verify my bucket.yaml for immutable changes.

สังเกตว่าเอเจนต์เลือกสคริปต์ที่ถูกต้องอย่างชาญฉลาดและปฏิบัติตาม "กฎทอง" จากSKILL.md

11. การรักษาความปลอดภัยของ Agent

การให้สิทธิ์เข้าถึงเทอร์มินัลแก่ AI Agent เป็นเรื่องที่มีประสิทธิภาพ แต่ต้องมีการควบคุม

ไปที่ Antigravity - Settings - Terminal แล้วสำรวจรายการที่อนุญาตและรายการที่ไม่อนุญาต

รายการที่อนุญาต: เพิ่ม ls, kubectl get และสคริปต์ทักษะของคุณที่นี่
รายการที่ไม่อนุญาต: เพิ่ม sudo, rm -rf หรือคำสั่งที่เป็นอันตรายอื่นๆ เพื่อให้มั่นใจว่าเอเจนต์จะขอสิทธิ์เสมอ

12. บทสรุป

ยินดีด้วย คุณได้เปลี่ยนจากการติดตั้ง Antigravity ไปเป็นการสร้าง KCC Operations Skill ที่มีความเที่ยงตรงสูง

คุณได้เรียนรู้สิ่งต่อไปนี้

วิธีขยาย Agent ด้วยเครื่องมือ Bash ที่กำหนดเอง
วิธีเข้ารหัส "กฎทอง" ด้านการปฏิบัติงานลงใน SKILL.md
วิธีจัดเตรียมแนวทางด้านความปลอดภัยสำหรับการจัดการโครงสร้างพื้นฐานที่ซับซ้อน

ขั้นตอนถัดไป

ขยายโฟลเดอร์ resources/policies ด้วยข้อจำกัด OPA เพิ่มเติม หรือเพิ่มสคริปต์ check-health.sh เพื่อตรวจสอบความพร้อมของคลัสเตอร์โดยอัตโนมัติ