使用 Azure Kubernetes Service (AKS) 的應用程式路由附加元件進行進階 NGINX 輸入控制器和輸入設定

本文會逐步引導您使用適用於 Azure Kubernetes Service （AKS）的應用程式路由附加元件來設定輸入控制器和輸入物件的兩種方式：

NGINX 輸入控制器的設定，例如建立多個控制器、設定私人負載平衡器，以及設定靜態 IP 位址。
透過註釋每個輸入資源設定。

先決條件

已啟用應用程式路由附加元件的 AKS 叢集。
kubectl 已配置為連線至您的 AKS 叢集。如需詳細資訊，請參閱連線到 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 $RESOURCE_GROUP --name $CLUSTER_NAME
```

NGINX 輸入控制器的組態屬性

應用程式路由附加元件會使用稱為的 Kubernetes NginxIngressController 來設定 NGINX 輸入控制器。您可以建立更多輸入控制器或修改現有組態。

下表列出您可以設定的屬性，以設定 NginxIngressController：

領域	類型	描述	為必填項目	預設
`controllerNamePrefix`	字串	受管理的 NGINX 入口控制器資源名稱。	是的	`nginx`
`customHTTPErrors`	陣列	將錯誤碼陣列傳送至預設後端系統，如果發生錯誤。	否
`defaultBackendService`	物件	用來路由不相符 HTTP 流量的服務。包含巢狀屬性：	否
`name`	字串	服務名稱。	是的
`namespace`	字串	服務命名空間。	是的
`defaultSSLCertificate`	物件	包含存取預設後端服務的預設憑證。包含巢狀屬性：	否
`forceSSLRedirect`	boolean	設定憑證時強制 HTTPS 重新導向。	否	`false`
`keyVaultURI`	字串	用於儲存憑證的 Key Vault 祕密的 URI。	否
`secret`	物件	保留預設 SSL 憑證的秘密資訊。包含巢狀屬性：	否
`name`	字串	祕密名稱。	是的
`namespace`	字串	秘密命名空間。	是的
`httpDisabled`	boolean	旗標用於禁用控制器的 HTTP 流量。	否
`ingressClassName`	字串	控制器所使用的 IngressClass 名稱。	是的	`nginx.approuting.kubernetes.azure.com`
`loadBalancerAnnotations`	物件	透過設定負載平衡器註釋來控制 NGINX 輸入控制器服務行為的註釋對應。	否
`scaling`	物件	用於擴縮控制器的設定。包含巢狀屬性：	否
`maxReplicas`	整數	複本數上限。	否	`100`
`minReplicas`	整數	複本數下限。	否	`2`
`threshold`	字串	定義如何積極地擴縮的擴縮閾值。 `rapid` 快速應對突發流量高峰，`steady` 有利於成本效益，而且 `balanced` 是綜合方案。	否	`balanced`

控制預設 NGINX 輸入控制器組態

當您使用 NGINX 啟用應用程式路由附加元件時，它會在使用公開的 Azure 負載平衡器設定的 default 中建立名為 app-routing-namespace 的輸入控制器。該輸入控制器會使用 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> 為控制預設 NGINX 輸入控制器組態中所述的其中一個組態選項。
```
az aks create \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --location $LOCATION \
  --enable-app-routing \
  --app-routing-default-nginx-controller <DefaultIngressControllerType>
```

webAppRouting設定檔具有可選的nginx組態，您可以修改defaultIngressControllerType屬性以調整預設組態。

將屬性 defaultIngressControllerType 設定為控制預設 NGINX 輸入控制器組態中所述的其中一個組態選項。

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

更新現有叢集上的預設輸入控制器組態

Azure CLI
肱二頭肌

使用具有旗標的az aks approuting update命令，更新--nginx現有叢集上的應用程式路由預設輸入控制器組態。您必須將設定 <DefaultIngressControllerType> 為控制預設 NGINX 輸入控制器組態中所述的其中一個組態選項。
```
az aks approuting update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --nginx <DefaultIngressControllerType>
```

webAppRouting設定檔具有可選的nginx組態，您可以修改defaultIngressControllerType屬性以調整預設組態。

將屬性 defaultIngressControllerType 設定為控制預設 NGINX 輸入控制器組態中所述的其中一個組態選項。

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

建立另一個面向公用的 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 輸入控制器

將下列 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 輸入控制器

使用 az group create 命令來建立 Azure 資源群組。

az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION

使用 az network public ip create 命令建立靜態公用 IP 位址。
```
az network public-ip create \
  --resource-group $NETWORK_RESOURCE_GROUP \
  --name $PUBLIC_IP_NAME \
  --sku Standard \
  --allocation-method static
```
附註

如果您在 AKS 叢集中使用基本 SKU 負載平衡器，請在定義公用 IP 時使用Basic作為--sku參數。只有 Basic SKU IP 可與基本 SKU 負載平衡器搭配使用，而只有 Standard SKU IP 可與標準 SKU 負載平衡器搭配使用。

請確定 AKS 叢集所使用的叢集身分識別使用 az role assignment create 命令，將權限委派給公用 IP 的資源群組。

CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --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 註解可確保建立最有效率的負載平衡器，並強烈建議以避免潛在的節流問題。
```
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: "$PUBLIC_IP_NAME"
    service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"
```

使用 kubectl apply 命令建立 NGINX 輸入控制器資源。

kubectl apply -f nginx-staticip-controller.yaml

下列範例輸出顯示已建立的資源：

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

確認已建立的輸入控制器

使用命令 kubectl get nginxingresscontroller 驗證NGINX輸入控制器的狀態。

kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME

下列範例輸出顯示已建立的資源。控制器變為可用可能需要數分鐘的時間：

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

檢視輸入控制器的條件

檢視輸入控制器的條件，以使用命令 kubectl get nginxingresscontroller 對任何問題進行故障排除。

kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -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 --namespace hello-web-app-routing

下列範例輸出顯示已建立的資源：

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

確認已建立受控輸入

確認已使用命令 kubectl get ingress 建立受管理輸入。

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

您的輸出應該與下列範例輸出類似：

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輸入控制器。
```
kubectl delete nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
```

透過註釋每個輸入資源設定

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 Ingress 控制器使用 HTTP 連線到服務。若要設定替代後端通訊協定，例如 HTTPS 或 GRPC，請使用下列其中一個註解：

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

# GRPC annotation
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），請使用下列註解：

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

NGINX 健康情況探查路徑更新

與 NGINX 輸入控制器相關聯之 Azure 負載平衡器的預設健康情況探查路徑必須設定為 "/healthz"。若要確保健康檢查正確，請確認 ingress 控制器服務具有下列註解：

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

如果您使用 Helm 來管理 NGINX 輸入控制器，您可以在值檔案中定義 Azure Load Balancer 健康情況探查註釋，並在升級期間套用它：

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

此配置有助於維護服務可用性並避免升級期間意外的流量中斷。

後續步驟

了解如何使用 Grafana 中的 Prometheus 監視應用程式路由附加元件中的 Ingress-nginx 控制器計量，協助分析應用程式的效能和使用。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-31

共用方式為

使用 Azure Kubernetes Service (AKS) 的應用程式路由附加元件進行進階 NGINX 輸入控制器和輸入設定

先決條件

連線至您的 AKS 叢集

NGINX 輸入控制器的組態屬性

控制預設 NGINX 輸入控制器組態

控制新叢集上的預設輸入控制器組態

更新現有叢集上的預設輸入控制器組態

建立另一個面向公用的 NGINX 輸入控制器

使用私人 IP 位址建立內部 NGINX 輸入控制器

使用靜態 IP 位址建立 NGINX 輸入控制器

確認已建立的輸入控制器

檢視輸入控制器的條件

在輸入中使用輸入控制器

確認已建立受控輸入

移除輸入控制器

透過註釋每個輸入資源設定

自訂主體大小上限

自訂的連線逾時設定

後端通訊協定

跨原始來源資源分享 (CORS)

停用 SSL 重新導向

URL 重寫

NGINX 健康情況探查路徑更新

後續步驟

意見反應

其他資源