whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Custom resource docs

Browse Source
This commit is contained in:
Anthony Yeh
2017-06-22 16:48:48 -07:00
committed by Andrew Chen
parent d8f5b4f8a4
commit 171a5aeddf
10 changed files with 356 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md
+80 -58
View File
@@ -1,48 +1,36 @@
---
title: Extend the Kubernetes API with CustomResourceDefinitions
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"
- deads2k
- enisoc
---
* TOC
{:toc}
{% capture overview %}
This page shows how to install a [custom resource](/docs/concepts/api-extension/custom-resources/)
into the Kubernetes API by creating a CustomResourceDefinition.
{% endcapture %}
## What is a CustomResourceDefinition?
{% capture prerequisites %}
* Read about [custom resources](/docs/concepts/api-extension/custom-resources/).
* Make sure your Kubernetes cluster has a master version of 1.7.0 or higher.
{% endcapture %}
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.
{% capture steps %}
## Create a CustomResourceDefinition
`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
When you create a new *CustomResourceDefinition* (CRD), the Kubernetes API Server
reacts by creating a new RESTful resource path, either namespaced or cluster-scoped,
as specified in the CRD's `scope` field. 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.
CustomResourceDefinitions themselves are non-namespaced and are available to all namespaces.
For example, if you save the following `CustomResourceDefinition` to `resourcedefinition.yaml`:
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 must match the spec fields below, and be in the form: <plural>.<group>
name: crontabs.stable.example.com
spec:
# group name to use for REST API: /apis/<group>/<version>
@@ -54,9 +42,9 @@ spec:
names:
# plural name to be used in the URL: /apis/<group>/<version>/<plural>
plural: crontabs
# singular name to be used as alias on the CLI and for display
# singular name to be used as an alias on the CLI and for display
singular: crontab
# kind is normally the CamelCased singular type. Your resource manifests use this
# 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:
@@ -66,27 +54,28 @@ spec:
And create it:
```shell
$ kubectl create -f resourcedefinition.yaml
customresourcedefinitions "crontabs.stable.example.com" created
kubectl create -f resourcedefinition.yaml
```
Then a new RESTful API endpoint is created at:
Then a new namespaced RESTful API endpoint is created at:
`/apis/stable.example.com/v1/namespaces/<namespace>/crontabs/...`
```
/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.
CustomResourceDefinition object you created above.
## Creating Custom Objects
## Create custom objects
After the `CustomResourceDefinition` object has been created you can create
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
contain arbitrary JSON.
In the following example, the `cronSpec` and `image` custom fields are set in a
custom object of kind `CronTab`. The kind `CronTab` comes from the spec of the
`CustomResourceDefinition` object we created above.
CustomResourceDefinition object you created above.
If you save the following YAML to `my-crontab.yaml`:
@@ -103,23 +92,36 @@ spec:
and create it:
```shell
$ kubectl create -f my-crontab.yaml
crontab "my-new-cron-object" created
kubectl create -f my-crontab.yaml
```
You can then manage our `CronTab` objects using kubectl. Note that resource
names are not case-sensitive when using kubectl:
You can then manage your CronTab objects using kubectl. For example:
```shell
$ kubectl get crontab
kubectl get crontab
```
Should print a list like this:
```console
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:
Note that resource names are not case-sensitive when using kubectl,
and you can use either the singular or plural forms defined in the CRD,
as well as any short names.
```yaml
$ kubectl get ct -o yaml
You can also view the raw JSON data:
```shell
kubectl get ct -o yaml
```
You should see that it contains the custom `cronSpec` and `image` fields
from the yaml you used to create it:
```console
apiVersion: v1
items:
- apiVersion: stable.example.com/v1
@@ -142,11 +144,17 @@ metadata:
resourceVersion: ""
selfLink: ""
```
{% endcapture %}
{% capture discussion %}
## Advanced topics
## Advanced Topics
### Finalizers
CustomResources (objects created in the schema defined by CustomResourceDefintions)
support finalizers. If you add a `metadata.finalizers` stanza like
*Finalizers* allow controllers to implement asynchronous pre-delete hooks.
Custom objects support finalizers just like built-in objects.
You can add a finalizer to a custom object like this:
```yaml
apiVersion: "stable.example.com/v1"
@@ -156,7 +164,21 @@ metadata:
- 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.
The first delete request on an object with finalizers merely sets a value for the
`metadata.deletionTimestamp` field instead of deleting it.
This triggers controllers watching the object to execute any finalizers they handle.
Each controller then removes its finalizer from the list and issues the delete request again.
This request only deletes the object if the list of finalizers is now empty,
meaning all finalizers are done.
{% endcapture %}
{% capture whatsnext %}
* Learn how to [Migrate a ThirdPartyResource to CustomResourceDefinition](/docs/tasks/access-kubernetes-api/migrate-third-party-resource/).
{% endcapture %}
{% include templates/task.md %}