應用程式路由附加元件的進階 NGINX 輸入控制器和輸入設定

發行項
09/11/2024

應用程式路由附加元件支援兩種方式來設定輸入控制器和輸入物件：

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

必要條件

連線至您的 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	服務的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	秘密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 自定義資源來設定負載平衡器批註。

Azure CLI
Bicep

建立叢集時控制預設輸入控制器組態

若要在新叢集上啟用應用程式路由，請使用 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>

配置檔webAppRouting具有具有屬性的defaultIngressControllerType選擇性nginx組態。您必須將 defaultIngressControllerType 屬性設定為先前所述的其中一個組態選項。

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

建立另一個面向公用的 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)，請使用註釋：

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 控制器計量，協助分析應用程式的效能和使用。

共用方式為

應用程式路由附加元件的進階 NGINX 輸入控制器和輸入設定

必要條件

連線至您的 AKS 叢集

NGINX 輸入控制器的設定

一般設定

控制預設 NGINX 輸入控制器組態（預覽）

建立叢集時控制預設輸入控制器組態

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

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

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

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

確認已建立的輸入控制器

在輸入中使用輸入控制器

確認已建立受控輸入

清除輸入控制器

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

自訂主體大小上限

自訂連線逾時

後端通訊協定

停用 SSL 重新導向

URL 重寫

下一步

其他資源

共用方式為

應用程式路由附加元件的進階 NGINX 輸入控制器和輸入設定

必要條件

連線至您的 AKS 叢集

NGINX 輸入控制器的設定

一般設定

控制預設 NGINX 輸入控制器組態 （預覽）

建立叢集時控制預設輸入控制器組態

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

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

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

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

確認已建立的輸入控制器

在輸入中使用輸入控制器

確認已建立受控輸入

清除輸入控制器

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

自訂主體大小上限

自訂連線逾時

後端通訊協定

跨原始來源資源共用 (CORS)

停用 SSL 重新導向

URL 重寫

下一步

其他資源

控制預設 NGINX 輸入控制器組態（預覽）