自訂資源

自訂資源 是 Kubernetes API 的擴充功能。本頁討論何時將自訂資源新增至您的 Kubernetes 叢集，以及何時使用獨立服務。它描述了新增自訂資源的兩種方法，以及如何在它們之間做出選擇。

自訂資源

資源 是 Kubernetes API 中的端點，用於儲存特定種類的 API 物件的集合；例如，內建的 pods 資源包含 Pod 物件的集合。

自訂資源 是 Kubernetes API 的擴充功能，不一定在預設 Kubernetes 安裝中提供。它代表特定 Kubernetes 安裝的自訂。然而，現在許多核心 Kubernetes 功能是使用自訂資源建置的，這使得 Kubernetes 更加模組化。

自訂資源可以透過動態註冊在執行中的叢集中出現和消失，而叢集管理員可以獨立於叢集本身來更新自訂資源。一旦安裝了自訂資源，使用者就可以使用 kubectl 建立和存取其物件，就像他們對內建資源（如 Pods）所做的那樣。

自訂控制器

單獨來看，自訂資源可讓您儲存和檢索結構化資料。當您將自訂資源與自訂控制器結合使用時，自訂資源會提供真正的宣告式 API。

Kubernetes 宣告式 API 強制執行職責分離。您宣告資源的期望狀態。Kubernetes 控制器使 Kubernetes 物件的目前狀態與您宣告的期望狀態保持同步。這與命令式 API 相反，在命令式 API 中，您指示伺服器執行什麼操作。

您可以在執行中的叢集上部署和更新自訂控制器，而與叢集的生命週期無關。自訂控制器可以與任何種類的資源一起使用，但當與自訂資源結合使用時尤其有效。Operator 模式 結合了自訂資源和自訂控制器。您可以使用自訂控制器將特定應用程式的領域知識編碼到 Kubernetes API 的擴充功能中。

我應該將自訂資源新增到我的 Kubernetes 叢集中嗎？

在建立新的 API 時，請考慮是否要將您的 API 與 Kubernetes 叢集 API 聚合，還是讓您的 API 獨立運作。

宣告式 API

在宣告式 API 中，通常

• 您的 API 由相對少量的相對小的物件（資源）組成。
• 這些物件定義應用程式或基礎架構的組態。
• 物件更新的頻率相對較低。
• 人類通常需要讀取和寫入物件。
• 物件的主要操作是 CRUD 式的（建立、讀取、更新和刪除）。
• 不需要跨物件的事務：API 代表期望狀態，而不是確切狀態。

命令式 API 不是宣告式的。您的 API 可能不是宣告式的跡象包括

• 用戶端說「執行此操作」，然後在完成時收到同步回應。
• 用戶端說「執行此操作」，然後收到操作 ID，並且必須檢查單獨的操作物件以確定請求是否完成。
• 您談論遠端程序呼叫 (RPC)。
• 直接儲存大量資料；例如，每個物件 > 幾 kB，或 > 數千個物件。
• 需要高頻寬存取（持續每秒 10 個請求）。
• 儲存終端使用者資料（例如影像、PII 等）或應用程式處理的其他大規模資料。
• 物件的自然操作不是 CRUD 式的。
• API 不容易建模為物件。
• 您選擇使用操作 ID 或操作物件來表示待處理的操作。

我應該使用 ConfigMap 還是自訂資源？

如果符合以下任何一項，請使用 ConfigMap

• 存在現有的、文件完善的組態檔格式，例如 mysql.cnf 或 pom.xml。
• 您想要將整個組態放入 ConfigMap 的一個鍵中。
• 組態檔的主要用途是讓在叢集上的 Pod 中執行的程式取用該檔案以配置自身。
• 檔案的消費者偏好透過 Pod 中的檔案或 Pod 中的環境變數來取用，而不是透過 Kubernetes API。
• 當檔案更新時，您想要透過 Deployment 等執行滾動更新。

如果以下大多數情況適用，請使用自訂資源（CRD 或 Aggregated API）

• 您想要使用 Kubernetes 用戶端程式庫和 CLI 來建立和更新新的資源。
• 您想要來自 kubectl 的頂層支援；例如，kubectl get my-object object-name。
• 您想要建立新的自動化，以監看新物件的更新，然後 CRUD 其他物件，或反之亦然。
• 您想要編寫自動化來處理物件的更新。
• 您想要使用 Kubernetes API 慣例，例如 .spec、.status 和 .metadata。
• 您希望物件是對受控資源集合的抽象，或是其他資源的摘要。

新增自訂資源

Kubernetes 提供兩種將自訂資源新增到叢集的方法

• CRD 很簡單，無需任何程式設計即可建立。
• API 聚合 需要程式設計，但允許對 API 行為進行更多控制，例如資料的儲存方式以及 API 版本之間的轉換。

Kubernetes 提供這兩個選項來滿足不同使用者的需求，以便易用性和彈性都不會受到影響。

聚合 API 是位於主要 API 伺服器後面的從屬 API 伺服器，主要 API 伺服器充當代理。這種安排稱為 API 聚合 (AA)。對於使用者來說，Kubernetes API 似乎已擴充。

CRD 允許使用者建立新的資源類型，而無需新增另一個 API 伺服器。您不需要了解 API 聚合即可使用 CRD。

無論它們是如何安裝的，新的資源都被稱為自訂資源，以區別於內建的 Kubernetes 資源（如 Pod）。

CustomResourceDefinitions

CustomResourceDefinition API 資源允許您定義自訂資源。定義 CRD 物件會建立一個新的自訂資源，其中包含您指定的名稱和綱要。Kubernetes API 服務並處理自訂資源的儲存。CRD 物件本身的名稱必須是有效的 DNS 子網域名稱，該名稱衍生自定義的資源名稱及其 API 群組；請參閱如何建立 CRD 以取得更多詳細資訊。此外，種類/資源由 CRD 定義的物件名稱也必須是有效的 DNS 子網域名稱。

這使您無需編寫自己的 API 伺服器來處理自訂資源，但實作的通用性意味著您的彈性不如API 伺服器聚合。

請參閱 自訂控制器範例，以了解如何註冊新的自訂資源、使用新資源類型的執行個體，以及使用控制器來處理事件的範例。

API 伺服器聚合

通常，Kubernetes API 中的每個資源都需要程式碼來處理 REST 請求並管理物件的持久儲存。主要的 Kubernetes API 伺服器處理內建資源，例如 pod 和 service，也可以透過 CRD 通用地處理自訂資源。

聚合層 允許您透過編寫和部署自己的 API 伺服器，為自訂資源提供特殊化的實作。主要 API 伺服器將針對您處理的自訂資源的請求委派給您的 API 伺服器，使其可供所有用戶端使用。

選擇新增自訂資源的方法

CRD 更易於使用。聚合 API 更具彈性。選擇最符合您需求的方法。

通常，如果符合以下情況，CRD 是不錯的選擇

• 您只有少數欄位
• 您在公司內部使用該資源，或作為小型開放原始碼專案的一部分（而不是商業產品）

比較易用性

CRD 比聚合 API 更容易建立。

進階功能和彈性

聚合 API 提供更進階的 API 功能以及其他功能的自訂，例如，儲存層。

通用功能

當您建立自訂資源時，無論是透過 CRD 還是 AA，與在 Kubernetes 平台外部實作相比，您都可以獲得 API 的許多功能

準備安裝自訂資源

在將自訂資源新增到叢集之前，需要注意以下幾點。

第三方程式碼和新的故障點

雖然建立 CRD 不會自動新增任何新的故障點（例如，透過導致第三方程式碼在您的 API 伺服器上執行），但套件（例如 Charts）或其他安裝套件通常包含 CRD 以及實作新自訂資源業務邏輯的第三方程式碼的 Deployment。

安裝聚合 API 伺服器始終涉及執行新的 Deployment。

儲存

自訂資源消耗儲存空間的方式與 ConfigMap 相同。建立過多的自訂資源可能會使 API 伺服器的儲存空間過載。

聚合 API 伺服器可能使用與主要 API 伺服器相同的儲存，在這種情況下，相同的警告適用。

身份驗證、授權和稽核

CRD 始終使用與 API 伺服器的內建資源相同的身份驗證、授權和稽核日誌記錄。

如果您使用 RBAC 進行授權，則大多數 RBAC 角色將不會授予對新資源的存取權（叢集管理員角色或使用萬用字元規則建立的任何角色除外）。您需要明確授予對新資源的存取權。CRD 和聚合 API 通常與它們新增的類型的新角色定義捆綁在一起。

聚合 API 伺服器可能會或可能不會使用與主要 API 伺服器相同的身份驗證、授權和稽核。

存取自訂資源

Kubernetes 用戶端程式庫可用於存取自訂資源。並非所有用戶端程式庫都支援自訂資源。Go 和 Python 用戶端程式庫支援。

當您新增自訂資源時，可以使用以下方式存取它

• kubectl
• Kubernetes 動態用戶端。
• 您編寫的 REST 用戶端。
• 使用 Kubernetes 用戶端產生工具產生的用戶端（產生一個用戶端是一項進階任務，但某些專案可能會提供一個與 CRD 或 AA 一起提供的用戶端）。

自訂資源欄位選擇器

欄位選擇器 允許用戶端根據一個或多個資源欄位的值來選擇自訂資源。

所有自訂資源都支援 metadata.name 和 metadata.namespace 欄位選擇器。

在 CustomResourceDefinition 中宣告的欄位，如果包含在 CustomResourceDefinition 的 spec.versions[*].selectableFields 欄位中，也可以與欄位選擇器一起使用。

自訂資源的可選欄位

CustomResourceDefinition 的 spec.versions[*].selectableFields 欄位可用於宣告自訂資源中的哪些其他欄位可以用於欄位選擇器。

以下範例新增 .spec.color 和 .spec.size 欄位作為可選欄位。

customresourcedefinition/shirt-resource-definition.yaml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: shirts.stable.example.com
spec:
  group: stable.example.com
  scope: Namespaced
  names:
    plural: shirts
    singular: shirt
    kind: Shirt
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              color:
                type: string
              size:
                type: string
    selectableFields:
    - jsonPath: .spec.color
    - jsonPath: .spec.size
    additionalPrinterColumns:
    - jsonPath: .spec.color
      name: Color
      type: string
    - jsonPath: .spec.size
      name: Size
      type: string

然後可以使用欄位選擇器來僅取得 color 為 blue 的資源

kubectl get shirts.stable.example.com --field-selector spec.color=blue

輸出應為

NAME       COLOR  SIZE
example1   blue   S
example2   blue   M

下一步

• 了解如何使用聚合層擴充 Kubernetes API。
• 了解如何使用 CustomResourceDefinition 擴充 Kubernetes API。