アプリケーション ルーティング アドオンを使用した高度な NGINX イングレス コントローラーとイングレスの構成
アプリケーション ルーティング アドオンでは、イングレス コントローラーとイングレス オブジェクトを構成する 2 つの方法がサポートされています。
- 複数のコントローラーの作成、プライベート ロード バランサーの構成、静的 IP アドレスの設定などの NGINX イングレス コントローラーの構成。
- 注釈を使用したイングレス リソースごとの構成。
前提条件
アプリケーション ルーティング アドオンでの 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 クラスターのバージョンを確認するには、「利用可能な AKS クラスターのアップグレードを確認する」を参照してください。
NGINX を使用してアプリケーション ルーティング アドオンを有効にすると、一般向けの Azure ロード バランサーを使用して構成された app-routing-namespace
に、default
と呼ばれるイングレス コントローラーが作成されます。 このイングレス コントローラーは、webapprouting.kubernetes.azure.com
のイングレス クラス名を使用します。
既定値がパブリック IP または内部 IP どちらを取得するか、アドオンを有効にするときに作成するかどうかを制御することもできます。
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)
イングレス ルールでクロス オリジン リソース共有 (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 コントローラー メトリックを監視する方法についてご確認ください。
Azure Kubernetes Service