Ingress2gateway

Skill name: ingress2gateway

Intent and objective

Automate the discovery, analysis, risk-profiling, and translation of legacy GKE and NGINX Ingress resources into native GKE Gateway API specifications using the ingress2gateway tool.

Activation criteria

• Use when: Migrating legacy GKE or NGINX Ingress manifests to native GKE Gateway API specifications (Gateway, HTTPRoute)

Prerequisites and sandbox configuration

1. Environment sandbox specification

This skill runs in a local sandbox environment with the following specifications:

• Type: local-sandbox
• Python Version: >=3.10
• Virtual Environment Path: .agent/skills/ingress2gateway/scripts/.venv
• Requirements Lockfile: .agent/skills/ingress2gateway/scripts/requirements.txt

2. Host binary constraints (prerequisites validation)

Before execution, verify the following host binary constraints:

• python3: Must be version >=3.10 (check using python3 --version).
• gcloud: Required to handle identity challenges, project queries, and GKE cluster authentication (check using gcloud --version).
• kubectl: Must be version >=1.30 (check using kubectl version --client -o json). Required to interact with GKE 1.30+ compatible APIs.

3. Secure outbound network allowlists (egress guardrails)

The sandbox requires outbound HTTPS access to the following domains:

• github.com: To verify network download access to the ingress2gateway repository releases without downloading assets.
• *.googleapis.com: To authenticate Google Cloud identities and communicate with GKE Control Planes.
• dl.google.com: To download Google Cloud SDK framework assets and kubectl components if missing.
• bootstrap.pypa.io: As a secure fallback to fetch get-pip.py if the host environment lacks pip and ensurepip completely.

Interactive JSON exchange protocol (crucial)

This skill utilizes a strict JSON payload protocol on stdout (delimited by __AGENT_UI_DATA_START__ and __AGENT_UI_DATA_END__) and expects a JSON response on stdin for every user input step.

The executing agent must:

1. Never truncate or summarize any JSON payloads emitted between __AGENT_UI_DATA_START__ and __AGENT_UI_DATA_END__. Display them in full to the user.
2. Never make assumptions or skip user input. Prompt the user for input at every single stage the script pauses and waits for stdin.
3. Format user choices as the required JSON structure and append a newline (\n) before writing to the script's stdin.
4. Render Risk Profiles Visually: When presenting the risk profile at Phase 4, the agent must render a clear Markdown table of the compatible (Green Lane) and incompatible (Red Lane) resources, detailing the risks/blockers, so the operator can make an informed decision.

Strict execution lifecycle and master report pipeline

Master report markdown template (to be updated incrementally)

The structural markdown template for the migration analysis report is maintained in assets/report_template.md.

When initialized or updated across the pipeline phases, the runtime engine automatically copies this template to output GKE_Ingress_to_Gateway_API_Migration_Analysis_Report.md and incrementally populates its section placeholders.

Structured macro-pipeline execution phases

You will advance strictly through these 6 consecutive operational phases.

• Phase 1: Environment Sandbox Pre-flight Validation.
• Phase 2: Identity & Context Resolution
• Phase 3: Resource Discovery & Target Inventory.
• Phase 4: Ingress scanning & Risk Profiling.
• Phase 5: Translation & Dry Run validation.
• Phase 6: Approval and execution

Phase 1: Environment sandbox pre-flight validation

Before executing any Python scripts or processing cluster manifests, you must verify and initialize the local environment by reading and following the pre-flight validation instructions in references/preflight_validation.md.

Phase 2: Identity and context resolution

1. Invoke the Core Python Script: Instantly upon entering Phase 2, run the python orchestrator script:

   python3 .agent/skills/ingress2gateway/scripts/main.py
   

2. Cluster Discovery UI Payload: The script discovers GKE clusters and emits a JSON payload (select_cluster). Intercept this payload, present options to the operator, and write the choice to the script's stdin.

3. Kubeconfig Sandboxing: Once selected, the script configures local sandboxed credentials for the chosen GKE cluster.

Phase 3: Resource discovery and target inventory

1. Orchestrated Scanning: The active script scans the target GKE cluster context to discover Ingress manifests.
2. Incremental Report Generation: The script copies the report template to GKE_Ingress_to_Gateway_API_Migration_Analysis_Report.md and updates the [Populated in Phase 3] placeholder with the target inventory.
3. Intermediate UI Exchange: The script does not pause at this stage, but advances to Phase 4.

Phase 4: Ingress scanning and risk profiling

1. Automated Risk Triage: The scanner.py sub-component will programmatically evaluate metadata arrays for custom or native rewrite snippets.

2. Incremental Document Update: The script replaces the [Populated in Phase 4] placeholder with a breakdown of Critical Blockers and Translation Warnings discovered during verification.

3. Interactive JSON Handoff Gate: The agent must capture the script's emitted stdout payload between AGENT_UI_DATA_START and AGENT_UI_DATA_END. Display the comprehensive risk inventory full-string array to the operator, pause processing execution, and wait for a structured JSON map selection on stdin identifying approved migration asset targets.

Phase 5: Translation and dry run validation

1. Translation Execution: The engine passes approved target JSON structures to translator.py, which pulls down and runs the pre-compiled ingress2gateway compiler to generate native Gateway API resource maps.

2. Validation & Safety Check: The script executes the dry-run kubectl apply --dry-run=server -f {GATEWAY_API_MANIFEST_YAML} command against the target cluster context. It analyzes the resulting stdout/stderr for validation errors and captures the server response using Kubernetes API.

3. Incremental Document Update: The script replaces the [Populated in Phase 5 & 6] placeholder with the consolidated raw Gateway, HttpRoute and URLMap API manifest, the detected server-side validation results, and a detailed explanation of any translation or deployment anomalies.

4. Interactive Deployment Signature: The script prints out the compilation details using the approve_deployment UI protocol template. The agent must display this text entirely and halt, blocking the runtime sequence until the user submits a signed APPROVE or CANCEL string map to stdin.

5. Conditional Execution Gate:

   • If the validation response indicates zero deploy-time errors, the agent immediately proceeds to Phase 6 (Execution).
   • If validation errors are returned, the agent must halt, append a comprehensive error report to the bottom of the Markdown document, display the final document, and explicitly ask the user for permission to proceed with manual correction or bypass strict validation rules.

Phase 6: Approval and execution

1. Live Data Plane Injection: If the interaction response on stdin reads APPROVE, the script applies the manifests to the cluster using kubectl apply -f -. It then overwrites the final placeholders with a complete transaction receipt string block.

2. Conditional Execution Gate: If the response reads CANCEL, the script intercepts the rejection, dumps the fully compiled Gateway configurations locally into a migration-fallback.yaml asset backup, and posts a Deployment Paused status block to the analysis file.

3. Mandatory Hold & Exit: Once the underlying script lifecycle gracefully exits, the agent must present a final execution summary to the workspace terminal and wait for further user interaction commands.