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

什麼是 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 的值.