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

[アーティクル]
08/16/2024

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

複数のコントローラーの作成、プライベートロードバランサーの構成、静的 IP アドレスの設定などの NGINX イングレスコントローラーの構成。
注釈を使用したイングレスリソースごとの構成。

前提条件

ご利用の 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 クラスターのバージョンを確認するには、「利用可能な AKS クラスターのアップグレードを確認する」を参照してください。

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

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

Bicep

webAppRouting プロファイルには、defaultIngressControllerType プロパティを持つ nginx 構成があります (省略可能)。

    "ingressProfile": {
      "webAppRouting": {
        "nginx": {
            "defaultIngressControllerType": "None|Internal|External|AnnotationControlled"
        }
    }

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

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

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

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

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

apiVersion: approuting.kubernetes.azure.com/v1alpha1
kind: NginxIngressController
metadata:
  name: nginx-public
spec:
  ingressClassName: nginx-public
  controllerNamePrefix: nginx-public

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 イングレスコントローラーを作成するには:

次の 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"

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 イングレスコントローラーを作成するには:

az group create コマンドを使用して、Azure リソースグループを作成します。
```
az group create --name myNetworkResourceGroup --location eastus
```
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 ロードバランサーで動作します。
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}
```
次の 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"
```
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

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

次の 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

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 を使用してサービスに到達します。 HTTPS や GRPC などの代替バックエンドプロトコルを構成するには、次の注釈を使用します。

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) を有効にするには、次の注釈を使用します。

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 コントローラーメトリックを監視する方法についてご確認ください。

次の方法で共有

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

前提条件

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

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

一般的な構成

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

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

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

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

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

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

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

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

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

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

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

バックエンドプロトコル

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

URL リライト

次のステップ

その他のリソース

次の方法で共有

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

前提条件

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

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

一般的な構成

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

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

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

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

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

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

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

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

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

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

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

バックエンド プロトコル

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

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

URL リライト

次のステップ

その他のリソース

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

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

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

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

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

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

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

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

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

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

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

バックエンドプロトコル

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