次の方法で共有


アプリケーション ルーティング アドオンを使用した高度な NGINX イングレス コントローラーとイングレスの構成

アプリケーション ルーティング アドオンでは、イングレス コントローラーとイングレス オブジェクトを構成する 2 つの方法がサポートされています。

前提条件

アプリケーション ルーティング アドオンでの AKS クラスター。

ご利用の AKS クラスターに接続する

お使いのローカル コンピューターから Kubernetes クラスターに接続するには、kubectl (Kubernetes コマンドライン クライアント) を使用します。 az aks install-cli コマンドを使用してローカルにインストールできます。 Azure Cloud Shell を使用している場合、kubectl は既にインストールされています。

az aks get-credentials コマンドを使って Kubernetes クラスターに接続するように、kubectl を構成します。

az aks get-credentials -resource-group <ResourceGroupName> --name <ClusterName>

NGINX イングレス コントローラーの構成

アプリケーション ルーティング アドオンは、NginxIngressController と呼ばれる Kubernetes カスタム リソース定義 (CRD) を使用して、NGINX イングレス コントローラーを構成します。 より多くのイングレス コントローラーを作成することも、既存の構成を変更することもできます。

NginxIngressController を構成するために設定できるプロパティのリファレンスを次に示します。

プロパティ 説明
ingressClassName NGINX イングレス コントローラーに使用する IngressClass の名前。 指定しない場合は、既定の名前 NginxIngressController となります。
controllerNamePrefix マネージド NGINX イングレス コントローラー リソースのプレフィックスとして使用する名前。 既定値は nginx です。
loadBalancerAnnotations ロード バランサーの注釈を設定することで、NGINX イングレス コントローラーのサービスの動作を制御する注釈セット
scaling NGINX イングレス コントローラーのスケーリング方法に関する構成オプション。
scaling.minReplicas イングレス コントローラー レプリカの数の下限。 既定値は 2 ポッドです。
scaling.maxReplicas イングレス コントローラー レプリカの数の上限。 既定値は 100 ポッドです。
scaling.threshold NGINX イングレス コントローラー ポッドをワークロードに基づいてどのくらい速くスケーリングするかを定義します。 Rapid は、イングレス コントローラーを迅速かつ積極的にスケーリングして、突然のトラフィックの急増に対処することを意味します。 Steady は、より少ないレプリカでより多くの作業量を処理することでコスト効率を優先します。 Balanced は、2 点の適切な組み合わせであり、ほとんどのユース ケースに適しています。 指定しない場合は、フィールドの既定値 Balanced となります。
defaultBackendService NGINX イングレス コントローラーが既定で、Ingress-NGINX コントローラーが解釈しないすべての URL パスおよびホストを処理する Kubernetes サービス (イングレスにマップされていないすべての要求)。 コントローラーは、サービスの最初のポートにトラフィックを転送します。 指定しない場合は、組み込みの既定のバックエンドを使用します。
defaultBackendService.namespace サービスの名前空間。
defaultBackendService.name サービスの名前。
defaultSSLCertificate このプロパティによって参照されるシークレットには、既定のバックエンド サービスへのアクセス時に使用する既定の証明書が含まれています。 このプロパティを指定しない場合、NGINX は自己署名証明書を使用します。 tls: セクションがイングレスに設定されていない場合、NGINX は既定の証明書を指定しますが、HTTPS リダイレクトは強制しません。
defaultSSLCertificate.forceSSLRedirect tls: セクションを指定していないイングレスにリダイレクトを強制します。
defaultSSLCertificate.keyVaultURI 既定の SSL 証明書がある Azure Key Vault URI。 アドオンは、キー コンテナーを使用するように構成する必要があります。
defaultSSLCertificate.secret クラスター上で、既定の SSL シークレットがある場所の名前と名前空間を構成します。
defaultSSLCertificate.secret.name シークレットの名前。
defaultSSLCertificate.secret.namespace シークレットの名前空間。

一般的な構成

既定の NGINX イングレス コントローラーの構成を制御する (プレビュー)

Note

アドオンを有効にするときの NGINX イングレス コントローラー構成の制御は、API 2024-06-02-preview、Kubernetes バージョン 1.30 以降、aks-preview Azure CLI 拡張機能バージョン 7.0.0b5 以降で使用できます。 AKS クラスターのバージョンを確認するには、「利用可能な AKS クラスターのアップグレードを確認する」を参照してください。

NGINX を使用してアプリケーション ルーティング アドオンを有効にすると、一般向けの Azure ロード バランサーを使用して構成された app-routing-namespace に、default と呼ばれるイングレス コントローラーが作成されます。 このイングレス コントローラーは、webapprouting.kubernetes.azure.com のイングレス クラス名を使用します。

既定値がパブリック IP または内部 IP どちらを取得するか、アドオンを有効にするときに作成するかどうかを制御することもできます。

取り得る構成オプションを次に示します。

  • None: 既定の Nginx イングレス コントローラーは作成されず、既に存在する場合は削除されません。 必要に応じて、既定の NginxIngressController カスタム リソースを削除します。
  • Internal: 既定の Nginx イングレス コントローラーは、内部ロード バランサーで作成されます。 NginxIngressController カスタム リソースを外部にするための注釈の変更は、上書きされます。
  • External: 外部ロード バランサーで作成された既定の Nginx イングレス コントローラー。 NginxIngressController カスタム リソースを内部にするための注釈の変更は、上書きされます。
  • AnnotationControlled (既定値): 既定の Nginx イングレス コントローラーは、外部ロード バランサーを使用して作成されます。 ユーザーは、既定の NginxIngressController カスタム リソースを編集して、ロード バランサーの注釈を構成できます。

クラスター作成時の既定のイングレス コントローラーの構成を制御する

新しいクラスターでアプリケーション ルーティングを有効にするには、az aks create コマンドを使い、--enable-app-routing--app-routing-default-nginx-controller フラグを指定します。 前に説明した構成オプションのいずれかに <DefaultIngressControllerType> を設定する必要があります。

az aks create \
--resource-group <ResourceGroupName> \
--name <ClusterName> \
--location <Location> \
--enable-app-routing \
--app-routing-default-nginx-controller <DefaultIngressControllerType>

既存のクラスターで既定のイングレス コントローラーの構成を更新する

既存のクラスターでアプリケーション ルーティングの既定のイングレス コントローラーの構成を更新するには、az aks approuting update コマンドを使い、--nginx フラグを指定します。 前に説明した構成オプションのいずれかに <DefaultIngressControllerType> を設定する必要があります。

az aks approuting update --resource-group <ResourceGroupName> --name <ClusterName> --nginx <DefaultIngressControllerType>

別の一般向けの NGINX イングレス コントローラーを作成する

一般向けの Azure Load Balancer を使用して別の NGINX イングレス コントローラーを作成するには:

  1. 次の YAML マニフェストを nginx-public-controller.yaml という名前の新しいファイルにコピーし、ファイルをローカル コンピューターに保存します。

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
    kind: NginxIngressController
    metadata:
      name: nginx-public
    spec:
      ingressClassName: nginx-public
      controllerNamePrefix: nginx-public
    
  2. kubectl apply コマンドを使用して NGINX イングレス コントローラー リソースを作成します。

    kubectl apply -f nginx-public-controller.yaml
    

    次の出力例では、作成されたリソースが示されています。

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
    

プライベート IP アドレスを持つ内部 NGINX イングレス コントローラーを作成する

プライベート IP アドレスを持つ内部接続の Azure Load Balancer を使用して NGINX イングレス コントローラーを作成するには:

  1. 次の YAML マニフェストを nginx-internal-controller.yaml という名前の新しいファイルにコピーし、ファイルをローカル コンピューターに保存します。

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
    kind: NginxIngressController
    metadata:
      name: nginx-internal
    spec:
      ingressClassName: nginx-internal
      controllerNamePrefix: nginx-internal
      loadBalancerAnnotations: 
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
    
  2. kubectl apply コマンドを使用して NGINX イングレス コントローラー リソースを作成します。

    kubectl apply -f nginx-internal-controller.yaml
    

    次の出力例では、作成されたリソースが示されています。

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
    

静的 IP アドレスを使用して NGINX イングレス コントローラーを作成する

Azure Load Balancer で静的 IP アドレスを使用して NGINX イングレス コントローラーを作成するには:

  1. az group create コマンドを使用して、Azure リソース グループを作成します。

    az group create --name myNetworkResourceGroup --location eastus
    
  2. az network public ip create コマンドを使用して静的パブリック IP アドレスを作成します。

    az network public-ip create \
        --resource-group myNetworkResourceGroup \
        --name myIngressPublicIP \
        --sku Standard \
        --allocation-method static
    

    Note

    AKS クラスターで Basic SKU ロード バランサーを使用している場合は、パブリック IP を定義するときに パラメーターに Basic--sku を使用します。 Basic SKU IP のみが Basic SKU ロード バランサーで動作し、Standard SKU IP のみが Standard SKU ロード バランサーで動作します。

  3. az role assignment create コマンドを使用して、AKS クラスターで使用されるクラスター ID に、パブリック IP のリソース グループへの委任されたアクセス許可が含まれていることを確認してください。

    Note

    <ClusterName><ClusterResourceGroup> を AKS クラスターの名前とリソース グループ名で更新します。

    CLIENT_ID=$(az aks show --name <ClusterName> --resource-group <ClusterResourceGroup> --query identity.principalId -o tsv)
    RG_SCOPE=$(az group show --name myNetworkResourceGroup --query id -o tsv)
    az role assignment create \
        --assignee ${CLIENT_ID} \
        --role "Network Contributor" \
        --scope ${RG_SCOPE}
    
  4. 次の YAML マニフェストを nginx-staticip-controller.yaml という名前の新しいファイルにコピーし、ファイルをローカル コンピューターに保存します。

    Note

    YAML 例のように、パブリック IP 名に service.beta.kubernetes.io/azure-pip-name を使用するか、IPv4 アドレスには service.beta.kubernetes.io/azure-load-balancer-ipv4、IPv6 アドレスには service.beta.kubernetes.io/azure-load-balancer-ipv6 を使用できます。 service.beta.kubernetes.io/azure-pip-name 注釈を追加することで、最も効率的な LoadBalancer が確実に作成されます。調整の可能性があるため、それを回避するために強く推奨されます。

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
    kind: NginxIngressController
    metadata:
      name: nginx-static
    spec:
      ingressClassName: nginx-static
      controllerNamePrefix: nginx-static
      loadBalancerAnnotations: 
        service.beta.kubernetes.io/azure-pip-name: "myIngressPublicIP"
        service.beta.kubernetes.io/azure-load-balancer-resource-group: "myNetworkResourceGroup"
    
  5. kubectl apply コマンドを使用して NGINX イングレス コントローラー リソースを作成します。

    kubectl apply -f nginx-staticip-controller.yaml
    

    次の出力例では、作成されたリソースが示されています。

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
    

イングレス コントローラーが作成されたことを確認する

kubectl get nginxingresscontroller コマンドを使用して、NGINX イングレス コントローラーの状態を検証できます。

Note

'NginxIngressController' の作成時に使用した名前で <IngressControllerName> を更新します。

kubectl get nginxingresscontroller -n <IngressControllerName>

次の出力例では、作成されたリソースが示されています。 コントローラーが使用可能になるまでに数分かかる場合があります。

NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
nginx-public   nginx-public   nginx                  True

問題のトラブルシューティングを行う条件を表示することもできます。

kubectl get nginxingresscontroller -n <IngressControllerName> -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'

次の出力例では、正常なイングレス コントローラーの状態が示されています。

2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed

イングレスでイングレス コントローラーを使用する

  1. 次の YAML マニフェストを ingress.yaml という名前の新しいファイルにコピーし、ファイルをローカル コンピューターに保存します。

    Note

    <Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: aks-helloworld
      namespace: hello-web-app-routing
    spec:
      ingressClassName: <IngressClassName>
      rules:
      - host: <Hostname>
        http:
          paths:
          - backend:
              service:
                name: aks-helloworld
                port:
                  number: 80
            path: /
            pathType: Prefix
    
  2. kubectl apply コマンドを使ってクラスター リソースを作成します。

    kubectl apply -f ingress.yaml -n hello-web-app-routing
    

    次の出力例では、作成されたリソースが示されています。

    ingress.networking.k8s.io/aks-helloworld created
    

マネージド イングレスが作成されたことを確認する

マネージド イングレスが作成されたことは、kubectl get ingress コマンドを使って確認できます。

kubectl get ingress -n hello-web-app-routing

次の出力例では、作成されたマネージド イングレスが示されています。 イングレス クラス、ホスト、IP アドレスは異なる場合があります。

NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m

イングレス コントローラーをクリーンアップする

kubectl delete nginxingresscontroller コマンドを使用して NGINX イングレス コントローラーを削除できます。

Note

NginxIngressController の作成時に使用した名前で <IngressControllerName> を更新します。

kubectl delete nginxingresscontroller -n <IngressControllerName>

注釈を使用したイングレス リソースごとの構成

NGINX イングレス コントローラーでは、特定のイングレス オブジェクトへの注釈の追加による動作のカスタマイズがサポートされています。

metadata.annotations フィールドにそれぞれの注釈を追加すると、イングレス オブジェクトに注釈を設定できます。

Note

注釈キーおよび値には文字列のみを使用できます。 ブール値や数値などのその他の型は引用符で囲む必要があります (つまり、"true""false""100")。

一般的な構成の注釈の例を次に示します。 完全なリストについては、「NGINX イングレスの注釈のドキュメント」を確認してください。

カスタムの最大本文サイズ

NGINX の場合、要求のサイズがクライアントの要求本文の最大許容サイズを超えると、クライアントに 413 エラーが返されます。 既定値をオーバーライドするには、注釈を使用します。

nginx.ingress.kubernetes.io/proxy-body-size: 4m

この注釈を使用したイングレス構成の例を次に示します。

Note

<Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

カスタム接続タイムアウト

NGINX イングレス コントローラーがワークロードとの接続を閉じるのを待機するタイムアウトを変更できます。 タイムアウト値はすべて、単位が付けられていません (秒単位)。 既定のタイムアウトをオーバーライドするには、次の注釈を使用して有効な 120 秒のプロキシ読み取りタイムアウトを設定します。

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

その他の構成オプションについては、「カスタム タイムアウト」を確認してください。

この注釈を使用したイングレス構成の例を次に示します。

Note

<Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

バックエンド プロトコル

既定では、NGINX イングレス コントローラーは HTTP を使用してサービスに到達します。 HTTPSGRPC などの代替バックエンド プロトコルを構成するには、次の注釈を使用します。

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

または

nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

その他の構成オプションについては、「バックエンド プロトコル」を確認してください。

この注釈を使用したイングレス構成の例を次に示します。

Note

<Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

クロスオリジン リソース共有 (CORS)

イングレス ルールでクロス オリジン リソース共有 (CORS) を有効にするには、次の注釈を使用します。

nginx.ingress.kubernetes.io/enable-cors: "true"

その他の構成オプションについては、「CORS を有効にする」を確認してください。

この注釈を使用したイングレス構成の例を次に示します。

Note

<Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

SSL リダイレクトを無効にする

既定では、イングレスに対して TLS が有効になっている場合、コントローラーは (308) を HTTPS にリダイレクトします。 特定のイングレス リソースに対してこの機能を無効にするには、次の注釈を使用します。

nginx.ingress.kubernetes.io/ssl-redirect: "false"

その他の構成オプションについては、「リダイレクトを使用した サーバー側の HTTPS の適用」を確認してください。

この注釈を使用したイングレス構成の例を次に示します。

Note

<Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

URL リライト

一部のシナリオでは、バックエンド サービスで公開されている URL がイングレス ルールに指定されたパスと異なります。 再書き込みがない場合、要求は 404 を返します。 この構成は、同じドメインの下で 2 つの異なる Web アプリケーションを処理できるパス ベースのルーティングの場合に便利です。 次の注釈を使用して、サービスで想定されるパスを設定できます。

nginx.ingress.kubernetes.io/rewrite-target": /$2

この注釈を使用したイングレス構成の例を次に示します。

Note

<Hostname> を DNS ホスト名で更新します。 <IngressClassName> は、NginxIngressController の作成時に定義したものです。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

次のステップ

アプリケーションのパフォーマンスと使用状況の分析の一環として、Grafana で Prometheus を使用して、アプリケーション ルーティング アドオンに含まれる ingress-nginx コントローラー メトリックを監視する方法についてご確認ください。