Ingress 是什么
- Ingress 是對k8s集群中服務的外部訪問進行管理的 API 對象，典型的訪問方式是 HTTP。
- Ingress 可以提供負載均衡、SSL 終結和基於名稱的虛擬托管。
最近發布了 1.0.0正式版, 有很多不兼容的改動.
名詞說明:
注解 annotation
資源 resource
對象 object
控制器 controller
=============================================================
本文原始英文文檔在此: https://kubernetes.github.io/ingress-nginx/#faq-migration-to-apiversion-networkingk8siov1
2021.8.27
歡迎
這是 NGINX Ingress 控制器 的文檔.
它基於 Kubernetes Ingress resource 構建, 使用 ConfigMap 來保存 NGINX 的配置.
要了解更多關於使用 Ingress的內容, 點擊這里 k8s.io .
開始
如果想快速開始請閱讀這里 Deployment .
常見問題FAQ - 版本升級到 networking.k8s.io/v1
-
請閱讀這里 關於廢棄ingress api 版本的官方說明 如果你在K8s v1.22之前版本的集群里使用了ingress對象, 然后你想升級到 K8s v1.22, 那這個文檔對你有用.
-
請閱讀這里 關於IngressClass 對象的官方文檔
什么是 ingressClass , 為什么現在它對 Ingress-NGINX 控制器 用戶如此重要 ?
IngressClass是一種 Kubernetes 資源, 請閱讀后面的描述.
這個很重要, 安裝Ingress-NGINX 控制器, 以前的版本不需要ingressClass對象. 但是從 1.0.0版本之后, 就必須需要ingressclass這個對象了.
在集群里, 如果有多個Ingress-NGINX 控制器, 那么所有控制器的實例必須知道它們服務的是什么類型的 Ingress對象. 設置 ingress 對象的 ingressClass 字段就可以讓控制器知道.
_$ k ingressClass 說明
KIND: IngressClass
VERSION: networking.k8s.io/v1
DESCRIPTION:
IngressClass
IngressClass 表示 Ingress的類, 在 Ingress Spec 里使用.
使用 `ingressclass.kubernetes.io/is-default-class` 注解可以用來設置 IngressClass 是否為缺省的class.
當一個單獨的 IngressClass 資源的此選項被設置為 true 時, 新的Ingress資源如果沒有指定class字段, 則缺省使用這個IngressClass.
FIELDS:
apiVersion <string>
APIVersion 定義一個對象的版本. 會轉換已知的值到最新的內部值, 不認識的值則可能會被拒絕.
更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind <string>
Kind 是一個字符串值, 代表了這個對象的 REST 資源. 服務器會根據這個推斷請求提交的服務終端(endpoint).
此值不可修改. 使用駝峰式語法.
更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadata <Object>
標准對象的元數據. 更多信息:
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
spec <Object>
Spec用來定義 IngressClass 預期到達的狀態. 更多信息:
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status`
引發了什么變化 ?
主要有兩大重要變更.
(變更 #1) 使用 K8s 1.21版本或更早版本, 使用如下方式來聲明使用 ingress 資源 ;
-
apiVersion: extensions/v1beta1
-
apiVersion: networking.k8s.io/v1beta1
(你會得到一個廢棄警告, 但是ingress資源還是會被創建.)
從 K8s 1.22 版本之后, 你只能設置 "apiVersion:" 這個字段的值為 "networking.k8s.io/v1". 原因是 關於廢棄ingress api 版本的官方說明.
(變更 #2) 當你升級到 K8s v1.22版本, 如果你已經在使用Ingress-NGINX 控制器, 已經存在的ingress對象在幾種情況下不能正常工作. 閱讀此文檔來檢查是不是你使用的場景.
ingressClassName 字段是什么 ?
ingressClassName 是ingress對象的spec下的字段.
% k ingress.spec.ingressClassName 說明
KIND: Ingress
VERSION: networking.k8s.io/v1
FIELD: ingressClassName <string>
DESCRIPTION:
IngressClassName 是IngressClass集群資源的名字.
這個相關的IngressClass定義了用哪個控制器來實現這個資源.
這個字段用來代替廢棄的 "kubernetes.io/ingress.class" 注解.
為了保持向后兼容, 如果也同時注解了這個字段, 那優先使用這個設置的值.
如果注解和此字段的設置不一致, 控制器會發出一個警告信息.
如果一個Ingress對象沒有指定 ingressClassName字段, 則它會被忽略(也就是沒有創建).
如果系統中有一個IngressClass對象設置了缺省選項, 而且當前Ingress沒有設置ingressClassName字段, 則此Ingress也會使用系統缺省的設置.
相關更多信息, 請閱讀 IngressClass 的文檔.
注意: spec.ingressClassName 優先級比 注解(annotation) 高.
在我的集群里只有一個 Ingresss-NGINX controller 實例. 我應該怎么辦 ?
- 如果你只有一個 Ingress-NGINX 控制器實例, 而且你想用 ingressclass, 你應該在你的 ingressClass 資源聲明里面添加 "ingressclass.kubernetes.io/is-default-class" 注解, 這樣你新的Ingress對象就會使用缺省的設置.
在這種情況下, 你需要讓你的控制器感知Ingress對象. 如果你有幾個 Ingress對象, 而且他們沒有設置 ingressClassName 字段,
而且也沒有設置注解 (kubernetes.io/ingress.class) , 那么你應該用 [--watch-ingress-without-class=true](## 這個 '--watch-ingress-without-class' 是什么設置 ?) 參數來啟動你的 ingress-controller .
你可以使用 .controller.watchIngressWithoutClass: true 來配置你的 helm chart 安裝.
我們強烈建議你按下面的方法來創建你的 ingressClass (譯注: 缺省的配置里是沒有開啟的):
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
labels:
app.kubernetes.io/component: controller
name: nginx
annotations:
ingressclass.kubernetes.io/is-default-class: "true"
spec:
controller: k8s.io/ingress-nginx
並在你的 Ingress對象聲明中添加 "spec.ingressClassName=nginx"
在我的集群里有很多 ingress 對象. 我應該怎么辦 ?
- 如果你不關心 ingressClass , 或者你有很多沒有配置ingressClass 的ingress對象, 你可以使用
--watch-ingress-without-class=true來啟動你的 ingress-controller .
這個 '--watch-ingress-without-class' 是什么設置 ?
- 這個設置會作為一個參數, 傳遞給 ingress-controller 調用, 就像下面這樣:
...
...
args:
- /nginx-ingress-controller
- --publish-service=$(POD_NAMESPACE)/ingress-nginx-dev-v1-test-controller
- --election-id=ingress-controller-leader
- --controller-class=k8s.io/ingress-nginx
- --configmap=$(POD_NAMESPACE)/ingress-nginx-dev-v1-test-controller
- --validating-webhook=:8443
- --validating-webhook-certificate=/usr/local/certificates/cert
- --validating-webhook-key=/usr/local/certificates/key
- --watch-ingress-without-class=true
...
...
在我的集群里有很多 controller 而且已經用了 annotation ?
沒問題, 它會依然保持工作, 不過我們強烈建議你測試驗證一下.
在我的集群里有很多 controller 已經在運行了, 需要我使用新的規范嗎?
在這種情況下, 你需要創建多個 ingressClasses (參加樣例一). 但是一定要注意此時 ingressClass 工作在一種特別的方式下: 你需要修改 IngressClass 的 .spec.controller 的值來讓控制器指向相應的ingressClass. 讓我們看一些例子, 假設你現在有2個 Ingress類:
- Ingress-Nginx-IngressClass-1 , 其設置 .spec.controller 為 "k8s.io/ingress-nginx1"
- Ingress-Nginx-IngressClass-2 , 其設置 .spec.controller 為 "k8s.io/ingress-nginx2"
當部署你的 ingress控制器時, 你必須修改按如下方式修改 --controller-class 字段:
- Ingress-Nginx-Controller-nginx1 使用
k8s.io/ingress-nginx1 - Ingress-Nginx-Controller-nginx2 使用
k8s.io/ingress-nginx2
然后, 當你使用 IngressClassName = ingress-nginx2 來創建一個Ingress對象是, 它會根據 controller-class=k8s.io/ingress-nginx2 這個配置來查找控制器, 同時 Ingress-Nginx-Controller-nginx2 會監測指向 ingressClass="k8s.io/ingress-nginx2 的對象, 它會為這個對象提供服務, 而 Ingress-Nginx-Controller-nginx1 會忽略這個對象.
要注意, 如果你的 Ingress-Nginx-Controller-nginx2 啟動時帶了參數 --watch-ingress-without-class=true , 它會為一下對象提供服務:
- 沒有指定 ingress-class 屬性的對象
- 使用注解
--ingress-class來設置並且內容相同的對象 - 使用
--controller-class來設定, 也就是和指定 .spec.controller 字段一樣的對象
為什么 helm chart 里缺省禁用了 ingressClassResource ?
- 如果這個字段被設置開啟(enabled), 而且原來的集群里已經存在 ingress對象, 那原來已經存在的 ingress對象不在被關注(honored), 只有你創建的新的對象才會繼承 ingressClass 的值.