使用CRD擴展Kubernetes API · kubernetes完整攻略

# 使用CRD擴展Kubernetes API 本文是如何創建 CRD 來擴展 Kubernetes API 的教程。CRD 是用來擴展 Kubernetes 最常用的方式，在 Service Mesh 和 Operator 中也被大量使用。因此讀者如果想在 Kubernetes 上做擴展和開發的話，是十分有必要了解 CRD 的。在閱讀本文前您需要先了解[使用自定義資源擴展 API](custom-resource.md)，以下內容譯自 [Kubernetes 官方文檔](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/)，有刪改，推薦閱讀[如何從零開始編寫一個 Kubernetes CRD](http://www.servicemesher.com/blog/kubernetes-crd-quick-start/)。 ## 創建 CRD（CustomResourceDefinition）創建新的 CustomResourceDefinition（CRD）時，Kubernetes API Server 會為您指定的每個版本創建新的 RESTful 資源路徑。CRD 可以是命名空間的，也可以是集群范圍的，可以在 CRD `scope` 字段中所指定。與現有的內置對象一樣，刪除命名空間會刪除該命名空間中的所有自定義對象。CustomResourceDefinition 本身是非命名空間的，可供所有命名空間使用。參考下面的 CRD，將其配置保存在 `resourcedefinition.yaml` 文件中： ```yaml apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: # 名稱必須符合下面的格式：<plural>.<group> name: crontabs.stable.example.com spec: # REST API使用的組名稱：/apis/<group>/<version> group: stable.example.com # REST API使用的版本號：/apis/<group>/<version> version: v1 # Namespaced或Cluster scope: Namespaced names: # URL中使用的復數名稱: /apis/<group>/<version>/<plural> plural: crontabs # CLI中使用的單數名稱 singular: crontab # CamelCased格式的單數類型。在清單文件中使用 kind: CronTab # CLI中使用的資源簡稱 shortNames: - ct ``` 創建該 CRD： ```bash kubectl create -f resourcedefinition.yaml ``` 訪問 RESTful API 端點如 <http://172.20.0.113:8080> 將看到如下 API 端點已創建： ```bash /apis/stable.example.com/v1/namespaces/*/crontabs/... ``` 然后，此端點 URL 可用于創建和管理自定義對象。上面的 CRD 中定義的類型就是 `CronTab`。可能需要幾秒鐘才能創建端點。您可以監控 CustomResourceDefinition 中 `Established` 的狀態何時為 true，或者查看 API 資源的發現信息中是否顯示了您的資源。 ## 創建自定義對象創建 CustomResourceDefinition 對象后，您可以創建自定義對象。自定義對象可包含自定義字段。這些字段可以包含任意 JSON。在以下示例中， `cronSpec` 和 `image` 自定義字段在自定義對象中設置 `CronTab`。`CronTab` 類型來自您在上面創建的 CustomResourceDefinition 對象的規范。如果您將以下 YAML 保存到`my-crontab.yaml`： ```yaml apiVersion: "stable.example.com/v1" kind: CronTab metadata: name: my-new-cron-object spec: cronSpec: "* * * * */5" image: my-awesome-cron-image ``` 并創建它： ```bash kubectl create -f my-crontab.yaml ``` 然后，您可以使用 kubectl 管理 CronTab 對象。例如： ```bash kubectl get crontab ``` 應該打印這樣的列表： ```bash NAME AGE my-new-cron-object 6s ``` 使用 kubectl 時，資源名稱不區分大小寫，您可以使用 CRD 中定義的單數或復數形式，以及任何短名稱。您還可以查看原始 YAML 數據： ```bash kubectl get ct -o yaml ``` 您應該看到它的 yaml 中的自定義 `cronSpec` 和 `image` 字段： ```yaml apiVersion: v1 items: - apiVersion: stable.example.com/v1 kind: CronTab metadata: clusterName: "" creationTimestamp: 2017-05-31T12:56:35Z deletionGracePeriodSeconds: null deletionTimestamp: null name: my-new-cron-object namespace: default resourceVersion: "285" selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object uid: 9423255b-4600-11e7-af6a-28d2447dc82b spec: cronSpec: '* * * * */5' image: my-awesome-cron-image kind: List metadata: resourceVersion: "" selfLink: "" ``` ## 刪除 CustomResourceDefinition 刪除 CustomResourceDefinition 時，服務器將刪除 RESTful API 端點并**刪除存儲在其中的所有自定義對象**。 ```bash kubectl delete -f resourcedefinition.yaml kubectl get crontabs Error from server (NotFound): Unable to list "crontabs": the server could not find the requested resource (get crontabs.stable.example.com) ``` 如果稍后重新創建相同的 CustomResourceDefinition，它將從空開始。 ## 提供 CRD 的多個版本有關提供 CustomResourceDefinition 的多個版本以及將對象從一個版本遷移到另一個[版本](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/)的詳細信息，請參閱[自定義資源定義版本控制](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/)。 ## 高級主題 ### Finalizer（終結器） *Finalizer（終結器）*允許控制器實現異步預刪除 hook。自定義對象支持終結器，就像內置對象一樣。您可以將終結器添加到自定義對象，如下所示： ```yaml apiVersion: "stable.example.com/v1" kind: CronTab metadata: finalizers: - finalizer.stable.example.com ``` 終結器是任意字符串值，當存在時確保在資源存在時不可能進行硬刪除。對具有終結器的對象的第一個刪除請求設置該`metadata.deletionTimestamp`字段的值，但不刪除它。設置此值后，`finalizer` 只能刪除列表中的條目。如果設置了 `metadata.deletionTimestamp` 字段，控制器監控對象將執行它們所有的終結器，對該對象輪詢更新請求。執行完所有終結器后，將刪除該資源。值`metadata.deletionGracePeriodSeconds`控制輪詢更新之間的間隔。每個控制器都有責任從列表中刪除其終結器。如果終結器列表為空，Kubernetes 最終只會刪除該對象，這意味著所有終結器都已執行。 ### Validation（驗證） **功能狀態：** `Kubernetes v1.12` [beta](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#) 可以通過 [OpenAPI v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject)驗證自定義對象是否符合標準。此外，以下限制適用于 schema： - 字段`default`、`nullable`、`discriminator`、`readOnly`、`writeOnly`、`xml`、 `deprecated` 和 `$ref` 不能設置。 - 該字段 `uniqueItems` 不能設置為 true。 - 該字段 `additionalProperties` 不能設置為 false。您可以使用 [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver)`CustomResourceValidation` 上的功能門（feature gate）禁用此功能： ``` --feature-gates=CustomResourceValidation=false ``` 該 schema 在 CustomResourceDefinition 中定義。在以下示例中，CustomResourceDefinition 對自定義對象應用以下驗證： - `spec.cronSpec` 必須是字符串，并且必須是正則表達式描述的形式。 - `spec.replicas` 必須是整數，且最小值必須為 1，最大值為 10。將 CustomResourceDefinition 保存到 `resourcedefinition.yaml`： ```yaml apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: crontabs.stable.example.com spec: group: stable.example.com versions: - name: v1 served: true storage: true version: v1 scope: Namespaced names: plural: crontabs singular: crontab kind: CronTab shortNames: - ct validation: # openAPIV3Schema 適用于驗證自定義對象的 schema。 openAPIV3Schema: properties: spec: properties: cronSpec: type: string pattern: '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$' replicas: type: integer minimum: 1 maximum: 10 ``` 并創建它： ```bash kubectl create -f resourcedefinition.yaml ``` `CronTab` 如果其字段中存在無效值，則將拒絕創建類型的自定義對象的請求。在以下示例中，自定義對象包含具有無效值的字段： - `spec.cronSpec` 與正則表達式不匹配。 - `spec.replicas` 大于10。如果您將以下YAML保存到`my-crontab.yaml`： ```yaml apiVersion: "stable.example.com/v1" kind: CronTab metadata: name: my-new-cron-object spec: cronSpec: "* * * *" image: my-awesome-cron-image replicas: 15 ``` 并創建它： ```bash kubectl create -f my-crontab.yaml ``` 你會收到一個錯誤： ```bash The CronTab "my-new-cron-object" is invalid: []: Invalid value: map[string]interface {}{"apiVersion":"stable.example.com/v1", "kind":"CronTab", "metadata":map[string]interface {}{"name":"my-new-cron-object", "namespace":"default", "deletionTimestamp":interface {}(nil), "deletionGracePeriodSeconds":(*int64)(nil), "creationTimestamp":"2017-09-05T05:20:07Z", "uid":"e14d79e7-91f9-11e7-a598-f0761cb232d1", "selfLink":"", "clusterName":""}, "spec":map[string]interface {}{"cronSpec":"* * * *", "image":"my-awesome-cron-image", "replicas":15}}: validation failure list: spec.cronSpec in body should match '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$' spec.replicas in body should be less than or equal to 10 ``` 如果字段包含有效值，則接受對象創建請求。將以下 YAML 保存到 `my-crontab.yaml`： ```yaml apiVersion: "stable.example.com/v1" kind: CronTab metadata: name: my-new-cron-object spec: cronSpec: "* * * * */5" image: my-awesome-cron-image replicas: 5 ``` 并創建它： ```bash kubectl create -f my-crontab.yaml crontab "my-new-cron-object" created ``` ### 其他打印列從 Kubernetes 1.11 開始，kubectl 使用服務器端打印。服務器決定 `kubectl get` 命令顯示哪些列。您可以使用 CustomResourceDefinition 自定義這些列。下面的示例將輸出 `Spec`、`Replicas` 和 `Age` 列。 1. 將 CustomResourceDefinition保存到 `resourcedefinition.yaml`。 ```yaml apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: crontabs.stable.example.com spec: group: stable.example.com version: v1 scope: Namespaced names: plural: crontabs singular: crontab kind: CronTab shortNames: - ct additionalPrinterColumns: - name: Spec type: string description: The cron spec defining the interval a CronJob is run JSONPath: .spec.cronSpec - name: Replicas type: integer description: The number of jobs launched by the CronJob JSONPath: .spec.replicas - name: Age type: date JSONPath: .metadata.creationTimestamp ``` 2. 創建 CustomResourceDefinition： ```bash kubectl create -f resourcedefinition.yaml ``` 3. 使用上一節中的創建的 `my-crontab.yaml` 實例。 4. 調用服務器端打印： ```bash kubectl get crontab my-new-cron-object ``` 請注意 `NAME`、`SPEC`、`REPLICAS` 和 `AGE` 在輸出列： ```bash NAME SPEC REPLICAS AGE my-new-cron-object * * * * * 1 7s ``` `NAME` 列是隱含的，不需要在 CustomResourceDefinition 中定義。 #### Priority（優先級）每列中都包含一個 `priority` 字段。目前，優先級區分標準視圖或 wide 視圖中顯示的列（使用 `-o wide` 標志）。 - 具有優先級的列 `0` 顯示在標準視圖中。 - 優先級大于 `0` 的列僅在 wide 視圖中顯示。 #### Type（類型）列中的 `type` 字段可以是以下任何一種（參考 [OpenAPI v3 數據類型](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypes)）： - `integer` - 非浮點數 - `number` - 浮點數 - `string` - 字符串 - `boolean` - ture 或 false - `date` - 自此時間戳以來的時間差異呈現如果 CustomResource 中的值與為列指定的類型不匹配，則省略該值。使用 CustomResource 驗證以確保值類型正確。 #### Format（格式）列中的 `format` 字段可以是以下任何一個： - `int32` - `int64` - `float` - `double` - `byte` - `date` - `date-time` - `password` 該列 `format` 控制 `kubectl` 打印值時使用的樣式。 ### 子資源 **功能狀態：** `Kubernetes v1.12` [beta](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#) 自定義資源支持 `/status` 和 `/scale` 子資源。您可以使用 [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver) `CustomResourceSubresources` 上的功能門（feature gate）禁用此功能： ```bash --feature-gates=CustomResourceSubresources=false ``` 可以通過在 CustomResourceDefinition 中定義它們來選擇性地啟用 status 和 scale 子資源。 #### 狀態子資源啟用狀態子資源后，將公開自定義資源的子資源 `/status`。 - 狀態和規范節分別由自定義資源內的 JSONPath `.status` 和 `.spec`JSONPath 表示。 - `PUT``/status` 對子資源的請求采用自定義資源對象，并忽略除狀態節之外的任何更改。 - `PUT``/status` 對子資源的請求僅驗證自定義資源的狀態節。 - `PUT`/ `POST`/ `PATCH` 請求自定義資源忽略更改狀態節。 - 對 spec 節的任何更改都會增加 `.metadata.generation` 的值。 - 在 CRD OpenAPI 驗證模式的根目錄中只允許以下構造： - - Description - Example - ExclusiveMaximum - ExclusiveMinimum - ExternalDocs - Format - Items - Maximum - MaxItems - MaxLength - Minimum - MinItems - MinLength - MultipleOf - Pattern - Properties - Required - Title - Type - UniqueItems #### 擴展子資源啟用 scale 子資源后，將公開自定義資源的子資源 `/scale`。該 `autoscaling/v1.Scale` 對象作為有效負載發送 `/scale`。要啟用 scale 子資源，CustomResourceDefinition 中需要定義以下值。 - `SpecReplicasPath` 在與之對應的自定義資源中定義 JSONPath `Scale.Spec.Replicas`。 - 這是一個必需的值。 - `.spec` 只允許使用帶點符號的 JSONPaths 。 - 如果 `SpecReplicasPath` 自定義資源中沒有值，則 `/scale` 子資源將在GET上返回錯誤。 - `StatusReplicasPath` 在與之對應的自定義資源中定義 JSONPath `Scale.Status.Replicas`。 - 這是一個必需的值。 - `.stutus` 只允許使用帶點符號的 JSONPaths 。 - 如果 `StatusReplicasPath` 自定義資源中沒有值，則子資源 `/scale` 中的狀態副本值將默認為 0。 - `LabelSelectorPath `在與之對應的自定義資源中定義 JSONPath `Scale.Status.Selector`。 - 這是一個可選值。 - 必須將其設置為與 HPA 一起使用。 - `.status` 只允許使用帶點符號的 JSONPaths 。 - 如果 `LabelSelectorPath` 自定義資源中沒有值，則子資源 `/scale` 中的狀態選擇器值將默認為空字符串。在以下示例中，啟用了status 和 scale 子資源。將 CustomResourceDefinition 保存到`resourcedefinition.yaml`： ```yaml apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: crontabs.stable.example.com spec: group: stable.example.com versions: - name: v1 served: true storage: true scope: Namespaced names: plural: crontabs singular: crontab kind: CronTab shortNames: - ct # subresources describes the subresources for custom resources. subresources: # status enables the status subresource. status: {} # scale enables the scale subresource. scale: # specReplicasPath defines the JSONPath inside of a custom resource that corresponds to Scale.Spec.Replicas. specReplicasPath: .spec.replicas # statusReplicasPath defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Replicas. statusReplicasPath: .status.replicas # labelSelectorPath defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Selector. labelSelectorPath: .status.labelSelector ``` 并創建它： ```bash kubectl create -f resourcedefinition.yaml ``` 創建 CustomResourceDefinition 對象后，您可以創建自定義對象。如果您將以下 YAML 保存到 `my-crontab.yaml`： ```yaml apiVersion: "stable.example.com/v1" kind: CronTab metadata: name: my-new-cron-object spec: cronSpec: "* * * * */5" image: my-awesome-cron-image replicas: 3 ``` 并創建它： ```bash kubectl create -f my-crontab.yaml ``` 然后在以下位置創建新的命名空間 RESTful API 端點： ```bash /apis/stable.example.com/v1/namespaces/*/crontabs/status ``` 和 ```bash /apis/stable.example.com/v1/namespaces/*/crontabs/scale ``` 可以使用該 `kubectl scale` 命令縮放自定義資源。例如，以上創建的自定義資源的的 `.spec.replicas` 設置為 5： ```bash kubectl scale --replicas=5 crontabs/my-new-cron-object crontabs "my-new-cron-object" scaled kubectl get crontabs my-new-cron-object -o jsonpath='{.spec.replicas}' 5 ``` ### Category（分類）類別是自定義資源所屬的分組資源的列表（例如 `all`）。您可以使用 `kubectl get <category-name>` 列出屬于該類別的資源。此功能是 **beta**，可用于 v1.10 中的自定義資源。以下示例添加 `all` CustomResourceDefinition 中的類別列表，并說明如何使用 `kubectl get all` 輸出自定義資源。將以下 CustomResourceDefinition 保存到 `resourcedefinition.yaml`： ```yaml apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition metadata: name: crontabs.stable.example.com spec: group: stable.example.com versions: - name: v1 served: true storage: true scope: Namespaced names: plural: crontabs singular: crontab kind: CronTab shortNames: - ct # categories is a list of grouped resources the custom resource belongs to. categories: - all ``` 并創建它： ```bash kubectl create -f resourcedefinition.yaml ``` 創建 CustomResourceDefinition 對象后，您可以創建自定義對象。將以下 YAML 保存到 `my-crontab.yaml`： ```yaml apiVersion: "stable.example.com/v1" kind: CronTab metadata: name: my-new-cron-object spec: cronSpec: "* * * * */5" image: my-awesome-cron-image ``` 并創建它： ```bash kubectl create -f my-crontab.yaml ``` 您可以使用`kubectl get`以下方式指定類別： ```bash kubectl get all ``` 它將包括種類的自定義資源`CronTab`： ```bash NAME AGE crontabs/my-new-cron-object 3s ``` ## 參考 - [Extend the Kubernetes API with CustomResourceDefinitions - kubernetes.io](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) - [如何從零開始編寫一個Kubernetes CRD - servicemesher.com](http://www.servicemesher.com/blog/kubernetes-crd-quick-start/)