Crossplane CompositeResourceDefinition 深度解析與實戰演練

– 8 分鐘閱讀

Kubernetes 擴充套件機制雖然允許定義新的資源型別，但缺乏管理這些資源的生命週期和狀態的機制。Crossplane 的 CompositeResourceDefinition (XRD) 正是為瞭解決這個問題而生。XRD 不僅定義了新的資源型別，更重要的是，它提供了一種機制，將這些自定義資源與底層的雲端資源繫結起來，實作了雲端資源的統一管理。一個典型的 XRD 包含 spec.group、spec.names、spec.versions、spec.served、spec.referenceable 和 spec.schema 等關鍵部分。其中，spec.schema 根據 OpenAPI v3 規範，定義了資源的結構和驗證規則，確保使用者提供的組態符合預期。透過 kubectl apply 命令佈署 XRD 後，Kubernetes 會自動建立對應的 Custom Resource Definitions (CRD)。開發者可以透過 kubectl get crds 和 kubectl explain 命令驗證 XRD 的建立以及檢視 CRD 的詳細資訊。建立 XRD 之後，就可以建立根據該定義的資源例項。Crossplane 會監控這些資源例項，並根據預先定義的 Composition，自動在目標雲端平台上組態對應的資源。

跨越雲端的根本：解構 Crossplane 的 CompositeResourceDefinition

在雲原生架構的世界裡，Crossplane 以其獨特的資源組合與管理能力，正逐漸成為建構內部開發者平台（Internal Developer Platform, IDP）的熱門選擇。而要理解 Crossplane 的強大之處，就必須從它的核心概念之一：CompositeResourceDefinition (XRD) 開始。

從 Kubernetes 延伸：XRD 的本質與作用

CompositeResourceDefinition，顧名思義，是一種用於定義複合資源的 Kubernetes API 擴充套件。它允許我們像定義 Deployment 或 Service 一樣，定義自己的資源型別，並指定這些資源的 schema、版本等資訊。簡單來說，XRD 就像是樂高積木的藍圖，告訴 Kubernetes 如何組裝和管理更複雜的雲端服務。

XRD 的關鍵組成：解鎖雲端資源的密碼

一個 XRD 定義包含了以下幾個關鍵部分：

  • spec.group: 定義 API Group，確保資源在 Kubernetes API 中的唯一性。例如，devopstoolkitseries.com 可以作為組織或專案的名稱空間。
  • spec.names: 定義資源的名稱，包括單數 (Kind) 和複數 (Plural) 形式。例如，Kind: SQL 和 Plural: sqls，讓我們能以 kubectl get sqls 來管理 SQL 伺服器。
  • spec.versions: 定義資源的版本，遵循 Kubernetes 版本控制慣例 (v1alpha1, v1beta2, v1)。
  • spec.served: 標記特定版本是否啟用，對使用者可見。
  • spec.referenceable: 指定哪個版本可以被參照，一個 XRD 只能有一個可被參照的版本。
  • spec.schema: 根據 OpenAPI 的 schema 定義，描述資源的結構和驗證規則。

為何 spec.schema 如此重要？洞悉資源的結構與行為

spec.schema 可能是 XRD 中最重要的部分。它定義了 Composite Resource 的結構，包括哪些欄位是必須的，哪些是可選的，以及每個欄位的資料型別。透過 spec.schema，我們可以確保使用者提供的組態是有效的，並在資源建立之前進行驗證。

舉個例子，如果我們想要定義一個 SQL 伺服器資源，我們可以在 spec.schema 中定義 storageGB 欄位，並指定它必須是一個整數，與數值範圍在 10 到 1000 之間。這樣，當使用者嘗試建立一個 storageGB 為 5 或 2000 的 SQL 伺服器時，Kubernetes 就會拒絕這個請求，從而避免了潛在的組態錯誤。

實戰演練：建立你的第一個 XRD

讓我們透過一個簡單的例子來演示如何建立一個 XRD。假設我們想要定義一個 SQL 資源，用於管理 SQL 伺服器。以下是一個基本的 XRD 定義：

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: sqls.devopstoolkitseries.com
spec:
  group: devopstoolkitseries.com
  names:
    kind: SQL
    plural: sqls
    claimNames:
      kind: SQLClaim
      plural: sqlclaims
  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema: {}

這個 XRD 定義了 sqls.devopstoolkitseries.com API，以及 SQL 資源的 v1alpha1 版本。目前 openAPIV3Schema 是空的，我們稍後會擴充套件它。

佈署與驗證：確認 XRD 的存在

我們可以透過 kubectl apply 命令來佈署這個 XRD：

kubectl apply --filename compositions/sql-v1/definition.yaml

佈署完成後，我們可以透過以下命令來驗證 XRD 是否成功建立：

kubectl get compositeresourcedefinitions
# 或者使用簡短名稱
kubectl get xrds

探索 CRD：XRD 的成果展現

XRD 的主要作用是建立 Kubernetes Custom Resource Definitions (CRD)。我們可以透過以下命令來列出所有 CRD，並篩選出與 sql 相關的 CRD：

kubectl get crds | grep sql

預期會看到類別似以下的輸出：

sqlclaims.devopstoolkitseries.com   2024-01-03T16:04:16Z
sqls.devopstoolkitseries.com      2024-01-03T16:04:16Z

這表示 XRD 成功建立了 sqls.devopstoolkitseries.com 和 sqlclaims.devopstoolkitseries.com 兩個 CRD。

深入探索：使用 kubectl explain 瞭解資源結構

Kubernetes 提供了 kubectl explain 命令，讓我們可以深入瞭解 CRD 的結構。例如，我們可以執行以下命令來檢視 sqls.devopstoolkitseries.com 的詳細資訊：

kubectl explain sqls.devopstoolkitseries.com --recursive

這個命令會輸出 SQL 資源的 API Group、Kind、Version，以及所有欄位的詳細描述。

從 XRD 到例項：建立你的第一個 SQL 伺服器

有了 XRD，我們就可以建立根據該定義的資源例項。以下是一個簡單的 SQL 資源範例：

apiVersion: devopstoolkitseries.com/v1alpha1
kind: SQL
metadata:
  name: my-db
spec: {}

這個 YAML 檔案定義了一個名為 my-db 的 SQL 資源，並且 spec 是空的。

佈署與觀察：追蹤資源的狀態

我們可以透過 kubectl apply 命令來佈署這個 SQL 資源：

kubectl apply --filename examples/sql-v1.yaml

佈署完成後，我們可以透過以下命令來檢視 SQL 資源的狀態：

kubectl get sqls

你可能會看到類別似以下的輸出：

NAME    SYNCED   READY   COMPOSITION   AGE
my-db   False    
        2m41s

SYNCED 欄位顯示 False，表示 Crossplane 還沒有開始處理這個資源。

XRD 的價值與挑戰

從玄貓的經驗來看，XRD 的價值在於它提供了一種標準化的方式來定義和管理雲端資源。透過 XRD，我們可以將複雜的雲端服務抽象成簡單的 Kubernetes 資源，從而降低了開發和維運的複雜性。

然而，XRD 也帶來了一些挑戰。首先，定義一個完善的 spec.schema 需要對雲端服務的底層細節有深入的瞭解。其次，如何管理 XRD 的版本和依賴關係也是一個需要仔細考慮的問題。

儘管如此，玄貓仍然相信 XRD 是建構現代雲原生應用程式的重要根本。透過不斷學習和實踐，我們可以充分利用 XRD 的優勢，開發更高效、更可靠的雲端平台。

內容解密

  • apiVersion: 定義 Kubernetes API 的版本。
  • kind: 定義資源的型別，例如 CompositeResourceDefinition。
  • metadata: 包含資源的中繼資料，例如名稱。
  • spec: 定義資源的規格，包括 group、names、versions 和 schema。
  • group: API Group，用於在 Kubernetes API 中唯一標識資源。
  • names: 定義資源的名稱，包括 Kind 和 Plural 形式。
  • versions: 定義資源的版本。
  • served: 標記特定版本是否啟用。
  • referenceable: 指定哪個版本可以被參照。
  • schema: 根據 OpenAPI 的 schema 定義，描述資源的結構和驗證規則。
  • openAPIV3Schema: 實際的 OpenAPI schema 定義。

總之，CompositeResourceDefinition 是 Crossplane 中一個非常重要的概念。它允許我們定義自己的雲端資源，並像管理 Kubernetes 原生資源一樣管理它們。透過深入理解 XRD 的原理和使用方法，我們可以更好地利用 Crossplane 的強大功能，開發更高效、更可靠的雲端平台。

為何 Kubernetes API 擴充套件後還不夠：揭秘 Crossplane Compositions 的必要性

在雲原生世界中，Kubernetes 已經成為容器協調的標準。但當我們需要管理更複雜的雲端資源時，單純的 Kubernetes API 擴充套件就顯得力不從心。今天，玄貓（BlackCat）將帶領大家深入瞭解 Crossplane Compositions，看看它是如何彌補 Kubernetes 的不足，真正實作雲端資源的統一管理。

擴充套件 Kubernetes API：第一步，但遠遠不夠

首先，我們透過 Composite Resource Definition (XRD) 擴充套件了 Kubernetes API，建立了一個名為 SQL 的新資源型別。這就像在城市裡新建了一條道路，但沒有任何交通規則和運輸公司。

# 範例：SQL 的 Composite Resource Definition
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: sqls.devopstoolkitseries.com
spec:
  group: devopstoolkitseries.com
  names:
    kind: SQL
    plural: sqls
  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                parameters:
                  type: object
                  properties:
                    region:
                      type: string
                      description: 雲端區域

這段 YAML 定義了一個新的 SQL 資源，允許我們在 Kubernetes 中宣告 SQL 資料函式庫。但問題是，Kubernetes 並不知道如何處理這些 SQL 資源。它只是一個靜態的定義，沒有任何控制器來監控和管理它們。

玄貓（BlackCat）在過去的經驗中，常常看到開發者誤以為擴充套件了 API 就可以高枕無憂。但實際上，這只是萬裡長徵的第一步。如果沒有後續的控制器和邏輯，這些資源就只是靜靜地躺在 etcd 裡，毫無用處。

Crossplane Compositions：讓資源真正動起來

這時候，Crossplane Compositions 就派上用場了。Compositions 可以告訴 Crossplane，當檢測到我們定義的 SQL 資源時，應該做些什麼。

簡單來說，Composition 就像是一個藍圖，定義瞭如何將一個 Composite Resource（例如 SQL）轉換為一組 Managed Resources（例如 Google Cloud SQL 例項、使用者帳戶等）。

# 範例：Google Cloud SQL 的 Composition
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: google-postgresql
  labels:
    provider: google
    db: postgresql
spec:
  compositeTypeRef:
    apiVersion: devopstoolkitseries.com/v1alpha1
    kind: SQL
  resources:
    - name: sql
      base:
        apiVersion: sql.gcp.upbound.io/v1beta1
        kind: DatabaseInstance
        spec:
          forProvider:
            region: us-east1
            rootPasswordSecretRef:
              namespace: crossplane-system
              key: password
              name: my-db-password
            databaseVersion: "POSTGRES_13"
            settings:
              - availabilityType: REGIONAL
                tier: db-custom-1-3840
            backupConfiguration:
              - enabled: true
                binaryLogEnabled: false
            ipConfiguration:
              - ipv4Enabled: true
                authorizedNetworks:
                  - name: all
                    value: 0.0.0.0/0
            deletionProtection: false
    - name: user
      base:
        apiVersion: sql.gcp.upbound.io/v1beta1
        kind: User
        spec:
          forProvider:
            passwordSecretRef:
              key: password
              name: my-db-password
              namespace: crossplane-system
          instanceSelector:
            matchLabels:
              crossplane.io/composite: my-db

這個 Composition 告訴 Crossplane，當有人建立一個 SQL 資源時，它應該在 Google Cloud 中建立一個 PostgreSQL 資料函式庫例項和一個使用者帳戶。

玄貓（BlackCat）認為，Compositions 的最大優勢在於其靈活性和可重用性。我們可以為不同的雲端供應商、不同的資料函式庫型別定義不同的 Compositions，並根據需求選擇使用。

實戰演練：讓 SQL 資源真正運作起來

為了讓大家更深入理解，讓玄貓（BlackCat）帶領大家一步步實作。

  1. 建立 Kubernetes Secret：

首先，我們需要建立一個 Kubernetes Secret，用於儲存資料函式庫的 root 密碼。

kubectl create secret generic my-db-password \
  --namespace=crossplane-system \
  --from-literal=password=your_db_root_password
  1. 套用 Composition：

接下來，我們套用上面定義的 Google Cloud SQL Composition。

kubectl apply -f compositions/sql-v1/google.yaml
  1. 建立 SQL 資源：

現在，我們可以建立一個 SQL 資源，告訴 Crossplane 我們想要一個 PostgreSQL 資料函式庫。

# 範例：建立 SQL 資源
apiVersion: devopstoolkitseries.com/v1alpha1
kind: SQL
metadata:
  name: my-db
spec:
  parameters:
    region: us-east1
  1. Crossplane 自動 Provisioning：

Crossplane 會監控到這個 SQL 資源，並根據我們定義的 Composition，自動在 Google Cloud 中建立 PostgreSQL 資料函式庫例項和使用者帳戶。

玄貓（BlackCat）在實際專案中，經常使用這種方式來管理雲端資源。它不僅簡化了佈署流程，還提高了資源的一致性和可維護性。

玄貓

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。