alibabacloud-nginx-ingress-to-api-gateway

Nginx Ingress から APIG への移行

シナリオの説明

Kubernetes の nginx Ingress リソースを Alibaba Cloud API Gateway（APIG）に移行します。APIG は ingressClassName: apig を使用する、Envoy ベースのゲートウェイ（Higress）です。このスキルでは、nginx.ingress.kubernetes.io/* アノテーションを「互換」「無視可能」「非対応」に分類し、4 段階の判断ツリー（Higress ネイティブ → 安全に削除可能 → 組み込みプラグイン → カスタム WasmPlugin）で非対応のアノテーションに対処して、移行後の Ingress YAML を生成し、デプロイ可能な移行レポートを作成します。

アーキテクチャ：nginx Ingress Controller → APIG (Envoy/Higress) + optional WasmPlugin (Go, proxy-wasm-go-sdk)

中核となる分析ワークフローは、ユーザーが提供する YAML のみを使って完全にオフラインで実行されます。クラスターへのアクセス、CLI ツール、クラウド認証情報は必要ありません。

インストール

このスキルは、ユーザーが提供する YAML のみを使って完全にオフラインで実行されます。CLI ツール、SDK、クラウド認証情報は必要ありません。

必要に応じて使用するツール（ワークフローで必要な手順に進んだ場合のみ）：

ツール	必要となるタイミング	確認コマンド	最小バージョン
jq	スクリプトベースのオフライン分析	jq --version	>= 1.6
python3 + PyYAML	YAML の解析（yq の代替）	python3 -c "import yaml; print(yaml.__version__)"	python3 >= 3.8, PyYAML >= 5.0
yq	YAML の解析（python3+PyYAML の代替）	yq --version	>= 4.0
Go	ステップ 3 でカスタム WasmPlugin が必要と判断された場合	go version	>= 1.24
Docker	カスタム WasmPlugin を OCI イメージとしてビルドする必要がある場合	docker version	—

分析中にツールの事前確認やインストールの案内を行わないでください。

環境変数

環境変数は必要ありません。このスキルはクラウド API や CLI ツールを呼び出しません。

認証

該当しません。このスキルは Alibaba Cloud API や CLI を呼び出しません。認証情報は必要ありません。

RAM ポリシー

該当しません。このスキルはローカルの YAML ファイルのみを扱い、クラウド API を呼び出しません。

パラメーターの確認

このスキルは分析とコード生成のみを行い、デプロイやクラスターへの書き込み操作は実行しません。

ユーザーから Ingress YAML が提供されたら、ただちにワークフロー全体（ステップ 1→5）を進め、結果をすべて出力してください。RegionId、OCI レジストリ、その他のパラメーターを質問しないでください。出力では <REGION> と <YOUR_REGISTRY> のプレースホルダーを使用してください。

次のようなやり取りは避け、対応する操作を直接実行してください。

• 「この Ingress を分析しましょうか？」— そのまま分析してください
• 「移行後の YAML を生成しましょうか？」— そのまま生成してください
• 「移行設定ファイル／チェックリストを作成しましょうか？」— そのまま作成してください
• 「WasmPlugin を開発しましょうか？」— 判断ツリーで必要と判定された場合は、そのまま開発してください
• 「RegionId／OCI アドレスを確認してください」— プレースホルダーを使用してください

パラメーター名	必須／任意	説明	デフォルト値
Ingress YAML	必須	移行する nginx Ingress YAML（貼り付け、ファイル、またはディレクトリ）	—

Ingress YAML が提供されていない場合：ユーザーが移行について尋ねていても YAML を提供していない場合は、 次のように応答してください：「移行する nginx Ingress YAML を提供してください（直接貼り付けるか、ファイルまたはディレクトリのパスを指定できます）。」 会話を中断せず、必要な入力を提供するよう案内してください。

コアワークフロー

推奨：YAML を受け取ったら、分析の全ステップを一度に完了してください

ユーザーから Ingress YAML が提供されたら、ただちにすべてのステップ（ステップ 1→5）を実行し、1 回の応答で結果をすべて出力してください。

• 指定されていないパラメーター（RegionId、OCI レジストリなど）には、<REGION> などのプレースホルダーを使用してください
• YAML を受け取ったら、追加確認なしで分析を開始してください
• 各ステップを続けて実行し、途中でユーザーへの確認のために中断しないでください
• 移行設定ファイルとチェックリストは、標準出力の一部として自動生成してください
• ワークフロー全体は決定的です。YAML 入力から移行レポート全体を出力し、途中確認は必要ありません
• 必須の入力は Ingress YAML のみです

ステップ 1：Ingress YAML を解析する

以下のいずれかの入力形式で YAML を受け取ります。

• 会話に直接貼り付け（Markdown のコードフェンスの有無は問いません）
• ファイルパス（例：ingress.yaml、./k8s/ingress.yaml）
• ディレクトリパス（すべての .yaml／.yml ファイルをスキャンし、Ingress リソースを検索）
• 複数ドキュメントの YAML（--- で区切られています）
• 部分的な YAML（apiVersion／kind がない場合、nginx.ingress.kubernetes.io/* を含む annotations があれば Ingress として推定）

見つかった各 Ingress から、すべての nginx.ingress.kubernetes.io/* アノテーションを抽出します。

ユーザーのメッセージに移行または分析についての記載があるものの、YAML が含まれていない場合は、次のように応答します。 「迁移する nginx Ingress YAML を提供してください（直接貼り付けるか、ファイルパスまたはディレクトリパスを指定できます）。」 処理を中断したり、エラーを返したりせず、入力を提供するようユーザーに案内してください。

ステップ 2：アノテーションを分類する

各アノテーションを、以下の 3 つのカテゴリのいずれか 1 つに分類します。全 117 種類のアノテーションの対応表については、references/annotation-mapping.md を参照してください。

カテゴリ	数	対応	例
互換	50	移行後の YAML に残す	rewrite-target、enable-cors、canary-weight、ssl-redirect
無視可能	16	削除（Envoy がネイティブに処理）	proxy-connect-timeout、proxy-buffering、proxy-body-size
非対応	51	削除 → 判定ツリーで解決	auth-url、server-snippet、limit-rps

インライン簡易検索 — 使用頻度の高いアノテーション：

アノテーション	カテゴリ	対応
rewrite-target	✅ 互換	残す
enable-cors	✅ 互換	残す
cors-allow-origin	✅ 互換	残す
ssl-redirect	✅ 互換	残す
canary / canary-weight / canary-by-header	✅ 互換	残す
whitelist-source-range	✅ 互換	残す
backend-protocol	✅ 互換	残す
use-regex	✅ 互換	残す
upstream-vhost	✅ 互換	残す
proxy-connect-timeout	⚪ 無視可能	削除
proxy-read-timeout	⚪ 無視可能	削除
proxy-send-timeout	⚪ 無視可能	削除
proxy-body-size	⚪ 無視可能	削除
proxy-buffering	⚪ 無視可能	削除
client-body-buffer-size	⚪ 無視可能	削除
auth-url	❌ 非対応	WasmPlugin（HTTP コールアウト）
server-snippet	❌ 非対応	WasmPlugin（ディレクティブ変換）
configuration-snippet	❌ 非対応	WasmPlugin（ディレクティブ変換）
limit-rps	❌ 非対応	組み込みの key-rate-limit プラグイン
limit-connections	❌ 非対応	組み込みの key-rate-limit プラグイン
enable-modsecurity	❌ 非対応	組み込みの waf プラグイン
denylist-source-range	❌ 非対応	Higress ネイティブの higress.io/blacklist-source-range
service-upstream	❌ 非対応	安全に削除可能（Envoy のデフォルト動作）
ssl-ciphers	❌ 非対応	ssl-cipher に名前を変更（互換）

上記の表にないアノテーションは、references/annotation-mapping.md で確認してください。それでも見つからない場合は非対応に分類し、ステップ 3 の判定ツリーで解決してください。

値の変更が必要な特例（互換ですが、値を変更する必要があります）：

• load-balance: ewma → round_robin（APIG は EWMA をサポートしていません）
• ssl-ciphers → ssl-cipher に名前を変更（単数形）
• affinity-mode: persistent → balanced（APIG がサポートするのは balanced のみです）

ステップ 3：サポートされていないアノテーションを解決する

サポートされていないアノテーションごとに、次の判断フローを順番に確認してください。

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

完全な判断フローについては references/migration-patterns.md を、組み込みプラグインの一覧については references/builtin-plugins.md を参照してください。

Higress のネイティブマッピング：

nginx アノテーション	Higress の同等機能
denylist-source-range	higress.io/blacklist-source-range
mirror-target	higress.io/mirror-target-service + higress.io/mirror-percentage

安全に削除可能： service-upstream、enable-access-log、proxy-request-buffering: off、connection-proxy-header

組み込みプラグイン： limit-rps／limit-connections → key-rate-limit、enable-modsecurity → waf。references/builtin-plugins.md を参照してください。

カスタム WasmPlugin（最終手段）： auth-url、server-snippet、configuration-snippet など。SDK のリファレンスについては references/wasm-plugin-sdk.md を、変換パターンについては references/snippet-patterns.md を参照してください。

ステップ 4：移行後の Ingress YAML を生成する

入力された Ingress ごとに、移行後のコピーを生成してください。

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

ステップ 5：移行レポートを出力する

すべての出力は中国語（中文）を使用してください。分析表、移行の要約、後続の操作ガイド、およびすべての説明文が対象です。コードブロック（YAML、Go、bash）は元の構文を維持してください。

以下の内容はすべて標準出力項目です。ユーザーに項目ごとに確認する必要はありません。1 回の応答で完全に出力することを推奨します。

各 Ingress について、以下をすべて出力してください。

1. 互換性分析表 — アノテーション、値、カテゴリ（互換／無視可能／非対応）、対応
2. 移行後の Ingress YAML — ユーザーが適用できる状態のもの
3. カスタム WasmPlugin のソースコード — ステップ 3 でカスタムプラグインが必要と判断された場合（カスタムプラグインが不要な場合に限り省略）
4. 移行の要約 — 変更内容、値の変更、必要なプラグイン
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 以上であることを確認してください。満たさない場合は、バージョンをアップグレードするか、新しいゲートウェイを作成する必要があります。

ガイドのテンプレートについては references/deployment-guide-template.md を参照してください。

対象範囲の境界：このスキルは、すべての成果物と手順を生成します。kubectl apply、docker push、その他のクラスターやレジストリへの書き込み操作は実行しません。これらの操作はユーザーが行います。 確認不要：上記の項目はすべて常に生成してください。「移行ファイル／チェックリスト／デプロイガイドを生成しますか？」と尋ねないでください。

成功の検証方法

移行レポートに含める検証手順については references/verification-method.md を参照してください。

移行レポートでは、次のコマンドで検証するようユーザーに案内してください。

# 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

このスキルは、ユーザー向けの検証手順を出力します。これらのコマンドは実行しません。

クリーンアップ

該当しません。このスキルはテキスト出力（YAML、Go のソースコード、移行レポート）のみを生成します。クラウドリソースやクラスターオブジェクトは作成しません。

API とコマンドの表

このスキルは、CLI コマンドや API 呼び出しを実行しません。すべての出力はテキスト（YAML、Go のソースコード、ユーザー向けの手順を含む移行レポート）です。

ベストプラクティス

1. 移行後の YAML を生成する前に、すべてのアノテーションを必ず分類してください。アノテーションを見落とさないでください
2. 指定されていないパラメーターにはプレースホルダー（<REGION>、<YOUR_REGISTRY>）を使用し、ユーザー固有の値をハードコードしないでください
3. 移行後の YAML では、元の rules、tls、namespace を保持してください
4. 識別しやすいよう、移行後の Ingress 名に -apig サフィックスを追加してください
5. カスタム WasmPlugin より組み込みプラグインを優先してください。まず references/builtin-plugins.md を確認してください
6. カスタム WasmPlugin には、github.com/higress-group/wasm-go/pkg/wrapper SDK のみを使用してください
7. アノテーションの値の変更（例：ewma → round_robin）は、レポートに明記してください
8. server-snippet／configuration-snippet については、すべてのディレクティブを列挙し、1 対 1 で漏れなく変換されていることを確認してください
9. クラスターへの書き込み操作（kubectl apply、docker push など）は実行しないでください。ユーザー向けの手順を出力するだけにしてください

参考リンク

参考資料	内容
references/annotation-mapping.md	117 件のアノテーションの互換性を網羅した対応表
references/migration-patterns.md	判断ツリー、Higress のネイティブマッピング、安全に削除できる項目の一覧、特別な取り扱い
references/builtin-plugins.md	APIG プラットフォーム組み込みプラグインのカタログと OCI URL
references/platform-oci-registry.md	組み込みプラグイン向けのリージョン別 OCI レジストリアドレス
references/snippet-patterns.md	server-snippet／configuration-snippet から WasmPlugin への変換パターン
references/wasm-plugin-sdk.md	Higress WASM Go Plugin SDK リファレンス（コア API）
references/wasm-http-client.md	WasmPlugin の HTTP クライアントパターン（外部認証、コールアウト）
references/wasm-redis-client.md	WasmPlugin の Redis クライアントパターン（レート制限、セッション）
references/wasm-advanced-patterns.md	WasmPlugin の高度なパターン（ストリーミング、tick、リーダー選出）
references/wasm-local-testing.md	Docker Compose を使用した WasmPlugin のローカルテスト
references/plugin-deployment.md	WasmPlugin のビルド、OCI へのプッシュ、Ingress アノテーションのバインド
references/deployment-guide-template.md	移行レポートのデプロイガイドテンプレート
references/acceptance-criteria.md	正しいパターンと誤ったパターンを含むテスト受け入れ基準
references/verification-method.md	成功確認の手順とコマンド
references/security-review-policy.md	定期的なセキュリティ再レビューの方針と確認項目
references/security-impact-assessment.md	セキュリティ影響評価とデータ処理手順
references/ram-policies.md	RAM 権限の宣言（この Skill では権限は不要です）