Merge pull request #45888 from kquinn1204/TELCODOCS-419

Telcodocs 419: Updating Sysctl and creating section on setting interface sysctl values

Author: bergerhoffer

_topic_maps/_topic_map.yml

@@ -983,6 +983,8 @@ Topics:
   File: configuring-node-port-service-range
 - Name: Configuring IP failover
   File: configuring-ipfailover
+- Name: Configuring interface-level network sysctls
+  File: setting-interface-level-network-sysctls
 - Name: Using SCTP
   File: using-sctp
   Distros: openshift-enterprise,openshift-origin

images/264_OpenShift_CNI_plugin_chain_0622.png

@@ -0,0 +1,114 @@
+// Module included in the following assemblies:
+//
+// * nodes/containers/nodes-containers-sysctls.adoc
+
+:_content-type: PROCEDURE
+[id="nodes-starting-pod-safe-sysctls_{context}"]
+= Starting a pod with safe sysctls
+
+You can set sysctls on pods using the pod's `securityContext`. The `securityContext` applies to all containers in the same pod.
+
+Safe sysctls are allowed by default.
+
+This example uses the pod `securityContext` to set the following safe sysctls:
+
+* `kernel.shm_rmid_forced`
+* `net.ipv4.ip_local_port_range`
+* `net.ipv4.tcp_syncookies`
+* `net.ipv4.ping_group_range`
+
+[WARNING]
+====
+To avoid destabilizing your operating system, modify sysctl parameters only after you understand their effects.
+====
+
+Use this procedure to start a pod with the configured sysctl settings.
+[NOTE]
+====
+In most cases you modify an existing pod definition and add the `securityContext` spec.
+====
+
+
+.Procedure
+
+. Create a YAML file `sysctl_pod.yaml` that defines an example pod and add the `securityContext` spec, as shown in the following example:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: sysctl-example
+  namespace: default
+spec:
+  containers:
+  - name: podexample
+    image: centos
+    command: ["bin/bash", "-c", "sleep INF"]
+    securityContext:
+      runAsUser: 2000 <1>
+      runAsGroup: 3000 <2>
+      allowPrivilegeEscalation: false <3>
+      capabilities: <4>
+        drop: ["ALL"]
+  securityContext:
+    runAsNonRoot: true <5> 
+    seccompProfile: <6>
+      type: RuntimeDefault
+    sysctls:
+    - name: kernel.shm_rmid_forced
+      value: "1"
+    - name: net.ipv4.ip_local_port_range
+      value: "32770       60666"
+    - name: net.ipv4.tcp_syncookies
+      value: "0"
+    - name: net.ipv4.ping_group_range
+      value: "0           200000000"
+----
+<1> `runAsUser` controls which user ID the container is run with.
+<2> `runAsGroup` controls which primary group ID the containers is run with.
+<3> `allowPrivilegeEscalation` determines if a pod can request to allow privilege escalation. If unspecified, it defaults to true. This boolean directly controls whether the `no_new_privs` flag gets set on the container process.
+<4> `capabilities` permit privileged actions without giving full root access. This policy ensures all capabilities are dropped from the pod. 
+<5> `runAsNonRoot: true` requires that the container will run with a user with any UID other than 0. 
+<6> `RuntimeDefault` enables the default seccomp profile for a pod or container workload.
+
+. Create the pod by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f sysctl_pod.yaml
+----
++
+. Verify that the pod is created by running the following command:
++
+[source,terminal]
+----
+$ oc get pod
+----
++
+.Example output
+[source,terminal]
+----
+NAME              READY   STATUS            RESTARTS   AGE
+sysctl-example    1/1     Running           0          14s
+----
+
+. Log in to the pod by running the following command:
++
+[source,terminal]
+----
+$ oc rsh sysctl-example
+----
+
+. Verify the values of the configured sysctl flags. For example, find the value `kernel.shm_rmid_forced` by running the following command:
++
+[source,terminal]
+----
+sh-4.4# sysctl kernel.shm_rmid_forced
+----
++
+.Expected output
+[source,terminal]
+----
+kernel.shm_rmid_forced = 1
+----

images/264_OpenShift_CNI_plugin_chain_0722.png

@@ -6,94 +6,17 @@
 [id="nodes-containers-sysctls-about_{context}"]
 = About sysctls
 
-In Linux, the sysctl interface allows an administrator to modify kernel
-parameters at runtime. Parameters are available via the *_/proc/sys/_* virtual
-process file system. The parameters cover various subsystems, such as:
+In Linux, the sysctl interface allows an administrator to modify kernel parameters at runtime. Parameters are available from the `_/proc/sys/_` virtual process file system. The parameters cover various subsystems, such as:
 
-- kernel (common prefix: *_kernel._*)
-- networking (common prefix: *_net._*)
-- virtual memory (common prefix: *_vm._*)
-- MDADM (common prefix: *_dev._*)
+- kernel (common prefix: `_kernel._`)
+- networking (common prefix: `_net._`)
+- virtual memory (common prefix: `_vm._`)
+- MDADM (common prefix: `_dev._`)
 
-More subsystems are described in
-link:https://www.kernel.org/doc/Documentation/sysctl/README[Kernel documentation].
+More subsystems are described in link:https://www.kernel.org/doc/Documentation/sysctl/README[Kernel documentation].
 To get a list of all parameters, run:
 
 [source,terminal]
 ----
 $ sudo sysctl -a
-----
-
-[[namespaced-vs-node-level-sysctls]]
-== Namespaced versus node-level sysctls
-
-A number of sysctls are _namespaced_ in the Linux kernels. This means that
-you can set them independently for each pod on a node. Being namespaced is a
-requirement for sysctls to be accessible in a pod context within Kubernetes.
-
-The following sysctls are known to be namespaced:
-
-- *_kernel.shm*_*
-- *_kernel.msg*_*
-- *_kernel.sem_*
-- *_fs.mqueue.*_*
-
-Additionally, most of the sysctls in the *net.** group are known
-to be namespaced. Their namespace adoption differs based on the kernel
-version and distributor.
-
-Sysctls that are not namespaced are called _node-level_ and must be set
-manually by the cluster administrator, either by means of the underlying Linux
-distribution of the nodes, such as by modifying the *_/etc/sysctls.conf_* file,
-or by using a daemon set with privileged containers. You can use
-the Node Tuning Operator to set _node-level_ sysctls.
-
-
-[NOTE]
-====
-Consider marking nodes with special sysctls as tainted. Only schedule pods onto
-them that need those sysctl settings. Use the taints and toleration feature to mark the nodes.
-====
-
-[[safe-vs-unsafe-sysclts]]
-== Safe versus unsafe sysctls
-
-Sysctls are grouped into _safe_ and _unsafe_ sysctls.
-
-For a sysctl to be considered safe, it must use proper
-namespacing and must be properly isolated between pods on the same
-node. This means that if you set a sysctl for one pod it must not:
-
-- Influence any other pod on the node
-- Harm the node's health
-- Gain CPU or memory resources outside of the resource limits of a pod
-
-{product-title} supports, or whitelists, the following sysctls
-in the safe set:
-
-- *_kernel.shm_rmid_forced_*
-- *_net.ipv4.ip_local_port_range_*
-- *_net.ipv4.tcp_syncookies_*
-- *_net.ipv4.ping_group_range_*
-
-All safe sysctls are enabled by default. You can use a sysctl in a pod by modifying
-the `Pod` spec.
-
-Any sysctl not whitelisted by {product-title} is considered unsafe for {product-title}.
-Note that being namespaced alone is not sufficient for the sysctl to be considered safe.
-
-All unsafe sysctls are disabled by default, and the cluster administrator must
-manually enable them on a per-node basis. Pods with disabled unsafe sysctls 
-are scheduled but do not launch.
-
-[source,terminal]
-----
-$ oc get pod
-----
-
-.Example output
-[source,terminal]
-----
-NAME        READY   STATUS            RESTARTS   AGE
-hello-pod   0/1     SysctlForbidden   0          14s
-----
+----

modules/nodes-containers-start-pod-safe-sysctls.adoc

@@ -3,63 +3,63 @@
 // * nodes/containers/nodes-containers-sysctls.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-containers-sysctls-setting_{context}"]
-= Setting sysctls for a pod
+[id="nodes-containers-starting-pod-with-unsafe-sysctls_{context}"]
+= Starting a pod with unsafe sysctls
 
-You can set sysctls on pods using the pod's `securityContext`. The `securityContext`
-applies to all containers in the same pod.
+A pod with unsafe sysctls fails to launch on any node unless the cluster administrator explicitly enables unsafe sysctls for that node. As with node-level sysctls, use the taints and toleration feature or labels on nodes to schedule those pods onto the right nodes.
 
-Safe sysctls are allowed by default. A pod with unsafe sysctls fails 
-to launch on any node unless the cluster administrator explicitly enables unsafe sysctls for 
-that node. As with node-level sysctls, use the taints and toleration feature 
-or labels on nodes to schedule those pods onto the right nodes.
-
-The following example uses the pod `securityContext` to set a safe sysctl
-`kernel.shm_rmid_forced` and two unsafe sysctls, `net.core.somaxconn` and
-`kernel.msgmax`. There is no distinction between _safe_ and _unsafe_ sysctls in
-the specification.
+The following example uses the pod `securityContext` to set a safe sysctl `kernel.shm_rmid_forced` and two unsafe sysctls, `net.core.somaxconn` and `kernel.msgmax`. There is no distinction between _safe_ and _unsafe_ sysctls in the specification.
 
 [WARNING]
 ====
-To avoid destabilizing your operating system, modify sysctl parameters only 
-after you understand their effects.
+To avoid destabilizing your operating system, modify sysctl parameters only after you understand their effects.
 ====
 
-.Procedure
+The following example illustrates what happens when you add safe and unsafe sysctls to a pod specification:
 
-To use safe and unsafe sysctls:
+.Procedure
 
-. Modify the YAML file that defines the pod and add the `securityContext` spec, as
-shown in the following example:
+. Create a YAML file `sysctl-example-unsafe.yaml` that defines an example pod and add the `securityContext` specification, as shown in the following example:
 +
 [source,yaml]
 ----
 apiVersion: v1
 kind: Pod
 metadata:
-  name: sysctl-example
+  name: sysctl-example-unsafe
 spec:
+  containers:
+  - name: podexample
+    image: centos
+    command: ["bin/bash", "-c", "sleep INF"]
+    securityContext: 
+      runAsUser: 2000 
+      runAsGroup: 3000 
+      allowPrivilegeEscalation: false 
+      capabilities: 
+        drop: ["ALL"]
   securityContext:
+    runAsNonRoot: true 
+    seccompProfile: 
+      type: RuntimeDefault
     sysctls:
     - name: kernel.shm_rmid_forced
       value: "0"
     - name: net.core.somaxconn
       value: "1024"
     - name: kernel.msgmax
       value: "65536"
-  ...
 ----
 
-. Create the pod:
+. Create the pod using the following command:
 +
 [source,terminal]
 ----
-$ oc apply -f <file-name>.yaml
+$ oc apply -f sysctl-example-unsafe.yaml
 ----
-+
-If the unsafe sysctls are not allowed for the node, the pod is scheduled, 
-but does not deploy:
-+
+
+. Verify that the pod is scheduled but does not deploy because unsafe sysctls are not allowed for the node using the following command:
++  
 [source,terminal]
 ----
 $ oc get pod
@@ -68,6 +68,6 @@ $ oc get pod
 .Example output
 [source,terminal]
 ----
-NAME        READY   STATUS            RESTARTS   AGE
-hello-pod   0/1     SysctlForbidden   0          14s
+NAME                       READY             STATUS            RESTARTS   AGE
+sysctl-example-unsafe      0/1               SysctlForbidden   0          14s
 ----