應用程式路由附加元件的進階 NGINX 輸入控制器和輸入設定
應用程式路由附加元件支援兩種方式來設定輸入控制器和輸入物件:
- NGINX 輸入控制器的設定,例如建立多個控制器、設定私人負載平衡器,以及設定靜態 IP 位址。
- 透過註釋每個輸入資源設定。
必要條件
具有應用程式路由附加元件的 AKS 叢集。
連線至您的 AKS 叢集
如果要從本機電腦連線至 Kubernetes 叢集,應使用 Kubernetes 命令列用戶端 kubectl
。 您可以使用 az aks install-cli 命令將其安裝於本機。 如果您使用 Azure Cloud Shell,則 kubectl
已安裝。
使用 az aks get-credentials
命令設定 kubectl,以連線到您的 Kubernetes 叢集。
az aks get-credentials -resource-group <ResourceGroupName> --name <ClusterName>
NGINX 輸入控制器的設定
應用程式路由附加元件會使用稱為 NginxIngressController
的 Kubernetes 自訂資源定義 (CRD) 來設定 NGINX 輸入控制器。 您可以建立更多輸入控制器或修改現有的設定。
以下是您可以設定的屬性 NginxIngressController
參考。
屬性 | 說明 |
---|---|
ingressClassName | 將用於 NGINX 輸入控制器的 名稱 IngressClass 。 如果未指定,則預設為 的名稱 NginxIngressController 。 |
controllerNamePrefix | 用來在Managed NGINX 輸入控制器資源前面加上的名稱。 預設為 nginx 。 |
loadBalancerAnnotations | 一組註釋,可藉由設定 負載平衡器註釋來控制 NGINX 輸入控制器服務的行為 |
縮放 | NGINX 輸入控制器調整方式的組態選項。 |
scaling.minReplicas | 輸入控制器複本數目的下限。 預設為 2 個 Pod。 |
scaling.maxReplicas | 輸入控制器複本數目的上限。 預設為 100 個 Pod。 |
scaling.threshold | 定義 NGINX 輸入控制器 Pod 應該根據工作負載調整的速度。 Rapid 表示輸入控制器會快速且積極地調整,以處理突然和顯著的流量尖峰。 Steady 使用較少的複本處理更多工作來排定成本效益的優先順序。 Balanced 是兩者之間適用於大部分使用案例的好組合。 如果未指定,此欄位預設為 Balanced 。 |
defaultBackendService | NGINX 輸入控制器應預設的 Kubernetes 服務,其會處理所有 URL 路徑,並裝載 Ingress-NGINX 控制器不瞭解 (亦即,未與輸入對應的所有要求)。 控制器會將流量導向至服務的第一個埠。 如果未指定,這會使用 內建的預設後端 。 |
defaultBackendService.namespace | 服務的命名空間。 |
defaultBackendService.name | 服務的名稱。 |
defaultSSLCertificate | 這個屬性所參考的秘密包含存取預設後端服務時要使用的預設憑證。 如果未提供此屬性,NGINX 會使用自我簽署憑證。 如果未在 tls: 輸入上設定 區段,NGINX 會提供預設憑證,但不會強制 HTTPS 重新導向。 |
defaultSSLCertificate.forceSSLRedirect | 針對未指定 tls: 區段的輸入強制重新導向。 |
defaultSSLCertificate.keyVaultURI | 您可以在其中找到預設 SSL 憑證的 Azure 金鑰保存庫 URI。 附加元件必須 設定為使用金鑰保存庫。 |
defaultSSLCertificate.secret | 設定叢集上預設 SSL 秘密所在的名稱和命名空間。 |
defaultSSLCertificate.secret.name | 秘密的名稱。 |
defaultSSLCertificate.secret.namespace | 秘密的命名空間。 |
一般設定
控制預設 NGINX 輸入控制器組態 (預覽)
注意
啟用附加元件時,控制 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,或在啟用附加元件時完全建立它。
以下是可能的組態選項:
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 輸入控制器:
將下列 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 輸入控制器
使用靜態 IP 位址建立 Azure Load Balancer 上的 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
注意
如果您在 AKS 叢集中使用基本 SKU 負載平衡器,請在定義公用 IP 時針對
--sku
參數使用 Basic。 只有基本 SKU IP 可用於基本 SKU 負載平衡器,且只有標準 SKU IP 可用於標準 SKU 負載平衡器。請確定 AKS 叢集所使用的叢集身分識別使用
az role assignment create
命令,將權限委派給公用 IP 的資源群組。注意
使用 AKS 叢集名稱和資源群組名稱更新
<ClusterName>
和<ClusterResourceGroup>
。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 的新檔案中,並儲存於本機電腦。
注意
您可以對於公用 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
,如範例 YAML 所示。 新增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 輸入控制器的狀態。
注意
使用您在建立「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 的新檔案中,並儲存於本機電腦。
注意
使用您的 DNS 主機名稱更新
<Hostname>
。<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 輸入控制器資源。
注意
使用您在建立 NginxIngressController
時所使用的名稱更新 <IngressControllerName>
。
kubectl delete nginxingresscontroller -n <IngressControllerName>
透過註釋每個輸入資源設定
NGINX 輸入控制器支援新增註釋至特定輸入物件,以自自訂其行為。
您可以在 metadata.annotations
欄位中新增個別註釋,以註釋輸入物件。
注意
註釋索引鍵和值只能是字串。 其他類型,例如布林值或數值必須加上引號,例如 "true"
、"false"
、"100"
。
以下是一些常見組態的範例註釋。 如需完整清單,請檢閱 NGINX 輸入註釋文件。
自訂主體大小上限
針對 NGINX,當要求的大小超過用戶端要求主體允許的大小上限時,就會傳回 413 錯誤給用戶端。 若要覆寫預設值,請使用註釋:
nginx.ingress.kubernetes.io/proxy-body-size: 4m
以下是使用此註釋的輸入設定範例:
注意
使用您的 DNS 主機名稱更新 <Hostname>
。
<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 秒 Proxy 讀取逾時:
nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
檢閱其他設定選項自訂逾時。
以下是使用此註釋的輸入設定範例:
注意
使用您的 DNS 主機名稱更新 <Hostname>
。
<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"
檢閱後端通訊協定,以取得其他設定選項。
以下是使用此註釋的輸入設定範例:
注意
使用您的 DNS 主機名稱更新 <Hostname>
。
<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,以取得其他設定選項。
以下是使用此註釋的輸入設定範例:
注意
使用您的 DNS 主機名稱更新 <Hostname>
。
<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,以取得其他設定選項。
以下是使用此註釋的輸入設定範例:
注意
使用您的 DNS 主機名稱更新 <Hostname>
。
<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。 此設定適用於 路徑型路由 ,您可以在相同的網域下提供兩個不同的 Web 應用程式。 您可以使用註解來設定服務預期的路徑:
nginx.ingress.kubernetes.io/rewrite-target": /$2
以下是使用此註釋的輸入設定範例:
注意
使用您的 DNS 主機名稱更新 <Hostname>
。
<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 控制器計量,協助分析應用程式的效能和使用。