全部產品
Search
文件中心

Container Service for Kubernetes:建立並使用Nginx Ingress對外暴露服務

更新時間:Sep 18, 2025

Nginx Ingress作為ACK託管叢集中的流量入口網關,通過靈活的路由規則將外部請求精確轉寄至內部服務。配合使用HTTPS安全加密、灰階發布、通過註解自訂配置等能力,Nginx Ingress可以滿足安全、高可用、可擴充的L7層網路訪問需求。

重要

因傳統型負載平衡CLB按規格計費停止售賣,Container Service for Kubernetes自2025年08月28日起,通過控制台新安裝Nginx Ingress Controller時,將預設使用NLB執行個體,CLB執行個體轉為白名單開放;對於仍需建立CLB的情境,將預設使用按使用量計費模式。詳細內容,請參見【產品變更】關於建立Service與Nginx Ingress Controller預設負載平衡類型與計費方式變更的公告

注意事項

  • 請勿刪除Nginx Ingress Controller預設使用的服務。安裝組件後將預設建立kube-system命名空間下的nginx-ingress-lb服務,將其刪除將會導致組件運行不穩定,嚴重時會出現崩潰。

  • 請通過組件管理或者OpenAPI方式配置組件的自訂參數。通過其他渠道修改組件配置可能會導致組件功能異常,且會影響組件後續的升級過程。

  • 請優先使用Nginx Ingress配置詞典來實現所需功能。若使用Snippet或Lua代碼等方式對組件進行額外配置,所出現的與預期功能不符等問題無法得到支援人員。

  • 請及時升級Nginx Ingress Controller組件,以避免上遊社區版組件的Bug或漏洞導致業務受損。

前提條件

  • 已安裝Nginx Ingress Controller組件。安裝完成後,組件將關聯一個傳統型負載平衡 CLB執行個體作為Nginx Ingress的流量入口。

    建立叢集時安裝

    1. 選擇組件

    1. 登入Container Service管理主控台,單擊建立叢集

    2. 組件配置階段的Ingress參數配置地區,選擇安裝Nginx Ingress

    image

    2. 選擇負載平衡來源

    • 建立:在叢集VPC內自動建立一個按規格計費對應執行個體規格的多可用性區域公網/私網CLB執行個體。

    • 使用已有:可選與叢集同地區的、未被其他叢集關聯的公網CLB執行個體,以及與叢集同VPC的、未被其他叢集關聯的私網CLB執行個體。

    image

    通過組件管理安裝和配置

    通過組件管理安裝,將自動建立一個按規格計費簡約型I(slb.s1.small)的公網CLB執行個體,作為Nginx Ingress的流量入口。

    1. 選擇和配置組件

    1. 登入Container Service管理主控台,在左側導覽列選擇叢集列表

    2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,單擊組件管理

    3. 通過搜尋欄或者網路頁簽找到組件,在Nginx Ingress Controller組件卡片的右下角,單擊安裝

    4. 安裝組件 Nginx Ingress Controller對話方塊,配置相關參數,然後單擊確認完成安裝。

    image

  • 擷取叢集KubeConfig並通過kubectl工具串連叢集

  • 註冊網域名稱

  • 購買正式認證,並完成申請認證,確認待使用的認證處於已簽發狀態。

建立樣本應用

樣本應用將部署兩個名稱分別為coffeetea的無狀態工作負載(Deployment)以及對應的coffee-svctea-svc服務(Service)。

控制台

1. 建立資源

  1. 登入Container Service管理主控台,在左側導覽列選擇叢集列表

  2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,選擇工作負載 > 無狀態

  3. 單擊使用YAML建立資源樣本模板選擇自訂。然後將以下內容複寫到模板地區,單擊建立

image

樣本應用YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: coffee
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: coffee
  template:
    metadata:
      labels:
        app: coffee
    spec:
      containers:
      - name: coffee
        image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: coffee-svc
  namespace: default
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  selector:
    app: coffee
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tea
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: tea
  template:
    metadata:
      labels:
        app: tea
    spec:
      containers:
      - name: tea
        image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: tea-svc
  namespace: default
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  selector:
    app: tea
  type: ClusterIP

2. 查看建立結果

Yaml 資源建立結果彈窗中,單擊資源右側操作列中的查看,確認建立結果。 

image

kubectl

  1. 使用以下內容,建立test-deployment-service.yaml檔案。

    YAML檔案樣本

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: coffee
      namespace: default
    spec:
      replicas: 2
      selector:
        matchLabels:
          app: coffee
      template:
        metadata:
          labels:
            app: coffee
        spec:
          containers:
          - name: coffee
            image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
            ports:
            - containerPort: 80
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: coffee-svc
      namespace: default
    spec:
      ports:
      - port: 80
        targetPort: 80
        protocol: TCP
      selector:
        app: coffee
      type: ClusterIP
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: tea
      namespace: default
    spec:
      replicas: 2
      selector:
        matchLabels:
          app: tea
      template:
        metadata:
          labels:
            app: tea
        spec:
          containers:
          - name: tea
            image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
            ports:
            - containerPort: 80
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: tea-svc
      namespace: default
    spec:
      ports:
      - port: 80
        targetPort: 80
        protocol: TCP
      selector:
        app: tea
      type: ClusterIP
  2. 執行以下命令,建立Deployment和Service。

    kubectl apply -f test-deployment-service.yaml
  3. 執行以下命令,查看coffeetea的建立進度。

    kubectl get deployment coffee tea

    預期輸出:

    NAME     READY   UP-TO-DATE   AVAILABLE   AGE
    coffee   2/2     2            2           14m
    tea      2/2     2            2           14m
  4. 執行以下命令,查看coffee-svctea-svc服務。

    kubectl get service coffee-svc tea-svc

    預期輸出:

    NAME         TYPE        CLUSTER-IP        EXTERNAL-IP   PORT(S)   AGE
    coffee-svc   ClusterIP   192.168.xxx.xxx   <none>        80/TCP    15m
    tea-svc      ClusterIP   192.168.xxx.xxx   <none>        80/TCP    15m

建立Nginx Ingress

以下樣本的規則(rules)中的網域名稱(host)以test-nginx-ingress.com為例,請替換為實際註冊網域名稱;規則中的路徑映射(paths)以建立樣本應用為例,請按實際情況修改。

控制台

1. 建立資源

  1. 登入Container Service管理主控台,在左側導覽列選擇叢集列表

  2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,選擇網路 > 路由選擇default命名空間後,然後單擊建立 Ingress,參考以下樣本進行配置。

    • 網關類型Nginx Ingress

    • 名稱test-nginx-ingress

    • 網域名稱test-nginx-ingress.com(請替換為實際註冊網域名稱)

    • 路徑映射

      • 路徑/coffee

      • 匹配規則預設(ImplementationSpecific)

      • 服務名稱coffee-svc

      • 連接埠80

  3. 繼續單擊+添加路徑,配置tea-svc服務的路由。

    • 路徑映射

      • 路徑/tea

      • 匹配規則預設(ImplementationSpecific)

      • 服務名稱tea-svc

      • 連接埠80

  4. 參考以上步驟,繼續單擊+添加規則,添加www.test-nginx-ingress.com(請替換為實際註冊網域名稱)和對應的路徑映射,完成後單擊確定

image

2. 擷取訪問地址

建立完成後,等待約1分鐘,然後單擊右上方重新整理按鈕。若端點顯示對應的Elastic IP Address(即關聯公網CLB執行個體的服務地址),說明Nginx Ingress已建立成功。

若長時間未更新端點資訊,可單擊路由名稱,進入事件頁簽,進行異常排查。

image

kubectl

  1. 使用以下內容,建立test-ingress.yaml檔案。

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: test-nginx-ingress
      namespace: default
    spec:
      ingressClassName: nginx
      rules:
      - host: test-nginx-ingress.com # 請替換為實際註冊網域名稱
        http:
          paths:
          - path: /coffee
            backend:
              service: 
                name: coffee-svc
                port:
                  number: 80
            pathType: ImplementationSpecific
          - path: /tea
            backend:
              service: 
                name: tea-svc
                port:
                  number: 80
            pathType: ImplementationSpecific
      - host: www.test-nginx-ingress.com # 請替換為實際註冊網域名稱
        http:
          paths:
          - path: /coffee
            backend:
              service: 
                name: coffee-svc
                port:
                  number: 80
            pathType: ImplementationSpecific
          - path: /tea
            backend:
              service: 
                name: tea-svc
                port:
                  number: 80
            pathType: ImplementationSpecific

    重點參數說明:

    • name:Ingress的名稱。本樣本為test-nginx-ingress

    • host:指定服務訪問網域名稱。本樣本為test-nginx-ingress.com,請替換為實際註冊網域名稱。

    • path:指定訪問的URL路徑。CLB將流量轉寄到backend之前,所有的入站請求都要先匹配hostpath。本樣本為/coffee/tea

    • backend:由服務名稱和服務連接埠組成。

      • 服務名稱:Ingress轉寄的backend服務名稱。本樣本為coffee-svctea-svc

      • 服務連接埠:服務暴露的連接埠。本樣本為80

  2. 執行以下命令,建立Ingress。

    kubectl apply -f test-ingress.yaml
  3. 執行以下命令,查看Ingress並擷取Elastic IP Address,如8.xxx.xxx.117

    kubectl get ingress

    預期輸出:

    NAME                 CLASS   HOSTS                                               ADDRESS         PORTS   AGE
    test-nginx-ingress   nginx   test-nginx-ingress.com,www.test-nginx-ingress.com   8.xxx.xxx.117   80      2m39s
  4. 執行以下命令,請使用實際擷取的Elastic IP Address,驗證Nginx Ingress是否生效。

    curl http://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"

    預期輸出:

    ...
    <title>Hello World</title>
    ...
    <p><span>Server&nbsp;address:</span> <span>10.xxx.xxx.19:80</span></p>
    <p><span>Server&nbsp;name:</span> <span>coffee-96d4bc87-l29dh</span></p>
    <p class="smaller"><span>Date:</span> <span>08/Aug/2025:02:21:02 +0000</span></p>
    <p class="smaller"><span>URI:</span> <span>/coffee</span></p>
    ...
        <div id="footer">
            <div id="center" align="center">
                Request ID: 42e2d73c85b16b55b6ab52deb7d995d4<br/>
                &copy; NGINX, Inc. 2018
            </div>
        </div>
    ...

佈建網域名解析

添加網域名稱的操作僅適用於非阿里雲註冊網域名稱。若通過阿里雲網域名稱註冊購買的網域名稱,會自動同步到DNS公網權威解析列表,可直接添加解析記錄。

1. 添加網域名稱

  1. 訪問Alibaba Cloud DNS-公網權威解析

    權威網域名稱解析 頁面中,單擊 添加網域名稱

  2. 添加網域名稱對話方塊中,輸入您需要設定解析的三方網域名稱,並選擇已經建立的公網權威解析執行個體。

image

2. 添加解析記錄

  1. 找到目標網域名稱,單擊右側操作列的解析設定。然後單擊添加記錄,添加一個記錄類型為A記錄、主機記錄為@的解析記錄,其中的記錄值Nginx Ingress的訪問地址

  2. 按照前面的步驟,再添加一個主機記錄為www的解析記錄。

  3. 單擊剛剛建立的解析記錄後的生效檢測,查看解析結果。

更多詳細內容,請參見添加網站解析

image

3. 驗證網域名稱和路徑生效

在瀏覽器中訪問http://test-nginx-ingress.com/coffee(請替換為實際註冊網域名稱),驗證通過網域名稱訪問業務路徑生效。

還可參考解析生效測試方法進行確認,如發現解析不生效,可參考解析不生效問題快速排查

image

配置HTTPS安全加密(TLS配置)

請先完成前提條件中購買和申請認證的步驟,然後參考以下步驟下載認證並添加TLS配置,從而實現通過HTTPS加密通訊的方式訪問網域名稱。

控制台

1. 下載認證

  1. 登入數位憑證管理服務控制台在左側導覽列,選擇認證管理 > SSL認證管理

  2. 正式認證頁簽,選中需要下載的認證,在認證列表左下方單擊下載

  3. 在彈出的對話方塊,選擇Nginx伺服器類型下載認證包並解壓。

更多詳細內容,請參見下載SSL認證

image

2. 建立保密字典

  1. 登入Container Service管理主控台,在左側導覽列選擇叢集列表

  2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,選擇組態管理 > 保密字典

  3. 保密字典頁面,選擇default命名空間後,單擊左側建立,在彈出面板中配置新的保密字典。配置完成後,單擊確定

    • 名稱nginx-ingress-tls

    • 類型TLS認證

    • 認證:已下載並解壓的認證檔案(.pem)中的完整內容

    • 密鑰:已下載並解壓的認證私密金鑰檔案(.key)中的完整內容

image

3. 添加TLS配置

  1. 然後在左側導覽列,選擇網路 > 路由。在目標路由右側操作欄中,單擊更新

  2. 編輯Ingress頁面中,添加以下TLS配置後,單擊確定

    • TLS配置:開啟

    • 網域名稱test-nginx-ingress.com(請替換為實際註冊網域名稱)

    • 保密字典nginx-ingress-tls

image

4. 驗證HTTPS訪問

在瀏覽器中訪問https://test-nginx-ingress.com/coffee(請替換為實際註冊網域名稱),驗證通過HTTPS加密通訊的方式訪問網域名稱及業務路徑生效。

image

kubectl

  1. 登入數位憑證管理服務控制台在左側導覽列,選擇認證管理 > SSL認證管理

  2. 正式認證頁簽,選中需要下載的認證,在認證列表左下方單擊下載

  3. 在彈出的對話方塊,選擇Nginx伺服器類型下載認證包並解壓。

  4. 執行以下命令,使用已下載的認證檔案(.pem)和認證私密金鑰檔案(.key)建立保密字典。

    kubectl create secret tls nginx-ingress-tls --cert test-nginx-ingress.com.pem --key test-nginx-ingress.com.key -n default
  5. 執行以下命令,為test-nginx-ingress路由添加TLS配置。請將命令中的test-nginx-ingress.com替換為實際註冊網域名稱。

    kubectl patch ingress test-nginx-ingress -p '{"spec":{"tls":[{"hosts":["test-nginx-ingress.com"],"secretName":"nginx-ingress-tls"}]}}'
  6. 執行以下命令,請使用實際的Elastic IP Address,驗證通過HTTPS加密通訊的方式訪問網域名稱及業務路徑生效。

    curl -v -k https://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"
    • 參數說明:

      • -v:顯示詳細的通訊過程,包括TLS握手資訊等。

      • -k(或 --insecure):若使用自我簽署憑證可以忽略認證驗證。

    • 預期輸出:

      ...
      *   Trying 8.xxx.xxx.117:443...
      * Connected to 8.xxx.xxx.117 (8.xxx.xxx.117) port 443
      * ALPN: curl offers h2,http/1.1
      * (304) (OUT), TLS handshake, Client hello (1):
      * (304) (IN), TLS handshake, Server hello (2):
      * (304) (IN), TLS handshake, Unknown (8):
      * (304) (IN), TLS handshake, Certificate (11):
      * (304) (IN), TLS handshake, CERT verify (15):
      * (304) (IN), TLS handshake, Finished (20):
      * (304) (OUT), TLS handshake, Finished (20):
      ...
      <title>Hello World</title>
      ...
      <p><span>Server&nbsp;address:</span> <span>10.xxx.xxx.159:80</span></p>
      <p><span>Server&nbsp;name:</span> <span>coffee-96d4bc87-6cstv</span></p>
      <p class="smaller"><span>Date:</span> <span>14/Aug/2025:09:27:42 +0000</span></p>
      <p class="smaller"><span>URI:</span> <span>/coffee</span></p>
      ...
          <div id="footer">
              <div id="center" align="center">
                  Request ID: fee5fe107106748a35d99a2dbbbc6652<br/>
                  &copy; NGINX, Inc. 2018
              </div>
          </div>
      ...

更多配置

灰階發布

當對服務進行版本更新升級時,需要使用到滾動升級、分批暫停發布、藍綠髮布以及灰階發布等發布方式。詳細操作,請參見通過Nginx Ingress實現灰階發布和藍綠髮布

後端服務合約

指定後端服務的協議,設定後會添加註解nginx.ingress.kubernetes.io/backend-protocol。支援HTTP、HTTPS、gRPC、gRPCS四種服務合約。配置樣本,請參見在Nginx Ingress Controller後端部署gRPC服務

重寫路徑

當您在使用Nginx Ingress Controller的時候,Nginx會將路徑完整轉寄到後端(如,從Ingress訪問的/service1/api路徑會直接轉寄到後端Pod的/service1/api/路徑)。如果您後端的服務路徑為/api,則會出現路徑錯誤,導致404的情況。該情況下,您可以通過配置nginx.ingress.kubernetes.io/rewrite-target的方式,來將路徑重寫至需要的目錄。

詳細操作,請參見配置URL重新導向的路由服務

添加註解

Nginx Ingress支援通過添加註釋(Annotations)來啟用更多功能。詳細操作,請參見Nginx Ingress配置詞典Nginx Ingress進階用法

可觀測性

在建立叢集時啟用Log Service,然後在阿里雲Log ServiceSLS查看Nginx Ingress的訪問日誌分析報表和監控Nginx Ingress即時狀態。相關內容,請參見Nginx Ingress訪問日誌分析與監控

高負載情境

關於如何提升Nginx Ingress Controller高負載情境下的效能和穩定性,請參見配置高負載情境的Nginx Ingress ControllerNginx Ingress Controller使用建議

常見問題

為什麼從叢集內訪問叢集LoadBalancer的外部地址不通?

問題現象

叢集中有部分節點下的Pod通過Nginx Ingress Controller外部地址(Server Load Balancer執行個體IP地址)無法訪問後端Pod,有部分能夠訪問。

問題原因

該問題由Controller所屬Service的externalTrafficPolicy配置導致,該配置決定了外部流量的處理規則:當設定為local時,僅有與Controller所屬Pod處於同一節點的後端Pod可以成功接收請求;當設定為cluster時,則可以正常訪問。而叢集中的資源使用LoadBalancer的外部地址訪問時,請求也會被作為外部流量處理。

解決方案

  • (推薦)在Kubernetes叢集內通過Nginx Ingress的ClusterIP或者服務名訪問,其中Nginx Ingress的服務名為nginx-ingress-lb.kube-system

  • 執行kubectl edit svc nginx-ingress-lb -n kube-system命令,修改Nginx Ingress的服務。將LoadBalancer的Service中externalTrafficPolicy修改為Cluster。如果叢集容器網路外掛程式為Flannel,請求會丟失用戶端源IP,如果使用Terway則可保留源IP。

    樣本如下:

    apiVersion: v1
    kind: Service
    metadata:
      annotations:
        service.beta.kubernetes.io/backend-type: eni   # 直通ENI。
      labels:
        app: nginx-ingress-lb
      name: nginx-ingress-lb
      namespace: kube-system
    spec:
      externalTrafficPolicy: Cluster

關於Service的Annotation的更多資訊,請參見通過Annotation配置傳統型負載平衡CLB

如何支援用戶端Header或者Cookie過大的請求?

若用戶端請求Header或者Cookie過大,訪問Nginx Ingress時遇到報錯資訊類似"400 Request Header Or Cookie Too Large /Bad request"時,需要調整相關buffer size 配置。具體有如下兩個配置參數:

可通過執行kubectl edit cm -n kube-system nginx-configuration編輯ConfigMap並修改這兩個配置參數。例如:

client-header-buffer-size: "16k"
large-client-header-buffers: "4 32k" 

配置完之後,請確認配置在Nginx資料面是否生效。可通過執行kubectl exec <nginx-ingress-pod> -n kube-system -- cat /etc/nginx/nginx.conf | vim -查看nginx.conf配置,確認是否與ConfigMap中的修改同步。

Nginx Ingress如何配置跨域?

通過在Ingress資源的metadata.annotations部分添加指定註解來實現跨域。更多內容,請參見Nginx Ingress跨網域設定

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"     # 啟用CORS。
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"  # 允許所有域訪問。
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH, OPTIONS"  # 允許的HTTP方法。
     # 允許的自訂要求標頭。
    nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range" 
    nginx.ingress.kubernetes.io/cors-expose-headers: "Content-Length,Content-Range"  # 暴露的回應標頭。
    nginx.ingress.kubernetes.io/cors-max-age: "86400"  # 預檢請求緩衝時間。
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

如何配置透傳用戶端IP?

Nginx Ingress預設會通過X-Forwarded-For和X-Real-IP來透傳用戶端IP,但是當用戶端主動在要求標頭裡指定了X-Forwarded-For和X-Real-IP時,會導致服務端無法擷取到真實的用戶端IP。

可執行kubectl edit cm -n kube-system nginx-configuration命令在ConfigMap中添加配置,以實現Ingress L7透傳用戶端IP。

compute-full-forwarded-for: "true"
forwarded-for-header: "X-Forwarded-For"
use-forwarded-headers: "true"

如果在Nginx Ingress之前有多層代理,需要根據proxy-real-ip-cidr參數對配置進行調整,將前置代理的IP地址以CIDR格式添加到proxy-real-ip-cidr中,多個CIDR之間用逗號分隔。詳細資料請參見使用WAF

proxy-real-ip-cidr:  "0.0.0.0/0,::/0"  

在IPv6情境下,如果Nginx Ingress收到的X-Forwarded-For頭為空白,並且前置有CLB可以啟用CLB 的Proxy Protocol來擷取用戶端IP。關於Proxy Protocol詳細資料,請參見後端伺服器通過CLB四層監聽擷取用戶端真實IP

相關文檔