diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index ab2bd3fb8913..1408a33c4567 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -124,4 +124,4 @@ :mce: multicluster engine for Kubernetes Operator :mce-short: multicluster engine Operator //Kueue -:ocp-full: Red Hat OpenShift Container Platform +:platform: Red Hat OpenShift Container Platform diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index f2bbec0bfe25..310b015c97ea 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -38,3 +38,10 @@ Distros: openshift-kueue Topics: - Name: RBAC permissions File: rbac-permissions +--- +Name: Configure +Dir: configure +Distros: openshift-kueue +Topics: +- Name: Configuring quotas + File: configuring-quotas diff --git a/configure/_attributes b/configure/_attributes new file mode 120000 index 000000000000..f27fd275ea6b --- /dev/null +++ b/configure/_attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/configure/configuring-quotas.adoc b/configure/configuring-quotas.adoc new file mode 100644 index 000000000000..3c4e32074824 --- /dev/null +++ b/configure/configuring-quotas.adoc @@ -0,0 +1,47 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/common-attributes.adoc[] +[id="configuring-quotas"] += Configuring quotas +:context: configuring-quotas + +toc::[] + +As an administrator, you can use {product-title} to configure quotas to optimize resource allocation and system throughput for user workloads. +You can configure quotas for compute resources such as CPU, memory, pods, and GPU. + +You can configure quotas in {product-title} by completing the following steps: + +. Configure a cluster queue. +. Configure a resource flavor. +. Configure a local queue. + +Users can then submit their workloads to the local queue. + +include::modules/configuring-clusterqueues.adoc[leveloffset=+1] + +[role="_next-steps"] +[id="clusterqueues-next-steps_{context}"] +.Next steps + +The cluster queue is not ready for use until a xref:../configure/configuring-quotas.adoc#configuring-resourceflavors_configuring-quotas[`ResourceFlavor` object] has also been configured. + +include::modules/configuring-resourceflavors.adoc[leveloffset=+1] + +include::modules/configuring-localqueues.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="clusterqueues-additional-resources_{context}"] +== Additional resources +* xref:../authentication/rbac-permissions.adoc#rbac-permissions[RBAC permissions] +* link:https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/[Kubernetes documentation about cluster queues] + +//// +// Save this content for user content journey abstract +// Users create jobs to be admitted to {product-title} by using the standard link:https://kubernetes.io/docs/concepts/workloads/controllers/job/[Kubernetes `Job` API]. +// Users can create any supported `Job` object, and then add the `kueue.x-k8s.io/queue-name` label to that object to connect it to a `LocalQueue` resource. + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/nodes/using-jobs-and-daemon-sets#nodes-nodes-jobs[Running tasks in pods using jobs] +//// diff --git a/configure/images b/configure/images new file mode 120000 index 000000000000..e4c5bd02a10a --- /dev/null +++ b/configure/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/configure/modules b/configure/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/configure/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/configure/snippets b/configure/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/configure/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/modules/configuring-clusterqueues.adoc b/modules/configuring-clusterqueues.adoc new file mode 100644 index 000000000000..707bbeec3765 --- /dev/null +++ b/modules/configuring-clusterqueues.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// * /configure/configuring-quotas.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-clusterqueues_{context}"] += Configuring a cluster queue + +A cluster queue is a cluster-scoped resource, represented by a `ClusterQueue` object, that governs a pool of resources such as CPU, memory, and pods. +Cluster queues can be used to define usage limits, quotas for resource flavors, order of consumption, and fair sharing rules. + +[NOTE] +==== +The cluster queue is not ready for use until a `ResourceFlavor` object has also been configured. +==== + +.Prerequisites + +include::snippets/prereqs-snippet.adoc[] + +.Procedure + +. Create a `ClusterQueue` object as a YAML file: ++ +.Example of a basic `ClusterQueue` object using a single resource flavor +[source,yaml] +---- +apiVersion: kueue.x-k8s.io/v1beta1 +kind: ClusterQueue +metadata: + name: example-queue +spec: + namespaceSelector: {} <1> + resourceGroups: + - coveredResources: ["cpu", "memory", "pods", "foo.com/gpu"] <2> + flavors: + - name: "default-flavor" <3> + resources: <4> + - name: "cpu" + nominalQuota: 9 + - name: "memory" + nominalQuota: 36Gi + - name: "pods" + nominalQuota: 5 + - name: "foo.com/gpu" + nominalQuota: 100 +---- +<1> Defines which namespaces can use the resources governed by this cluster queue. An empty `namespaceSelector` as shown in the example means that all namespaces can use these resources. +<2> Defines the resource types governed by the cluster queue. This example `ClusterQueue` object governs CPU, memory, pod, and GPU resources. +<3> Defines the resource flavor that is applied to the resource types listed. In this example, the `default-flavor` resource flavor is applied to CPU, memory, pod, and GPU resources. +<4> Defines the resource requirements for admitting jobs. This example cluster queue only admits jobs if the following conditions are met: ++ +* The sum of the CPU requests is less than or equal to 9. +* The sum of the memory requests is less than or equal to 36Gi. +* The total number of pods is less than or equal to 5. +* The sum of the GPU requests is less than or equal to 100. + +. Apply the `ClusterQueue` object by running the following command: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- diff --git a/modules/configuring-localqueues.adoc b/modules/configuring-localqueues.adoc new file mode 100644 index 000000000000..6e0df3831c1e --- /dev/null +++ b/modules/configuring-localqueues.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * /configure/configuring-quotas.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-localqueues_{context}"] += Configuring a local queue + +A local queue is a namespaced object, represented by a `LocalQueue` object, that groups closely related workloads that belong to a single namespace. + +As an administrator, you can configure a `LocalQueue` object to point to a cluster queue. This allocates resources from the cluster queue to workloads in the namespace specified in the `LocalQueue` object. + +.Prerequisites + +include::snippets/prereqs-snippet.adoc[] + +* You have created a `ClusterQueue` object. + +.Procedure + +. Create a `LocalQueue` object as a YAML file: ++ +.Example of a basic `LocalQueue` object +[source,yaml] +---- +apiVersion: kueue.x-k8s.io/v1beta1 +kind: LocalQueue +metadata: + namespace: team-a + name: team-a-queue +spec: + clusterQueue: cluster-queue +---- + +. Apply the `LocalQueue` object by running the following command: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- diff --git a/modules/configuring-resourceflavors.adoc b/modules/configuring-resourceflavors.adoc new file mode 100644 index 000000000000..9ae244bb4282 --- /dev/null +++ b/modules/configuring-resourceflavors.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * /configure/configuring-quotas.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-resourceflavors_{context}"] += Configuring a resource flavor + +After you have configured a `ClusterQueue` object, you can configure a `ResourceFlavor` object. + +Resources in a cluster are typically not homogeneous. If the resources in your cluster are homogeneous, you can use an empty `ResourceFlavor` instead of adding labels to custom resource flavors. + +You can use a custom `ResourceFlavor` object to represent different resource variations that are associated with cluster nodes through labels, taints, and tolerations. You can then associate workloads with specific node types to enable fine-grained resource management. + +.Prerequisites + +include::snippets/prereqs-snippet.adoc[] + +.Procedure + +. Create a `ResourceFlavor` object as a YAML file: ++ +.Example of an empty `ResourceFlavor` object +[source,yaml] +---- +apiVersion: kueue.x-k8s.io/v1beta1 +kind: ResourceFlavor +metadata: + name: default-flavor +---- ++ +.Example of a custom `ResourceFlavor` object +[source,yaml] +---- +apiVersion: kueue.x-k8s.io/v1beta1 +kind: ResourceFlavor +metadata: + name: "x86" +spec: + nodeLabels: + cpu-arch: x86 +---- + +. Apply the `ResourceFlavor` object by running the following command: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- diff --git a/snippets/fips-snippet.adoc b/snippets/fips-snippet.adoc index 81dfcf60ebae..aa5cc2d52ab0 100644 --- a/snippets/fips-snippet.adoc +++ b/snippets/fips-snippet.adoc @@ -1,28 +1,10 @@ // Text snippet included in the following modules: // -// * modules/agent-installer-fips-compliance.adoc -// * modules/installation-aws-config-yaml.adoc -// * modules/installation-aws-config-yaml.adoc -// * modules/installation-azure-config-yaml.adoc -// * modules/installation-azure-config-yaml.adoc -// * modules/installation-azure-config-yaml.adoc -// * modules/installation-azure-config-yaml.adoc -// * modules/installation-azure-stack-hub-config-yaml.adoc -// * modules/installation-bare-metal-config-yaml.adoc -// * modules/installation-configuration-parameters.adoc -// * modules/installation-gcp-config-yaml.adoc -// * modules/installation-gcp-user-infra-shared-vpc-config-yaml.adoc -// * modules/installation-ibm-cloud-config-yaml.adoc -// * modules/installation-vsphere-config-yaml.adoc -// * modules/machine-config-overview.adoc -// * modules/rhel-compute-requirements.adoc -// * modules/rosa-sts-interactive-cluster-creation-mode-options.adoc -// * modules/security-compliance-nist.adoc +// * // // Text snippet included in the following assemblies: // -// * security/compliance_operator/compliance-operator-release-notes.adoc -// * security/file_integrity_operator/file-integrity-operator-release-notes.adoc +// * :_mod-docs-content-type: SNIPPET diff --git a/snippets/prereqs-snippet.adoc b/snippets/prereqs-snippet.adoc new file mode 100644 index 000000000000..87a43b323460 --- /dev/null +++ b/snippets/prereqs-snippet.adoc @@ -0,0 +1,15 @@ +// Text snippet included in the following modules: +// +// * +// +// Text snippet included in the following assemblies: +// +// * + +:_mod-docs-content-type: SNIPPET + +Ensure that you have completed the following prerequisites: + +* The {product-title} Operator is installed on your cluster. +* You have cluster administrator permissions and the `kueue-batch-admin-role` role. +* You have installed the {oc-first}.