Update RuntimeClass documentation for beta

content/en/docs/concepts/containers/runtime-class.md

@@ -9,7 +9,7 @@ weight: 20
 
 {{% capture overview %}}
 
-{{< feature-state for_k8s_version="v1.12" state="alpha" >}}
+{{< feature-state for_k8s_version="v1.14" state="beta" >}}
 
 This page describes the RuntimeClass resource and runtime selection mechanism.
 
@@ -20,72 +20,61 @@ This page describes the RuntimeClass resource and runtime selection mechanism.
 
 ## Runtime Class
 
-RuntimeClass is an alpha feature for selecting the container runtime configuration to use to run a
-pod's containers.
+RuntimeClass is a beta feature (as of v1.14) for selecting the container runtime configuration to
+use to run a pod's containers.
 
-### Set Up
-
-As an early alpha feature, there are some additional setup steps that must be taken in order to use
-the RuntimeClass feature:
-
-1. Enable the RuntimeClass feature gate (on apiservers & kubelets, requires version 1.12+)
-2. Install the RuntimeClass CRD
-3. Configure the CRI implementation on nodes (runtime dependent)
-4. Create the corresponding RuntimeClass resources
+{{< warning >}} RuntimeClass includes *breaking* changes in the beta upgrade in v1.14. If you were
+using RuntimeClass prior to v1.14, the following actions are required:
 
-#### 1. Enable the RuntimeClass feature gate
+- The `node.k8s.io` API group and `runtimeclasses.node.k8s.io` resource have been migrated to a
+ built-in API. RuntimeClass resources must be recreated *after* upgrading to v1.14, and the
+ runtimeclasses.node.k8s.io CRD should be manually deleted.
+- The `spec.runtimeHandler` field in v1aplha1 has been renamed to `handler` (no more `spec`). The
+ handler is now a required field. Handlers can no longer include `.` characters.
 
-See [Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/) for an explanation
-of enabling feature gates. The `RuntimeClass` feature gate must be enabled on apiservers _and_
-kubelets.
+{{< /warning >}}
 
-#### 2. Install the RuntimeClass CRD
-
-The RuntimeClass [CustomResourceDefinition][] (CRD) can be found in the addons directory of the
-Kubernetes git repo: [kubernetes/cluster/addons/runtimeclass/runtimeclass_crd.yaml][runtimeclass_crd]
-
-Install the CRD with `kubectl apply -f runtimeclass_crd.yaml`.
+### Set Up
 
-[CustomResourceDefinition]: /docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
-[runtimeclass_crd]: https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/runtimeclass/runtimeclass_crd.yaml
+Prerequisite: Ensure the RuntimeClass feature gate is enabled (it is by default). See [Feature
+Gates](/docs/reference/command-line-tools-reference/feature-gates/) for an explanation of enabling
+feature gates. The `RuntimeClass` feature gate must be enabled on apiservers _and_ kubelets.
 
+1. Configure the CRI implementation on nodes (runtime dependent)
+2. Create the corresponding RuntimeClass resources
 
-#### 3. Configure the CRI implementation on nodes
+#### 1. Configure the CRI implementation on nodes
 
-The configurations to select between with RuntimeClass are CRI implementation dependent. See the
-corresponding documentation for your CRI implementation for how to configure. As this is an alpha
-feature, not all CRIs support multiple RuntimeClasses yet.
+The configurations available through RuntimeClass are CRI implementation dependent. See the
+corresponding documentation ([below](#cri-documentaiton)) for your CRI implementation for how to configure.
 
 {{< note >}}
-RuntimeClass currently assumes a homogeneous node configuration across the cluster
-(which means that all nodes are configured the same way with respect to container runtimes). Any heterogeneity (varying configurations) must be
-managed independently of RuntimeClass through scheduling features (see [Assigning Pods to
-Nodes](/docs/concepts/configuration/assign-pod-node/)).
+RuntimeClass currently assumes a homogeneous node configuration across the cluster (which means that
+all nodes are configured the same way with respect to container runtimes). Any heterogeneity
+(varying configurations) must be managed independently of RuntimeClass through scheduling features
+(see [Assigning Pods to Nodes](/docs/concepts/configuration/assign-pod-node/)).
 {{< /note >}}
 
-The configurations have a corresponding `RuntimeHandler` name, referenced by the RuntimeClass. The
-RuntimeHandler must be a valid DNS 1123 subdomain (alpha-numeric + `-` and `.` characters).
+The configurations have a corresponding `handler` name, referenced by the RuntimeClass. The
+handler must be a valid DNS 1123 label (alpha-numeric + `-` characters).
 
-#### 4. Create the corresponding RuntimeClass resources
+#### 2. Create the corresponding RuntimeClass resources
 
-The configurations setup in step 3 should each have an associated `RuntimeHandler` name, which
-identifies the configuration. For each RuntimeHandler (and optionally the empty `""` handler),
-create a corresponding RuntimeClass object.
+The configurations setup in step 1 should each have an associated `handler` name, which identifies
+the configuration. For each handler, create a corresponding RuntimeClass object.
 
 The RuntimeClass resource currently only has 2 significant fields: the RuntimeClass name
-(`metadata.name`) and the RuntimeHandler (`spec.runtimeHandler`). The object definition looks like this:
+(`metadata.name`) and the handler (`handler`). The object definition looks like this:
 
 ```yaml
-apiVersion: node.k8s.io/v1alpha1 # RuntimeClass is defined in the node.k8s.io API group
+apiVersion: node.k8s.io/v1beta1 # RuntimeClass is defined in the node.k8s.io API group
 kind: RuntimeClass
 metadata:
  name: myclass # The name the RuntimeClass will be referenced by
  # RuntimeClass is a non-namespaced resource
-spec:
- runtimeHandler: myconfiguration # The name of the corresponding CRI configuration
+handler: myconfiguration # The name of the corresponding CRI configuration
 ```
 
-
 {{< note >}}
 It is recommended that RuntimeClass write operations (create/update/patch/delete) be
 restricted to the cluster administrator. This is typically the default. See [Authorization
@@ -116,4 +105,38 @@ error message.
 If no `runtimeClassName` is specified, the default RuntimeHandler will be used, which is equivalent
 to the behavior when the RuntimeClass feature is disabled.
 
+### CRI Configuration
+
+For more details on setting up CRI runtimes, see [CRI installation](/docs/setup/cri/).
+
+#### dockershim
+
+Kubernete's built-in dockershim CRI does not support runtime handlers.
+
+#### [containerd](https://containerd.io/)
+
+Runtime handlers are configured through containerd's configuration at
+`/etc/containerd/config.toml`. Valid handlers are configured under the runtimes section:
+
+```
+[plugins.cri.containerd.runtimes.${HANDLER_NAME}]
+```
+
+See containerd's config documentation for more details:
+https://github.com/containerd/cri/blob/master/docs/config.md
+
+#### [cri-o](https://cri-o.io/)
+
+Runtime handlers are configured through cri-o's configuration at `/etc/crio/crio.conf`. Valid
+handlers are configured under the [crio.runtime
+table](https://github.com/kubernetes-sigs/cri-o/blob/master/docs/crio.conf.5.md#crioruntime-table):
+
+```
+[crio.runtime.runtimes.${HANDLER_NAME}]
+ runtime_path = "${PATH_TO_BINARY}"
+```
+
+See cri-o's config documentation for more details:
+https://github.com/kubernetes-sigs/cri-o/blob/master/cmd/crio/config.go
+
 {{% /capture %}}