RuntimeClass documentation (#10102)

* RuntimeClass documentation * Update runtime-class.md
2018-09-11 21:36:23 -07:00
parent 9a7a295d92
commit 57f4b2da60
2 changed files with 124 additions and 0 deletions
@@ -0,0 +1,122 @@
+---
+reviewers:
+- tallclair
+- dchen1107
+title: Runtime Class
+content_template: templates/concept
+weight: 20
+---
+
+{{% capture overview %}}
+
+{{< feature-state for_k8s_version="v1.12" state="alpha" >}}
+
+This page describes the RuntimeClass resource and runtime selection mechanism.
+
+{{% /capture %}}
+
+{{< toc >}}
+
+{{% capture body %}}
+
+## Runtime Class
+
+RuntimeClass is an alpha feature 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
+
+#### 1. Enable the RuntimeClass feature gate
+
+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.
+
+#### 2. Install the RuntimeClass CRD
+
+The RuntimeClass [CustiomResourceDefinition][] (CRD) can be found in the addons directory of the
+Kubernetes git repo:
+
+https://github.com/kubernetes/kubernetes/tree/release-1.12/cluster/addons/runtimeclass/runtimeclass_crd.yaml
+
+Install the CRD with `kubectl apply -f runtimeclass_crd.yaml`.
+
+[CustiomResourceDefinition]: /docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions
+
+#### 3. 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.
+
+{{< note >}}
+**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/)).
+{{< /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).
+
+#### 4. 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 RuntimeClass resource currently only has 2 significant fields: the RuntimeClass name
+(`metadata.name`) and the RuntimeHandler (`spec.runtimeHandler`). The object definition looks like this:
+
+```yaml
+apiVersion: node.k8s.io/v1alpha1  # 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 correpsonding CRI configuration
+```
+
+
+{{< note >}}
+
+**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
+Overview](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) for more details.
+
+{{< /note >}}
+
+### Usage
+
+Once RuntimeClasses are configured for the cluster, using them is very simple. Specify a
+`runtimeClassName` in the Pod spec. For example:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: mypod
+spec:
+  runtimeClassName: myclass
+  # ...
+```
+
+This will instruct the Kubelet to use the named RuntimeClass to run this pod. If the named
+RuntimeClass does not exist, or the CRI cannot run the corresponding handler, the pod will enter the
+`Failed` terminal [phase](/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase). Look for a
+corresponding [event](/docs/tasks/debug-application-cluster/debug-application-introspection/) for an
+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.
+
+{{% /capture %}}
@@ -92,6 +92,7 @@ different Kubernetes components.
 | `RotateKubeletClientCertificate` | `true` | Beta | 1.7 | |
 | `RotateKubeletServerCertificate` | `false` | Alpha | 1.7 | |
 | `RunAsGroup` | `false` | Alpha | 1.10 | |
+| `RuntimeClass` | `false` | Alpha | 1.12 | |
 | `ServiceNodeExclusion` | `false` | Alpha | 1.8 | |
 | `StorageObjectInUseProtection` | `true` | Beta | 1.10 | 1.10 |
 | `StorageObjectInUseProtection` | `true` | GA | 1.11 | |
@@ -235,6 +236,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `RotateKubeletServerCertificate`: Enable the rotation of the server TLS certificate on the kubelet.
  See [kubelet configuration](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#kubelet-configuration) for more details.
 - `RunAsGroup`: Enable control over the primary group ID set on the init processes of containers.
+- `RuntimeClass`: Enable the [RuntimeClass](/docs/concepts/containers/runtime-class/) feature for selecting container runtime configurations.
 - `ScheduleDaemonSetPods`: Enable DaemonSet Pods to be scheduled by the default scheduler instead of the DaemonSet controller.
 - `ServiceNodeExclusion`: Enable the exclusion of nodes from load balancers created by a cloud provider.
  A node is eligible for exclusion if annotated with "`alpha.service-controller.kubernetes.io/exclude-balancer`" key.