إتقان عمليات KCC باستخدام Google Antigravity

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على Google Antigravity (يُشار إليها باسم Antigravity في بقية المستند)، وهي منصة تطوير قائمة على وكلاء الذكاء الاصطناعي، وتطوّر بيئة التطوير المتكاملة لتصبح متوافقة مع عصر الذكاء الاصطناعي الوكيل.

على عكس مساعدي الترميز العاديين الذين يكملون الأسطر تلقائيًا، توفّر Antigravity "مركز التحكّم" لإدارة الوكلاء المستقلين الذين يمكنهم التخطيط والترميز وحتى تصفّح الويب لمساعدتك في إنشاء التطبيقات.

تم تصميم Antigravity كمنصة تستند إلى الذكاء الاصطناعي الوكيل. ويفترض ذلك أنّ الذكاء الاصطناعي ليس مجرد أداة لكتابة الرموز البرمجية، بل هو عامل مستقل قادر على التخطيط لمهام هندسية معقّدة وتنفيذها والتحقّق منها وتكرارها بأقل قدر من التدخّل البشري.

ما ستتعلمه

• تثبيت Antigravity وإعداده
• استكشاف المفاهيم الرئيسية في Antigravity، مثل "مدير الوكلاء" و"المحرّر" و"المتصفّح" وغير ذلك
• إنشاء مهارة KCC Ops مناسبة لمرحلة الإنتاج من البداية لإدارة موارد Google Cloud بأمان وامتثال

المتطلبات

تتوفّر ميزة Antigravity حاليًا كمعاينة لحسابات Gmail الشخصية. يتضمّن حصة مجانية لاستخدام النماذج المميزة.

يجب تثبيت Antigravity على نظامك. يتوفّر المنتج على أجهزة Mac وWindows وبعض توزيعات Linux. بالإضافة إلى جهازك، ستحتاج إلى ما يلي:

• حساب Gmail (حساب Gmail شخصي)
• حساب على Google Cloud ومشروع على Google Cloud
• متصفّح ويب، مثل Chrome، متوافق مع "وحدة تحكّم Google Cloud" وCloud Shell

2. الإعداد والمتطلبات

إعداد المشروع

إنشاء مشروع على Google Cloud

1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

تم تصميم هذا الدرس التطبيقي حول الترميز للمستخدمين والمطوّرين من جميع المستويات (بما في ذلك المبتدئين).

3- تثبيت

إذا لم يكن تطبيق Antigravity مثبّتًا على جهازك، لنبدأ بتثبيته. يتوفّر المنتج حاليًا للمعاينة ويمكنك استخدام حسابك الشخصي على Gmail لبدء استخدامه.

انتقِل إلى صفحة عمليات التنزيل وانقر على إصدار نظام التشغيل المناسب لحالتك. شغِّل مثبِّت التطبيق وثبِّت التطبيق نفسه على جهازك. بعد اكتمال عملية التثبيت، شغِّل تطبيق Antigravity.

الخطوات الرئيسية أثناء عملية الإعداد:

• اختيار مسار الإعداد: ننصحك بالبدء من جديد في هذا الدرس العملي.
• التطوير المستند إلى المراجعة (يُنصح به): حدِّد هذا الخيار. ويسمح هذا الخيار للوكيل باتخاذ قرار والعودة إلى المستخدم للحصول على الموافقة، وهو أمر بالغ الأهمية لعمليات البنية الأساسية.

بعد ذلك، اضبط إعدادات المحرّر وسجِّل الدخول إلى Google. أخيرًا، اقبل بنود الاستخدام.

4. إعداد البنية الأساسية: GKE وConfig Connector

قبل إنشاء المهارة، تحتاج إلى بيئة Google Cloud مثبَّت فيها Config Connector (KCC) يدويًا وتم إعدادها في وضع تحديد نطاق الاسم. يتيح لك ذلك إدارة موارد Google Cloud Platform كعناصر 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

يحرص المشغّل على تحديث عملية التثبيت باستمرار.

# 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. ضبط "الوضع ذو مساحة الاسم"

أنشئ مورد 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) المفتوح المصدر، ولكنّها تغيّر تجربة المستخدم بشكل جذري لإعطاء الأولوية لإدارة الوكلاء على تعديل النصوص. تنقسم الواجهة إلى نافذتَين أساسيتَين مختلفتَين: Editor وAgent Manager.

مدير موظّفي الدعم

عند تشغيل Antigravity، يظهر عادةً "مدير وكلاء الذكاء الاصطناعي" للمستخدم. تعمل هذه الواجهة كلوحة بيانات مركز التحكّم. تم تصميمها لتنفيذ عمليات التنسيق على مستوى عالٍ، ما يتيح للمطوّرين إنشاء العديد من البرامج الآلية ومراقبتها والتفاعل معها بشكل غير متزامن في مساحات عمل أو مهام مختلفة.

في طريقة العرض هذه، يعمل المطوّر كمهندس معماري. وهي تحدّد الأهداف العالية المستوى. يؤدي كل طلب من هذه الطلبات إلى إنشاء مثيل مخصّص للوكيل. توفر واجهة المستخدم تمثيلاً مرئيًا لمهام العمل المتوازية هذه، وتعرض حالة كل وكيل والنتائج التي أنتجها (الخطط والنتائج والاختلافات) وأي طلبات معلّقة للحصول على موافقة بشرية.

6. Antigravity Browser & Artifacts

تنشئ Antigravity قطعًا أثرية أثناء التخطيط وإنجاز العمل. وهي ملفات markdown غنية، ومخططات معمارية، وصور، وتسجيلات للمتصفّح، واختلافات في الرموز البرمجية.

تساعد النتائج الاصطناعية في سدّ "فجوة الثقة"

عندما يدّعي أحد العملاء أنّه "أصلح الخطأ"، كان على المطوّر في السابق قراءة الرمز للتحقّق من ذلك. في لعبة Antigravity، ينتج الوكيل قطعة أثرية لإثبات ذلك.

العناصر

في ما يلي العناصر الرئيسية التي تنتجها Antigravity:

• Task Lists: خطة منظَّمة يتم إنشاؤها قبل كتابة الرمز البرمجي.
• ‫Implementation Plan: تغييرات في التصميم مع تفاصيل فنية
• Walkthrough: ملخّص بالتغييرات وكيفية اختبارها
• ‫Browser Recordings: سجلّات فيديو لجلسات المتصفّح من أجل التحقّق من واجهة المستخدم

Antigravity Browser

عندما يحتاج الوكيل إلى التفاعل مع الويب، يستدعي وكيلًا فرعيًا للمتصفّح. يمكن لهذا الوكيل الفرعي النقر والتمرير والكتابة وقراءة سجلّات وحدة التحكّم. يستخدم هذا الوضع نموذجًا متخصصًا للعمل على الصفحات المفتوحة في المتصفّح الذي تديره Antigravity.

7. تجربة المحرّر

يحتفظ المحرّر بميزات VS Code المألوفة. ويشمل مستكشف الملفات العادي وتمييز بناء الجملة والنظام الشامل للإضافات.

ميزات "محرّر المفاتيح":

• الإكمال التلقائي: اقتراحات ذكية يتم قبولها بالضغط على Tab
• علامة التبويب "استيراد": تقترح إضافة التبعيات الناقصة.
• الأوامر (Cmd + I): يمكنك تشغيل ميزة "الإكمال التلقائي المضمّن" باستخدام اللغة الطبيعية.
• اللوحة الجانبية للوكيل (Cmd + L): يمكنك تبديل لوحة الوكيل لطرح الأسئلة أو الرجوع إلى الملفات باستخدام @.

8. تقديم الملاحظات

تتمثّل الميزة الأساسية في Antigravity في قدرتها على جمع ملاحظاتك بسهولة. تتيح لك هذه العناصر تقديم ملاحظات إلى الوكيل في تعليقات بأسلوب "مستندات Google".

عند إضافة تعليق إلى خطة أو مهمة، احرص على إرسال التعليق. يوجّه هذا الإجراء الوكيل في الاتجاه الذي تريده.

9- تطوير مهارات فريق العمليات في "مركز المحتوى الخاص بالأطفال"

بعد أن تعرّفت على المنصة، لننشئ مهارة عمليات KCC.

تتيح لك أداة Kubernetes Config Connector (KCC) إدارة موارد Google Cloud Platform ككائنات 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 لاستكشاف موارد "مركز مساعدة Chrome"، اتّبِع الخطوات التالية:

#!/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 للتحقّق من صحة بيانات البيان وفقًا لسياسات 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. اختبار مهارتك الجديدة

الآن، ابدأ محادثة جديدة واختبِر مهاراتك:

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.

11. تأمين الوكيل

يُعدّ منح إذن الوصول إلى الجهاز الطرفي لأحد وكلاء الذكاء الاصطناعي أمرًا فعّالاً، ولكنّه يتطلّب عناصر تحكّم.

انتقِل إلى Antigravity - الإعدادات - الوحدة الطرفية (Antigravity - Settings - Terminal) واستكشِف القائمة المسموح بها (Allow List) والقائمة المحظورة (Deny List).

• قائمة السماح: أضِف ls وkubectl get ونصوص المهارات هنا.
• قائمة الرفض: أضِف sudo أو rm -rf أو غيرهما من الأوامر المدمرة لضمان أن يطلب الموظف دائمًا الإذن.

12. الخاتمة

تهانينا! لقد انتقلت من تثبيت Antigravity إلى إنشاء مهارة عمليات KCC عالية الدقة.

لقد تعلّمت ما يلي:

• كيفية توسيع نطاق الوكيل باستخدام أدوات bash مخصّصة
• كيفية ترميز "القواعد الذهبية" التشغيلية في SKILL.md
• كيفية توفير ضوابط أمان لإدارة البنية التحتية المعقّدة

الخطوات التالية

يمكنك توسيع مجلد resources/policies بإضافة المزيد من قيود OPA، أو إضافة نص برمجي check-health.sh لأتمتة عمليات التحقّق من جاهزية المجموعات.