OSDOCS-6836: Updating conceptual, installation, and configuration info regarding migration from cgroup v1 to cgroup v2

Author: Daniel Chadwick

_topic_maps/_topic_map.yml

@@ -507,8 +507,8 @@ Topics:
     File: installing-customizing
   - Name: Configuring your firewall
     File: configuring-firewall
-  - Name: Enabling Linux control group version 2 (cgroup v2)
-    File: enabling-cgroup-v2
+  - Name: Enabling Linux control group version 1 (cgroup v1)
+    File: enabling-cgroup-v1
     Distros: openshift-enterprise
 - Name: Validating an installation
   File: validating-an-installation

installing/install_config/enabling-cgroup-v1.adoc

@@ -0,0 +1,34 @@
+:_content-type: ASSEMBLY
+:context: nodes-cluster-cgroups-1
+[id="enabling-cgroup-v1"]
+= Enabling Linux control group version 1 (cgroup v1)
+include::_attributes/common-attributes.adoc[]
+
+toc::[]
+
+
+As of {product-title} 4.14, {product-title} uses link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster. If you are using cgroup v1 on {product-title} 4.13 or earlier, migrating to {product-title} 4.14 will not automatically update your cgroup configuration to version 2. A fresh installation of {product-title} 4.14 will use cgroup v2 by default. However, you can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[Linux control group version 1] (cgroup v1) upon installation. Enabling cgroup v1 in {product-title} disables all cgroup v2 controllers and hierarchies in your cluster. 
+
+cgroup v2 is the current version of the Linux cgroup API. cgroup v2 offers several improvements over cgroup v1, including a unified hierarchy, safer sub-tree delegation, new features such as link:https://www.kernel.org/doc/html/latest/accounting/psi.html[Pressure Stall Information], and enhanced resource management and isolation.
+
+ifndef::openshift-origin[]
+You can switch between cgroup v1 and cgroup v2, as needed, by editing the `node.config` object. For more information, see "Configuring the Linux cgroup on your nodes" in the "Additional resources" of this section.
+endif::openshift-origin[]
+
+// 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.
+
+ifndef::openshift-origin[]
+include::modules/nodes-clusters-cgroups-2-install.adoc[leveloffset=+1]
+endif::openshift-origin[]
+
+ifdef::openshift-origin[]
+include::modules/nodes-clusters-cgroups-okd-configure.adoc[leveloffset=+1]
+endif::openshift-origin[]
+
+.Additional resources
+
+* xref:../../installing/index.adoc#ocp-installation-overview[OpenShift Container Platform installation overview]
+* xref:../../nodes/clusters/nodes-cluster-cgroups-2.adoc#nodes-clusters-cgroups-2_nodes-cluster-cgroups-2[Configuring the Linux cgroup on your nodes]

installing/install_config/enabling-cgroup-v2.adoc

@@ -17,6 +17,8 @@ include::modules/installation-openstack-ovs-dpdk-requirements.adoc[leveloffset=+
 
 You must configure {rh-openstack} before you install a cluster that uses SR-IOV on it.
 
+When installing a cluster using SR-IOV, you must deploy clusters using cgroup v1. For more information, xref:../../installing/install_config/enabling-cgroup-v1.adoc#enabling-cgroup-v1[Enabling Linux control group version 1 (cgroup v1)].
+
 include::modules/installation-osp-configuring-sr-iov.adoc[leveloffset=+2]
 
 [id="installing-openstack-nfv-preparing-tasks-ovs-dpdk"]

installing/installing_openstack/installing-openstack-nfv-preparing.adoc

@@ -4,22 +4,22 @@
 
 :_content-type: PROCEDURE
 [id="nodes-clusters-cgroups-2-install_{context}"]
-= Enabling Linux cgroup v2 during installation
+= Enabling Linux cgroup v1 during installation
 
-You can enable Linux control group version 2 (cgroup v2) when you install a cluster by creating installation manifests.
+You can enable Linux control group version 1 (cgroup v1) when you install a cluster by creating installation manifests.
 
 .Procedure 
 
-. Create or edit the `node.config` object to specify the `v2` cgroup: 
+. Create or edit the `node.config` object to specify the `v1` cgroup: 
 +
 [source,yaml]
 ----
-apiVersion: config.openshift.io/v1
+apiVersion: config.openshift.io/v2
 kind: Node
 metadata:
   name: cluster
   spec:
-    cgroupMode: "v2"
+    cgroupMode: "v1"
 ----
 
 . Proceed with the installation as usual. 

modules/nodes-clusters-cgroups-2-install.adoc

@@ -15,15 +15,15 @@ endif::[]
 = Configuring Linux cgroup
 
 ifdef::post[]
-link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 1] (cgroup v1) is enabled by default. You can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster by editing the `node.config` object. Enabling cgroup v2 in {product-title} disables all cgroup version 1 controllers and hierarchies in your cluster. 
+As of {product-title} 4.14, {product-title} uses link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster. If you are using cgroup v1 on {product-title} 4.13 or earlier, migrating to {product-title} 4.14 will not automatically update your cgroup configuration to version 2. A fresh installation of {product-title} 4.14 will use cgroup v2 by default. However, you can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[Linux control group version 1] (cgroup v1) upon installation. Enabling cgroup v1 in {product-title} disables all cgroup v2 controllers and hierarchies in your cluster. 
 
-cgroup v2 is the next version of the Linux cgroup API. cgroup v2 offers several improvements over cgroup v1, including a unified hierarchy, safer sub-tree delegation, new features such as link:https://www.kernel.org/doc/html/latest/accounting/psi.html[Pressure Stall Information], and enhanced resource management and isolation.
+cgroup v2 is the current version of the Linux cgroup API. cgroup v2 offers several improvements over cgroup v1, including a unified hierarchy, safer sub-tree delegation, new features such as link:https://www.kernel.org/doc/html/latest/accounting/psi.html[Pressure Stall Information], and enhanced resource management and isolation.
 
 You can change between cgroup v1 and cgroup v2, as needed.  For more information, see "Configuring the Linux cgroup on your nodes" in the "Additional resources" of this section. 
 endif::post[]
 
 ifdef::nodes[]
-You can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1.html[Linux control group version 1] (cgroup v1) or link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2)  by editing the `node.config` object. The default is cgroup v1.
+You can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[Linux control group version 1] (cgroup v1) or link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2)  by editing the `node.config` object. The default is cgroup v2.
 endif::nodes[]
 
 [NOTE]
@@ -37,7 +37,7 @@ Currently, disabling CPU load balancing is not supported by cgroup v2. As a resu
 
 .Procedure
 
-. Enable cgroup v2 on nodes:
+. Enable cgroup v1 on nodes:
 
 .. Edit the `node.config` object:
 +
@@ -47,12 +47,12 @@ $ oc edit nodes.config/cluster
 ----
 
 ifdef::post[]
-.. Add `spec.cgroupMode: "v2"`:
+.. Add `spec.cgroupMode: "v1"`:
 +
 .Example `node.config` object
 [source,yaml]
 ----
-apiVersion: config.openshift.io/v1
+apiVersion: config.openshift.io/v2
 kind: Node
 metadata:
   annotations:
@@ -64,17 +64,17 @@ metadata:
   generation: 1
   name: cluster
   ownerReferences:
-  - apiVersion: config.openshift.io/v1
+  - apiVersion: config.openshift.io/v2
     kind: ClusterVersion
     name: version
     uid: 36282574-bf9f-409e-a6cd-3032939293eb
   resourceVersion: "1865"
   uid: 0c0f7a4c-4307-4187-b591-6155695ac85b
 spec:
-  cgroupMode: "v2" <1>
+  cgroupMode: "v1" <1>
 ...
 ----
-<1> Enables cgroup v2.
+<1> Enables cgroup v1.
 endif::post[]
 
 ifdef::nodes[]
@@ -83,7 +83,7 @@ ifdef::nodes[]
 .Example `node.config` object
 [source,yaml]
 ----
-apiVersion: config.openshift.io/v1
+apiVersion: config.openshift.io/v2
 kind: Node
 metadata:
   annotations:
@@ -95,17 +95,17 @@ metadata:
   generation: 1
   name: cluster
   ownerReferences:
-  - apiVersion: config.openshift.io/v1
+  - apiVersion: config.openshift.io/v2
     kind: ClusterVersion
     name: version
     uid: 36282574-bf9f-409e-a6cd-3032939293eb
   resourceVersion: "1865"
   uid: 0c0f7a4c-4307-4187-b591-6155695ac85b
 spec:
-  cgroupMode: "v2" <1>
+  cgroupMode: "v1" <1>
 ...
 ----
-<1> Specify `v2` to enable cgroup v2 or `v1` for cgroup v1.
+<1> Specify `v1` to enable cgroup v1 or `v2` for cgroup v2.
 endif::nodes[]
 
 .Verification
@@ -148,10 +148,10 @@ $ oc describe mc <name>
 ----
 +
 ifdef::nodes[]
-.Example output for cgroup v1
+.Example output for cgroup v2
 [source,terminal]
 ----
-apiVersion: machineconfiguration.openshift.io/v1
+apiVersion: machineconfiguration.openshift.io/v2
 kind: MachineConfig
 metadata:
   labels:
@@ -162,14 +162,14 @@ spec:
     systemd.unified_cgroup_hierarchy=0 <1>
     systemd.legacy_systemd_cgroup_controller=1 <2>
 ----
-<1> Enables cgroup v1 in systemd.
-<2> Disables cgroup v2.
+<1> Enables cgroup v2 in systemd.
+<2> Disables cgroup v1.
 +
 endif::nodes[]
-.Example output for cgroup v2
+.Example output for cgroup v1
 [source,terminal]
 ----
-apiVersion: machineconfiguration.openshift.io/v1
+apiVersion: machineconfiguration.openshift.io/v2
 kind: MachineConfig
 metadata:
   labels:
@@ -181,8 +181,8 @@ spec:
   - cgroup_no_v1="all" <2>
   - psi=1 <3>
 ----
-<1> Enables cgroup v2 in systemd.
-<2> Disables cgroup v1.
+<1> Enables cgroup v1 in systemd.
+<2> Disables cgroup v2.
 <3> Enables the Linux Pressure Stall Information (PSI) feature.
 
 . Check the nodes to see that scheduling on the nodes is disabled. This indicates that the change is being applied:
@@ -219,7 +219,7 @@ sh-4.4# chroot /host
 ----
 
 ifdef::post[]
-. Check that the `sys/fs/cgroup/cgroup2fs` file is present on your nodes. This file is created by cgroup v2:
+. Check that the `sys/fs/cgroup/cgroup2fs` file is present on your nodes. This file is created by cgroup v1:
 +
 [source,terminal]
 ----
@@ -240,16 +240,16 @@ ifdef::nodes[]
 $ stat -c %T -f /sys/fs/cgroup
 ----
 +
-.Example output for cgroup v1
+.Example output for cgroup v2
 [source,terminal]
 ----
 tmp2fs
 ----
 +
-.Example output for cgroup v2
+.Example output for cgroup v1
 [source,terminal]
 ----
-cgroup2fs
+cgroup1fs
 ----
 endif::nodes[]
 

modules/nodes-clusters-cgroups-2.adoc

@@ -16,9 +16,9 @@ ifdef::post[]
 [id="nodes-clusters-cgroups-okd-configure_{context}"]
 = Configuring the Linux cgroup version on your nodes
 
-By default, {product-title} uses link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster. You can switch to link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1.html[Linux control group version 1] (cgroup v1), if needed, by using a machine config. Enabling cgroup v1 in {product-title} disables the cgroup v2 controllers and hierarchies in your cluster.
+As of {product-title} 4.14, {product-title} uses link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster. If you are using cgroup v1 on {product-title} 4.13 or earlier, migrating to {product-title} 4.14 will not automatically update your cgroup configuration to version 2. A fresh installation of {product-title} 4.14 will use cgroup v2 by default. However, you can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[Linux control group version 1] (cgroup v1) upon installation. Enabling cgroup v1 in {product-title} disables all cgroup v2 controllers and hierarchies in your cluster. 
 
-cgroup v2 is the next version of the kernel link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/resource_management_guide/ch01[control group] and offers multiple improvements. However, it can have some unwanted effects on your nodes.
+cgroup v2 is the current version of the Linux cgroup API. cgroup v2 offers several improvements over cgroup v1, including a unified hierarchy, safer sub-tree delegation, new features such as link:https://www.kernel.org/doc/html/latest/accounting/psi.html[Pressure Stall Information], and enhanced resource management and isolation.
 endif::post[]
 
 ifdef::node[]

modules/nodes-clusters-cgroups-okd-configure.adoc

@@ -6,9 +6,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-By default, {product-title} uses link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster. You can switch to link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[Linux control group version 1] (cgroup v1), if needed, by editing the `node.config` object. Enabling cgroup v1 in {product-title} disables all cgroup version 2 controllers and hierarchies in your cluster. 
+As of {product-title} 4.14, {product-title} uses link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[Linux control group version 2] (cgroup v2) in your cluster. If you are using cgroup v1 on {product-title} 4.13 or earlier, migrating to {product-title} 4.14 will not automatically update your cgroup configuration to version 2. A fresh installation of {product-title} 4.14 will use cgroup v2 by default. However, you can enable link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[Linux control group version 1] (cgroup v1) upon installation. Enabling cgroup v1 in {product-title} disables all cgroup v2 controllers and hierarchies in your cluster. 
 
-cgroup v2 offers several improvements over cgroup v1, including a unified hierarchy, safer sub-tree delegation, new features (such as link:https://www.kernel.org/doc/html/latest/accounting/psi.html[Pressure Stall Information]), and enhanced resource management and isolation. 
+cgroup v2 is the current version of the Linux cgroup API. cgroup v2 offers several improvements over cgroup v1, including a unified hierarchy, safer sub-tree delegation, new features such as link:https://www.kernel.org/doc/html/latest/accounting/psi.html[Pressure Stall Information], and enhanced resource management and isolation.
 
 [NOTE]
 ====