SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsalibabacloud-nginx-ingress-to-api-gateway

alibabacloud-nginx-ingress-to-api-gateway

Deployment & operations

View repository

Updated 10-15 19:54

About this skill

Nginx Ingress to APIG Migration

Scenario Description

Migrate Kubernetes nginx Ingress resources to Alibaba Cloud API Gateway (APIG). APIG is an Envoy-based gateway (Higress) that uses ingressClassName: apig. This skill classifies every nginx.ingress.kubernetes.io/* annotation into Compatible / Ignorable / Unsupported, resolves unsupported annotations via a four-level decision tree (Higress native → safe-to-drop → built-in plugin → custom WasmPlugin), generates migrated Ingress YAML, and produces a deployment-ready migration report.

Architecture: nginx Ingress Controller → APIG (Envoy/Higress) + optional WasmPlugin (Go, proxy-wasm-go-sdk)

The core analysis workflow operates entirely offline on user-provided YAML — no cluster access, CLI tools, or cloud credentials required.

Installation

This skill operates entirely offline on user-provided YAML. No CLI tools, SDKs, or cloud credentials are required.

On-demand tools (only when the workflow reaches a step that needs them):

Tool When needed Check command Minimum version
jq Script-based offline analysis jq --version >= 1.6
python3 + PyYAML YAML parsing (alternative to yq) python3 -c "import yaml; print(yaml.__version__)" python3 >= 3.8, PyYAML >= 5.0
yq YAML parsing (alternative to python3+PyYAML) yq --version >= 4.0
Go Step 3 determines a custom WasmPlugin is needed go version >= 1.24
Docker Custom WasmPlugin needs to be built as OCI image docker version —

Do NOT pre-check or prompt installation of any tool during analysis.

Environment Variables

No environment variables required. This skill does not invoke any cloud APIs or CLI tools.

Authentication

Not applicable. This skill does not invoke Alibaba Cloud APIs or CLI. No credentials are needed.

RAM Policy

Not applicable. This skill operates entirely on local YAML files and does not call any cloud APIs.

Parameter Confirmation

This skill only performs analysis and code generation — it does NOT execute any deployment or cluster write operations.

When the user provides Ingress YAML, proceed immediately with the full workflow (Step 1→5) and output the complete result. Do NOT ask for RegionId, OCI registry, or any other parameter. Use <REGION> and <YOUR_REGISTRY> placeholders in the output.

Please avoid the following interaction patterns and directly perform the corresponding operations:

  • "Do you need me to analyze this Ingress?" — It is recommended to analyze directly
  • "Do you need me to generate the migrated YAML?" — It is recommended to generate directly
  • "Do you need me to create a migration configuration file/checklist?" — It is recommended to create directly
  • "Do you need me to develop a WasmPlugin?" — If the decision tree determines it is needed, it is recommended to develop directly
  • "Please confirm the RegionId / OCI address" — It is recommended to use placeholders
Parameter Name Required/Optional Description Default Value
Ingress YAML Required nginx Ingress YAML to migrate (paste, file, or directory) —

When Ingress YAML is not provided: If the user asks about migration but does not provide YAML, respond with: "请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。" Do NOT abort the conversation — guide the user to provide the required input.

Core Workflow

Recommendation: After receiving the YAML, complete all analysis steps in one go

When the user provides Ingress YAML, it is recommended to immediately execute all steps (Step 1→5) and output the complete result in a single response.

  • For unspecified parameters (such as RegionId, OCI registry), use <REGION> and other placeholders
  • After receiving the YAML, proceed directly to the analysis process without additional confirmation
  • Execute each step consecutively without pausing midway to ask the user
  • The migration configuration file and checklist are automatically generated as part of the standard output
  • The entire workflow is deterministic: YAML input → complete migration report output, with no intermediate confirmation required
  • The only required input is the Ingress YAML itself

Step 1: Parse Ingress YAML

Accept YAML from any of the following input formats:

  • Direct paste in conversation (with or without markdown code fences)
  • File path (e.g., ingress.yaml, ./k8s/ingress.yaml)
  • Directory path (scan all .yaml/.yml files for Ingress resources)
  • Multi-document YAML (separated by ---)
  • Partial YAML (missing apiVersion/kind — infer as Ingress if annotations with nginx.ingress.kubernetes.io/* are present)

For each Ingress found, extract all nginx.ingress.kubernetes.io/* annotations.

If the user's message mentions migration/analysis but does NOT include any YAML, respond with: "请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。" Do NOT abort or error out — guide the user to provide input.

Step 2: Classify Annotations

Classify each annotation into exactly one of three categories. See references/annotation-mapping.md for the complete 117-annotation lookup table.

Category Count Action Example
Compatible 50 Keep in migrated YAML rewrite-target, enable-cors, canary-weight, ssl-redirect
Ignorable 16 Strip (Envoy handles natively) proxy-connect-timeout, proxy-buffering, proxy-body-size
Unsupported 51 Strip → resolve via decision tree auth-url, server-snippet, limit-rps

Inline Quick Lookup — High-Frequency Annotations:

Annotation Category Action
rewrite-target ✅ Compatible Keep
enable-cors ✅ Compatible Keep
cors-allow-origin ✅ Compatible Keep
ssl-redirect ✅ Compatible Keep
canary / canary-weight / canary-by-header ✅ Compatible Keep
whitelist-source-range ✅ Compatible Keep
backend-protocol ✅ Compatible Keep
use-regex ✅ Compatible Keep
upstream-vhost ✅ Compatible Keep
proxy-connect-timeout ⚪ Ignorable Strip
proxy-read-timeout ⚪ Ignorable Strip
proxy-send-timeout ⚪ Ignorable Strip
proxy-body-size ⚪ Ignorable Strip
proxy-buffering ⚪ Ignorable Strip
client-body-buffer-size ⚪ Ignorable Strip
auth-url ❌ Unsupported WasmPlugin (HTTP callout)
server-snippet ❌ Unsupported WasmPlugin (directive conversion)
configuration-snippet ❌ Unsupported WasmPlugin (directive conversion)
limit-rps ❌ Unsupported Built-in key-rate-limit plugin
limit-connections ❌ Unsupported Built-in key-rate-limit plugin
enable-modsecurity ❌ Unsupported Built-in waf plugin
denylist-source-range ❌ Unsupported Higress native higress.io/blacklist-source-range
service-upstream ❌ Unsupported Safe to drop (Envoy default behavior)
ssl-ciphers ❌ Unsupported Rename to ssl-cipher (compatible)

If an annotation is NOT in the above table, look it up in references/annotation-mapping.md. If still not found, classify as Unsupported and resolve via the decision tree in Step 3.

Special value changes (compatible but value must change):

  • load-balance: ewma → round_robin (APIG does not support EWMA)
  • ssl-ciphers → rename to ssl-cipher (singular form)
  • affinity-mode: persistent → balanced (APIG only supports balanced)

Step 3: Resolve Unsupported Annotations

For each unsupported annotation, follow this decision tree in order:

1. Higress native annotation?  → Use native equivalent (no WasmPlugin needed)
2. Safe to drop?               → Remove without replacement
3. Built-in platform plugin?   → Use built-in OCI image via higress.io/wasmplugin annotation
4. None of the above?          → Develop custom WasmPlugin

See references/migration-patterns.md for the complete decision tree, and references/builtin-plugins.md for the built-in plugin catalog.

Higress native mappings:

nginx annotation Higress equivalent
denylist-source-range higress.io/blacklist-source-range
mirror-target higress.io/mirror-target-service + higress.io/mirror-percentage

Safe-to-drop: service-upstream, enable-access-log, proxy-request-buffering: off, connection-proxy-header

Built-in plugins: limit-rps/limit-connections → key-rate-limit, enable-modsecurity → waf. See references/builtin-plugins.md.

Custom WasmPlugin (last resort): auth-url, server-snippet, configuration-snippet, etc. See references/wasm-plugin-sdk.md for SDK reference, references/snippet-patterns.md for conversion patterns.

Step 4: Generate Migrated Ingress YAML

For each input Ingress, generate a migrated copy:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <original-name>-apig
  namespace: <original-namespace>
  annotations:
    # Compatible annotations preserved
    # Unsupported annotations replaced with higress.io/wasmplugin if needed
spec:
  ingressClassName: apig    # MUST be hardcoded to apig
  rules: ...                # Preserved from original
  tls: ...                  # Preserved from original

Step 5: Output Migration Report

All output is recommended to use Chinese (中文). This includes analysis tables, migration summaries, subsequent operation guides, and all explanatory text. Code blocks (YAML, Go, bash) retain their original syntax.

All of the following are standard output items and are recommended to be output completely in a single response, without asking the user item by item.

Output ALL of the following for each Ingress:

  1. Compatibility analysis table — annotation, value, category (compatible/ignorable/unsupported), action
  2. Migrated Ingress YAML — ready for user to apply
  3. Custom WasmPlugin source code — if Step 3 determined custom plugins are needed (skip only if no custom plugin is needed)
  4. Migration summary — what changed, value changes, plugins needed
  5. Subsequent operation guide — Based on the compatibility analysis results, inform the user of the complete migration operation path by scenario:
    • Fully compatible (no incompatible annotations): All annotations are compatible or ignorable types, and the user can directly refer to Migrating Nginx Ingress to Cloud Native API Gateway to complete the migration.
    • Not fully compatible (incompatible annotations exist): Operate in the following order:
      1. Build and push the custom WasmPlugin OCI image
      2. Replace the OCI URL placeholder in the migrated Ingress YAML with the real WasmPlugin image address
      3. Deploy the replaced Ingress YAML to the cluster
      4. Refer to Migrating Nginx Ingress to Cloud Native API Gateway to continue with subsequent operations. In step 1 "Specify IngressClass", it needs to be specified as apig
      5. Gateway version requirements: To use WasmPlugin, ensure that the cloud-native API gateway version is 2.1.16 or later, otherwise you need to upgrade the version or create a new gateway

See references/deployment-guide-template.md for the guide template.

Scope boundary: This skill generates all artifacts and instructions. It does NOT execute kubectl apply, docker push, or any cluster/registry write operations. Those are left to the user. No confirmation needed: Every item above is always generated. Never ask "Do migration files/checklists/deployment guides need to be generated?"

Success Verification Method

See references/verification-method.md for verification steps to include in the migration report.

The migration report should instruct the user to verify with:

# Validate migrated YAML syntax (user runs this)
kubectl apply --dry-run=client -f <migrated-ingress>.yaml

# Confirm ingressClassName is apig
grep "ingressClassName: apig" <migrated-ingress>.yaml

This skill outputs verification instructions for the user. It does NOT execute these commands.

Cleanup

Not applicable. This skill only generates text output (YAML, Go source code, migration report). No cloud resources or cluster objects are created by this skill.

API and Command Tables

This skill does not execute any CLI commands or API calls. All output is text-based (YAML, Go source code, migration report with instructions for the user).

Best Practices

  1. Always classify ALL annotations before generating migrated YAML — never skip annotations
  2. Use placeholders (<REGION>, <YOUR_REGISTRY>) for unspecified parameters; never hardcode user-specific values
  3. Preserve original rules, tls, and namespace in migrated YAML
  4. Add -apig suffix to migrated Ingress name for easy identification
  5. Prefer built-in plugins over custom WasmPlugin — check references/builtin-plugins.md first
  6. For custom WasmPlugin, use github.com/higress-group/wasm-go/pkg/wrapper SDK exclusively
  7. Track annotation value changes (e.g., ewma → round_robin) explicitly in the report
  8. For server-snippet/configuration-snippet, enumerate every directive and verify 1:1 conversion completeness
  9. Never execute cluster write operations (kubectl apply, docker push, etc.) — only output instructions for the user

Reference Links

Reference Contents
references/annotation-mapping.md Complete 117-annotation compatibility lookup table
references/migration-patterns.md Decision tree, Higress native mappings, safe-to-drop list, special handling
references/builtin-plugins.md APIG built-in platform plugins catalog with OCI URLs
references/platform-oci-registry.md Region-specific OCI registry addresses for built-in plugins
references/snippet-patterns.md server-snippet / configuration-snippet → WasmPlugin conversion patterns
references/wasm-plugin-sdk.md Higress WASM Go Plugin SDK reference (core API)
references/wasm-http-client.md WasmPlugin HTTP client patterns (external auth, callouts)
references/wasm-redis-client.md WasmPlugin Redis client patterns (rate limiting, session)
references/wasm-advanced-patterns.md Advanced WasmPlugin patterns (streaming, tick, leader election)
references/wasm-local-testing.md Local WasmPlugin testing with Docker Compose
references/plugin-deployment.md WasmPlugin build, OCI push, and Ingress annotation binding
references/deployment-guide-template.md Migration report deployment guide template
references/acceptance-criteria.md Testing acceptance criteria with correct/incorrect patterns
references/verification-method.md Success verification steps and commands
references/security-review-policy.md Regular security review policy and check items
references/security-impact-assessment.md Security impact assessment and data processing flow
references/ram-policies.md RAM permission statement (this Skill requires no permissions)