Merge pull request #50502 from mburke5678/nodes-crun-tech-preview

OSDOCS3978: Tech preview of Crun in openshift

Author: mburke5678

_topic_maps/_topic_map.yml

@@ -2048,7 +2048,7 @@ Topics:
 - Name: Working with containers
   Dir: containers
   Topics:
-  - Name: Using containers
+  - Name: Understanding containers
     File: nodes-containers-using
   - Name: Using Init Containers to perform tasks before a pod is deployed
     File: nodes-containers-init

modules/about-crio.adoc

@@ -6,6 +6,6 @@
 [id="about-crio_{context}"]
 = About CRI-O container runtime engine
 
-CRI-O is a Kubernetes-native container runtime implementation that integrates closely with the operating system to deliver an efficient and optimized Kubernetes experience. CRI-O provides facilities for running, stopping, and restarting containers.
+include::snippets/about-crio-snippet.adoc[]
 
-The CRI-O container runtime engine is managed using a systemd service on each {product-title} cluster node. When container runtime issues occur, verify the status of the `crio` systemd service on each node. Gather CRI-O journald unit logs from nodes that manifest container runtime issues.
+When container runtime issues occur, verify the status of the `crio` systemd service on each node. Gather CRI-O journald unit logs from nodes that have container runtime issues.

modules/architecture-machine-roles.adoc

@@ -40,7 +40,12 @@ The `kubelet` service must not be newer than `kube-apiserver`, and can be up to
 [id="defining-workers_{context}"]
 == Cluster workers
 
-In a Kubernetes cluster, the worker nodes are where the actual workloads requested by Kubernetes users run and are managed. The worker nodes advertise their capacity and the scheduler, which is part of the master services, determines on which nodes to start containers and pods. Important services run on each worker node, including CRI-O, which is the container engine, Kubelet, which is the service that accepts and fulfills requests for running and stopping container workloads, and a service proxy, which manages communication for pods across workers.
+In a Kubernetes cluster, the worker nodes are where the actual workloads requested by Kubernetes users run and are managed. The worker nodes advertise their capacity and the scheduler, which a control plane service, determines on which nodes to start pods and containers. Important services run on each worker node, including CRI-O, which is the container engine; Kubelet, which is the service that accepts and fulfills requests for running and stopping container workloads; a service proxy, which manages communication for pods across workers; and the runC or crun (Technology Preview) low-level container runtime, which creates and runs containers.
+
+[NOTE]
+====
+For information about how to enable crun instead of the default runC, see the documentation for creating a `ContainerRuntimeConfig` CR.
+====
 
 In {product-title}, machine sets control the worker machines. Machines with the worker role drive compute workloads that are governed by a specific machine pool that autoscales them. Because {product-title} has the capacity to support multiple machine types, the worker machines are classed as _compute_ machines. In this release, the terms _worker machine_ and _compute machine_ are used interchangeably because the only default type of compute machine is the worker machine. In future versions of {product-title}, different types of compute machines, such as infrastructure machines, might be used by default.
 

modules/create-a-containerruntimeconfig-crd.adoc

@@ -19,7 +19,11 @@ You can modify the following settings by using a `ContainerRuntimeConfig` CR:
 * **Log level**: The `logLevel` parameter sets the CRI-O `log_level` parameter, which is the level of verbosity for log messages. The default is `info` (`log_level = info`). Other options include `fatal`, `panic`, `error`, `warn`, `debug`, and `trace`.
 * **Overlay size**: The `overlaySize` parameter sets the CRI-O Overlay storage driver `size` parameter, which is the maximum size of a container image.
 * **Maximum log size**: The `logSizeMax` parameter sets the CRI-O `log_size_max` parameter, which is the maximum size allowed for the container log file. The default is unlimited (`log_size_max = -1`). If set to a positive number, it must be at least 8192 to not be smaller than  the ConMon read buffer. ConMon is a program that
-monitors communications between a container manager (such as Podman or CRI-O) and the OCI runtime (such as runc or crun) for a single container.
+monitors communications between a container manager, such as Podman or CRI-O, and the OCI runtime, such as runC or crun, for a single container.
+* **Container runtime**: The `defaultRuntime` parameter sets the container runtime to either `runc` or `crun`. The default is `runc`.
+
+:FeatureName: Support for the crun container runtime
+include::snippets/technology-preview.adoc[]
 
 You should have one `ContainerRuntimeConfig` CR for each machine config pool with all the config changes you want for that pool. If you are applying the same content to all the pools, you only need one `ContainerRuntimeConfig` CR for all the pools.
 
@@ -87,13 +91,24 @@ spec:
    logLevel: debug <3>
    overlaySize: 8G <4>
    logSizeMax: "-1" <5>
+   defaultRuntime: "crun" <6>
 ----
 <1> Specifies the machine config pool label.
 <2> Optional: Specifies the maximum number of processes allowed in a container.
 <3> Optional: Specifies the level of verbosity for log messages.
 <4> Optional: Specifies the maximum size of a container image.
 <5> Optional: Specifies the maximum size allowed for the container log file. If
 	set to a positive number, it must be at least 8192.
+<6> Optional: Specifies the container runtime to deploy to new containers. The default is `runc`.
+
+.Prerequisite
+
+* To enable crun, you must enable the `TechPreviewNoUpgrade` feature set.
++
+[NOTE]
+====
+Enabling the `TechPreviewNoUpgrade` feature set cannot be undone and prevents minor version updates. These feature sets are not recommended on production clusters.
+====
 
 .Procedure
 

modules/rhcos-about.adoc

@@ -24,14 +24,19 @@ The following list describes key features of the {op-system} operating system:
 * **Controlled immutability**: Although it contains {op-system-base} components, {op-system} is designed to be managed more tightly than a default {op-system-base} installation. Management is performed remotely from the {product-title} cluster. When you set up your {op-system} machines, you can modify only a few system settings. This controlled immutability allows {product-title} to store the latest state of {op-system} systems in the cluster so it is always able to create additional machines and perform updates based on the latest {op-system} configurations.
 
 * **CRI-O container runtime**: Although {op-system} contains features for running the OCI- and libcontainer-formatted containers that Docker requires, it incorporates the CRI-O container engine instead of the Docker container engine. By focusing on features needed by Kubernetes platforms, such as {product-title}, CRI-O can offer specific compatibility with different Kubernetes versions. CRI-O also offers a smaller footprint and reduced attack surface than is possible with container engines that offer a larger feature set. At the moment, CRI-O is the only engine available within {product-title} clusters.
++
+CRI-O can use either the runC or crun container runtime to start and manage containers. For information about how to enable crun, see the documentation for creating a `ContainerRuntimeConfig` CR. 
+
+:FeatureName: Support for the crun container runtime
+include::snippets/technology-preview.adoc[leveloffset=+1]
 
 * **Set of container tools**: For tasks such as building, copying, and otherwise managing containers, {op-system} replaces the Docker CLI tool with a compatible set of container tools. The podman CLI tool supports many container runtime features, such as running, starting, stopping, listing, and removing containers and container images. The skopeo CLI tool can copy, authenticate, and sign images. You can use the `crictl` CLI tool to work with containers and pods from the CRI-O container engine. While direct use of these tools in {op-system} is discouraged, you can use them for debugging purposes.
 
 * **rpm-ostree upgrades**: {op-system} features transactional upgrades using the `rpm-ostree` system. Updates are delivered by means of container images and are part of the {product-title} update process. When deployed, the container image is pulled, extracted, and written to disk, then the bootloader is modified to boot into the new version. The machine will reboot into the update in a rolling manner to ensure cluster capacity is minimally impacted.
 
 * **bootupd firmware and bootloader updater**: Package managers and hybrid systems such as `rpm-ostree` do not update the firmware or the bootloader. With `bootupd`, {op-system} users have access to a cross-distribution, system-agnostic update tool that manages firmware and boot updates in UEFI and legacy BIOS boot modes that run on modern architectures, such as x86_64, ppc64le, and aarch64.
 +
-For information about how to install `bootupd`, see the documentation for _Updating the bootloader using bootupd_ for more information.
+For information about how to install `bootupd`, see the documentation for _Updating the bootloader using bootupd_.
 
 * **Updated through the Machine Config Operator**: In {product-title}, the Machine Config Operator handles operating system upgrades. Instead of upgrading individual packages, as is done with `yum` upgrades, `rpm-ostree` delivers upgrades of the OS as an atomic unit. The new OS deployment is staged during upgrades and goes into effect on the next reboot. If something goes wrong with the upgrade, a single rollback and reboot returns the system to the previous state. {op-system} upgrades in {product-title} are performed during cluster updates.
 

nodes/containers/nodes-containers-using.adoc

@@ -25,7 +25,6 @@ for years. {product-title} and
 Kubernetes add the ability to orchestrate containers across
 multi-host installations.
 
-[discrete]
 [id="nodes-containers-memory"]
 == About containers and RHEL kernel memory
 
@@ -40,9 +39,38 @@ To avoid losing containers due to kernel memory issues, ensure that the containe
 $(nproc) X 1/2 MiB
 ----
 
+[id="nodes-containers-runtimes"]
+== About the container engine and container runtime
 
+A _container engine_ is a piece of software that processes user requests, including command line options and image pulls. The container engine uses a _container runtime_, also called a _lower-level container runtime_, to run and manage the components required to deploy and operate containers. You likely will not need to interact with the container engine or container runtime.  
+
+[NOTE]
+====
+The {product-title} documentation uses the term _container runtime_ to refer to the lower-level container runtime. Other documentation can refer to the container engine as the container runtime.
+====
+
+{product-title} uses CRI-O as the container engine and runC or crun as the container runtime. The default container runtime is runC. Both container runtimes adhere to the link:https://www.opencontainers.org/[Open Container Initiative (OCI)] runtime specifications. 
+
+include::snippets/about-crio-snippet.adoc[]
+
+runC, developed by Docker and maintained by the Open Container Project, is a lightweight, portable container runtime written in Go. crun, developed by Red Hat, is a fast and low-memory container runtime fully written in C. As of {product-title} {product-version}, you can select between the two.
+
+:FeatureName: crun container runtime support
+include::snippets/technology-preview.adoc[]
+
+crun has several improvements over runC, including:
+
+* Smaller binary
+* Quicker processing
+* Lower memory footprint
+
+runC has some benefits over crun, including:
+
+* Most popular OCI container runtime.
+* Longer tenure in production.
+* Default container runtime of CRI-O.
+
+You can move between the two container runtimes as needed.
+
+For information on setting which container runtime to use, see xref:../../post_installation_configuration/machine-configuration-tasks.html#create-a-containerruntimeconfig_post-install-machine-configuration-tasks[Creating a `ContainerRuntimeConfig` CR to edit CRI-O parameters].
 
-// The following include statements pull in the module files that comprise
-// the assembly. Include any combination of concept, procedure, or reference
-// modules required to cover the user story. You can also include other
-// assemblies.

snippets/about-crio-snippet.adoc

@@ -0,0 +1,8 @@
+// Text snippet included in the following modules:
+//
+// * modules/about-crio.adoc
+// * modules/nodes-containers-using.adoc
+
+:_content-type: SNIPPET
+
+CRI-O is a Kubernetes-native container engine implementation that integrates closely with the operating system to deliver an efficient and optimized Kubernetes experience. The CRI-O container engine runs as a systemd service on each {product-title} cluster node.