Alibabacloud Nginx Ingress To Api Gateway

Alibaba Cloud APIG Migration Skill. Migrate Kubernetes nginx Ingress resources to Alibaba Cloud API Gateway (APIG, ingressClass: apig). Users provide Ingress...

Security Scan

The skill mostly matches its stated purpose (offline migration of nginx Ingress YAML to Alibaba Cloud APIG), but there are internal inconsistencies and a few operational choices that warrant caution before installing or invoking it autonomously.

Purpose & Capability

The name/description align with the included scripts and reference docs (annotation classification, generating migrated Ingress YAML, scaffolding WasmPlugins). That said, some reference files (platform-oci-registry.md) include kubectl auto-detection commands and registry lookup logic which partially contradicts the SKILL.md claim that the workflow is purely offline and requires no cluster access or CLI. The presence of build/push instructions and plugin scaffolds is proportionate to the migration purpose, but the kubectl mention is an unexplained outlier.

Instruction Scope

SKILL.md instructs the agent to accept pasted YAML, file paths, or directory paths and to immediately run the full analysis/workflow without prompting for region/registry. Accepting directory paths means the agent will read any .yml/.yaml files in that directory — which is expected for migration but is a significant file-read scope and should be made explicit to the user. Also, some included docs show commands (kubectl) and recommend auto-detecting region; SKILL.md explicitly forbids prompting for region or running external checks — the divergence is a scope inconsistency that could confuse an agent or lead to unexpected actions if the agent follows the other docs.

Install Mechanism

No install spec (instruction-only + helper scripts). Nothing is downloaded or installed automatically by the skill manifest itself, which reduces risk. The included scripts and Go/Docker build guidance are local and consistent with offline generation of Wasm plugins.

Credentials

The skill declares no required environment variables, credentials, or config paths. That aligns with the stated offline analysis behavior. The references show OCI registry URLs and instructions to push images to a registry, but the skill instructs using placeholders (e.g., <REGION>, <YOUR_REGISTRY>) rather than asking for or using credentials — this is proportionate as long as the agent does not attempt to push images or call cloud APIs on its own.

Persistence & Privilege

The skill is not marked always:true and does not request persistent/privileged presence. It does not declare any capability to modify other skills or system-wide settings. Autonomous model invocation is allowed (platform default) — combine this with the instruction to 'proceed immediately' only if you accept the agent acting without extra confirmations.

What to consider before installing

This skill appears to implement what it claims (offline migration and WasmPlugin scaffolding), but review before use: - Expect the agent to read any YAML files you provide (including scanning directories). Do not point it at directories containing secrets or unrelated config you don't want read. - The skill will generate migrated Ingress YAML with placeholders (<REGION>, <YOUR_REGISTRY>) and recommends not prompting for region/registry — you must manually replace these before deploying. - Some reference docs mention kubectl auto-detection of region; the SKILL.md forbids prompting or pre-checks. Confirm whether you want the agent to run cluster commands (it shouldn't by default). If you allow cluster access, consider providing explicit, limited credentials and explicit consent. - The skill includes scripts and Go/Docker scaffolding to build/push Wasm plugin images. Building/pushing requires local tooling and registry credentials; the skill does not request these but may instruct you how to run them. Do not run build/push commands until you inspect the generated plugin code and Dockerfile in a safe environment. - If you plan to let the agent run autonomously, prefer restricting it to analysis-only mode (no build/push or kubectl) and verify its output before any kubectl apply or image push. If you want, I can: (a) scan the included scripts for any network calls or suspicious commands, (b) run a safe dry-run analysis on pasted YAML and show the generated migration report (without running build/push), or (c) point out the exact lines where the kubectl auto-detect guidance appears.

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.

请避免以下交互模式，直接执行对应操作即可：

• "是否需要我分析这个 Ingress？" — 建议直接分析
• "是否需要生成迁移后的 YAML？" — 建议直接生成
• "是否需要创建迁移配置文件/检查清单？" — 建议直接创建
• "是否需要开发 WasmPlugin？" — 如果决策树判定需要，建议直接开发
• "请确认 RegionId / OCI 地址" — 建议使用占位符

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

建议：收到 YAML 后一次性完成全部分析步骤

当用户提供 Ingress YAML 时，建议立即执行全部步骤（Step 1→5）并在一次响应中输出完整结果。

• 对于未指定的参数（如 RegionId、OCI registry），使用 <REGION> 等占位符
• 收到 YAML 后直接进入分析流程，无需额外确认
• 各步骤之间连续执行，无需中途暂停询问用户
• 迁移配置文件和检查清单作为标准输出的一部分自动生成
• 整个工作流是确定性的：YAML 输入 → 完整迁移报告输出，无需中间确认
• 唯一必需的输入是 Ingress YAML 本身

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

所有输出建议使用中文（中文）。包括分析表、迁移总结、后续操作指南及所有说明性文字。代码块（YAML、Go、bash）保持原始语法。

以下所有内容均为标准输出项，建议在一次响应中完整输出，无需逐项询问用户。

Output ALL of the following for each Ingress:

1. 兼容性分析表 — annotation, value, category (兼容/可忽略/不支持), action
2. 迁移后的 Ingress YAML — ready for user to apply
3. 自定义 WasmPlugin 源码 — if Step 3 determined custom plugins are needed (skip only if no custom plugin is needed)
4. 迁移总结 — what changed, value changes, plugins needed
5. 后续操作指南 — 根据兼容性分析结果，分场景告知用户完整的迁移操作路径：
   • 完全兼容（无不兼容注解）：所有注解均为兼容或可忽略类型，用户可直接参考 Nginx Ingress 迁移到云原生 API 网关 完成迁移。
   • 不完全兼容（存在不兼容注解）：按以下顺序操作：
     1. 构建并推送自定义 WasmPlugin OCI 镜像
     2. 将迁移后 Ingress YAML 中的 OCI URL 占位符替换为真实的 WasmPlugin 镜像地址
     3. 将替换后的 Ingress YAML 部署到集群中
     4. 参考 Nginx Ingress 迁移到云原生 API 网关 继续后续操作，在步骤一「指定 IngressClass」处需指定为 apig
     5. 网关版本要求：使用 WasmPlugin 需确保云原生 API 网关版本在 2.1.16 及以上，否则需要升级版本或创建新网关

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 "是否需要生成迁移文件/检查清单/部署指南？"

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	定期安全复审策略与检查项
references/security-impact-assessment.md	安全影响评估与数据处理流程
references/ram-policies.md	RAM 权限声明（本 Skill 无需任何权限）