Custom resource docs

2017-06-22 16:48:48 -07:00
parent d8f5b4f8a4
commit 171a5aeddf
10 changed files with 356 additions and 88 deletions
@@ -0,0 +1,79 @@
+---
+title: Custom Resources
+assignees:
+- enisoc
+- deads2k
+---
+
+{% capture overview %}
+This page explains the concept of *custom resources*, which are extensions of the Kubernetes API.
+{% endcapture %}
+
+{% capture body %}
+## Custom resources
+
+A *resource* is an endpoint in the [Kubernetes API](/docs/reference/api-overview/) that stores a
+collection of [API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a
+certain kind.
+For example, the built-in *pods* resource contains a collection of Pod objects.
+
+A *custom resource* is an extension of the Kubernetes API that is not necessarily available on every
+Kubernetes cluster.
+In other words, it represents a customization of a particular Kubernetes installation.
+
+Custom resources can appear and disappear in a running cluster through dynamic registration,
+and cluster admins can update custom resources independently of the cluster itself.
+Once a custom resource is installed, users can create and access its objects with
+[kubectl](/docs/user-guide/kubectl-overview/), just as they do for built-in resources like *pods*.
+
+## Custom controllers
+
+On their own, custom resources simply let you store and retrieve structured data.
+It is only when combined with a *controller* that they become a true
+[declarative API](/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects).
+The controller interprets the structured data as a record of the user's desired state,
+and continually takes action to achieve and maintain that state.
+
+A *custom controller* is a controller that users can deploy and update on a running cluster,
+independently of the cluster's own lifecycle.
+Custom controllers can work with any kind of resource, but they are especially effective when
+combined with custom resources.
+The [Operator](https://coreos.com/blog/introducing-operators.html) pattern is one example of such a
+combination. It allows developers to encode domain knowledge for specific applications into an
+extension of the Kubernetes API.
+
+## CustomResourceDefinitions
+
+[CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
+(CRD) is a built-in API that offers a simple way to create custom resources.
+Deploying a CRD into the cluster causes the Kubernetes API server to begin serving the specified
+custom resource on your behalf.
+
+This frees you from writing your own API server to handle the custom resource,
+but the generic nature of the implementation means you have less flexibility than with
+[API server aggregation](#api-server-aggregation).
+
+CRD is the successor to the deprecated *ThirdPartyResource* (TPR) API, and is available as of
+Kubernetes 1.7.
+
+## API server aggregation
+
+Usually, each resource in the Kubernetes API requires code that handles REST requests and manages
+persistent storage of objects.
+The main Kubernetes API server handles built-in resources like *pods* and *services*,
+and can also handle custom resources in a generic way through [CustomResourceDefinitions](#customresourcedefinitions).
+
+The [aggregation layer](/docs/concepts/api-extension/) allows you to provide specialized
+implementations for your custom resources by writing and deploying your own standalone API server.
+The main API server delegates requests to you for the custom resources that you handle,
+making them available to all of its clients.
+
+{% endcapture %}
+
+{% capture whatsnext %}
+* Learn how to [Extend the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/).
+* Learn how to [Extend the Kubernetes API with CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/).
+* Learn how to [Migrate a ThirdPartyResource to CustomResourceDefinition](/docs/tasks/access-kubernetes-api/migrate-third-party-resource/).
+{% endcapture %}
+
+{% include templates/concept.md %}
@@ -82,9 +82,10 @@ Currently there are several API groups in use:
   (e.g. `apiVersion: batch/v1`).  Full list of supported API groups can be seen in [Kubernetes API reference](/docs/reference/).


-There are two supported paths to extending the API.
-1. [Third Party Resources](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/extending-api.md)
-   are for users with very basic CRUD needs.
+There are two supported paths to extending the API with [custom resources](/docs/concepts/api-extension/custom-resources/):
+
+1. [CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
+   is for users with very basic CRUD needs.
 1. Coming soon: users needing the full set of Kubernetes API semantics can implement their own apiserver
   and use the [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/aggregated-api-servers.md)
   to make it seamless for clients.
@@ -154,11 +154,9 @@ kubectl delete replicaset my-repset --cascade=false
 ```

 ## Known issues
-* In 1.6, garbage collection does not support non-core resources, e.g.,
-  resources added via ThirdPartyResource or via aggregated API servers. It will
-  support non-core resources in the future. When it does, garbage collector will
-  delete objects with ownerRefereneces referring to non-existent object of a
-  valid non-core resource.
+* As of 1.7, garbage collection does not yet support
+  [custom resources](/docs/concepts/api-extension/custom-resources/),
+  such as those added through CustomResourceDefinition or aggregated API servers.

 [Other known issues](https://github.com/kubernetes/kubernetes/issues/26120)