تسلط بر عملیات KCC با Google Antigravity

۱. مقدمه

در این آزمایشگاه کد، شما با Google Antigravity (که در ادامه سند به آن Antigravity گفته می‌شود) آشنا خواهید شد، یک پلتفرم توسعه عامل‌محور که IDE را به دوران عامل‌محوری تکامل می‌دهد.

برخلاف دستیارهای کدنویسی استاندارد که فقط خطوط را به صورت خودکار تکمیل می‌کنند، Antigravity یک «کنترل ماموریت» برای مدیریت عامل‌های خودمختار ارائه می‌دهد که می‌توانند برنامه‌ریزی، کدنویسی و حتی مرور وب را برای کمک به شما در ساخت و ساز انجام دهند.

آنتی‌گراویتی به عنوان یک پلتفرم عامل-محور طراحی شده است. این پلتفرم فرض می‌کند که هوش مصنوعی فقط ابزاری برای نوشتن کد نیست، بلکه یک بازیگر مستقل است که قادر به برنامه‌ریزی، اجرا، اعتبارسنجی و تکرار وظایف مهندسی پیچیده با حداقل دخالت انسان است.

آنچه یاد خواهید گرفت

  • نصب و پیکربندی آنتی گراویتی
  • بررسی مفاهیم کلیدی Antigravity مانند Agent Manager، Editor، Browser و موارد دیگر.
  • ساخت یک مهارت KCC Ops در سطح تولید از ابتدا برای مدیریت منابع Google Cloud با ایمنی و انطباق.

آنچه نیاز دارید

در حال حاضر Antigravity به صورت پیش‌نمایش برای حساب‌های جیمیل شخصی در دسترس است. این برنامه با سهمیه رایگان برای استفاده از مدل‌های برتر ارائه می‌شود.

آنتی‌گراویتی باید به صورت محلی روی سیستم شما نصب شود. این محصول روی مک، ویندوز و برخی توزیع‌های لینوکس موجود است. علاوه بر دستگاه خودتان، به موارد زیر نیز نیاز خواهید داشت:

  • یک حساب جیمیل (حساب جیمیل شخصی).
  • یک حساب کاربری گوگل کلود و پروژه گوگل کلود
  • یک مرورگر وب مانند کروم که از کنسول گوگل کلود و کلود شل پشتیبانی می‌کند

۲. تنظیمات و الزامات

راه‌اندازی پروژه

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

این آزمایشگاه کد، برای کاربران و توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است.

۳. نصب

اگر Antigravity را از قبل نصب نکرده‌اید، بیایید با نصب Antigravity شروع کنیم. در حال حاضر این محصول برای پیش‌نمایش در دسترس است و می‌توانید از حساب Gmail شخصی خود برای شروع کار با آن استفاده کنید.

به صفحه دانلودها بروید و روی نسخه سیستم عامل مناسب برای مورد خود کلیک کنید. نصب کننده برنامه را اجرا کنید و آن را روی دستگاه خود نصب کنید. پس از اتمام نصب، برنامه Antigravity را اجرا کنید.

مراحل کلیدی در طول راه‌اندازی:

  • انتخاب جریان راه‌اندازی: ما شروع تازه‌ای را برای این آزمایشگاه کد توصیه می‌کنیم.
  • توسعه مبتنی بر بررسی (توصیه می‌شود) : این گزینه را انتخاب کنید. این به عامل اجازه می‌دهد تا تصمیمی بگیرد و برای تأیید به کاربر مراجعه کند، که برای عملیات زیرساختی بسیار مهم است.

در مرحله بعد، ویرایشگر خود را پیکربندی کنید و وارد گوگل شوید. در نهایت، شرایط استفاده را بپذیرید.

۴. راه‌اندازی زیرساخت: رابط GKE و پیکربندی

قبل از اینکه بتوانید این مهارت را کسب کنید، به یک محیط Google Cloud نیاز دارید که Config Connector (KCC) به صورت دستی نصب شده و در حالت Namespaced Mode پیکربندی شده باشد. این به شما امکان می‌دهد منابع GCP را به عنوان اشیاء Kubernetes مدیریت کنید.

مرحله 0: محیط خود را آماده کنید

۱. پیش‌نیازهای کلاستر

یک کلاستر 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}

۲. اپراتور Config Connector را نصب کنید

اپراتور، نصب شما را به‌روز نگه می‌دارد.

# 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

۳. پیکربندی حالت Namespaced

یک منبع 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

۴. ایجاد یک هویت و فضای نام

برای این آزمایش، ما از فضای نام default و یک حساب کاربری سرویس گوگل (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"

۵. پیکربندی فضای نام

یک 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

۶. تأیید نصب

صبر کنید تا کنترلر برای فضای نام 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

۵. مدیر عامل: کنترل ماموریت

آنتی‌گراویتی (Antigravity) از پایه و اساس متن‌باز ویژوال استودیو کد (VS Code) منشعب شده است، اما تجربه کاربری را به طور اساسی تغییر می‌دهد تا مدیریت عامل را بر ویرایش متن اولویت دهد. رابط کاربری به دو پنجره اصلی مجزا تقسیم می‌شود: Editor و Agent Manager ).

مدیر عامل

پس از اجرای Antigravity، کاربر معمولاً با مدیر عامل (Agent Manager) مواجه می‌شود. این رابط کاربری به عنوان داشبورد کنترل ماموریت عمل می‌کند. این رابط برای هماهنگی سطح بالا طراحی شده است و به توسعه‌دهندگان اجازه می‌دهد تا چندین عامل (agent) را که به صورت غیرهمزمان در فضاهای کاری یا وظایف مختلف کار می‌کنند، ایجاد، نظارت و با آنها تعامل داشته باشند.

در این دیدگاه، توسعه‌دهنده به عنوان یک معمار عمل می‌کند. آن‌ها اهداف سطح بالا را تعریف می‌کنند. هر یک از این درخواست‌ها، یک نمونه عامل اختصاصی ایجاد می‌کند. رابط کاربری، تجسمی از این جریان‌های کاری موازی را ارائه می‌دهد و وضعیت هر عامل، مصنوعاتی که تولید کرده‌اند (طرح‌ها، نتایج، تفاوت‌ها) و هرگونه درخواست در انتظار برای تأیید انسانی را نمایش می‌دهد.

۶. مرورگر ضد جاذبه و مصنوعات

آنتی‌گراویتی همزمان با برنامه‌ریزی و انجام کار خود، مصنوعات (Artifacts) ایجاد می‌کند. این مصنوعات شامل فایل‌های نشانه‌گذاری غنی، نمودارهای معماری، تصاویر، ضبط‌های مرورگر و تفاوت‌های کد هستند.

مصنوعات «شکاف اعتماد» را حل می‌کنند

وقتی یک عامل ادعا می‌کند که «من اشکال را برطرف کرده‌ام»، توسعه‌دهنده قبلاً مجبور بود کد را بخواند تا تأیید کند. در Antigravity، عامل یک مصنوع تولید می‌کند تا این را اثبات کند.

مصنوعات

اینها مصنوعات اصلی تولید شده توسط Antigravity هستند:

  • Task Lists : یک برنامه ساختاریافته که قبل از نوشتن کد ایجاد می‌شود.
  • Implementation Plan : تغییرات معماری‌شده با جزئیات فنی.
  • Walkthrough : خلاصه‌ای از تغییرات و نحوه آزمایش آنها.
  • Browser Recordings : ضبط‌های ویدیویی از جلسات مرورگر برای تأیید رابط کاربری.

مرورگر ضد جاذبه

وقتی عامل نیاز به تعامل با وب دارد، یک زیرعامل مرورگر را فراخوانی می‌کند. این زیرعامل می‌تواند کلیک کند، اسکرول کند، تایپ کند و گزارش‌های کنسول را بخواند. این زیرعامل از یک مدل تخصصی برای کار روی صفحاتی که در مرورگر تحت مدیریت Antigravity باز هستند، استفاده می‌کند.

۷. تجربه ویراستاری

این ویرایشگر، حس آشنایی با VS Code را حفظ کرده است. این ویرایشگر شامل مرورگر فایل استاندارد، هایلایت سینتکس و اکوسیستم افزونه‌ها می‌شود.

ویژگی‌های ویرایشگر کلیدی:

  • تکمیل خودکار : پیشنهادات هوشمند با فشار دادن Tab پذیرفته می‌شوند.
  • تب برای وارد کردن : پیشنهاد می‌کند وابستگی‌های از دست رفته را اضافه کنید.
  • دستورات ( Cmd + I ) : تکمیل‌های درون‌خطی را با استفاده از زبان طبیعی فعال می‌کند.
  • پنل کناری نماینده ( Cmd + L ) : پنل نماینده را برای پرسیدن سوال یا ارجاع به فایل‌ها با استفاده از @ فعال یا غیرفعال کنید.

۸. ارائه بازخورد

در قلب Antigravity، توانایی آن در جمع‌آوری آسان بازخورد شما نهفته است. این مصنوعات راهی برای شما هستند تا بتوانید در قالب نظرات به سبک Google docs ، بازخورد خود را به عامل ارائه دهید.

هر زمان که نظری به یک طرح یا وظیفه اضافه می‌کنید، حتماً ارسال نظر را فراموش نکنید. این کار، عامل را در جهتی که شما می‌خواهید هدایت می‌کند.

۹. تقویت مهارت عملیات KCC

حالا که پلتفرم را درک کردید، بیایید مهارت KCC Ops را بسازیم.

رابط پیکربندی Kubernetes (KCC) به شما امکان می‌دهد منابع GCP را به عنوان اشیاء K8s مدیریت کنید. با این حال، برای جلوگیری از رانش پیکربندی، نقض انطباق و بازآفرینی تصادفی منابع، به ریل‌های ایمنی نیاز دارد.

مرحله ۱: مهارت را ساختارمند کنید

در ریشه فضای کاری خود، ساختار دایرکتوری مربوط به مهارت خود را ایجاد کنید:

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

مرحله ۲: 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
```

مرحله ۳: پیاده‌سازی ابزار فهرست موجودی

برای کشف منابع KCC .agents/skills/kcc-ops/scripts/inventory.sh را ایجاد کنید: 

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

مرحله ۴: منطق بررسی سیاست‌ها را اضافه کنید

.agents/skills/kcc-ops/scripts/vet-policy.sh را ایجاد کنید. این اسکریپت gator برای بررسی مانیفست‌ها در برابر سیاست‌های 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"

مرحله ۶: بازیابی اضطراری (حذف اجباری)

.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

مرحله ۷: منابع را نهایی کنید

همه اسکریپت‌ها را قابل اجرا کنید: 

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

۱۰. آزمایش مهارت جدیدتان

حالا، یک مکالمه جدید شروع کنید و مهارت خود را محک بزنید:

  1. کشف : @kcc-ops Show me all KCC resources in my cluster.
  2. انطباق : یک فایل bucket.yaml با StorageBucket ایجاد کنید. از: @kcc-ops Vet my bucket.yaml manifest.
  3. ایمنی : سعی کنید location یک سطل موجود در bucket.yaml را به‌روزرسانی کنید. بپرسید: @kcc-ops Verify my bucket.yaml for immutable changes.

توجه کنید که چگونه عامل هوشمندانه اسکریپت صحیح را انتخاب می‌کند و از «قانون طلایی» SKILL.md شما پیروی می‌کند.

۱۱. ایمن‌سازی عامل

دسترسی دادن به یک عامل هوش مصنوعی به ترمینال شما قدرتمند است اما نیاز به کنترل دارد.

به Antigravity - Settings - Terminal بروید و لیست مجاز و لیست ممنوع را بررسی کنید.

  • فهرست مجاز : ls ، kubectl get و اسکریپت‌های مهارت خود را اینجا اضافه کنید.
  • لیست رد درخواست‌ها : برای اطمینان از اینکه عامل همیشه درخواست اجازه می‌کند sudo ، rm -rf یا سایر دستورات مخرب را اضافه کنید.

۱۲. نتیجه‌گیری

تبریک! شما از نصب Antigravity به ساخت یک مهارت عملیاتی KCC با کیفیت بالا رسیده‌اید.

شما آموخته‌اید:

  • نحوه گسترش عامل با ابزارهای سفارشی bash.
  • چگونه «قوانین طلایی» عملیاتی را در یک SKILL.md کدگذاری کنیم؟
  • چگونه می‌توان برای مدیریت زیرساخت‌های پیچیده، ریل‌های ایمنی فراهم کرد؟

قدم بعدی چیست؟

پوشه resources/policies خود را با محدودیت‌های OPA بیشتر گسترش دهید، یا یک اسکریپت check-health.sh برای خودکارسازی بررسی‌های آمادگی کلاستر اضافه کنید!