diff --git a/modules/nodes-containers-port-forwarding-about.adoc b/modules/nodes-containers-port-forwarding-about.adoc index 74c14e200f14..b3434a60a165 100644 --- a/modules/nodes-containers-port-forwarding-about.adoc +++ b/modules/nodes-containers-port-forwarding-about.adoc @@ -6,20 +6,19 @@ [id="nodes-containers-port-forwarding-about_{context}"] = Understanding port forwarding -You can use the CLI to forward one or more local ports to a pod. This allows you -to listen on a given or random port locally, and have data forwarded to and from -given ports in the pod. +[role="_abstract"] +You can use the {oc-first} to forward one or more local ports to a pod. This allows you to listen on a given or random port locally, and have data forwarded to and from given ports in the pod. -Support for port forwarding is built into the CLI: +You can use a command similar to the following to forward one or more local ports to a pod. [source,terminal] ---- $ oc port-forward [:] [...[:]] ---- -The CLI listens on each local port specified by the user, forwarding using the protocol described below. +The {oc-first} listens on each local port specified by the user, forwarding using the protocol described below. -Ports may be specified using the following formats: +You can specify ports by using the following formats: [horizontal] `5000`:: The client listens on port 5000 locally and forwards to 5000 in the diff --git a/modules/nodes-containers-port-forwarding-protocol.adoc b/modules/nodes-containers-port-forwarding-protocol.adoc index 188cf044120f..9984cb57c1a7 100644 --- a/modules/nodes-containers-port-forwarding-protocol.adoc +++ b/modules/nodes-containers-port-forwarding-protocol.adoc @@ -6,21 +6,25 @@ [id="nodes-containers-port-forwarding-protocol_{context}"] = Protocol for initiating port forwarding from a client -Clients initiate port forwarding to a pod by issuing a request to the -Kubernetes API server: +[role="_abstract"] +A client resource in your cluster can initiate port forwarding to a pod by issuing a request to the Kubernetes API server. +Use a request in the following format: + +[source,terminal] ---- /proxy/nodes//portForward// ---- +where: -In the above URL: - -- `` is the FQDN of the node. -- `` is the namespace of the target pod. -- `` is the name of the target pod. - -For example: +-- +``:: Specifies the FQDN of the node. +``:: Specifies the namespace of the target pod. +``:: Specifies the name of the target pod. +-- +.Example request +[source,terminal] ---- /proxy/nodes/node123.openshift.com/portForward/myns/mypod ---- diff --git a/modules/nodes-containers-port-forwarding-using.adoc b/modules/nodes-containers-port-forwarding-using.adoc index 05243ca710be..3211163c74dc 100644 --- a/modules/nodes-containers-port-forwarding-using.adoc +++ b/modules/nodes-containers-port-forwarding-using.adoc @@ -6,20 +6,19 @@ [id="nodes-containers-port-forwarding-using_{context}"] = Using port forwarding -You can use the CLI to port-forward one or more local ports to a pod. +[role="_abstract"] +You can use the {oc-first} to port-forward one or more local ports to a pod. .Procedure -Use the following command to listen on the specified port in a pod: - +* Use a command similar to the following to listen on the specified port in a pod: ++ [source,terminal] ---- $ oc port-forward [:] [...[:]] ---- - -For example: - -* Use the following command to listen on ports `5000` and `6000` locally and forward data to and from ports `5000` and `6000` in the pod: ++ +For example, use the following command to listen on ports `5000` and `6000` locally and forward data to and from ports `5000` and `6000` in the pod: + [source,terminal] ---- @@ -34,8 +33,8 @@ Forwarding from [::1]:5000 -> 5000 Forwarding from 127.0.0.1:6000 -> 6000 Forwarding from [::1]:6000 -> 6000 ---- - -* Use the following command to listen on port `8888` locally and forward to `5000` in the pod: ++ +For example, use the following command to listen on port `8888` locally and forward to `5000` in the pod: + [source,terminal] ---- @@ -48,8 +47,8 @@ $ oc port-forward 8888:5000 Forwarding from 127.0.0.1:8888 -> 5000 Forwarding from [::1]:8888 -> 5000 ---- - -* Use the following command to listen on a free port locally and forward to `5000` in the pod: ++ +For example, use the following command to listen on a free port locally and forward to `5000` in the pod: + [source,terminal] ---- @@ -63,7 +62,7 @@ Forwarding from 127.0.0.1:42390 -> 5000 Forwarding from [::1]:42390 -> 5000 ---- + -Or: +Alternatively, use the following command to listen on a free port locally and forward to `5000` in the pod: + [source,terminal] ---- diff --git a/modules/nodes-containers-remote-commands-about.adoc b/modules/nodes-containers-remote-commands-about.adoc index 8e50c2bea5b2..17cbb4ac02ca 100644 --- a/modules/nodes-containers-remote-commands-about.adoc +++ b/modules/nodes-containers-remote-commands-about.adoc @@ -6,30 +6,31 @@ [id="nodes-containers-remote-commands-about_{context}"] = Executing remote commands in containers -Support for remote container command execution is built into the CLI. +[role="_abstract"] +You can use the {oc-first} to execute remote commands in {product-title} containers. By running commands in a container, you can perform troubleshooting, inspect logs, run scripts, and other tasks. .Procedure -To run a command in a container: - +* Use a command similar to the following to run a command in a container: ++ [source,terminal] ---- $ oc exec [-c ] -- [ ... ] ---- - ++ For example: - ++ [source,terminal] ---- $ oc exec mypod date ---- - ++ .Example output [source,terminal] ---- Thu Apr 9 02:21:53 UTC 2015 ---- - ++ [IMPORTANT] ==== link:https://access.redhat.com/errata/RHSA-2015:1650[For security purposes], the diff --git a/modules/nodes-containers-remote-commands-protocol.adoc b/modules/nodes-containers-remote-commands-protocol.adoc index 49626ce0c88e..0fb2af021066 100644 --- a/modules/nodes-containers-remote-commands-protocol.adoc +++ b/modules/nodes-containers-remote-commands-protocol.adoc @@ -6,35 +6,37 @@ [id="nodes-containers-remote-commands-protocol_{context}"] = Protocol for initiating a remote command from a client -Clients initiate the execution of a remote command in a container by issuing a -request to the Kubernetes API server: +[role="_abstract"] +A client resource in your cluster can initiate the execution of a remote command in a container by issuing a request to the Kubernetes API server. + +The following example is the format for a typical request to a Kubernetes API server: [source,terminal] ---- /proxy/nodes//exec///?command= ---- +where: -In the above URL: - -- `` is the FQDN of the node. -- `` is the project of the target pod. -- `` is the name of the target pod. -- `` is the name of the target container. -- `` is the desired command to be executed. - -For example: +-- +``:: Specifies the FQDN of the node. +``:: Specifies the project of the target pod. +``:: Specifies the name of the target pod. +``:: Specifies the name of the target container. +``:: Specifies the desired command to be executed. +-- +.Example request [source,terminal] ---- /proxy/nodes/node123.openshift.com/exec/myns/mypod/mycontainer?command=date ---- -Additionally, the client can add parameters to the request to indicate if: +Additionally, the client can add parameters to the request to indicate any of the following conditions: -- the client should send input to the remote container's command (stdin). -- the client's terminal is a TTY. -- the remote container's command should send output from stdout to the client. -- the remote container's command should send output from stderr to the client. +* The client should send input to the remote container's command (stdin). +* The client's terminal is a TTY. +* The remote container's command should send output from stdout to the client. +* The remote container's command should send output from stderr to the client. After sending an `exec` request to the API server, the client upgrades the connection to one that supports multiplexed streams; the current implementation diff --git a/modules/nodes-containers-start-pod-safe-sysctls.adoc b/modules/nodes-containers-start-pod-safe-sysctls.adoc index e2487ba991c9..f553909294d1 100644 --- a/modules/nodes-containers-start-pod-safe-sysctls.adoc +++ b/modules/nodes-containers-start-pod-safe-sysctls.adoc @@ -6,7 +6,8 @@ [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. +[role="_abstract"] +You can modify kernel parameters for all containers in a pod by adding the sysctls parameter to the `securityContext` parameter in a pod spec. Safe sysctls are allowed by default. @@ -22,7 +23,8 @@ This example uses the pod `securityContext` to set the following safe sysctls: 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. +The following procedure shows how to start a pod with the configured sysctl settings. + [NOTE] ==== In most cases you modify an existing pod definition and add the `securityContext` spec. @@ -46,14 +48,14 @@ spec: image: centos command: ["bin/bash", "-c", "sleep INF"] securityContext: - runAsUser: 2000 <1> - runAsGroup: 3000 <2> - allowPrivilegeEscalation: false <3> - capabilities: <4> + runAsUser: 2000 + runAsGroup: 3000 + allowPrivilegeEscalation: false + capabilities: drop: ["ALL"] securityContext: - runAsNonRoot: true <5> - seccompProfile: <6> + runAsNonRoot: true + seccompProfile: type: RuntimeDefault sysctls: - name: kernel.shm_rmid_forced @@ -65,12 +67,14 @@ spec: - 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. +where: + +`spec.containers.securityContext.runAsUser`:: Specifies which user ID the container is run with. +`spec.containers.securityContext.runAsGroup`:: Specifies which primary group ID the containers is run with. +`spec.containers.securityContext.allowPrivilegeEscalation`:: Specifies whether a pod can request privilege escalation. The default is `true`. This boolean directly controls whether the `no_new_privs` flag gets set on the container process. +`spec.containers.securityContext.capabilities`:: Specifies permitted privileged actions without giving full root access. This policy ensures all capabilities are dropped from the pod. +`spec.securityContext.runAsNonRoot: true`:: Specifies that the container runs with a user with any UID other than 0. +`spec.securityContext.seccompProfile.type: RuntimeDefault`:: Specifies that the default seccomp profile is enabled for a pod or container workload. . Create the pod by running the following command: + @@ -78,8 +82,10 @@ spec: ---- $ oc apply -f sysctl_pod.yaml ---- -+ -. Verify that the pod is created by running the following command: + +.Verification + +. Check that the pod is created by running the following command: + [source,terminal] ---- diff --git a/modules/nodes-containers-sysctls-about.adoc b/modules/nodes-containers-sysctls-about.adoc index f568706517cb..15f883b50aed 100644 --- a/modules/nodes-containers-sysctls-about.adoc +++ b/modules/nodes-containers-sysctls-about.adoc @@ -6,17 +6,20 @@ [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 from the `_/proc/sys/_` virtual process file system. The parameters cover various subsystems, such as: +[role="_abstract"] +The Linux sysctl interface allows you to modify kernel parameters at runtime to manage subsystems such as networking, virtual memory, and MDADM. By accessing the sysctl interface, you can view and adjust system configurations without rebooting the operating system. + +You can modify the following subsystems by using sysctls: - 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]. -To get a list of all parameters, run: +Refer to the link:https://www.kernel.org/doc/Documentation/sysctl/README[Kernel.org documentation] for more information on the subsystems you can manage. +You can get a list of all parameters by running the following command: [source,terminal] ---- $ sudo sysctl -a ----- \ No newline at end of file +---- diff --git a/modules/nodes-containers-sysctls-setting.adoc b/modules/nodes-containers-sysctls-setting.adoc index 47fd03fd60ec..872c194437e7 100644 --- a/modules/nodes-containers-sysctls-setting.adoc +++ b/modules/nodes-containers-sysctls-setting.adoc @@ -6,7 +6,10 @@ [id="nodes-containers-starting-pod-with-unsafe-sysctls_{context}"] = Starting a pod with unsafe sysctls -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. +[role="_abstract"] +You can run a pod that is configured to use unsafe sysctls on a node where a cluster administrator explicitly enabled unsafe sysctls. You might use unsafe sysctls for situations such as high performance or real-time application tuning. + +You can 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. @@ -51,7 +54,7 @@ spec: value: "65536" ---- -. Create the pod using the following command: +. Create the pod by using the following command: + [source,terminal] ---- diff --git a/modules/nodes-containers-sysctls-unsafe.adoc b/modules/nodes-containers-sysctls-unsafe.adoc index 0dd62a4614a1..86385b6c5282 100644 --- a/modules/nodes-containers-sysctls-unsafe.adoc +++ b/modules/nodes-containers-sysctls-unsafe.adoc @@ -6,26 +6,26 @@ [id="nodes-containers-sysctls-unsafe_{context}"] = Enabling unsafe sysctls -A cluster administrator can allow certain unsafe sysctls for very special -situations such as high performance or real-time application tuning. +[role="_abstract"] +As a cluster administrator, you can allow certain unsafe sysctls for very special situations such as high performance or real-time application tuning. If you want to use unsafe sysctls, a cluster administrator must enable them individually for a specific type of node. The sysctls must be namespaced. You can further control which sysctls are set in pods by specifying lists of sysctls or sysctl patterns in the `allowedUnsafeSysctls` field of the Security Context Constraints. -- The `allowedUnsafeSysctls` option controls specific needs such as high performance or real-time application tuning. +The `allowedUnsafeSysctls` option controls specific needs such as high performance or real-time application tuning. [WARNING] ==== -Due to their nature of being unsafe, the use of unsafe sysctls is +Because these sysctls are considered unsafe, the use of unsafe sysctls is at-your-own-risk and can lead to severe problems, such as improper behavior of -containers, resource shortage, or breaking a node. +containers, resource shortage, or node breakage. ==== .Procedure -. List existing MachineConfig objects for your {product-title} cluster to decide how to label your machine config by running the following command: +. List existing `MachineConfig` objects for your {product-title} cluster to decide how to label your machine config by running the following command: + [source,terminal] ---- @@ -40,13 +40,14 @@ master rendered-master-bfb92f0cd1684e54d8e234ab7423cc96 True False worker rendered-worker-21b6cb9a0f8919c88caf39db80ac1fce True False False 3 3 3 0 42m ---- -. Add a label to the machine config pool where the containers with the unsafe sysctls will run by running the following command: +. Add a label to the machine config pool where the containers with the unsafe sysctls are to run by running the following command: + [source,terminal] ---- $ oc label machineconfigpool worker custom-kubelet=sysctl ---- -. Create a YAML file `set-sysctl-worker.yaml` that defines a `KubeletConfig` custom resource (CR): + +. Create a YAML file that defines a `KubeletConfig` custom resource (CR): + [source,yaml] ---- @@ -57,14 +58,16 @@ metadata: spec: machineConfigPoolSelector: matchLabels: - custom-kubelet: sysctl <1> + custom-kubelet: sysctl kubeletConfig: - allowedUnsafeSysctls: <2> + allowedUnsafeSysctls: - "kernel.msg*" - "net.core.somaxconn" ---- -<1> Specify the label from the machine config pool. -<2> List the unsafe sysctls you want to allow. +where: + +`spec.machineConfigPoolSelector.matchLabels`:: Specifies the label from the machine config pool. +`spec.kubeletConfig.allowedUnsafeSysctls`:: Specifies a list of unsafe sysctls to allow. . Create the object by running the following command: + @@ -89,7 +92,8 @@ worker rendered-worker-f1704a00fc6f30d3a7de9a15fd68a800 False True worker rendered-worker-f1704a00fc6f30d3a7de9a15fd68a800 False True False 3 2 3 0 72m worker rendered-worker-0188658afe1f3a183ec8c4f14186f4d5 True False False 3 3 3 0 72m ---- -. Create a YAML file `sysctl-example-safe-unsafe.yaml` that defines an example pod and add the `securityContext` spec, as shown in the following example: + +. Create a YAML file that defines a pod and add the `securityContext` spec, as shown in the following example: + [source,yaml] ---- @@ -129,7 +133,6 @@ $ oc apply -f sysctl-example-safe-unsafe.yaml ---- + .Expected output -+ [source,terminal] ---- Warning: would violate PodSecurity "restricted:latest": forbidden sysctls (net.core.somaxconn, kernel.msgmax) @@ -157,7 +160,7 @@ sysctl-example-safe-unsafe 1/1 Running 0 19s $ oc rsh sysctl-example-safe-unsafe ---- -. Verify the values of the configured sysctl flags. For example, find the value `net.core.somaxconn` by running the following command: +. Verify the values of the configured sysctl flags. For example, find the value of the `net.core.somaxconn` parameter by running the following command: + [source,terminal] ---- @@ -169,5 +172,5 @@ sh-4.4# sysctl net.core.somaxconn ---- net.core.somaxconn = 1024 ---- - ++ The unsafe sysctl is now allowed and the value is set as defined in the `securityContext` spec of the updated pod specification. diff --git a/modules/nodes-namespaced-nodelevel-sysctls.adoc b/modules/nodes-namespaced-nodelevel-sysctls.adoc index 9798037e2d02..10d91ff99e49 100644 --- a/modules/nodes-namespaced-nodelevel-sysctls.adoc +++ b/modules/nodes-namespaced-nodelevel-sysctls.adoc @@ -7,7 +7,11 @@ [id="namespaced-and-node-level-sysctls"] = Namespaced and 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. +[role="_abstract"] +In a {product-title} cluster, you can use namespaced sysctls, which apply to specific pods on a node, or node-level sysctls, which affect an entire node. + +Some 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: @@ -18,11 +22,10 @@ The following sysctls are known to be namespaced: 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 +_Node-level_ sysctls are not namespaced and must be set +manually by a cluster administrator, either by using 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. - +or by using a daemon set with privileged containers. You can also use the Node Tuning Operator to set _node-level_ sysctls. [NOTE] ==== diff --git a/modules/nodes-safe-sysctls-list.adoc b/modules/nodes-safe-sysctls-list.adoc index d8eb5ade9c92..2d78c29d941e 100644 --- a/modules/nodes-safe-sysctls-list.adoc +++ b/modules/nodes-safe-sysctls-list.adoc @@ -6,11 +6,12 @@ [id="safe_and_unsafe_sysctls_{context}"] = Safe and unsafe sysctls -Sysctls are grouped into _safe_ and _unsafe_ sysctls. +[role="_abstract"] +In a {product-title} cluster, you can use _safe_ or _unsafe_ sysctls. -For system-wide sysctls to be considered safe, they must be namespaced. A namespaced sysctl ensures there is isolation between namespaces and therefore pods. If you set a sysctl for one pod it must not add any of the following: +For system-wide sysctls to be considered safe, they must be namespaced. A namespaced sysctl ensures there is isolation between namespaces and therefore pods. If you set a sysctl for one pod it must not take any of the following actions: -- Influence any other pod on the node +- Influence on any other pod on the node - Harm the node health - Gain CPU or memory resources outside of the resource limits of a pod @@ -18,9 +19,10 @@ For system-wide sysctls to be considered safe, they must be namespaced. A namesp ==== Being namespaced alone is not sufficient for the sysctl to be considered safe. ==== + Any sysctl that is not added to the allowed list on {product-title} is considered unsafe for {product-title}. -Unsafe sysctls are not allowed by default. For system-wide sysctls the cluster administrator must manually enable them on a per-node basis. Pods with disabled unsafe sysctls are scheduled but do not launch. +Unsafe sysctls are not allowed by default. For system-wide sysctls, a cluster administrator must manually enable them on a per-node basis. Pods with disabled unsafe sysctls are scheduled but do not launch. [NOTE] ==== @@ -38,32 +40,32 @@ You cannot manually enable interface-specific unsafe sysctls. a|When set to `1`, all shared memory objects in current IPC namespace are automatically forced to use IPC_RMID. For more information, see link:https://docs.kernel.org/admin-guide/sysctl/kernel.html?highlight=shm_rmid_forced#shm-rmid-forced[shm_rmid_forced]. | `net.ipv4.ip_local_port_range` -a| Defines the local port range that is used by TCP and UDP to choose the local port. The first number is the first port number, and the second number is the last local port number. If possible, it is better if these numbers have different parity (one even and one odd value). They must be greater than or equal to `ip_unprivileged_port_start`. The default values are `32768` and `60999` respectively. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=ip_local_port_range#ip-variables[ip_local_port_range]. +a| Defines the local port range that is used by TCP and UDP to choose the local port. The first number is the first port number, and the second number is the last local port number. If possible, it is better if these numbers have different parity (one even and one odd value). They must be greater than or equal to `ip_unprivileged_port_start`. The default values are `32768` and `60999` respectively. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=ip_local_port_range#ip-variables[ip_local_port_range (Kernel.org documentation)]. | `net.ipv4.tcp_syncookies` |When `net.ipv4.tcp_syncookies` is set, the kernel handles TCP SYN packets normally until the -half-open connection queue is full, at which time, the SYN cookie functionality kicks in. This functionality allows the system to keep accepting valid connections, even if under a denial-of-service attack. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=tcp_syncookies#tcp-variables[tcp_syncookies]. +half-open connection queue is full, at which time, the SYN cookie functionality kicks in. This functionality allows the system to keep accepting valid connections, even if under a denial-of-service attack. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=tcp_syncookies#tcp-variables[tcp_syncookies (Kernel.org documentation)]. | `net.ipv4.ping_group_range` -a| This restricts `ICMP_PROTO` datagram sockets to users in the group range. The default is `1 0`, meaning that nobody, not even root, can create ping sockets. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=ping_group_range#ip-variables[ping_group_range]. +a| Restricts `ICMP_PROTO` datagram sockets to users in the group range. The default is `1 0`, meaning that nobody, not even root, can create ping sockets. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=ping_group_range#ip-variables[ping_group_range (Kernel.org documentation)]. | `net.ipv4.ip_unprivileged_port_start` -| This defines the first unprivileged port in the network namespace. To disable all privileged ports, set this to `0`. Privileged ports must not overlap with the `ip_local_port_range`. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=ip_unprivileged_port_start#ip-variables#ip-variables[ip_unprivileged_port_start]. +| Defines the first unprivileged port in the network namespace. To disable all privileged ports, set to `0`. Privileged ports must not overlap with the `ip_local_port_range`. For more information, see link:https://docs.kernel.org/networking/ip-sysctl.html?highlight=ip_unprivileged_port_start#ip-variables#ip-variables[ip_unprivileged_port_start (Kernel.org documentation)]. |`net.ipv4.ip_local_reserved_ports` -| Specify a range of comma-separated local ports that you want to reserve for applications or services. +| Specifies a range of comma-separated local ports that you want to reserve for applications or services. | `net.ipv4.tcp_keepalive_time` -| Specify the interval in seconds before the first `keepalive` probe should be sent after a connection has become idle. +| Specifies the interval in seconds before the first `keepalive` probe should be sent after a connection has become idle. | `net.ipv4.tcp_fin_timeout` -| Specify the time in seconds that a connection remains in the `FIN-WAIT-2` state before it is aborted. +| Specifies the time in seconds that a connection remains in the `FIN-WAIT-2` state before it is aborted. | `net.ipv4.tcp_keepalive_intvl` -| Specify the interval in seconds between the `keepalive` probes. This value is multiplied by the `tcp_keepalive_probes` value to determine the total time required before it is decided that the connection is broken. +| Specifies the interval in seconds between the `keepalive` probes. This value is multiplied by the `tcp_keepalive_probes` value to determine the total time required before it is decided that the connection is broken. | `net.ipv4.tcp_keepalive_probes` -| Specify how many `keepalive` probes to send until it is determined that the connection is broken. +| Specifies how many `keepalive` probes to send until it is determined that the connection is broken. |=== @@ -74,54 +76,54 @@ a| This restricts `ICMP_PROTO` datagram sockets to users in the group range. The | sysctl | Description | `net.ipv4.conf.IFNAME.accept_redirects` -a| Accept IPv4 ICMP redirect messages. +a| Accepts IPv4 ICMP redirect messages. | `net.ipv4.conf.IFNAME.accept_source_route` -|Accept IPv4 packets with strict source route (SRR) option. +|Accepts IPv4 packets with strict source route (SRR) option. | `net.ipv4.conf.IFNAME.arp_accept` -a| Define behavior for gratuitous ARP frames with an IPv4 address that is not already present in the ARP table: +a| Defines the behavior for gratuitous ARP frames with an IPv4 address that is not already present in the ARP table: * `0` - Do not create new entries in the ARP table. * `1` - Create new entries in the ARP table. | `net.ipv4.conf.IFNAME.arp_notify` -| Define mode for notification of IPv4 address and device changes. +| Defines the mode for notification of IPv4 address and device changes. | `net.ipv4.conf.IFNAME.disable_policy` -a| Disable IPSEC policy (SPD) for this IPv4 interface. +a| Disables IPSEC policy (SPD) for this IPv4 interface. | `net.ipv4.conf.IFNAME.secure_redirects` -a| Accept ICMP redirect messages only to gateways listed in the interface’s current gateway list. +a| Accepts ICMP redirect messages only to gateways listed in the interface’s current gateway list. | `net.ipv4.conf.IFNAME.send_redirects` -| Send redirects is enabled only if the node acts as a router. That is, a host should not send an ICMP redirect message. It is used by routers to notify the host about a better routing path that is available for a particular destination. +| Sends redirects only if the node acts as a router. That is, a host should not send an ICMP redirect message. It is used by routers to notify the host about a better routing path that is available for a particular destination. | `net.ipv6.conf.IFNAME.accept_ra` -a| Accept IPv6 Router advertisements; autoconfigure using them. It also determines whether or not to transmit router solicitations. Router solicitations are transmitted only if the functional setting is to accept router advertisements. +a| Accepts IPv6 Router advertisements; autoconfigure using them. It also determines whether or not to transmit router solicitations. Router solicitations are transmitted only if the functional setting is to accept router advertisements. | `net.ipv6.conf.IFNAME.accept_redirects` -a| Accept IPv6 ICMP redirect messages. +a| Accepts IPv6 ICMP redirect messages. | `net.ipv6.conf.IFNAME.accept_source_route` -a| Accept IPv6 packets with SRR option. +a| Accepts IPv6 packets with SRR option. | `net.ipv6.conf.IFNAME.arp_accept` -a| Define behavior for gratuitous ARP frames with an IPv6 address that is not already present in the ARP table: +a| Defines the behavior for gratuitous ARP frames with an IPv6 address that is not already present in the ARP table: * `0` - Do not create new entries in the ARP table. * `1` - Create new entries in the ARP table. | `net.ipv6.conf.IFNAME.arp_notify` -| Define mode for notification of IPv6 address and device changes. +| Defines the mode for notification of IPv6 address and device changes. | `net.ipv6.neigh.IFNAME.base_reachable_time_ms` -| This parameter controls the hardware address to IP mapping lifetime in the neighbour table for IPv6. +| Controls the hardware address to IP mapping lifetime in the neighbor table for IPv6. | `net.ipv6.neigh.IFNAME.retrans_time_ms` -| Set the retransmit timer for neighbor discovery messages. +| Sets the retransmit timer for neighbor discovery messages. |=== diff --git a/modules/update-network-sysctl-allowlist.adoc b/modules/update-network-sysctl-allowlist.adoc index 791a5556ac87..01dab559d730 100644 --- a/modules/update-network-sysctl-allowlist.adoc +++ b/modules/update-network-sysctl-allowlist.adoc @@ -6,12 +6,13 @@ [id="updating-interface-specific-safe-sysctls-list_{context}"] = Updating the interface-specific safe sysctls list -{product-title} includes a predefined list of safe interface-specific `sysctls`. You can modify this list by updating the `cni-sysctl-allowlist` in the `openshift-multus` namespace. +[role="_abstract"] +You can modify the default list of safe interface-specific `sysctls` by updating the `cni-sysctl-allowlist` in the `openshift-multus` namespace. :FeatureName: The support for updating the interface-specific safe sysctls list include::snippets/technology-preview.adoc[leveloffset=+1] -Follow this procedure to modify the predefined list of safe `sysctls`. This procedure describes how to extend the default allow list. +For example, the following procedure modifies the predefined list of safe `sysctls` to add sysctls that allow users to enforce stricter reverse path forwarding for IPv4. For more information on reverse path forwarding see Reverse Path Forwarding. .Procedure @@ -23,7 +24,6 @@ $ oc get cm -n openshift-multus cni-sysctl-allowlist -oyaml ---- + .Expected output -+ [source,terminal,subs="attributes+"] ---- apiVersion: v1 @@ -62,8 +62,8 @@ metadata: ---- $ oc edit cm -n openshift-multus cni-sysctl-allowlist -oyaml ---- -+ -For example, to allow you to be able to implement stricter reverse path forwarding you need to add `^net.ipv4.conf.IFNAME.rp_filter$` and `^net.ipv6.conf.IFNAME.rp_filter$` to the list as shown here: + +. Add the `^net.ipv4.conf.IFNAME.rp_filter$` and `^net.ipv6.conf.IFNAME.rp_filter$` fields to the list of parameters to allow users to implement stricter reverse path forwarding. + [source,terminal] ---- @@ -101,10 +101,6 @@ The removal of `sysctls` is also supported. Edit the file, remove the `sysctl` o .Verification -Follow this procedure to enforce stricter reverse path forwarding for IPv4. -For more information on reverse path forwarding see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/security_guide/sect-security_guide-server_security-reverse_path_forwarding[Reverse Path Forwarding -]. - . Create a network attachment definition, such as `reverse-path-fwd-example.yaml`, with the following content: + [source,yaml] @@ -156,7 +152,7 @@ metadata: app: httpd namespace: default annotations: - k8s.v1.cni.cncf.io/networks: tuningnad <1> + k8s.v1.cni.cncf.io/networks: tuningnad spec: securityContext: runAsNonRoot: true @@ -173,9 +169,11 @@ spec: drop: - ALL ---- -<1> Specify the name of the configured `NetworkAttachmentDefinition`. +where: -. Apply the yaml by running the following command: +`metadata.annotations`:: Specifies the name of the configured `NetworkAttachmentDefinition`. + +. Apply the YAML by running the following command: + [source,terminal] ---- diff --git a/nodes/containers/nodes-containers-port-forwarding.adoc b/nodes/containers/nodes-containers-port-forwarding.adoc index a6a69fd7c828..1ce0902920cc 100644 --- a/nodes/containers/nodes-containers-port-forwarding.adoc +++ b/nodes/containers/nodes-containers-port-forwarding.adoc @@ -9,8 +9,8 @@ toc::[] - -{product-title} supports port forwarding to pods. +[role="_abstract"] +You can configure port forwarding to pods, which expose services in your cluster to clients outside of the cluster. // The following include statements pull in the module files that comprise diff --git a/nodes/containers/nodes-containers-remote-commands.adoc b/nodes/containers/nodes-containers-remote-commands.adoc index 50a4a45b38f9..ce7275637b04 100644 --- a/nodes/containers/nodes-containers-remote-commands.adoc +++ b/nodes/containers/nodes-containers-remote-commands.adoc @@ -9,8 +9,8 @@ toc::[] - -You can use the CLI to execute remote commands in an {product-title} container. +[role="_abstract"] +You can use the `oc exec` command to execute remote commands in {product-title} containers from your local machine. // The following include statements pull in the module files that comprise // the assembly. Include any combination of concept, procedure, or reference diff --git a/nodes/containers/nodes-containers-sysctls.adoc b/nodes/containers/nodes-containers-sysctls.adoc index 85914ff05152..b0904535e48a 100644 --- a/nodes/containers/nodes-containers-sysctls.adoc +++ b/nodes/containers/nodes-containers-sysctls.adoc @@ -6,19 +6,20 @@ include::_attributes/common-attributes.adoc[] toc::[] -Sysctl settings are exposed through Kubernetes, allowing users to modify certain kernel parameters at runtime. Only sysctls that are namespaced can be set independently on pods. If a sysctl is not namespaced, called _node-level_, you must use another method of setting the sysctl, such as by using the Node Tuning Operator. +[role="_abstract"] +You can configure namespaced sysctls to manage kernel parameters for specific pods or network interfaces. By enabling safe or unsafe namespaced sysctls, you can fine-tune your environment's performance and networking behavior at the pod level. + +Only sysctls that are namespaced can be set independently on pods. If a sysctl is not namespaced, it is known as a _node-level_ sysctl. You must use another method of setting the sysctl, such as by using the Node Tuning Operator. To set node-level sysctls, see "Using the Node Tuning Operator". Network sysctls are a special category of sysctl. Network sysctls include: * System-wide sysctls, for example `net.ipv4.ip_local_port_range`, that are valid for all networking. You can set these independently for each pod on a node. * Interface-specific sysctls, for example `net.ipv4.conf.IFNAME.accept_local`, that only apply to a specific additional network interface for a given pod. You can set these independently for each additional network configuration. You set these by using a configuration in the `tuning-cni` after the network interfaces are created. -Moreover, only those sysctls considered _safe_ are whitelisted by default; you -can manually enable other _unsafe_ sysctls on the node to be available to the +Only those sysctls considered _safe_ are enabled by default. A cluster administrator +can manually enable _unsafe_ sysctls on the node to be available to the user. -If you are setting the sysctl and it is node-level, you can find information on this procedure in the section xref:../../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[Using the Node Tuning Operator]. - // 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 @@ -32,11 +33,6 @@ include::modules/nodes-safe-sysctls-list.adoc[leveloffset=+1] include::modules/update-network-sysctl-allowlist.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources - -* link:https://docs.kernel.org/networking/ip-sysctl.html[Linux networking documentation] - include::modules/nodes-containers-start-pod-safe-sysctls.adoc[leveloffset=+1] include::modules/nodes-containers-sysctls-setting.adoc[leveloffset=+1] @@ -47,6 +43,10 @@ include::modules/nodes-containers-sysctls-unsafe.adoc[leveloffset=+1] [id="additional-resources_nodes-containers-sysctls"] == Additional resources +* link:https://docs.kernel.org/networking/ip-sysctl.html[Linux networking documentation] + * xref:../../networking/configuring_network_settings/configure-syscontrols-interface-tuning-cni.adoc#nw-configuring-tuning-cni_configure-syscontrols-interface-tuning-cni[Configuring system controls by using the tuning CNI] -* xref:../../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[Using the Node Tuning Operator] \ No newline at end of file +* xref:../../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[Using the Node Tuning Operator] + +* link:https://www.kernel.org/doc/Documentation/sysctl/[Kernel.org documentation] diff --git a/nodes/containers/nodes-containers-using.adoc b/nodes/containers/nodes-containers-using.adoc index 8a900ae24fdc..60af221b8398 100644 --- a/nodes/containers/nodes-containers-using.adoc +++ b/nodes/containers/nodes-containers-using.adoc @@ -8,8 +8,9 @@ toc::[] +[role="_abstract"] +Containers are the basic units of {product-title} applications that isolate processes to provide portable micro-services. To maintain cluster stability, you must understand how container runtimes manage workloads and how kernel memory allocation impacts resource limits on your nodes. -The basic units of {product-title} applications are called _containers_. link:https://www.redhat.com/en/topics/containers#overview[Linux container technologies] are lightweight mechanisms for isolating running processes so that they are limited to interacting with only their designated resources. @@ -28,7 +29,7 @@ multi-host installations. [id="nodes-containers-memory"] == About containers and RHEL kernel memory -Due to Red Hat Enterprise Linux (RHEL) behavior, a container on a node with high CPU usage might seem to consume more memory than expected. The higher memory consumption could be caused by the `kmem_cache` in the RHEL kernel. The RHEL kernel creates a `kmem_cache` for each cgroup. For added performance, the `kmem_cache` contains a `cpu_cache`, and a node cache for any NUMA nodes. These caches all consume kernel memory. +Due to {op-system-base-full} behavior, a container on a node with high CPU usage might seem to consume more memory than expected. The higher memory consumption could be caused by the `kmem_cache` in the RHEL kernel. The RHEL kernel creates a `kmem_cache` for each cgroup. For added performance, the `kmem_cache` contains a `cpu_cache`, and a node cache for any NUMA nodes. These caches all consume kernel memory. The amount of memory stored in those caches is proportional to the number of CPUs that the system uses. As a result, a higher number of CPUs results in a greater amount of kernel memory being held in these caches. Higher amounts of kernel memory in these caches can cause {product-title} containers to exceed the configured memory limits, resulting in the container being killed. @@ -69,10 +70,16 @@ runC has some benefits over crun, including: * 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:../../machine_configuration/machine-configs-custom.adoc#create-a-containerruntimeconfig_machine-configs-custom[Creating a `ContainerRuntimeConfig` CR to edit CRI-O parameters]. endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] {product-title} uses CRI-O as the container engine and crun or runC as the container runtime. The default container runtime is crun. endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] + +ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* xref:../../machine_configuration/machine-configs-custom.adoc#create-a-containerruntimeconfig_machine-configs-custom[Creating a `ContainerRuntimeConfig` CR to edit CRI-O parameters] +endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]