TELCODOCS-380-day0

Author: tshwartz

modules/sandboxed-containers-building-blocks.adoc

@@ -1,6 +1,6 @@
 //Module included in the following assemblies:
 //
-// * sandboxed_containers/understanding_sandboxed_containers.adoc
+// * sandboxed_containers/understanding_sandboxed_containers-workloads.adoc
 
 [id="sandboxed-containers-building-blocks_{context}"]
 

modules/sandboxed-containers-common-terms.adoc

@@ -1,6 +1,6 @@
 //Module included in the following assemblies:
 //
-// * sandboxed_containers/understanding_sandboxed_containers.adoc
+// * sandboxed_containers/understanding_sandboxed_containers-workoads.adoc
 [id="sandboxed-containers-common-terms_{context}"]
 = {sandboxed-containers-first} common terms
 
@@ -16,12 +16,10 @@ In the context of {sandboxed-containers-first}, a pod is implemented as a virtua
 
 {sandboxed-containers-operator}:: An Operator is a software component that automates operations, which are actions that a human operator could do on the system.
 +
-The {sandboxed-containers-operator} is tasked with managing the lifecycle of sandboxed containers on a cluster. It deals with operations, such as the installation and removal of sandboxed containers software and status monitoring.
+The {sandboxed-containers-operator} is tasked with managing the lifecycle of sandboxed containers on a cluster. You can use the {sandboxed-containers-operator} to perform tasks such as the installation and removal of sandboxed containers, software updates, and status monitoring.
 
 Kata Containers:: Kata Containers is a core upstream project that is used to build {sandboxed-containers-first}. {sandboxed-containers-first} integrate Kata Containers with {product-title}.
 
 KataConfig:: `KataConfig` objects represent configurations of sandboxed containers. They store information about the state of the cluster, such as the nodes on which the software is deployed.
 
-{op-system} extensions:: {op-system-first} extensions are a mechanism to install optional {product-title} software. The {sandboxed-containers-operator} uses this mechanism to deploy sandboxed containers on a cluster.
-
 Runtime class:: A `RuntimeClass` object describes which runtime can be used to run a given workload. A runtime class that is named `kata` is installed and deployed by the {sandboxed-containers-operator}. The runtime class contains information about the runtime that describes resources that the runtime needs to operate, such as the link:https://kubernetes.io/docs/concepts/scheduling-eviction/pod-overhead/[pod overhead].

modules/sandboxed-containers-deploying-osc-with-other-ocp-components.adoc

@@ -5,7 +5,7 @@
 :_content-type: CONCEPT
 [id="sandboxed-containers-with-other-ocp-components_{context}"]
 
-= Using {sandboxed-containers-first} with {VirtProductName}
+= Virtualization and {sandboxed-containers-first}
 //= Using {sandboxed-containers-first} with other {product-title} components
 
 You can use {sandboxed-containers-first} on clusters with {VirtProductName}.

modules/sandboxed-containers-rhcos-extensions.adoc

@@ -1,10 +1,12 @@
 //Module included in the following assemblies:
 //
-// * sandboxed_containers/understanding_sandboxed_containers.adoc
+// * sandboxed_containers/understanding_sandboxed_containers-workloads.adoc
 
 :_content-type: CONCEPT
 [id="sandboxed-containers-rhcos-extensions_{context}"]
 
 = {op-system} extensions
 
-The {sandboxed-containers-operator} is based on the {op-system-first} extensions concept. The sandboxed containers {op-system} extension contains RPMs for Kata, QEMU, and its dependencies. You can enable them by using the `MachineConfig` resources that the Machine Config Operator provides.
+The {sandboxed-containers-operator} is based on the {op-system-first} extensions concept. {op-system-first} extensions are a mechanism to install optional {product-title} software. The {sandboxed-containers-operator} uses this mechanism to deploy sandboxed containers on a cluster.
+
+The sandboxed containers {op-system} extension contains RPMs for Kata, QEMU, and its dependencies. You can enable them by using the `MachineConfig` resources that the Machine Config Operator provides.

modules/sandboxed-containers-supported-platforms.adoc

@@ -0,0 +1,13 @@
+//Module included in the following assemblies:
+//
+// * sandboxed_containers/understanding_sandboxed_containers-workloads.adoc
+
+:_content-type: CONCEPT
+[id="sandboxed-containers-supported-platforms_{context}"]
+= {sandboxed-containers-first} supported platforms
+
+You can install {sandboxed-containers-first} on a bare-metal server or on an Amazon Web Services (AWS) bare-metal instance. Bare-metal instances offered by other cloud providers are not supported.
+
+{op-system-first} is the only supported operating system for {sandboxed-containers-first}. {sandboxed-containers-first} {sandboxed-containers-version} runs on {op-system-first} 8.6.
+
+{sandboxed-containers-first} {sandboxed-containers-version} is compatible with {product-title} 4.11.

sandboxed_containers/understanding-sandboxed-containers.adoc

@@ -8,32 +8,42 @@ toc::[]
 
 [role="_abstract"]
 
-{sandboxed-containers-first} support for {product-title} provides users with built-in support for running Kata Containers as an additional optional runtime. This is particularly useful for users who are wanting to perform the following tasks:
+{sandboxed-containers-first} support for {product-title} provides you with built-in support for running Kata Containers as an additional optional runtime. The new runtime supports containers in dedicated virtual machines (VMs), providing improved workload isolation. This is particularly useful for performing the following tasks:
 
-- Run privileged or untrusted workloads.
-- Ensure kernel isolation for each workload.
-- Share the same workload across tenants.
-- Ensure proper isolation and sandboxing for testing software.
-- Ensure default resource containment through VM boundaries.
+Run privileged or untrusted workloads:: {sandboxed-containers-first} (OSC) makes it possible to safely run workloads that require specific privileges, without having to risk compromising cluster nodes by running privileged containers. Workloads that require special privileges include the following:
+* Workloads that require special capabilities from the kernel, beyond the default ones granted by standard container runtimes such as CRI-O, for example to access low-level networking features.
+* Workloads that need elevated root privileges, for example to access a specific physical device. With {sandboxed-containers-first}, it is possible to pass only a specific device through to the VM, ensuring that the workload cannot access or misconfigure the rest of the system.
+* Workloads for installing or using `set-uid` root binaries. These binaries grant special privileges and, as such, can present a security risk. With {sandboxed-containers-first}, additional privileges are restricted to the virtual machines, and grant no special access to the cluster nodes.
 
-{sandboxed-containers-first} also provides users the ability to choose from the type of workload that they want to run to cover a wide variety of use cases.
++
+Some workloads may require privileges specifically for configuring the cluster nodes. Such workloads should still use privileged containers, because running on a virtual machine would prevent them from functioning.
 
-You can use the {sandboxed-containers-operator} to perform tasks such as installation and removal, updates, and status monitoring.
+Ensure kernel isolation for each workload:: {sandboxed-containers-first} supports workloads that require custom kernel tuning (such as `sysctl`, scheduler changes, or cache tuning) and the creation of custom kernel modules (such as `out of tree` or special arguments).
 
-You can install {sandboxed-containers-first} on Amazon Web Services (AWS) bare-metal instances. Bare-metal instances offered by other cloud providers are not supported.
+Share the same workload across tenants:: {sandboxed-containers-first} enables you to support multiple users (tenants) from different organizations sharing the same OpenShift cluster. The system also lets you run third-party workloads from multiple vendors, such as container network functions (CNFs) and enterprise applications. Third-party CNFs, for example, may not want their custom settings interfering with packet tuning or with `sysctl` variables set by other applications. Running inside a completely isolated kernel is helpful in preventing "noisy neighbor" configuration problems.
 
-{op-system-first} is the only supported operating system for {sandboxed-containers-first} {sandboxed-containers-version}.
+Ensure proper isolation and sandboxing for testing software:: You can use {sandboxed-containers-first} to run a containerized workload with known vulnerabilities or to handle an issue in a legacy application.  This isolation also enables administrators to give developers administrative control over pods, which is useful when the developer wants to test or validate configurations beyond those an administrator would typically grant. Administrators can, for example, safely and securely delegate kernel packet filtering (eBPF) to developers. Kernel packet filtering requires `CAP_ADMIN` or `CAP_BPF` privileges, and is therefore not allowed under a standard CRI-O configuration, as this would grant access to every process on the Container Host worker node. Similarly, administrators can grant access to intrusive tools such as SystemTap, or support the loading of custom kernel modules during their development.
 
+Ensure default resource containment through VM boundaries:: By default, resources such as CPU, memory, storage, or networking are managed in a more robust and secure way in {sandboxed-containers-first}. Since {sandboxed-containers-first} are deployed on VMs, additional layers of isolation and security give a finer-grained access control to the resource. For example, an errant container will not be able to allocate more memory than is available to the VM. Conversely, a container that needs dedicated access to a network card or to a disk can take complete control over that device without getting any access to other devices.
+
+include::modules/sandboxed-containers-supported-platforms.adoc[leveloffset=+1]
 include::modules/sandboxed-containers-common-terms.adoc[leveloffset=+1]
-include::modules/sandboxed-containers-building-blocks.adoc[leveloffset=+1]
-include::modules/sandboxed-containers-rhcos-extensions.adoc[leveloffset=+1]
+
+[id="sandboxed-containers-workload-management"]
+== {sandboxed-containers-first} workload management
+
+{sandboxed-containers-first} provides the following features for enhancing workload management and allocation:
+
+include::modules/sandboxed-containers-building-blocks.adoc[leveloffset=+2]
+include::modules/sandboxed-containers-rhcos-extensions.adoc[leveloffset=+2]
 .Additional resources
 
 * xref:../post_installation_configuration/machine-configuration-tasks.adoc#rhcos-add-extensions_post-install-machine-configuration-tasks[Adding extensions to RHCOS]
 
-include::modules/security-compliance-nist.adoc[leveloffset=+1]
-include::modules/sandboxed-containers-deploying-osc-with-other-ocp-components.adoc[leveloffset=+1]
+include::modules/sandboxed-containers-deploying-osc-with-other-ocp-components.adoc[leveloffset=+2]
 .Additional resources
 
 * xref:../virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc#virt-creating-storage-class_virt-configuring-local-storage-for-vms[Configuring local storage for virtual machines]
 * xref:../virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc#virt-configuring-vmi-eviction-strategy[Configuring virtual machine eviction strategy]
+
+include::modules/security-compliance-nist.adoc[leveloffset=+1]