Ingress 常用配置

目錄

• Ingress 常用配置（持續更新）
  • Ingress 配置修改方法
    • 通過 Rancher UI 配置
    • 通過 kubectl 命令行修改
  • kubectl ingress-nginx plugin
    • 安裝 krew
    • 安裝 kubectl ingress-nginx plugin
    • kubectl ingress-nginx plugin 用法
  • 永久重定向狀態碼 （http-redirect-code）
    • 全局配置
    • 局部配置
  • 代理外部應用（域名（http、https）或 ip + 端口）
    • 創建外部服務
    • Ingress 規則創建
      • http 域名或者 ip + 端口
      • https
      • 外部服務后端重寫
  • 后端重寫
    • 單域名 + Path
    • 多域名 + Path
  • 隱藏 Ingress - Nginx 版本號
  • 自定義 http 和 https 端口
    • 更新工作負載修改 http 和 https 端口
    • RKE 配置文件修改
    • Rancher 自定義集群
  • 自定義 client_max_body_size 大小
  • 自定義 Proxy buffering 大小
  • 開啟 TLS/HTTPS
  • 記錄客戶端地址
  • 跨域配置
  • 白名單
  • 請求速率限制
  • websocket 配置
  • 自定義 header
    • 全局配置 header
    • 單個 ingress 規則配置自定義 header
    • 自定義日志輸出格式

Ingress 常用配置（持續更新）

參考鏈接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#permanent-redirect-code

Ingress 配置修改方法

通過 Rancher UI 配置

依次進入 system 項目|配置映射，然后在 ingress-nginx 命名空間部分找到 nginx-configuration配置映射並編輯 nginx-configuration。

然后在 配置映射 中以鍵值對形式添加參數，比如： server-tokens=false。

注意: 配置映射設置的參數是作用於全局，如果想局部生效，可通過對應的 注釋 去配置相應參數，配置方法文章后面會說明。

通過 kubectl 命令行修改

執行以下命令進入配置映射文件的編輯模式

kubectl -n ingress-nginx  edit configmaps nginx-configuration

然后在 data 字段中添加相應參數，比如： server-tokens: "false"，注意雙引號。

kubectl ingress-nginx plugin

ingress 大概從 0.26.0（或 v0.24.0）版本開始不再支持在 nginx.conf 配置文件中直接顯示 backend。

upstream upstream_balancer { ### Attention!!! # # We no longer create "upstream" section for every backend. # Backends are handled dynamically using Lua. If you would like to debug # and see what backends ingress-nginx has in its memory you can # install our kubectl plugin https://kubernetes.github.io/ingress-nginx/kubectl-plugin. # Once you have the plugin you can use "kubectl ingress-nginx backends" command to # inspect current backends. # ### server 0.0.0.1; # placeholder balancer_by_lua_block { balancer.balance() }

backend 數據保存在內存中，將通過 Lua 動態的去生成 Nginx 配置文件。為了 debug ingress 的配置，ingress 推出了一款 kubectl 插件，可以通過此插件查看相應的配置信息。

安裝 krew

Krew 可以理解為 kubectl 插件的包管理工具。借助 Krew，可以輕松地使用 kubectl plugin 查詢、安裝和管理插件，使用類似 apt、dnf 或 brew。

• macOS/Linux

1. 需要提前安裝 git 工具

2. 在終端中運行以下命令以下載並安裝 krew

( set -x; cd "$(mktemp -d)" && curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/krew.{tar.gz,yaml}" && tar zxvf krew.tar.gz && KREW=./krew-"$(uname | tr '[:upper:]' '[:lower:]')_amd64" && "$KREW" install --manifest=krew.yaml --archive=krew.tar.gz && "$KREW" update)

3. 在.bashrc 或.zshrc 文件中添加以下內容將 $HOME/.krew/bin 目錄添加到 PATH 環境變量。

4. 運行 kubectl krew 驗證命令是否運行正常。

   export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"
   

安裝 kubectl ingress-nginx plugin

1. 運行以下命令安裝 kubectl ingress-nginx plugin

   kubectl krew install ingress-nginx
   

2. 安裝完成后，可通過以下命令查看插件安裝是否正常

kubectl ingress-nginx --helpA kubectl plugin for inspecting your ingress-nginx deploymentsUsage: ingress-nginx [command]Available Commands: backends Inspect the dynamic backend information of an ingress-nginx instance certs Output the certificate data stored in an ingress-nginx pod conf Inspect the generated nginx.conf exec Execute a command inside an ingress-nginx pod general Inspect the other dynamic ingress-nginx information help Help about any command info Show information about the ingress-nginx service ingresses Provide a short summary of all of the ingress definitions lint Inspect kubernetes resources for possible issues logs Get the kubernetes logs for an ingress-nginx pod ssh ssh into a running ingress-nginx podFlags: --as string Username to impersonate for the operation --as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups. --cache-dir string Default HTTP cache directory (default "/Users/hxl/.kube/http-cache") --certificate-authority string Path to a cert file for the certificate authority --client-certificate string Path to a client certificate file for TLS --client-key string Path to a client key file for TLS --cluster string The name of the kubeconfig cluster to use --context string The name of the kubeconfig context to use -h, --help help for ingress-nginx --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure --kubeconfig string Path to the kubeconfig file to use for CLI requests. -n, --namespace string If present, the namespace scope for this CLI request --request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0") -s, --server string The address and port of the Kubernetes API server --tls-server-name string Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used --token string Bearer token for authentication to the API server --user string The name of the kubeconfig user to useUse "ingress-nginx [command] --help" for more information about a command.

kubectl ingress-nginx plugin 用法

注意: 因為 rancher 或 rke 創建的集群中，ingress 控制器是以 DaemonSet 的方式運行。kubectl ingress-nginx plugin 查看配置時需要指定資源，默認只支持 --deployment。在 rancher 或 rke 創建的 ingress 默認都有 app=ingress-nginx 標簽，所以這里用標簽來指定資源。

• 查看 Nginx 配置

  kubectl ingress-nginx --kubeconfig=xxxx -n ingress-nginx -l app=ingress-nginx conf
  

  以上的命令將會輸出全部規則的配置，可以通過指定域名來輸出指定配置的配置。

  kubectl ingress-nginx --kubeconfig=xxxx -n ingress-nginx -l app=ingress-nginx conf --host <配置的域名>
  

• 查看 backends

  kubectl ingress-nginx --kubeconfig=xxxx  -n ingress-nginx -l app=ingress-nginx backends
  

永久重定向狀態碼 （http-redirect-code）

ingress 中重定向的狀態碼默認是 308，某些情況下我們可能需要 301 狀態碼，可以按照以下方法配置。

全局配置

可通過在配置映射中添加 http-redirect-code=301 來修改全局重定向狀態碼，修改后所有 ingress 規則的重定向狀態碼都將是 301。

局部配置

如果只想某個域名使用 301 狀態碼，那可以編輯對應的 ingress 規則添加以下注釋。

nginx.ingress.kubernetes.io/permanent-redirect-code: '301' # 默認 308

代理外部應用（域名（http、https）或 ip + 端口）

創建外部服務

假設有一個外部應用，是通過域名 123.com 進行訪問。現在想在 ingress 中通過新的域名 abc.com 去代理這個外部應用。那么需要先把外部域名通過外部服務的方式引入 K8S 集群中，然后 ingress 去調用這個外部服務。

1. 在服務發現頁面，添加 一條 DNS 記錄（或者叫新建一個 SVC）

   

2. DNS 記錄配置詳情

   • DNS 記錄名稱

     名稱可以隨意填寫，但是不能以數字開頭，不能大寫

   • 命名空間

     DNS 記錄所在的命名空間

   • 解析類型

     選擇解析類型，可以選擇外部域名或者外部 ip

   • 填寫目標域名或者目標 ip (這里不用寫端口)

   • 端口映射

     這個參數很重要，需要根據外部服務訪問的真實端口來配置。比如你的服務訪問是通過 http://123.com:9000 來訪問的，那么這里就需要填寫 9000 端口。如果是通過 http://123.com 或者 https://123.com 訪問，80 或 443 端口也需要填寫。

Ingress 規則創建

1. 在負載均衡頁面添加一條新的 ingress 規則。如下圖，添加 目標后端 的時候先刪除默認的后端規則，然后點擊服務。

2. 因為只有選擇 服務 此處才能選擇之前創建的 DNS 記錄。

3. 最后點擊保存

http 域名或者 ip + 端口

編輯剛剛創建的 ingress 規則，在 標簽/注釋 中為 ingress 規則添加 annotations，通過 annotations 指定后端應用的訪問地址。

nginx.ingress.kubernetes.io/upstream-vhost: 123.com 或者 ip+端口

https

對於外部服務為 https 訪問又有兩種情況，一種是權威的 ssl 證書，一種是自簽名的 ssl 證書。不同類型需要添加不同的 annotations 配置。

• 權威 ssl 證書

nginx.ingress.kubernetes.io/upstream-vhost: 123.comnginx.ingress.kubernetes.io/secure-backends: "true"nginx.ingress.kubernetes.io/backend-protocol: HTTPS

• 自簽名 ssl 證書

nginx.ingress.kubernetes.io/upstream-vhost: 123.comnginx.ingress.kubernetes.io/secure-backends: "true"nginx.ingress.kubernetes.io/proxy-ssl-verify: "off"nginx.ingress.kubernetes.io/backend-protocol: HTTPS

外部服務后端重寫

如果外部服務是以 http(s)://123.com/path 的 url 形式訪問，那么需要為其配置后端重寫才能保證能通過 abc.com 這種形式訪問。

后端重寫

后端重寫 主要有兩種使用場景：

1. 有多個后端應用，但是當前只有一個可用域名，那么需要通過 <單域名>/ 的方式來區分。
2. 多個應用通過子目錄的方式部署在一個 web server 下，需要通過多個域名來訪問應用。

單域名 + Path

如上圖，可用配置多個 Path 來區分多個服務。 但是當訪問 <單域名>/ 的時候，可能會出現 404 錯誤。因為當訪問 <單域名>/ 的時候會是去后端服務頁面中找 Path 路徑，可能 Path 是隨意設置的，后端服務頁面並不存在此頁面，所以會提示 404 錯誤。並且我們要求訪問 <單域名>/ 的時候是訪問后端服務的根目錄，而不是子目錄，所以需要通過后端重寫的方式將請求轉發到根目錄。

在 ingress 可通過配置以下注釋達到預期要求：

nginx.ingress.kubernetes.io/rewrite-target: /

多域名 + Path

如果多個應用是以子目錄的方式部署在同一個 web 服務器中，這種情況其實是可通過 <域名>/ 的方式來訪問的。但是有時候可能需要不加 Path 后綴，直接通過域名訪問。這種需求也需要通過 后端重寫 的方式來設置，其配置方法正好與 單域名 + Path 相反。

注意： 如果請求的資源不是全部在子站點中，那么頁面重寫過去之后，可能存在一些靜態資源無法加載的問題，因此需要根據實際的應用架構來確定是否采用這種后端重寫。

1. 在 ingress 規則中添加以下注釋來實現頁面重寫:

   nginx.ingress.kubernetes.io/rewrite-target: /test
   

2. Path 處設置為 /(.*)

3. 完整 ingress yaml 示例：

apiVersion: extensions/v1beta1kind: Ingressmetadata: annotations: nginx.ingress.kubernetes.io/rewrite-target: /test/$1 name: test-domain namespace: defaultspec: rules: - host: www.test.local http: paths: - backend: serviceName: ingress-541fa2c5687afb7ccb3c7c9a13fa7119 servicePort: 80 path: /(.*)

隱藏 Ingress - Nginx 版本號

Ingress 是內置 NGINX 來提供負載均衡服務，默認顯示 nginx 版本號。為了安全有時候會要求關閉版本號顯示，可通過修改配置映射來隱藏版本號。

在配置映射中設置：

1. Rancher UI 配置 server-tokens=false
2. YAML 配置 server-tokens: "false"

自定義 http 和 https 端口

在 Rancher 部署的 K8S 集群中，默認部署了 ingress 控制器。ingress 控制器以 DaemonSet 類型部署，並且以 host 網絡模式運行。ingress 控制器默認會監聽 80 和 443 兩個端口來提供 web 服務，所以如果主機上原來已經有服務監聽了 80 或者 443 端口，那么 ingress 控制器部署將會出現端口沖突。

根據部署方式的不同，大概有以下幾種修改方式:

更新工作負載修改 http 和 https 端口

1. 依次進入 目標集群|system 項目，在工作負載中找到 nginx-ingress-controller，點擊右側省略號菜單，選擇編輯。

2. 在配置詳情頁面中，點擊右下角 顯示高級選項，然后打開 命令 選項卡

3. 在命令配置欄中添加配置參數，比如： --http-port=8880 --https-port=8443

RKE 配置文件修改

如果使用 rke 創建 K8S 集群，那么可以在 rke 配置文件中指定 ingress 的端口參數。

ingress:
  provider: nginx
  options:
    map-hash-bucket-size: "128"
    ssl-protocols: SSLv2
  extra_args:
    enable-ssl-passthrough: ""
    http-port: 8880
    https-port: 8443

Rancher 自定義集群

與 rke 集群相似，可以編輯集群的 YAML 配置文件，然后添加對應參數。

自定義 client_max_body_size 大小

編輯 ingress 規則，在注釋中添加:

nginx.ingress.kubernetes.io/proxy-body-size: 32m

如果想全局配置 proxy-body-size 大小，則在配置映射文件中添加 proxy-body-size=32m

自定義 Proxy buffering 大小

1. 默認情況下，ingress 配置中禁用 Proxy buffering 。所以需要配置以下設置開啟：

   nginx.ingress.kubernetes.io/proxy-buffering: "on"
   

   如果想全局開啟 Proxy buffering ，則在配置映射文件中添加 proxy-buffering=on。

2. 默認情況下，Proxy buffering 大小設置為 4k，可通過以下配置修改大小：

   nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"
   

   如果想全局配置 Proxy buffering 大小，則在配置映射文件中設置 proxy-buffer-size=8k

開啟 TLS/HTTPS

默認情況下，如果 ingress 規則對象入口啟用了 TLS/HTTPS，則 ingress-controller 將使用 308 永久重定向將 HTTP 請求重定向到 HTTPS 請求。如果需修改 308 為 301

某些情況下可能希望 http 和 https 同時使用，那么就需要禁止 TLS 自動重定向。可以在 ingress 規則中添加以下注釋來禁止重定向：

nginx.ingress.kubernetes.io/ssl-redirect: "false"

如果想全局禁止 TLS 自動重定向，可以在配置映射文件中配置： ssl-redirect=false 來禁止。

記錄客戶端地址

跨域配置

nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"
nginx.ingress.kubernetes.io/cors-allow-headers："DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization"
nginx.ingress.kubernetes.io/cors-allow-origin: "*"

白名單

nginx.ingress.kubernetes.io/whitelist-source-range: 192.168.1.0/24,192.168.2.8

請求速率限制

nginx.ingress.kubernetes.io/limit-rps: '100'

websocket 配置

nginx.ingress.kubernetes.io/configuration-snippet: |
    proxy_set_header Upgrade "websocket";
    proxy_set_header Connection "Upgrade";
    nginx.ingress.kubernetes.io/proxy-read-timeout 3600;
    nginx.ingress.kubernetes.io/proxy-send-timeout 3600;

自定義 header

全局配置 header

1. 復制以下內容創建自定義 header ConfigMap 文件

apiVersion: v1
data:
  X-Different-Name: "true"
  X-Request-Start: t=${msec}
  X-Using-Nginx-Controller: "true"
  x-custom-headers: xxxxx
kind: ConfigMap
metadata:
  name: custom-headers
  namespace: ingress-nginx

配置效果：

![img](https://www.xtplayer.cn/kubernetes/ingress-configuration-demo/g9kzTyf-MA0BAHgkxDuoxBsqRxrl1pPqtA.png)

2. 在 system 項目|配置映射 下找到 nginx-configuration 配置映射並編輯它，添加如下配置：

nable-underscores-in-headers=true
proxy-set-headers=ingress-nginx/custom-headers

配置效果：

3. 注意：如果配置一直沒有更新，則需要重啟 ingress 控制器 Pod，以觸發配置更新。

單個 ingress 規則配置自定義 header

1. 在 system 項目|配置映射 下找到 nginx-configuration 配置映射並編輯它，添加如下配置：

   enable-underscores-in-headers=true
   

2. 編輯 ingress 規則的 YAML 配置，添加如下配置：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      more_set_headers "Hello: World";
      more_set_headers "Hello1: World1";

配置效果：

自定義日志輸出格式

• upstream log format

  在配置映射文件中添加以下配置：

  log-format-upstream: '{"time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr", "x_forward_for": "$proxy_add_x_forwarded_for", "request_id": "$req_id", "remote_user": "$remote_user", "bytes_sent": $bytes_sent, "request_time": $request_time, "status": $status, "vhost": "$host", "request_proto": "$server_protocol", "path": "$uri", "request_query": "$args", "request_length": $request_length, "duration": $request_time,"method": "$request_method", "http_referrer": "$http_referer", "http_user_agent": "$http_user_agent" }'