From 6cbd6bda672f86b337f1c4fc339274d9dc031cc9 Mon Sep 17 00:00:00 2001 From: deads2k Date: Wed, 31 May 2017 09:08:56 -0400 Subject: [PATCH] document custom resource definitions --- _data/tasks.yml | 1 + .../extend-api-custom-resource-definitions.md | 162 ++++++++++++++++++ .../extend-api-third-party-resource.md | 17 +- 3 files changed, 177 insertions(+), 3 deletions(-) create mode 100644 docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 3193192942..46b84cb140 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -91,6 +91,7 @@ toc: - title: Accessing and Extending the Kubernetes API section: - docs/tasks/access-kubernetes-api/http-proxy-access-api.md + - docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md - docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md - title: Using TLS diff --git a/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md b/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md new file mode 100644 index 0000000000..12dc34b456 --- /dev/null +++ b/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md @@ -0,0 +1,162 @@ +--- +assignees: +- IanLewis +title: Extending the Kubernetes API Using Custom Resource Definitions +redirect_from: +- "/docs/user-guide/customresourcedefinitions/" +- "/docs/user-guide/customresourcedefinitions.html" +- "/docs/concepts/ecosystem/customresourcedefinitions/" +- "/docs/concepts/ecosystem/customresourcedefinitions.html" +--- + +* TOC +{:toc} + +## What is a CustomResourceDefinition? + +Kubernetes comes with many built-in API objects. However, there are often times +when you might need to extend Kubernetes with your own API objects in order to do custom automation. + +`CustomResourceDefinition` objects are a way to extend the Kubernetes API with +a new API object type. The new API object type will be given an API endpoint +URL and support CRUD operations, and watch API. You can then create custom +objects using this API endpoint. You can think of `CustomResourceDefinitions` +as being much like the schema for a database table. Once you have created the +table, you can then start storing rows in the table. Once created, +`CustomResourceDefinitions` can act as the data model behind custom controllers +or automation programs. + +A `CustomResourceDefinition` creates the REST API for a custom resource of your chosen name. + +## Creating a CustomResourceDefinition + +When you create a new `CustomResourceDefinition`, the Kubernetes API Server +reacts by creating a new RESTful resource path (namespaced or cluster-scoped) +depending on your request. As with existing built-in objects, deleting a +namespace deletes all custom objects in that namespace. +`CustomResourceDefinitions` themselves are non-namespaced and are available to all namespaces. + +For example, if you save the following `CustomResourceDefinition` to `resourcedefinition.yaml`: + +```yaml +apiVersion: apiextensions.k8s.io/v1beta1 +kind: CustomResourceDefinition +metadata: + # name must be in the form: plural.group + name: crontabs.stable.example.com +spec: + # group name to use for REST API: /apis// + group: stable.example.com + # version name to use for REST API: /apis// + version: v1 + # either Namespaced or Cluster + scope: Namespaced + names: + # plural name to be used in the URL: /apis/// + plural: crontabs + # singular name to be used as alias on the CLI and for display + singular: crontab + # kind is normally the CamelCased singular type. Your resource manifests use this + kind: CronTab + # shortNames allow shorter string to match your resource on the CLI + shortNames: + - ct +``` + +And create it: + +```shell +$ kubectl create -f resourcedefinition.yaml +customresourcedefinitions "crontabs.stable.example.com" created +``` + +Then a new RESTful API endpoint is created at: + +`/apis/stable.example.com/v1/namespaces//crontabs/...` + +This endpoint URL can then be used to create and manage custom objects. +The `kind` of these objects will be `CronTab` from the spec of the +`CustomResourceDefinition` object we created above. + + +## Creating Custom Objects + +After the `CustomResourceDefinition` object has been created you can create +custom objects. Custom objects can contain custom fields. These fields can +contain arbitrary JSON. +In the following example, a `cronSpec` and `image` custom fields are set to the +custom object of kind `CronTab`. The kind `CronTab` comes from the spec of the +`CustomResourceDefinition` object we created above. + +If you save the following YAML to `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 +``` + +and create it: + +```shell +$ kubectl create -f my-crontab.yaml +crontab "my-new-cron-object" created +``` + +You can then manage our `CronTab` objects using kubectl. Note that resource +names are not case-sensitive when using kubectl: + +```shell +$ kubectl get crontab +NAME KIND +my-new-cron-object CronTab.v1.stable.example.com +``` + +You can also view the raw JSON data. Here you can see that it contains the custom `cronSpec` and `image` fields from the yaml you used to create it: + +```yaml +$ kubectl get ct -o 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: "" +``` + +## Advanced Topics +### Finalizers +CustomResources (objects created in the schema defined by CustomResourceDefintions) +support finalizers. If you add a `metadata.finalizers` stanza like + +```yaml +apiVersion: "stable.example.com/v1" +kind: CronTab +metadata: + finalizers: + - finalizer.stable.example.com +``` + +Then when the CustomResource is deleted, the `metadata.deletionTimestamp` will +be set and update watch events will be sent to a controller which can perform +finalization steps before removing the finalizer and deleting the object again. +This allows cleanup for CustomResources like "normal" Kubernetes APIs. \ No newline at end of file diff --git a/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md b/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md index 15aa0c356a..f5bc59530a 100644 --- a/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md +++ b/docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md @@ -14,13 +14,24 @@ redirect_from: ## What is ThirdPartyResource? -**WARNING: ThirdPartyResources are not yet considered stable, and the API and/or storage could change before GA. -Development and outstanding issues are tracked at [https://github.com/kubernetes/features/issues/95](https://github.com/kubernetes/features/issues/95).** +**WARNING: ThirdPartyResources are deprecated as of 1.7 and will be removed as soon as possible without access to existing data! See https://kubernetes.io/docs/reference/deprecation-policy/ for deprecation rules. Please [migrate to CustomResourceDefinition](#Migration-to-CustomResourceDefinitions).** -Kubernetes comes with many built-in API objects. However, there are often times when you might need to extend Kubernetes with their own API objects in order to do custom automation. +Kubernetes comes with many built-in API objects. However, there are often times when you might need to extend Kubernetes with your own API objects in order to do custom automation. `ThirdPartyResource` objects are a way to extend the Kubernetes API with a new API object type. The new API object type will be given an API endpoint URL and support CRUD operations, and watch API. You can then create custom objects using this API endpoint. You can think of `ThirdPartyResources` as being much like the schema for a database table. Once you have created the table, you can then start storing rows in the table. Once created, `ThirdPartyResources` can act as the data model behind custom controllers or automation programs. +## Migration to CustomResourceDefinitions +`ThirdPartyResources` are being replaced by `CustomResourceDefinitions` as of 1.7, so you must migrate your data from one to the other. +The types are not directly compatible so you'll need to perform some manual steps. +You should do a dry-run of these steps in a non-production cluster to make sure things work as expected. + 1. Create a `CustomResourceDefinition` that has a spec matching your current `ThirdPartyResource`. + 2. Stop your ThirdPartyResource controllers. + 3. Backup your ThirdPartyResource *Data* (the custom objects you've created). + 4. Delete the `ThirdPartyResource`. This will trigger migration to the `CustomResourceDefinition` + 5. Wait for the `ThirdPartyResource` to be removed. + 6. Confirm that your custom objects are still present. If this doesn't work, simply recreate your `ThirdPartyResource` to get your data back. + 7. Restart your ThirdPartyResource controllers. + ## Structure of a ThirdPartyResource Each `ThirdPartyResource` has the following: