**協助改進此頁面** 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # kro 概念 kro 可讓平台團隊建立自訂 Kubernetes APIs，將多個資源組成更高階的抽象概念。本主題會逐步解說實際範例，然後說明使用 kro 的 EKS 功能時需要了解的核心概念。 ## kro 入門 建立 kro 功能後 （請參閱 [建立 kro 功能](create-kro-capability.md))，您可以在叢集中使用 ResourceGraphDefinitions 開始建立自訂 APIs。 以下是建立簡單 Web 應用程式抽象化的完整範例： ``` apiVersion: kro.run/v1alpha1 kind: ResourceGraphDefinition metadata: name: webapplication spec: schema: apiVersion: v1alpha1 kind: WebApplication group: kro.run spec: name: string | required=true image: string | default="nginx:latest" replicas: integer | default=3 resources: - id: deployment template: apiVersion: apps/v1 kind: Deployment metadata: name: ${schema.spec.name} spec: replicas: ${schema.spec.replicas} selector: matchLabels: app: ${schema.spec.name} template: metadata: labels: app: ${schema.spec.name} spec: containers: - name: app image: ${schema.spec.image} ports: - containerPort: 80 - id: service template: apiVersion: v1 kind: Service metadata: name: ${schema.spec.name} spec: selector: app: ${schema.spec.name} ports: - protocol: TCP port: 80 targetPort: 80 ``` 套用此 ResourceGraphDefinition 後，應用程式團隊可以使用簡化的 API 建立 Web 應用程式： ``` apiVersion: kro.run/v1alpha1 kind: WebApplication metadata: name: my-app spec: name: my-app replicas: 5 ``` kro 會自動使用適當的組態建立部署和服務。由於 `image` 未指定，因此會使用結構描述`nginx:latest`中的預設值。 ## 核心概念 **重要** kro 會在建立時間驗證 ResourceGraphDefinitions，而不是在執行時間。當您建立 RGD 時，kro 會驗證 CEL 語法、根據實際 Kubernetes 結構描述類型檢查表達式、驗證欄位是否存在，以及偵測循環相依性。這表示在部署任何執行個體之前，建立 RGD 時會立即發現錯誤。 ### ResourceGraphDefinition ResourceGraphDefinition (RGD) 透過指定下列項目來定義自訂 Kubernetes API： + **結構描述** - 使用 SimpleSchema 格式的 API 結構 （欄位名稱、類型、預設值、驗證） + **資源** - 要建立的基礎 Kubernetes 或 AWS 資源的範本 + **相依性** - 資源彼此的關係 （從欄位參考自動偵測） 當您套用 RGD 時，kro 會在叢集中註冊新的自訂資源定義 (CRD)。然後，應用程式團隊可以建立自訂 API 的執行個體，然後 kro 會處理建立和管理所有基礎資源。 如需詳細資訊，請參閱 kro 文件中的 [ResourceGraphDefinition 概觀](https://kro.run/docs/concepts/rgd/overview/)。 ### SimpleSchema 格式 SimpleSchema 提供簡單的方式來定義 API 結構描述，而不需要 OpenAPI 知識： ``` schema: apiVersion: v1alpha1 kind: Database spec: name: string | required=true description="Database name" size: string | default="small" enum=small,medium,large replicas: integer | default=1 minimum=1 maximum=5 ``` SimpleSchema `integer`支援 `string`、`boolean`、 和 `number`類型，具有 `required`、、`default``minimum`/`maximum`、 `enum`和 等限制`pattern`條件。 如需詳細資訊，請參閱 kro 文件中的 [SimpleSchema](https://kro.run/docs/concepts/rgd/schema/)。 ### CEL 表達式 kro 使用通用表達式語言 (CEL) 動態參考值，並新增條件式邏輯。CEL 表達式包裝在 `${`和 中，`}`可用兩種方式使用： **獨立表達式** - 整個欄位值是單一表達式： ``` spec: replicas: ${schema.spec.replicaCount} # Expression returns integer labels: ${schema.spec.labelMap} # Expression returns object ``` 表達式結果會取代整個欄位值，且必須符合欄位的預期類型。 **字串範本** - 內嵌在字串中的一或多個表達式： ``` metadata: name: "${schema.spec.prefix}-${schema.spec.name}" # Multiple expressions annotation: "Created by ${schema.spec.owner}" # Single expression in string ``` 字串範本中的所有表達式都必須傳回字串。使用 `string()`轉換其他類型：`"replicas-${string(schema.spec.count)}"`。 **欄位參考** - 使用 存取執行個體規格值`schema.spec`： ``` template: metadata: name: ${schema.spec.name}-deployment namespace: ${schema.metadata.namespace} # Can also reference metadata spec: replicas: ${schema.spec.replicas} ``` **選用欄位存取** - `?`用於可能不存在的欄位： ``` # For ConfigMaps or Secrets with unknown structure value: ${configmap.data.?DATABASE_URL} # For optional status fields ready: ${deployment.status.?readyReplicas > 0} ``` 如果 欄位不存在，則表達式會傳回 `null`而非失敗。 **條件式資源** - 只有在符合條件時才包含資源： ``` resources: - id: ingress includeWhen: - ${schema.spec.enableIngress == true} template: # ... ingress configuration ``` `includeWhen` 欄位接受布林表達式的清單。所有條件都必須為 true，才能建立資源。目前， `includeWhen` 只能參考 `schema.spec` 欄位。 **轉換** - 使用三元運算子和函數轉換值： ``` template: spec: resources: requests: memory: ${schema.spec.size == "small" ? "512Mi" : "2Gi"} # String concatenation image: ${schema.spec.registry + "/" + schema.spec.imageName} # Type conversion port: ${string(schema.spec.portNumber)} ``` **跨資源參考** - 來自其他資源的參考值： ``` resources: - id: bucket template: apiVersion: s3.services.k8s.aws/v1alpha1 kind: Bucket spec: name: ${schema.spec.name}-data - id: configmap template: apiVersion: v1 kind: ConfigMap data: BUCKET_NAME: ${bucket.spec.name} BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn} ``` 當您在 CEL 表達式中參考另一個資源時，它會自動建立相依性。 kro 會確保先建立參考的資源。 如需詳細資訊，請參閱 kro 文件中的 [CEL 表達式](https://kro.run/docs/concepts/rgd/cel-expressions/)。 ### 資源相依性 kro 會自動從 CEL 表達式推斷相依性 - 您不會指定順序，而是描述關係。當一個資源使用 CEL 表達式參考另一個資源時，kro 會建立相依性並決定正確的建立順序。 ``` resources: - id: bucket template: apiVersion: s3.services.k8s.aws/v1alpha1 kind: Bucket spec: name: ${schema.spec.name}-data - id: notification template: apiVersion: s3.services.k8s.aws/v1alpha1 kind: BucketNotification spec: bucket: ${bucket.spec.name} # Creates dependency: notification depends on bucket ``` 表達式`${bucket.spec.name}`會建立相依性。 kro 會建立所有資源及其相依性的定向無環圖 (DAG)，然後運算拓撲順序以進行建立。 **建立順序**：依拓撲順序建立資源 （依存性優先）。 **平行建立**：同時建立沒有相依性的資源。 **刪除順序**：以反向拓撲順序刪除資源 （先依存）。 **循環相依性**：不允許 - Kro 在驗證期間拒絕具有循環相依性的 ResourceGraphDefinitions。 您可以檢視計算的建立順序： ``` kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}' ``` 如需詳細資訊，請參閱 kro 文件中的[圖形推論](https://kro.run/docs/concepts/rgd/dependencies-ordering/)。 ## 使用 ACK 編寫 kro 與 ACK 的 EKS 功能無縫搭配運作，以使用 Kubernetes AWS 資源編寫資源： ``` resources: # Create {aws} S3 bucket with ACK - id: bucket template: apiVersion: s3.services.k8s.aws/v1alpha1 kind: Bucket spec: name: ${schema.spec.name}-files # Inject bucket details into Kubernetes ConfigMap - id: config template: apiVersion: v1 kind: ConfigMap data: BUCKET_NAME: ${bucket.spec.name} BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn} # Use ConfigMap in application deployment - id: deployment template: apiVersion: apps/v1 kind: Deployment spec: template: spec: containers: - name: app envFrom: - configMapRef: name: ${config.metadata.name} ``` 此模式可讓您建立 AWS 資源、擷取其詳細資訊 (ARNs、URLs、端點），並將它們插入您的應用程式組態，全都以單一單位管理。 如需更多合成模式和進階範例，請參閱 [EKS 的 kro 考量](kro-considerations.md)。 ## 後續步驟 + [EKS 的 kro 考量](kro-considerations.md) - 了解 EKS 特定的模式、RBAC 以及與 ACK 和 Argo CD 的整合 + [kro 文件](https://kro.run/docs/overview) - 完整的 kro 文件，包括進階 CEL 表達式、驗證模式和故障診斷