Merge pull request #54111 from aireilly/encapsulated-namespaces

jab-rh · web-flow · commit 3517feb6f0b6 · 2023-01-04T16:07:01.000-05:00
TELCODOCS-640 updates
diff --git a/modules/enabling-encapsulation.adoc b/modules/enabling-encapsulation.adoc
@@ -1,12 +1,17 @@
 // Module included in the following assemblies:
 //
 // * scalability_and_performance/optimizing-cpu-usage.adoc
+
 :_content-type: PROCEDURE
 [id="enabling-encapsulation_{context}"]
 = Configuring mount namespace encapsulation
 
 You can configure mount namespace encapsulation so that a cluster runs with less resource overhead.
-Because mount namespace encapsulation is a Technology Preview feature, it is disabled by default, and must be manually enabled.
+
+[NOTE]
+====
+Mount namespace encapsulation is a Technology Preview feature and it is disabled by default. To use it, you must enable the feature manually.
+====
 
 .Prerequisites
 
@@ -16,42 +21,40 @@ Because mount namespace encapsulation is a Technology Preview feature, it is dis
 
 .Procedure
 
-. Create a file called `mount_namespace_config.yaml` with the following YAML to control whether encapsulation is enabled or disabled:
+. Create a file called `mount_namespace_config.yaml` with the following YAML:
 +
 [source,yaml]
 ----
-  apiVersion: machineconfiguration.openshift.io/v1
-  kind: MachineConfig
-  metadata:
-    labels:
-      machineconfiguration.openshift.io/role: master
-    name: 99-kubens-master
-  spec:
-    config:
-      ignition:
-        version: 3.2.0
-      systemd:
-        units:
-        - enabled: true <1>
-          name: kubens.service
-  ---
-  apiVersion: machineconfiguration.openshift.io/v1
-  kind: MachineConfig
-  metadata:
-    labels:
-      machineconfiguration.openshift.io/role: worker
-    name: 99-kubens-worker
-  spec:
-    config:
-      ignition:
-        version: 3.2.0
-      systemd:
-        units:
-        - enabled: true <2>
-          name: kubens.service
-----
-<1> If `enabled` is set to true, encapsulation is in effect for all control plane nodes (in the role of `master`) .
-<2> If `enabled` is set to true, encapsulation is in effect for all compute nodes (in the role of `worker`).
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfig
+metadata:
+  labels:
+    machineconfiguration.openshift.io/role: master
+  name: 99-kubens-master
+spec:
+  config:
+    ignition:
+      version: 3.2.0
+    systemd:
+      units:
+      - enabled: true
+        name: kubens.service
+---
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfig
+metadata:
+  labels:
+    machineconfiguration.openshift.io/role: worker
+  name: 99-kubens-worker
+spec:
+  config:
+    ignition:
+      version: 3.2.0
+    systemd:
+      units:
+      - enabled: true
+        name: kubens.service
+----
 
 . Apply the mount namespace `MachineConfig` CR by running the following command:
 +
@@ -98,9 +101,9 @@ machineconfigpool.machineconfiguration.openshift.io/worker condition met
 
 .Verification
 
-To establish whether or not encapsulation is enabled, run the following commands:
+To verify encapsulation for a cluster host, run the following commands:
 
-. Open a debug shell to the cluster host.
+. Open a debug shell to the cluster host:
 +
 [source,terminal]
 ----
@@ -114,7 +117,7 @@ $ oc debug node/<node_name>
 sh-4.4# chroot /host
 ----
 
-. Check systemd mount namespace:
+. Check the systemd mount namespace:
 +
 [source,terminal]
 ----
@@ -140,7 +143,7 @@ sh-4.4# readlink /proc/$(pgrep kubelet)/ns/mnt
 mnt:[4026531840]
 ----
 
-. Check CRI-O mount namespace:
+. Check the CRI-O mount namespace:
 +
 [source,terminal]
 ----
@@ -152,9 +155,8 @@ sh-4.4# readlink /proc/$(pgrep crio)/ns/mnt
 ----
 mnt:[4026531840]
 ----
-+
-These commands return the mount namespaces associated with systemd, kubelet and the container runtime. In {product-title}, the container runtime is CRI-O.
-+
-Encapsulation is in effect if kubelet and CRI-O have a different mount namespace location to systemd.
-This is the case in the above example.
-Encapsulation is not in effect if all three namespaces are in the same mount namespace location.
+
+These commands return the mount namespaces associated with systemd, kubelet, and the container runtime. In {product-title}, the container runtime is CRI-O.
+
+Encapsulation is in effect if systemd is in a different mount namespace to kubelet and CRI-O as in the above example.
+Encapsulation is not in effect if all three processes are in the same mount namespace.
diff --git a/modules/optimizing-by-encapsulation.adoc b/modules/optimizing-by-encapsulation.adoc
@@ -1,41 +1,41 @@
 // Module included in the following assemblies:
 //
-// * scalability_and_performance/optimizing-cpu-usage
+// * scalability_and_performance/optimizing-cpu-usage.adoc
+
 :_content-type: CONCEPT
 [id="optimizing-cpu-usage_{context}"]
 = Encapsulating mount namespaces
 
 Mount namespaces are used to isolate mount points so that processes in different namespaces cannot view each others' files. Encapsulation is the process of moving Kubernetes mount namespaces to an alternative location where they will not be constantly scanned by the host operating system.
 
-The host operating system uses systemd to constantly scan all mount namespaces: both the standard Linux mounts and the numerous mounts that Kubernetes uses to operate. The current implementation of kubelet and CRI-O both use the top-level namespace for all container runtime and kubelet mountpoints. However, encapsulating these container-specific mountpoints in a private namespace reduces systemd overhead with no difference in functionality. Using a separate mount namespace for both CRI-O and kubelet can encapsulate container-specific mounts from any systemd or other host OS interaction.
+The host operating system uses systemd to constantly scan all mount namespaces: both the standard Linux mounts and the numerous mounts that Kubernetes uses to operate. The current implementation of kubelet and CRI-O both use the top-level namespace for all container runtime and kubelet mount points. However, encapsulating these container-specific mount points in a private namespace reduces systemd overhead with no difference in functionality. Using a separate mount namespace for both CRI-O and kubelet can encapsulate container-specific mounts from any systemd or other host operating system interaction.
 
 This ability to potentially achieve major CPU optimization is now available to all {product-title} administrators. Encapsulation can also improve security by storing Kubernetes-specific mount points in a location safe from inspection by unprivileged users.
 
 The following diagrams illustrate a Kubernetes installation before and after encapsulation. Both scenarios show example containers which have mount propagation settings of bidirectional, host-to-container, and none.
 
 image::before-k8s-mount-propagation.png[Before encapsulation]
 
-Here we see systemd, host OS processes, kubelet, and the container runtime sharing a single mount namespace.
+Here we see systemd, host operating system processes, kubelet, and the container runtime sharing a single mount namespace.
 
-* systemd, host OS processes, kubelet, and the container runtime each have access to and visibility of all mount points.
+* systemd, host operating system processes, kubelet, and the container runtime each have access to and visibility of all mount points.
 
-* Container 1, configured with bidirectional mount propagation, can access systemd and host mounts, kubelet and CRI-O mounts. A mount originating in Container 1, such as `/run/a` is visible to systemd, host OS processes, kubelet, container runtime, and other containers with host-to-container or bidirectional mount propagation configured (as in Container 2).
+* Container 1, configured with bidirectional mount propagation, can access systemd and host mounts, kubelet and CRI-O mounts. A mount originating in Container 1, such as `/run/a` is visible to systemd, host operating system processes, kubelet, container runtime, and other containers with host-to-container or bidirectional mount propagation configured (as in Container 2).
 
 * Container 2, configured with host-to-container mount propagation, can access systemd and host mounts, kubelet and CRI-O mounts. A mount originating in Container 2, such as `/run/b`, is not visible to any other context.
 
 * Container 3, configured with no mount propagation, has no visibility of external mount points. A mount originating in Container 3, such as `/run/c`, is not visible to any other context.
 
-
 The following diagram illustrates the system state after encapsulation.
 
 image::after-k8s-mount-propagation.png[After encapsulation]
 
-* The main systemd process is no longer devoted to unnecessary scanning of Kubernetes-specific mount points. It only monitors systemd-specific and host mountpoints.
+* The main systemd process is no longer devoted to unnecessary scanning of Kubernetes-specific mount points. It only monitors systemd-specific and host mount points.
 
-* The host OS processes can access only the systemd and host mountpoints.
+* The host operating system processes can access only the systemd and host mount points.
 
-* Using a separate mount namespace for both CRI-O and kubelet completely separates all container-specific mounts away from any systemd or other host OS interaction whatsoever.
+* Using a separate mount namespace for both CRI-O and kubelet completely separates all container-specific mounts away from any systemd or other host operating system interaction whatsoever.
 
-* The behavior of Container 1 is unchanged, except a mount it creates such as `/run/a` is no longer visible to systemd or host OS processes. It is still visible to kubelet, CRI-O, and other containers with host-to-container or bidirectional mount propagation configured (like Container 2).
+* The behavior of Container 1 is unchanged, except a mount it creates such as `/run/a` is no longer visible to systemd or host operating system processes. It is still visible to kubelet, CRI-O, and other containers with host-to-container or bidirectional mount propagation configured (like Container 2).
 
 * The behavior of Container 2 and Container 3 is unchanged.
diff --git a/modules/running-services-with-encapsulation.adoc b/modules/running-services-with-encapsulation.adoc
@@ -2,10 +2,10 @@
 //
 // * scalability_and_performance/optimizing-cpu-usage.adoc
 :_content-type: PROCEDURE
-[id="running_services_with_encapsulation_{context}"]
+[id="running-services-with-encapsulation_{context}"]
 = Running additional services in the encapsulated namespace
 
-Any monitoring tool that relies on the ability to run in the host OS and have visibility of mountpoints created by kubelet, CRI-O, or containers themselves, must enter the container mount namespace to see these mountpoints. The `kubensenter` script that comes with {product-title} executes another command inside the Kubernetes mountpoint and can be used to adapt any existing tools.
+Any monitoring tool that relies on the ability to run in the host operating system and have visibility of mount points created by kubelet, CRI-O, or containers themselves, must enter the container mount namespace to see these mount points. The `kubensenter` script that is provided with {product-title} executes another command inside the Kubernetes mount point and can be used to adapt any existing tools.
 
 The `kubensenter` script is aware of the state of the mount encapsulation feature status, and is safe to run even if encapsulation is not enabled. In that case the script executes the provided command in the default mount namespace.
 
diff --git a/modules/supporting-encapsulation.adoc b/modules/supporting-encapsulation.adoc
@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// * scalability_and_performance/optimizing-cpu-usage.adoc
+
+:_content-type: PROCEDURE
+[id="supporting-encapsulation_{context}"]
+= Inspecting encapsulated namespaces
+
+You can inspect Kubernetes-specific mount points in the cluster host operating system for debugging or auditing purposes by using the `kubensenter` script that is available in {op-system-first}.
+
+SSH shell sessions to the cluster host are in the default namespace.
+To inspect Kubernetes-specific mount points in an SSH shell prompt, you need to run the `kubensenter` script as root.
+The `kubensenter` script is aware of the state of the mount encapsulation, and is safe to run even if encapsulation is not enabled.
+
+[NOTE]
+====
+`oc debug` remote shell sessions start inside the Kubernetes namespace by default.
+You do not need to run `kubensenter` to inspect mount points when you use `oc debug`.
+====
+
+If the encapsulation feature is not enabled, the `kubensenter findmnt` and `findmnt` commands return the same output, regardless of whether they are run in an `oc debug` session or in an SSH shell prompt.
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+
+* You have logged in as a user with `cluster-admin` privileges.
+
+* You have configured SSH access to the cluster host.
+
+.Procedure
+
+. Open a remote SSH shell to the cluster host. For example:
++
+[source,terminal]
+----
+$ ssh core@<node_name>
+----
+
+. Run commands using the provided `kubensenter` script as the root user.
+To run a single command inside the Kubernetes namespace, provide the command and any arguments to the `kubensenter` script.
+For example, to run the `findmnt` command inside the Kubernetes namespace, run the following command:
++
+[source,terminal]
+----
+[core@control-plane-1 ~]$ sudo kubensenter findmnt
+----
++
+.Example output
+[source,terminal]
+----
+kubensenter: Autodetect: kubens.service namespace found at /run/kubens/mnt
+TARGET                                SOURCE                 FSTYPE     OPTIONS
+/                                     /dev/sda4[/ostree/deploy/rhcos/deploy/32074f0e8e5ec453e56f5a8a7bc9347eaa4172349ceab9c22b709d9d71a3f4b0.0]
+|                                                            xfs        rw,relatime,seclabel,attr2,inode64,logbufs=8,logbsize=32k,prjquota
+                                      shm                    tmpfs
+...
+----
+
+. To start a new interactive shell inside the Kubernetes namespace, run the `kubensenter` script without any arguments:
++
+[source,terminal]
+----
+[core@control-plane-1 ~]$ sudo kubensenter
+----
++
+.Example output
+[source,terminal]
+----
+kubensenter: Autodetect: kubens.service namespace found at /run/kubens/mnt
+----
diff --git a/modules/supporting_encapsulation.adoc b/modules/supporting_encapsulation.adoc
diff --git a/scalability_and_performance/optimizing-cpu-usage.adoc b/scalability_and_performance/optimizing-cpu-usage.adoc
@@ -13,11 +13,11 @@ include::snippets/technology-preview.adoc[]
 
 include::modules/optimizing-by-encapsulation.adoc[leveloffset=+1]
 
-include::modules/enabling_encapsulation.adoc[leveloffset=+1]
+include::modules/enabling-encapsulation.adoc[leveloffset=+1]
 
-include::modules/supporting_encapsulation.adoc[leveloffset=+1]
+include::modules/supporting-encapsulation.adoc[leveloffset=+1]
 
-include::modules/running_services_with_encapsulation.adoc[leveloffset=+1]
+include::modules/running-services-with-encapsulation.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 [id="optimizing-cpu-usage-additional-resources"]
@@ -27,4 +27,4 @@ include::modules/running_services_with_encapsulation.adoc[leveloffset=+1]
 
 * link:https://www.redhat.com/sysadmin/container-namespaces-nsenter[Manage containers in namespaces by using nsenter]
 
-* xref:../rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.html[MachineConfig]
+* xref:../rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc[MachineConfig]
