Custom resource docs

_data/concepts.yml

@@ -89,4 +89,6 @@ toc:
     - docs/concepts/policy/security-context.md
     - docs/concepts/policy/pod-security-policy.md
 
-
+- title: Extensions
+  section:
+  - docs/concepts/extensions/custom-resources.md

_data/tasks.yml

@@ -93,6 +93,7 @@ toc:
   - 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
+  - docs/tasks/access-kubernetes-api/migrate-third-party-resource.md
 
 - title: TLS
   section:

docs/concepts/extensions/custom-resources.md

@@ -0,0 +1,77 @@
+---
+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 installation of
+Kubernetes.
+
+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 it's installed, users can create and access objects in a custom resource with
+[kubectl](/docs/user-guide/kubectl-overview/) like they do for built-in resources like *pods*
+and *services*.
+
+## 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 fit especially well with custom
+resources.
+For example, the [Operator](https://coreos.com/blog/introducing-operators.html) pattern is a
+combination of a custom resource and a custom controller that 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 an
+[aggregated API server](#aggregated-api-servers).
+
+CRD is the successor to the deprecated *ThirdPartyResource* (TPR) API, and is available as of
+Kubernetes 1.7.
+
+## Aggregated API servers
+
+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).
+
+For custom resources that need specialized implementations, you can write and deploy a standalone
+API server, then make the resource available to clients of the main API server through aggregation.
+The main API server will delegate requests to you for the custom resources that you handle.
+{% endcapture %}
+
+{% capture whatsnext %}
+* 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 %}

docs/concepts/overview/kubernetes-api.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/extensions/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.

docs/concepts/workloads/controllers/garbage-collection.md

@@ -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/extensions/custom-resources/),
+  such as those added through CustomResourceDefinition or aggregated API servers.
 
 [Other known issues](https://github.com/kubernetes/kubernetes/issues/26120)
 

docs/reference/api-overview.md

@@ -65,9 +65,13 @@ Currently, there are several API groups in use:
 *  The named groups are at REST path `/apis/$GROUP_NAME/$VERSION`, and use `apiVersion: $GROUP_NAME/$VERSION`
    (for example, `apiVersion: batch/v1`).  Full list of supported API groups can be seen in [Kubernetes API reference](/docs/reference/).
 
-There is a supported path to extending the API:
-* [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/extensions/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.
 
 
 ## Enabling API groups

docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md

@@ -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/extensions/custom-resources/)
+into the Kubernetes API by creating a CustomResourceDefinition.
+{% endcapture %}
 
-## What is a CustomResourceDefinition?
+{% capture prerequisites %}
+* Read about [custom resources](/docs/concepts/extensions/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)
+When you create a new *CustomResourceDefinition* (CRD), the Kubernetes API Server
+reacts by creating a new RESTful resource path, either 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.
+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 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:
 
-`/apis/stable.example.com/v1/namespaces/<namespace>/crontabs/...`
+```
+/apis/stable.example.com/v1/namespaces/<namespace>/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 we 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 we 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,14 @@ 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
+
+Custom objects support finalizers. If you add a `metadata.finalizers` stanza like:
 
 ```yaml
 apiVersion: "stable.example.com/v1"
@@ -156,7 +161,18 @@ 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
+Then when the objects 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.
+This allows cleanup for custom objects similar to built-in objects.
+{% endcapture %}
+
+{% capture whatsnext %}
+* Learn how to [Migrate from ThirdPartyResource to CustomResourceDefinition](/docs/tasks/access-kubernetes-api/migrate-third-party-resource/).
+{% endcapture %}
+
+{% include templates/task.md %}
+
+
+
+