Merge pull request #30619 from mikemckiernan/feat-hugepages

(OSDOCS-1808) Hugepages is GA

Author: ahardin-rh

modules/consuming-huge-pages-resource-using-the-downward-api.adoc

@@ -0,0 +1,107 @@
+// Module included in the following assemblies:
+//
+// * scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc
+
+:file-name: hugepages-volume-pod.yaml
+
+[id="consuming-huge-pages-resource-using-the-downward-api_{context}"]
+= Consuming huge pages resources using the Downward API
+
+You can use the Downward API to inject information about the huge pages resources that are consumed by a container.
+
+You can inject the resource allocation as environment variables, a volume plug-in, or both. Applications that you develop and run in the container can determine the resources that are available by reading the environment variables or files in the specified volumes.
+
+.Procedure
+
+. Create a `{file-name}` file that is similar to the following example:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  generateName: hugepages-volume-
+  labels:
+    app: hugepages-example
+spec:
+  containers:
+  - securityContext:
+      capabilities:
+        add: [ "IPC_LOCK" ]
+    image: rhel7:latest
+    command:
+    - sleep
+    - inf
+    name: example
+    volumeMounts:
+    - mountPath: /dev/hugepages
+      name: hugepage
+    - mountPath: /etc/podinfo
+      name: podinfo
+    resources:
+      limits:
+        hugepages-1Gi: 2Gi
+        memory: "1Gi"
+        cpu: "1"
+      requests:
+        hugepages-1Gi: 2Gi
+    env:
+    - name: REQUESTS_HUGEPAGES_1GI <.>
+      valueFrom:
+        resourceFieldRef:
+          containerName: example
+          resource: requests.hugepages-1Gi
+  volumes:
+  - name: hugepage
+    emptyDir:
+      medium: HugePages
+  - name: podinfo
+    downwardAPI:
+      items:
+        - path: "hugepages_1G_request" <.>
+          resourceFieldRef:
+            containerName: example
+            resource: requests.hugepages-1Gi
+            divisor: 1Gi
+----
+<.> Specifies to read the resource use from `requests.hugepages-1Gi` and expose the value as the `REQUESTS_HUGEPAGES_1GI` environment variable.
+<.> Specifies to read the resource use from `requests.hugepages-1Gi` and expose the value as the file `/etc/podinfo/hugepages_1G_request`.
+
+. Create the pod from the `{file-name}` file:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc create -f {file-name}
+----
+
+.Verification
+
+. Check the value of the `REQUESTS_HUGEPAGES_1GI` environment variable:
++
+[source,terminal]
+----
+$ oc exec -it $(oc get pods -l app=hugepages-example -o jsonpath='{.items[0].metadata.name}') \
+     -- env | grep REQUESTS_HUGEPAGES_1GI
+----
++
+.Example output
+[source,terminal]
+----
+REQUESTS_HUGEPAGES_1GI=2147483648
+----
+
+. Check the value of the `/etc/podinfo/hugepages_1G_request` file:
++
+[source,terminal]
+----
+$ oc exec -it $(oc get pods -l app=hugepages-example -o jsonpath='{.items[0].metadata.name}') \
+     -- cat /etc/podinfo/hugepages_1G_request
+----
++
+.Example output
+[source,terminal]
+----
+2
+----
+
+:!file-name:

modules/nw-sriov-app-netutil.adoc

@@ -7,20 +7,15 @@
 
 An link:https://github.com/openshift/app-netutil[optional library], `app-netutil`, provides several API methods for gathering network information about a pod from within a container running within that pod.
 
-This library is intended to assist with integrating SR-IOV virtual functions (VFs) in Data Plane Development Kit (DPDK) mode into the container.
+This library can assist with integrating SR-IOV virtual functions (VFs) in Data Plane Development Kit (DPDK) mode into the container.
 The library provides both a Golang API and a C API.
 
 Currently there are three API methods implemented:
 
-`GetCPUInfo()`:: This function determines which CPUs are available to the container and returns the list to the caller.
+`GetCPUInfo()`:: This function determines which CPUs are available to the container and returns the list.
 
-`GetHugepages()`:: This function determines the amount of hugepage memory requested in the `Pod` spec for each container and returns the values to the caller.
-+
-[NOTE]
-====
-Exposing hugepages via Kubernetes Downward API is an alpha feature in Kubernetes 1.20 and is not enabled in {product-title}. The API can be tested by enabling the feature gate, `FEATURE_GATES="DownwardAPIHugePages=true"` on Kubernetes 1.20 or greater.
-====
+`GetHugepages()`:: This function determines the amount of huge page memory requested in the `Pod` spec for each container and returns the values.
 
-`GetInterfaces()`:: This function determines the set of interfaces in the container and returns the list, along with the interface type and type specific data.
+`GetInterfaces()`:: This function determines the set of interfaces in the container and returns the list. The return value includes the interface type and type-specific data for each interface.
 
-There is also a sample Docker image, `dpdk-app-centos`, which can run one of the following DPDK sample applications based on an environmental variable in the pod-spec: `l2fwd`, `l3wd` or `testpmd`. This Docker image provides an example of integrating the `app-netutil` into the container image itself. The library can also integrate into an `init-container` which collects the required data and passes the data to an existing DPDK workload.
+The repository for the library includes a sample Dockerfile to build a container image, `dpdk-app-centos`. The container image can run one of the following DPDK sample applications, depending on an environment variable in the pod specification: `l2fwd`, `l3wd` or `testpmd`. The container image provides an example of integrating the `app-netutil` library into the container image itself. The library can also integrate into an init container. The init container can collect the required data and pass the data to an existing DPDK workload.

modules/nw-sriov-configuring-operator.adoc

@@ -33,10 +33,10 @@ The `SriovOperatorConfig` object provides several fields for configuring the ope
 The Network Resources Injector is a Kubernetes Dynamic Admission Controller
 application. It provides the following capabilities:
 
-* Mutation of resource requests and limits in `Pod` specification to add an SR-IOV resource name according to an SR-IOV network attachment definition annotation.
-* Mutation of `Pod` specifications with downward API volume to expose pod annotations and labels to the running container as files under the `/etc/podnetinfo` path.
+* Mutation of resource requests and limits in a pod specification to add an SR-IOV resource name according to an SR-IOV network attachment definition annotation.
+* Mutation of a pod specification with a Downward API volume to expose pod annotations, labels, and huge pages requests and limits. Containers that run in the pod can access the exposed information as files under the `/etc/podnetinfo` path.
 
-By default the Network Resources Injector is enabled by the SR-IOV operator and runs as a daemon set on all master nodes. The following is an example of Network Resources Injector pods running in a cluster with three master nodes:
+By default, the Network Resources Injector is enabled by the SR-IOV Network Operator and runs as a daemon set on all master nodes. The following is an example of Network Resources Injector pods running in a cluster with three master nodes:
 
 [source,terminal]
 ----
@@ -53,15 +53,15 @@ network-resources-injector-lktz5          1/1     Running   0          10m
 ----
 
 [id="about-sr-iov-operator-admission-control-webhook_{context}"]
-== About the SR-IOV Operator admission controller webhook
+== About the SR-IOV Network Operator admission controller webhook
 
-The SR-IOV Operator Admission Controller webhook is a Kubernetes Dynamic
+The SR-IOV Network Operator Admission Controller webhook is a Kubernetes Dynamic
 Admission Controller application. It provides the following capabilities:
 
 * Validation of the `SriovNetworkNodePolicy` CR when it is created or updated.
 * Mutation of the `SriovNetworkNodePolicy` CR by setting the default value for the `priority` and `deviceType` fields when the CR is created or updated.
 
-By default the SR-IOV Operator Admission Controller webhook is enabled by the operator and runs as a daemon set on all master nodes.
+By default the SR-IOV Network Operator Admission Controller webhook is enabled by the Operator and runs as a daemon set on all master nodes.
 The following is an example of the Operator Admission Controller webhook pods running in a cluster with three master nodes:
 
 [source,terminal]
@@ -94,7 +94,7 @@ To disable or enable the Network Resources Injector, which is enabled by default
 
 * Install the OpenShift CLI (`oc`).
 * Log in as a user with `cluster-admin` privileges.
-* You must have installed the SR-IOV Operator.
+* You must have installed the SR-IOV Network Operator.
 
 .Procedure
 
@@ -108,15 +108,15 @@ $ oc patch sriovoperatorconfig default \
 ----
 
 [id="disable-enable-sr-iov-operator-admission-control-webhook_{context}"]
-== Disabling or enabling the SR-IOV Operator admission controller webhook
+== Disabling or enabling the SR-IOV Network Operator admission controller webhook
 
 To disable or enable the admission controller webhook, which is enabled by default, complete the following procedure.
 
 .Prerequisites
 
 * Install the OpenShift CLI (`oc`).
 * Log in as a user with `cluster-admin` privileges.
-* You must have installed the SR-IOV Operator.
+* You must have installed the SR-IOV Network Operator.
 
 .Procedure
 

modules/nw-sriov-huge-pages.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * networking/hardware_networks/about-sriov.adoc
+
+[id="nw-sriov-hugepages_{context}"]
+= Huge pages resource injection for Downward API
+
+When a pod specification includes a resource request or limit for huge pages, the Network Resources Injector automatically adds Downward API fields to the pod specification to provide the huge pages information to the container.
+
+The Network Resources Injector adds a volume that is named `podnetinfo` and is mounted at `/etc/podnetinfo` for each container in the pod. The volume uses the Downward API and includes a file for huge pages requests and limits. The file naming convention is as follows:
+
+* `/etc/podnetinfo/hugepages_1G_request_<container-name>`
+* `/etc/podnetinfo/hugepages_1G_limit_<container-name>`
+* `/etc/podnetinfo/hugepages_2M_request_<container-name>`
+* `/etc/podnetinfo/hugepages_2M_limit_<container-name>`
+
+The paths specified in the previous list are compatible with the `app-netutil` library. By default, the library is configured to search for resource information in the `/etc/podnetinfo` directory. If you choose to specify the Downward API path items yourself manually, the `app-netutil` library searches for the following paths in addition to the paths in the previous list.
+
+* `/etc/podnetinfo/hugepages_request`
+* `/etc/podnetinfo/hugepages_limit`
+* `/etc/podnetinfo/hugepages_1G_request`
+* `/etc/podnetinfo/hugepages_1G_limit`
+* `/etc/podnetinfo/hugepages_2M_request`
+* `/etc/podnetinfo/hugepages_2M_limit`
+
+As with the paths that the Network Resources Injector can create, the paths in the preceding list can optionally end with a `_<container-name>` suffix.

networking/hardware_networks/about-sriov.adoc

@@ -7,9 +7,9 @@ toc::[]
 
 The Single Root I/O Virtualization (SR-IOV) specification is a standard for a type of PCI device assignment that can share a single device with multiple pods.
 
-SR-IOV enables you to segment a compliant network device, recognized on the host node as a physical function (PF), into multiple virtual functions (VFs).
+SR-IOV can segment a compliant network device, recognized on the host node as a physical function (PF), into multiple virtual functions (VFs).
 The VF is used like any other network device.
-The SR-IOV device driver for the device determines how the VF is exposed in the container:
+The SR-IOV network device driver for the device determines how the VF is exposed in the container:
 
 * `netdevice` driver: A regular kernel network device in the `netns` of the container
 * `vfio-pci` driver: A character device mounted in the container
@@ -31,9 +31,9 @@ It performs the following functions:
 The Operator provisions the following components:
 
 SR-IOV network configuration daemon::
-A DaemonSet that is deployed on worker nodes when the SR-IOV Operator starts. The daemon is responsible for discovering and initializing SR-IOV network devices in the cluster.
+A daemon set that is deployed on worker nodes when the SR-IOV Network Operator starts. The daemon is responsible for discovering and initializing SR-IOV network devices in the cluster.
 
-SR-IOV Operator webhook::
+SR-IOV Network Operator webhook::
 A dynamic admission controller webhook that validates the Operator custom resource and sets appropriate default values for unset fields.
 
 SR-IOV Network resources injector::
@@ -43,10 +43,10 @@ SR-IOV network device plug-in::
 A device plug-in that discovers, advertises, and allocates SR-IOV network virtual function (VF) resources. Device plug-ins are used in Kubernetes to enable the use of limited resources, typically in physical devices. Device plug-ins give the Kubernetes scheduler awareness of resource availability, so that the scheduler can schedule pods on nodes with sufficient resources.
 
 SR-IOV CNI plug-in::
-A CNI plug-in that attaches VF interfaces allocated from the SR-IOV device plug-in directly into a pod.
+A CNI plug-in that attaches VF interfaces allocated from the SR-IOV network device plug-in directly into a pod.
 
 SR-IOV InfiniBand CNI plug-in::
-A CNI plug-in that attaches InfiniBand (IB) VF interfaces allocated from the SR-IOV device plug-in directly into a pod.
+A CNI plug-in that attaches InfiniBand (IB) VF interfaces allocated from the SR-IOV network device plug-in directly into a pod.
 
 [NOTE]
 ====
@@ -57,6 +57,7 @@ include::modules/nw-sriov-supported-devices.adoc[leveloffset=+2]
 include::modules/nw-sriov-device-discovery.adoc[leveloffset=+2]
 include::modules/nw-sriov-example-vf-function-in-pod.adoc[leveloffset=+2]
 include::modules/nw-sriov-app-netutil.adoc[leveloffset=+2]
+include::modules/nw-sriov-huge-pages.adoc[leveloffset=+2]
 
 [id="about-sriov-next-steps"]
 == Next steps

scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc

@@ -9,4 +9,10 @@ include::modules/what-huge-pages-do.adoc[leveloffset=+1]
 
 include::modules/how-huge-pages-are-consumed-by-apps.adoc[leveloffset=+1]
 
+include::modules/consuming-huge-pages-resource-using-the-downward-api.adoc[leveloffset=+1]
+
+.Additional resources
+
+* xref:../nodes/containers/nodes-containers-downward-api.adoc#nodes-containers-downward-api[Allowing containers to consume Downward API objects]
+
 include::modules/configuring-huge-pages.adoc[leveloffset=+1]