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

發行項
03/25/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 -g <ResourceGroupName> -n <ClusterName>

NGINX 輸入控制器的設定

應用程式路由附加元件會使用稱為 NginxIngressController 的 Kubernetes 自訂資源定義 (CRD) 來設定 NGINX 輸入控制器。您可以建立更多輸入控制器或修改現有的設定。

NginxIngressControllerCRD 具有 loadBalancerAnnotations 欄位，可藉由設定負載平衡器註釋來控制 NGINX 輸入控制器服務的行為。

預設 NGINX 輸入控制器

當您使用 NGINX 啟用應用程式路由附加元件時，它會在使用公開的 Azure 負載平衡器設定的 app-routing-namespace 中建立名為 default 的輸入控制器。該輸入控制器會使用 webapprouting.kubernetes.azure.com 的輸入類別名稱。

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

確認已建立的輸入控制器

在輸入中使用輸入控制器

確認已建立受控輸入

清除輸入控制器

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

自訂主體大小上限

自訂連線逾時

後端通訊協定

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

停用 SSL 重新導向

URL 重寫

下一步

其他資源