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

reviewers, title, content_template, weight

reviewers	title	content_template	weight
tallclair dchen1107	RuntimeClass	templates/concept	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 %}}

RuntimeClass

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 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 [CustomResourceDefinition][/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/] (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.

[CustomResourceDefinition][/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/]

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 >}} 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). {{< /note >}}

The configurations have a corresponding RuntimeHandler name, referenced by the RuntimeClass. The RuntimeHandler must be a valid DNS-1123 subdomain (alpha-numeric characters, -, or .).

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:

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 >}} 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 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:

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. Look for a corresponding event 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 %}}