MENU

AKS Application Routingをingress-nginxからGateway APIへ移行する手順

Azure

AKS Application Routingをingress-nginxからGateway APIへ移行する場合は、既存のingress-nginxを稼働させたままGateway API版を追加し、新しいIPアドレスで動作確認した後にDNSを切り替える方法が最も安全です。

Application RoutingのGateway API版は2026年7月に一般提供されました。サービスメッシュを導入する必要はなく、既存のIngressはingress2gatewayを使ってGatewayとHTTPRouteへ段階的に変換できます。一方、Application Routingで管理されるingress-nginxへのMicrosoftのサポートは2026年11月までです。移行検証とロールバック期間を考えると、11月直前ではなく、早めに作業を始める必要があります。

日程Fit。無料・登録不要。「いつ空いてる？」を、ひとつのリンクで。リンクを送って、○△×でかんたん日程調整。無料で日程を作る。
目次

AKSのApplication RoutingをGateway APIへ移行する期限

最初に理解しておきたいのは、OSS版Ingress NGINXと、AKS Application Routingで管理されるingress-nginxではサポート期限が異なることです。

KubernetesのIngress NGINXプロジェクトは2026年3月24日に廃止され、それ以降は新しいリリース、バグ修正、脆弱性対応が提供されません。一方、AKSのApplication Routingアドオンで稼働するNGINX Ingressリソースについては、Microsoftが2026年11月まで重大なセキュリティ修正をサポートします。(Kubernetes)

項目状況
OSS版Ingress NGINX2026年3月24日に廃止
AKS Application RoutingのNGINX2026年11月までMicrosoftがサポート
Application Routing Gateway API版2026年7月に一般提供
AKSの長期的な推奨先Gateway API
移行方式ingress-nginxとGateway APIを並行稼働し、DNSで切り替える

「2026年11月まで動く」という意味ではありません。既存環境は期限後も直ちに停止するわけではありませんが、セキュリティ更新やMicrosoftのサポートを前提にした運用ができなくなります。

実務上は、次のスケジュールが安全です。

時期推奨作業
できるだけ早い時期Ingress、アノテーション、DNS、TLS、外部連携の棚卸し
移行1～2か月前検証環境でingress2gatewayによる変換と動作確認
2026年10月まで本番トラフィックをGateway APIへ切り替え
2026年11月ロールバック余裕期間として確保し、旧NGINXを撤去

Microsoftの案内は「2026年11月まで」という月単位の表現です。11月末ぎりぎりの切り替え計画は避け、少なくとも数週間のロールバック期間を確保してください。

Gateway API版はサービスメッシュを必要としない

Application RoutingのGateway API実装は、内部的にはIstioの軽量なコントロールプレーンを使用します。ただし、これはIstioサービスメッシュアドオンとは別の機能です。

Application Routing Gateway API版では、次の機能は提供されません。

  • アプリケーションPodへのサイドカー注入
  • VirtualServiceやDestinationRuleなどのIstio CRD
  • サービス間通信のmTLS制御
  • Istioを使ったイグレス制御
  • Istio Telemetry APIによる詳細なログ設定

管理対象となるのは、approuting-istioというGatewayClassに属するGateway APIリソースだけです。そのため、外部からAKS内のHTTP／HTTPSサービスへ通信を振り分けたいだけであれば、フル機能のサービスメッシュを導入する必要はありません。(Microsoft Learn)

項目Application Routing Gateway APIIstioサービスメッシュアドオン
GatewayClassapprouting-istioistio
サイドカー注入非対応対応
Istio CRD非対応対応
主な用途AKSへのHTTP／HTTPS ingressサービス間通信を含むメッシュ制御
更新方式AKSによるインプレース更新リビジョンを使った更新に対応

ただし、Application Routing Gateway API版とAKSのIstioサービスメッシュアドオンは同時に有効化できません。すでにIstioアドオンを使用しているクラスターでは、単純にGateway API版を追加するのではなく、現在のIstio利用状況を確認してから移行方式を決める必要があります。(Microsoft Learn)

ingress-nginxとGateway APIの主な違い

移行では、単にAPIの名前が変わるだけではありません。Ingressにまとめて書いていた入口とルーティング設定が、複数のリソースに分離されます。

項目ingress-nginx版Gateway API版
Kubernetes APInetworking.k8s.io/v1gateway.networking.k8s.io/v1
主なリソースIngressGateway、HTTPRoute
クラス名webapprouting.kubernetes.azure.comapprouting-istio
外部通信の入口Ingress Controllerが暗黙的に管理Gatewayのlistenerで明示
ルーティングIngress.spec.rulesHTTPRoute.spec.rules
拡張方法NGINX固有アノテーションが中心構造化されたフィルターやポリシー
Load Balancerapp-routing-system/nginxGatewayごとのLoadBalancer Service
移行時のIP既存IP新しいIPが発行される

Gateway APIでは、クラスター管理者や基盤担当者がGatewayを管理し、アプリケーション担当者がHTTPRouteを管理する構成を取りやすくなります。複数チームで共通の入口を共有するクラスターでは、Ingressより権限を分離しやすい設計です。(Microsoft Learn)

移行は上書きではなく並行稼働で行う

AKS Application Routingの移行では、既存のingress-nginxをGateway APIへ直接置き換えるフラグはありません。

Gateway API版を有効にすると、既存のNGINXとは別にDeploymentとLoadBalancer Serviceが作成され、新しいフロントエンドIPアドレスが割り当てられます。そのため、移行は次の流れになります。

  1. ingress-nginxを稼働したままGateway API版を有効化する
  2. IngressをGatewayとHTTPRouteへ変換する
  3. 新しいGatewayのIPアドレスを直接指定してテストする
  4. DNSやAzure Front Doorの接続先を新IPへ変更する
  5. 旧NGINXへの通信がゼロになったことを確認する
  6. ロールバック期間後にNGINXを削除する

旧NGINXのパブリックIPをGatewayへ付け替える方法は推奨されません。AKSが管理するLoadBalancer ServiceのIPは、所有元のServiceが削除されると、Staticを指定していても削除される可能性があります。Azure Front Doorのオリジン、Traffic Managerのエンドポイント、ファイアウォールの許可リストなどに旧IPを登録している場合は、新しいGateway IPへ個別に変更します。(Microsoft Learn)

移行前に確認する項目

Azure CLIを2.86.0以降へ更新する

Application Routing Gateway API版とManaged Gateway APIを操作するには、Azure CLI 2.86.0以降が必要です。(Microsoft Learn)

az --version
az upgrade

Azure Cloud Shellを利用している場合も、実行時のバージョンを確認してください。

self-managedのGateway API CRDがないか確認する

AKSの正式サポートを受けるには、AKSが管理するManaged Gateway API CRDを使用します。クラスターへ独自にインストールしたGateway API CRDとApplication Routing Gateway API版を組み合わせる構成はサポート対象外です。

また、Managed Gateway APIで利用できるのはStandardチャネルのCRDです。ExperimentalチャネルのCRDが残っている場合は、有効化前に削除または移行が必要です。(Microsoft Learn)

kubectl get crd | grep gateway.networking.k8s.io

kubectl get crd gateways.gateway.networking.k8s.io \
  -o jsonpath='{.metadata.annotations}'

Istioサービスメッシュアドオンの有無を確認する

既存クラスターでIstioサービスメッシュアドオンを使用している場合、Application Routing Gateway API版を同時に有効化できません。

Istioアドオンを停止した後も、IstioのCRDやistio GatewayClassは自動削除されません。残存しているとApplication Routing側のistiodが起動できないため、不要であることを確認してから削除します。(Microsoft Learn)

kubectl get gatewayclass
kubectl get crd | grep istio.io

削除例は次のとおりです。

kubectl delete crd $(kubectl get crd -o name | grep -E 'istio\.io')
kubectl delete gatewayclass istio

この操作を行うと、VirtualServiceやDestinationRuleなど、そのCRDを使用する既存リソースも削除されます。実際にサービスメッシュを利用しているクラスターでは、確認せずに実行しないでください。

現在サポートされない機能を確認する

Application Routing Gateway API版は、標準的なHTTP／HTTPS ingressに適しています。一方、次の要件がある場合は移行前の検証が必要です。

機能現在の扱い
TLSRouteによるSNIパススルー現時点では非対応
Application Routingによるイグレス管理非対応
Gateway Podへの独自サイドカー注入正式サポート外
Istio Telemetry APIによるログ形式変更非対応
Istio CRDを使った高度なトラフィック制御非対応
フル機能のサービスメッシュIstioサービスメッシュアドオンを検討

特に、現在のIngressでnginx.ingress.kubernetes.io/ssl-passthroughを使用している場合は注意が必要です。ingress2gatewayはこの設定をTLSRouteへ変換できますが、Application Routing Gateway API版ではTLSRouteによるSNIパススルーが現時点でサポートされていません。自動変換できても、そのままAKSで利用できるとは限りません。(Microsoft Learn)

AKS Application RoutingをGateway APIへ移行する手順

現在のIngressと外部依存関係を棚卸しする

以下のコマンド例は、BashまたはAzure Cloud Shellを前提としています。

export RG="<resource-group>"
export CLUSTER="<aks-cluster-name>"

az aks get-credentials \
  --resource-group "$RG" \
  --name "$CLUSTER"

Application Routingを使用しているIngressを確認します。

kubectl get ingress -A \
  -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.ingressClassName,HOSTS:.spec.rules[*].host,TLS-SECRET:.spec.tls[*].secretName'

Application Routingの標準IngressClassはwebapprouting.kubernetes.azure.comです。(Microsoft Learn)

対象だけを一覧化する場合は、次のコマンドを使えます。

kubectl get ingress -A \
  -o jsonpath='{range .items[?(@.spec.ingressClassName=="webapprouting.kubernetes.azure.com")]}{.metadata.namespace}{"/"}{.metadata.name}{"\n"}{end}'

作業前に全Ingressをバックアップします。

kubectl get ingress -A -o yaml \
  > "ingress-backup-$(date +%Y%m%d).yaml"

現在のNGINXの外部IPも記録します。

export INGRESS_NGINX_IP=$(
  kubectl get svc \
    -n app-routing-system \
    nginx \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
)

echo "$INGRESS_NGINX_IP"

マニフェストだけでなく、次の外部依存関係も一覧化してください。

  • Azure DNSや外部DNS事業者のAレコード
  • Azure Front Doorのオリジン
  • Traffic Managerのエンドポイント
  • Application Gatewayやロードバランサーからの接続
  • ファイアウォールや取引先ネットワークのIP許可リスト
  • 外形監視サービスの接続先
  • TLS証明書と更新方法
  • IPアドレスを直接使用しているクライアント
  • WebSocket、gRPC、ストリーミング通信
  • 大容量アップロードや長時間リクエスト

NGINX固有アノテーションを抽出する

移行で最も問題になりやすいのは、Ingress.spec.rulesではなくNGINX固有アノテーションです。

kubectl get ingress -A -o json | jq -r '
  .items[]
  | select(
      .spec.ingressClassName
      == "webapprouting.kubernetes.azure.com"
    )
  | [
      .metadata.namespace,
      .metadata.name,
      (
        (.metadata.annotations // {})
        | to_entries
        | map(
            select(
              .key
              | startswith("nginx.ingress.kubernetes.io/")
            )
          )
        | map(.key + "=" + .value)
        | join(";")
      )
    ]
  | @tsv
'

アノテーションが多いIngressほど、変換後の差分確認に時間がかかります。単純なホスト名・パスルーティングだけのIngressから先に移行し、複雑なIngressを後に回すと失敗の影響を限定できます。

DNSのTTLを下げる

本番切り替えの前に、対象ホスト名のDNS TTLを60秒程度、またはDNS事業者が許容する最小値まで下げます。

TTLを変更しただけでは、すでにキャッシュされたレコードの有効期間は短くなりません。変更前のTTLが1時間だった場合は、少なくとも1時間待ってから切り替え作業を開始します。(Microsoft Learn)

IPアドレスを直接指定してアクセスしているシステムでは、DNSによる段階切り替えが使えません。その場合は、接続元の設定変更方法と停止時間の有無を別途確認してください。

Managed Gateway APIとApplication Routing Gateway API版を有効化する

まず、AKS管理のGateway API CRDを有効化します。

az aks update \
  --resource-group "$RG" \
  --name "$CLUSTER" \
  --enable-gateway-api

続いて、Application Routing Gateway API実装を有効化します。

az aks update \
  --resource-group "$RG" \
  --name "$CLUSTER" \
  --enable-app-routing-istio

この時点では、既存のingress-nginxは停止しません。NGINXとGateway APIのデータプレーンを同じクラスター内で並行稼働できます。(Microsoft Learn)

CRD、コントロールプレーン、GatewayClassを確認します。

kubectl get crd | grep gateway.networking.k8s.io

kubectl -n aks-istio-system \
  rollout status deployment/istiod \
  --timeout=5m

kubectl get gatewayclass approuting-istio

istiodがReadyにならない場合は、先にIstioサービスメッシュアドオンの残存CRDやistio GatewayClassを確認してください。

なお、AKS 1.36以降の新しいAKS Automaticクラスターでは、Application RoutingのGateway APIが標準で有効化されます。既存クラスターやAKS Standardでは、上記の有効化作業が必要です。(Microsoft Learn)

ingress2gatewayでIngressを変換する

ingress2gatewayは、Kubernetes SIG Networkが管理するオープンソースツールです。Ingressやプロバイダー固有の設定を読み取り、Gateway APIリソースへ変換します。変換できない設定は警告として出力されます。(GitHub)

Homebrewを使用できる環境では、次のようにインストールできます。

brew install ingress2gateway

Go環境がある場合は、バージョンを固定してインストールします。次はv1.0.0の例です。

go install \
  github.com/kubernetes-sigs/[email protected]

Application RoutingのIngressClassを明示して変換します。

ingress2gateway print \
  --providers=ingress-nginx \
  --ingress-nginx-ingress-class=webapprouting.kubernetes.azure.com \
  --all-namespaces \
  --output=yaml \
  > gateway-generated.yaml \
  2> ingress2gateway-warnings.log

警告を確認します。

cat ingress2gateway-warnings.log

生成されたGatewayClassを必ず修正する

ingress2gatewayは、IngressのingressClassNameを、生成するGatewayのgatewayClassNameへ利用します。そのため、Application RoutingのIngressから変換した場合、次のように生成される可能性があります。

spec:
  gatewayClassName: webapprouting.kubernetes.azure.com

これはIngressClassの名前であり、Application Routing Gateway API版のGatewayClassではありません。次のように修正します。

spec:
  gatewayClassName: approuting-istio

この修正を忘れると、Gatewayを適用してもAKSのApplication Routingコントローラーに処理されません。ingress2gatewayの出力は完成版ではなく、レビュー用の初期マニフェストとして扱ってください。(Microsoft Learn)

自動変換されたアノテーションを確認する

ingress2gatewayは、すべてのNGINXアノテーションをそのままコピーするツールではありません。Gateway APIで表現できる設定だけを構造化されたフィールドへ変換します。(GitHub)

NGINX設定変換時の注意
rewrite-targetURLRewriteへ変換可能。ただし$1などのキャプチャ参照は非対応
permanent-redirectHTTPRequestRedirectへ変換
ssl-redirectHTTPからHTTPSへのリダイレクトとして変換
proxy-*-timeoutGateway APIのタイムアウト設定へ変換
custom-headers自動変換されず警告
proxy-redirect-from/to自動変換されず警告
Cookieによるカナリア自動変換されず警告
正規表現によるカナリアヘッダー自動変換されず警告
ssl-passthroughTLSRouteへ変換されるが、AKS側が現時点で非対応
独自snippet手動で代替方式を設計

特に、リライト、リダイレクト、認証連携、CORS、送信元IP制限、大容量アップロード、バックエンドTLSは、HTTP 200が返るだけでは移行成功と判断できません。実際のリクエスト条件で比較してください。(GitHub)

GatewayとHTTPRouteを作成する

単純なIngressは、次のようなGatewayとHTTPRouteへ置き換えられます。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: httpbin-gateway
  namespace: demo
spec:
  gatewayClassName: approuting-istio
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
  namespace: demo
spec:
  parentRefs:
    - name: httpbin-gateway
  hostnames:
    - httpbin.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /get
      backendRefs:
        - name: httpbin
          port: 8000

Ingressでは暗黙的だったHTTPの入口を、Gatewayのlistenersで明示しています。ホスト名とパスによる振り分けはHTTPRouteへ移動します。(Microsoft Learn)

最初にサーバーサイドのドライランを行います。

kubectl apply \
  --dry-run=server \
  -f gateway-reviewed.yaml

既存リソースとの差分を確認します。

kubectl diff -f gateway-reviewed.yaml

問題がなければ適用します。

kubectl apply -f gateway-reviewed.yaml

Gatewayがプログラムされるまで待ち、新しいIPを取得します。

kubectl wait \
  --for=condition=Programmed \
  -n demo \
  gateway/httpbin-gateway \
  --timeout=5m

export GW_IP=$(
  kubectl get gateway \
    -n demo \
    httpbin-gateway \
    -o jsonpath='{.status.addresses[0].value}'
)

echo "$GW_IP"

Gatewayを作成すると、対応するDeployment、LoadBalancer Service、HPA、PodDisruptionBudgetが管理対象として作成されます。標準設定では、Gatewayプロキシの可用性を確保するために複数レプリカとPodDisruptionBudgetが構成されます。(Microsoft Learn)

kubectl get deployment,service,hpa,pdb -n demo

HTTPSとAzure Key Vaultを移行する

Kubernetes Secretを直接参照する場合

既存のTLS証明書をKubernetes Secretとして利用する場合は、GatewayのHTTPS listenerからcertificateRefsで参照します。

listeners:
  - name: https
    hostname: app.example.com
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
        - kind: Secret
          name: app-example-com-tls
    allowedRoutes:
      namespaces:
        from: Same

GatewayとSecretが別のNamespaceにある場合は、Gateway APIの参照許可を適切に構成する必要があります。移行を単純化するなら、まずGatewayとTLS Secretを同じNamespaceへ配置する方法が安全です。

Azure Key Vault連携を使う場合

Gateway API版では、Azure Key Vault証明書とAzure DNSをApplication Routingオペレーターから自動管理できます。ただし、従来のNGINX版とは認証方式が異なります。

Gateway API版では、Microsoft Entra Workload Identityに紐づけたServiceAccountを利用します。従来の--attach-kvや--attach-zonesで設定したApplication Routingアドオン自身のマネージドIDは、Gateway API版のDNS／TLS連携には使用されません。(Microsoft Learn)

必要となる主な機能は次のとおりです。

  • --enable-app-routing
  • --enable-app-routing-istio
  • --enable-gateway-api
  • OIDC Issuer
  • Microsoft Entra Workload Identity
  • Azure Key Vault provider for Secrets Store CSI Driver
  • ユーザー割り当てマネージドID
  • Key Vaultに対するKey Vault Secrets User
  • Azure DNSに対するDNS Zone Contributor

既存クラスターでWorkload IdentityとKey Vault CSI Driverを有効化する例です。

az aks update \
  --resource-group "$RG" \
  --name "$CLUSTER" \
  --enable-oidc-issuer \
  --enable-workload-identity

az aks enable-addons \
  --resource-group "$RG" \
  --name "$CLUSTER" \
  --addons azure-keyvault-secrets-provider

Gatewayのlistenerには、Key Vault証明書のURIとServiceAccount名を指定します。

listeners:
  - name: https
    hostname: app.example.com
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      options:
        kubernetes.azure.com/tls-cert-keyvault-uri: https://example-vault.vault.azure.net/certificates/app-example-com
        kubernetes.azure.com/tls-cert-service-account: approuting-tls-sa
    allowedRoutes:
      namespaces:
        from: Same

証明書URIはバージョンを含まない形式にすると、Key Vault側で更新された証明書をApplication Routingオペレーターが追従できます。オペレーターはSecretProviderClassとTLS Secretを作成し、GatewayのcertificateRefsを更新します。(Microsoft Learn)

本番DNSの自動更新を有効にする場合は、移行前に意図せず新IPへ切り替わらないよう注意してください。検証用ホスト名を使用するか、ExternalDNSのNamespaceスコープやラベルフィルターを使い、対象Gatewayを限定する方法が安全です。(Microsoft Learn)

DNSを切り替える前に新しいGatewayを検証する

DNS変更前は、curl --resolveを使うと、実際のホスト名を維持したまま新しいGateway IPへ接続できます。

新しいGatewayを確認します。

curl -sS \
  -o /dev/null \
  -w '%{http_code}\n' \
  --resolve "httpbin.example.com:80:${GW_IP}" \
  http://httpbin.example.com/get

既存のingress-nginxも同じ条件で確認します。

curl -sS \
  -o /dev/null \
  -w '%{http_code}\n' \
  --resolve "httpbin.example.com:80:${INGRESS_NGINX_IP}" \
  http://httpbin.example.com/get

HTTPSの場合は、ポートを443、URLをhttps://へ変更します。

curl -sS \
  --resolve "httpbin.example.com:443:${GW_IP}" \
  https://httpbin.example.com/get

証明書エラーを無視する-kや--insecureだけで検証を終えないでください。本番証明書のSAN、証明書チェーン、有効期限まで確認します。

最低限、次の項目を旧NGINXと新Gatewayで比較します。

確認項目具体的なテスト
全ホスト名すべてのhostnamesへアクセス
全パス/だけでなくAPIや管理画面も確認
HTTPメソッドGET、POST、PUT、DELETEなど
認証Cookie、Bearer Token、OIDCログイン
リダイレクトHTTP→HTTPS、末尾スラッシュ、URL変更
リライトバックエンドへ渡されるパスを確認
ヘッダーHost、X-Forwarded-*、独自ヘッダー
TLSSAN、チェーン、SNI、証明書更新
大容量通信ファイルアップロード、リクエストボディ上限
長時間通信WebSocket、gRPC、ストリーミング
負荷数分以上の連続リクエストと5xx監視
外部連携Front Doorや監視サービスのヘルスプローブ

Microsoftの移行手順でも、HTTPステータスだけでなく、認証、POSTボディ、WebSocket、gRPC、持続負荷、外部サービスのヘルスプローブまで確認してから切り替えるよう案内されています。(Microsoft Learn)

Gateway API版ではEnvoyのアクセスログが標準で有効です。

kubectl logs \
  -n demo \
  deployment/httpbin-gateway-approuting-istio

GatewayやHTTPRouteが期待どおり受け入れられていない場合は、ステータス条件を確認します。

kubectl describe gateway \
  -n demo \
  httpbin-gateway

kubectl describe httproute \
  -n demo \
  httpbin

DNSをGateway APIのIPへ切り替える

すべての検証に合格したら、DNSのAレコードをINGRESS_NGINX_IPからGW_IPへ変更します。

同時に、旧IPを直接参照している次の設定も更新します。

  • Azure Front Doorのオリジン
  • Traffic Managerのエンドポイント
  • Application Gatewayのバックエンド
  • ファイアウォールの許可リスト
  • 監視サービスの接続先
  • 外部システムの固定IP設定

切り替え後は、Gateway側のアクセスログ、5xx、レイテンシ、バックエンドエラーを監視します。旧ingress-nginx側のリクエスト数も確認し、TTL経過後に通信がゼロになることを確認してください。

DNSのTTLはすぐに元へ戻さず、数時間程度は低い状態を維持します。問題が発生した場合に、短時間で旧IPへ戻せるためです。(Microsoft Learn)

問題が発生した場合はDNSを戻す

旧NGINXを削除する前であれば、ロールバックは比較的簡単です。

  1. 旧Ingressリソースが残っていることを確認する
  2. DNSのAレコードをINGRESS_NGINX_IPへ戻す
  3. Azure Front Doorなどの接続先も旧IPへ戻す
  4. TTL期間が経過するまで監視する
  5. Gateway側の設定を修正して再度検証する

必要であれば、Gateway API実装を無効化できます。

az aks update \
  --resource-group "$RG" \
  --name "$CLUSTER" \
  --disable-app-routing-istio

ただし、切り替え直後に無効化する必要はありません。旧NGINXとGateway APIを並行稼働させた状態で問題を修正する方が、安全に再試行できます。(Microsoft Learn)

安定稼働後にingress-nginxを削除する

Gateway API側で十分な期間安定稼働し、旧NGINXのリクエストがゼロになったら、Application Routingアドオンが既定のNGINXコントローラーを再作成しないよう設定します。

az aks approuting update \
  --resource-group "$RG" \
  --name "$CLUSTER" \
  --nginx None

続いて、既存のNginxIngressControllerカスタムリソースを削除します。

kubectl delete \
  nginxingresscontrollers.approuting.kubernetes.azure.com \
  --all

この2段階が必要です。--nginx Noneだけでは、既存のNGINX DeploymentとServiceは残ります。所有元のNginxIngressControllerを削除することで、NGINXのデータプレーンが削除されます。(Microsoft Learn)

Gateway API版でAzure DNSやAzure Key Vaultとの連携を使う場合は、Application Routingアドオン全体を無効化しないでください。Gateway API版のDNS／TLS自動化にもApplication Routingオペレーターが必要です。

つまり、次のコマンドでアドオン全体を削除するのではなく、NGINXだけをNoneにするのが基本です。

# Gateway APIのDNS／TLS連携を使う場合は安易に実行しない
az aks approuting disable \
  --resource-group "$RG" \
  --name "$CLUSTER"

最後に、不要になった旧IngressマニフェストをGitリポジトリやデプロイパイプラインから削除し、DNS TTLを通常値へ戻します。

移行で発生しやすい問題と対処法

症状主な原因確認・対処
approuting-istioが見つからないGateway API実装が未有効--enable-app-routing-istioを確認
Gateway API CRDがないManaged Gateway API未有効--enable-gateway-apiを実行
istiodが起動しないIstioアドオンのCRDが残存istio.io CRDとGatewayClassを確認
GatewayがProgrammed=FalselistenerやLoadBalancer作成失敗kubectl describe gatewayを確認
HTTPRouteがAccepted=FalseparentRefsやallowedRoutesの不一致Gateway名、Namespace、listenerを確認
一部のURLだけ404パス変換やリライトの差異全パスとURLRewriteを比較
HTTPからHTTPSへ転送されないredirect設定の変換漏れRequestRedirectフィルターを追加
TLS Secretが作成されないWorkload IdentityやRBAC不足ServiceAccount、FIC、Key Vaultロールを確認
DNSが一部だけ旧IPを返す変更前TTLが残っている旧TTL期間の経過を待つ
Front Doorのヘルスプローブが失敗オリジンHostや証明書の不一致Hostヘッダー、証明書SAN、パスを確認
旧IPをGatewayへ設定できないAKS管理IPは付け替え前提ではないDNSや上流サービスを新IPへ変更
ingress2gatewayの出力が適用できない未対応アノテーションやGatewayClassの違い警告確認と手動修正を実施

移行完了のチェックリスト

次の条件をすべて満たせば、ingress-nginxからGateway APIへの移行は完了です。

  • GatewayClass/approuting-istioが正常に受け入れられている
  • すべてのGatewayがProgrammed=Trueになっている
  • すべてのHTTPRouteがAccepted=Trueになっている
  • 全ホスト名と全パスを新Gateway IPで確認した
  • HTTPS証明書のSANと証明書チェーンを確認した
  • POST、認証、アップロード、WebSocket、gRPCを確認した
  • Azure Front Doorやファイアウォールの固定IPを更新した
  • DNSが新Gateway IPを返している
  • 旧ingress-nginxへのリクエストがゼロになった
  • DNSを旧IPへ戻すロールバック手順を確認した
  • 十分な安定稼働期間を設けた
  • --nginx Noneを設定した
  • NginxIngressControllerを削除した
  • 旧Ingressマニフェストをデプロイ対象から除外した
  • DNS TTLを通常値へ戻した

AKS Application RoutingのGateway API移行で重要なのは、Ingressを機械的に変換することではありません。新旧データプレーンを並行稼働させ、IPを直接指定して実際のアプリケーション動作を比較し、DNSで切り替えることが成功のポイントです。

まずは現在のIngressとNGINX固有アノテーションを一覧化し、ssl-passthrough、複雑なリライト、独自ヘッダー、固定IP参照など、移行を難しくする設定を洗い出してください。その後、影響の小さいアプリケーションからingress2gatewayで変換し、本番と同じ条件で検証を進めるのが安全です。

Azure
AKS Gateway API Application Routing ingress-nginx ingress2gateway

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次