From 57f4b2da606a129f24e848628dd8729bac91a8be Mon Sep 17 00:00:00 2001 From: "Tim Allclair (St. Clair)" Date: Tue, 11 Sep 2018 21:36:23 -0700 Subject: [PATCH] RuntimeClass documentation (#10102) * RuntimeClass documentation * Update runtime-class.md --- .../docs/concepts/containers/runtime-class.md | 122 ++++++++++++++++++ .../feature-gates.md | 2 + 2 files changed, 124 insertions(+) create mode 100644 content/en/docs/concepts/containers/runtime-class.md diff --git a/content/en/docs/concepts/containers/runtime-class.md b/content/en/docs/concepts/containers/runtime-class.md new file mode 100644 index 0000000000..a0fc10c95a --- /dev/null +++ b/content/en/docs/concepts/containers/runtime-class.md @@ -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 %}} diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 1537292ace..2b9e4fb439 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -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.