From 7a68120764646a1f88891803e755a26cd9b0eb38 Mon Sep 17 00:00:00 2001 From: Shubha Narayanan Date: Thu, 6 Aug 2026 15:30:16 +0530 Subject: [PATCH] Misc apps CQA --- applications/idling-applications.adoc | 9 +- applications/pruning-objects.adoc | 12 +- ...otas-setting-across-multiple-projects.adoc | 3 +- .../quotas/quotas-setting-per-project.adoc | 3 +- applications/red-hat-marketplace.adoc | 9 +- applications/working-with-quotas.adoc | 6 +- .../idle-idling-applications-multiple.adoc | 29 ++++ modules/idle-idling-applications-single.adoc | 19 +++ modules/idle-idling-applications.adoc | 49 +----- modules/idle-unidling-applications.adoc | 11 +- modules/oadp-creating-restore-cr.adoc | 2 +- modules/oadp-review-backup-restore.adoc | 2 +- modules/pruning-basic-operations.adoc | 3 + modules/pruning-builds.adoc | 5 +- modules/pruning-cronjobs.adoc | 9 +- modules/pruning-deployments.adoc | 3 + modules/pruning-groups.adoc | 3 + modules/pruning-hard-pruning-registry.adoc | 19 +-- modules/pruning-images-conditions.adoc | 21 +-- modules/pruning-images-manual.adoc | 10 +- modules/pruning-images-options.adoc | 14 +- modules/pruning-images-running-operation.adoc | 7 +- modules/pruning-images-secure-insecure.adoc | 3 + modules/pruning-images-troubleshooting.adoc | 47 +++--- modules/pruning-images.adoc | 4 +- modules/quotas-creating-a-quota.adoc | 3 +- .../quotas-creating-object-count-quotas.adoc | 28 ++-- modules/quotas-enforcement.adoc | 5 +- modules/quotas-requests-vs-limits.adoc | 5 +- modules/quotas-requiring-explicit-quota.adoc | 33 ++-- modules/quotas-resources-managed.adoc | 3 +- .../quotas-sample-resource-quotas-def.adoc | 145 ++++++++++-------- modules/quotas-scopes.adoc | 8 +- modules/quotas-selecting-projects.adoc | 37 +++-- modules/quotas-selection-granularity.adoc | 10 +- .../quotas-viewing-clusterresourcequotas.adoc | 5 +- modules/quotas-viewing-quotas.adoc | 5 +- modules/red-hat-marketplace-features.adoc | 20 +-- ...resource-quota-for-extended-resources.adoc | 3 + 39 files changed, 348 insertions(+), 264 deletions(-) create mode 100644 modules/idle-idling-applications-multiple.adoc create mode 100644 modules/idle-idling-applications-single.adoc diff --git a/applications/idling-applications.adoc b/applications/idling-applications.adoc index 25375c9dcb6..28a717106ce 100644 --- a/applications/idling-applications.adoc +++ b/applications/idling-applications.adoc @@ -1,12 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="idling-applications"] -= Idling applications += Reducing resource consumption with application idling include::_attributes/common-attributes.adoc[] :context: idling-applications toc::[] -Cluster administrators can idle applications to reduce resource consumption. This is useful when the cluster is deployed on a public cloud where cost is related to resource consumption. +[role="_abstract"] +As an administrator, you can reduce cluster resource consumption and lower public cloud costs by temporarily scaling inactive application resources to zero replicas. If any scalable resources are not in use, {product-title} discovers and idles them by scaling their replicas to `0`. The next time network traffic is directed to the resources, the resources are unidled by scaling up the replicas, and normal operation continues. @@ -14,4 +15,8 @@ Applications are made of services, as well as other scalable resources, such as include::modules/idle-idling-applications.adoc[leveloffset=+1] +include::modules/idle-idling-applications-single.adoc[leveloffset=+2] + +include::modules/idle-idling-applications-multiple.adoc[leveloffset=+2] + include::modules/idle-unidling-applications.adoc[leveloffset=+1] diff --git a/applications/pruning-objects.adoc b/applications/pruning-objects.adoc index 83e695bbea8..18d0b1d18d0 100644 --- a/applications/pruning-objects.adoc +++ b/applications/pruning-objects.adoc @@ -6,6 +6,9 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] +Reclaim cluster storage and optimize API server performance by pruning stale resources. You can run manual CLI commands or configure automated cron jobs to clean up obsolete deployment, build, image, and group records. + Over time, API objects created in {product-title} can accumulate in the cluster's etcd data store through normal user operations, such as when building and deploying applications. @@ -34,7 +37,7 @@ include::modules/pruning-builds.adoc[leveloffset=+1] ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] [role="_additional-resources"] .Additional resources -* xref:../cicd/builds/advanced-build-operations.adoc#builds-build-pruning-advanced-build-operations[Performing advanced builds -> Pruning builds] +* xref:../cicd/builds/advanced-build-operations.adoc#builds-build-pruning_advanced-build-operations[Performing advanced builds -> Pruning builds] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] include::modules/pruning-images.adoc[leveloffset=+1] @@ -59,10 +62,7 @@ include::modules/pruning-images-troubleshooting.adoc[leveloffset=+2] .Additional resources * xref:../registry/accessing-the-registry.adoc#accessing-the-registry[Accessing the registry] * xref:../registry/securing-exposing-registry.adoc#securing-exposing-registry[Exposing the registry] -* See -xref:../registry/configuring-registry-operator.adoc#configuring-registry-operator[Image -Registry Operator in {product-title}] for information on how to create a -registry route. +* xref:../registry/configuring-registry-operator.adoc#configuring-registry-operator[Image Registry Operator in {product-title}] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] // cannot patch resource "configs" @@ -78,7 +78,7 @@ include::modules/pruning-cronjobs.adoc[leveloffset=+1] .Additional resources // When the Operators book is added to ROSA/OSD, check if this link is valid. ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -* xref:../nodes/jobs/nodes-nodes-jobs.adoc#nodes-nodes-jobs_nodes-nodes-jobs[Running tasks in pods using jobs] +* xref:../nodes/jobs/nodes-nodes-jobs.adoc#nodes-nodes-jobs[Running tasks in pods using jobs] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] * xref:../applications/quotas/quotas-setting-across-multiple-projects.adoc#setting-quotas-across-multiple-projects[Resource quotas across multiple projects] // When the Operators book is added to ROSA/OSD, check if this link is valid. diff --git a/applications/quotas/quotas-setting-across-multiple-projects.adoc b/applications/quotas/quotas-setting-across-multiple-projects.adoc index 4c6a0250f2b..137ee34c479 100644 --- a/applications/quotas/quotas-setting-across-multiple-projects.adoc +++ b/applications/quotas/quotas-setting-across-multiple-projects.adoc @@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -A multi-project quota, defined by a `ClusterResourceQuota` object, allows quotas to be shared across multiple projects. Resources used in each selected project are aggregated and that aggregate is used to limit resources across all the selected projects. +[role="_abstract"] +A multi-project quota, defined by a `ClusterResourceQuota` object, shares quotas across multiple projects. The system aggregates the resources used in each selected project and applies the aggregate limit across all selected projects. This guide describes how cluster administrators can set and manage resource quotas across multiple projects. diff --git a/applications/quotas/quotas-setting-per-project.adoc b/applications/quotas/quotas-setting-per-project.adoc index 8885853f698..46dceca898d 100644 --- a/applications/quotas/quotas-setting-per-project.adoc +++ b/applications/quotas/quotas-setting-per-project.adoc @@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -A _resource quota_, defined by a `ResourceQuota` object, provides constraints that limit aggregate resource consumption per project. It can limit the quantity of objects that can be created in a project by type, as well as the total amount of compute resources and storage that might be consumed by resources in that project. +[role="_abstract"] +A resource quota, defined by a `ResourceQuota` object, limits aggregate resource consumption per project. It can limit the quantity of objects that you can create in a project by type, and the total amount of compute resources and storage consumed by resources in that project. This guide describes how resource quotas work, how cluster administrators can set and manage resource quotas on a per project basis, and how developers and cluster administrators can view them. diff --git a/applications/red-hat-marketplace.adoc b/applications/red-hat-marketplace.adoc index ac0936d05c4..fbe92905271 100644 --- a/applications/red-hat-marketplace.adoc +++ b/applications/red-hat-marketplace.adoc @@ -6,6 +6,13 @@ include::_attributes/common-attributes.adoc[] toc::[] -The link:https://marketplace.redhat.com[Red Hat Marketplace] is an open cloud marketplace that makes it easy to discover and access certified software for container-based environments that run on public clouds and on-premise. +[role="_abstract"] +The Red Hat Marketplace is an open cloud marketplace that makes it easy to discover and access certified software for container-based environments that run on public clouds and on-premise. include::modules/red-hat-marketplace-features.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://marketplace.redhat.com[Red Hat Marketplace] \ No newline at end of file diff --git a/applications/working-with-quotas.adoc b/applications/working-with-quotas.adoc index e6a52e273e1..9d8b22f12d6 100644 --- a/applications/working-with-quotas.adoc +++ b/applications/working-with-quotas.adoc @@ -6,10 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -A _resource quota_, defined by a ResourceQuota object, provides constraints that -limit aggregate resource consumption per project. It can limit the quantity of -objects that can be created in a project by type, as well as the total amount of -compute resources and storage that may be consumed by resources in that project. +[role="_abstract"] +A resource quota, defined by a `ResourceQuota` object, limits aggregate resource consumption per project. You can limit the quantity of objects that you can create in a project by type, and the total amount of compute resources and storage consumed by resources in that project. An _object quota count_ places a defined quota on all standard namespaced resource types. When using a resource quota, an object is charged against the quota if it diff --git a/modules/idle-idling-applications-multiple.adoc b/modules/idle-idling-applications-multiple.adoc new file mode 100644 index 00000000000..11f993142d5 --- /dev/null +++ b/modules/idle-idling-applications-multiple.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * applications/idling-applications.adoc + +:_mod-docs-content-type: PROCEDURE +[id="idle-idling-applications-multiple_{context}"] += Idling multiple services + +[role="_abstract"] +Scale multiple inactive services down to zero replicas to optimize cluster capacity. + +Idling multiple services is helpful if an application spans across a set of services within a project, or when idling multiple services in conjunction with a script to idle multiple applications in bulk within the same project. + +.Procedure + +. Create a file containing a list of the services, each on their own line. + +. Idle the services using the `--resource-names-file` option: ++ +[source,terminal] +---- +$ oc idle --resource-names-file +---- ++ +[NOTE] +==== +The `idle` command is limited to a single project. For idling applications across +a cluster, run the `idle` command for each project individually. +==== diff --git a/modules/idle-idling-applications-single.adoc b/modules/idle-idling-applications-single.adoc new file mode 100644 index 00000000000..4e8e80aab49 --- /dev/null +++ b/modules/idle-idling-applications-single.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * applications/idling-applications.adoc + +:_mod-docs-content-type: PROCEDURE +[id="idle-idling-applications-single_{context}"] += Idling a single service + +[role="_abstract"] +Scale down the scalable resources of a specific service to zero replicas to reduce cluster consumption. + +.Procedure + +. To idle a single service, run: ++ +[source,terminal] +---- +$ oc idle +---- diff --git a/modules/idle-idling-applications.adoc b/modules/idle-idling-applications.adoc index 0c02461dfc9..d4e477ac78e 100644 --- a/modules/idle-idling-applications.adoc +++ b/modules/idle-idling-applications.adoc @@ -2,50 +2,11 @@ // // * applications/idling-applications.adoc -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="idle-idling-applications_{context}"] -= Idling applications += Application idling -Idling an application involves finding the scalable resources (deployment -configurations, replication controllers, and others) associated with a service. -Idling an application finds the service and marks it as idled, scaling down the -resources to zero replicas. +[role="_abstract"] +Identify the scalable resources for one or more services, such as deployment configurations and replication controllers, and scale them down to zero replicas to optimize cluster capacity. -You can use the `oc idle` command to idle a single service, or use the -`--resource-names-file` option to idle multiple services. - -[id="idle-idling-applications-single_{context}"] -== Idling a single service - -.Procedure - -. To idle a single service, run: -+ -[source,terminal] ----- -$ oc idle ----- - -[id="idle-idling-applications-multiple_{context}"] -== Idling multiple services - -Idling multiple services is helpful if an application spans across a set of -services within a project, or when idling multiple services in conjunction with -a script to idle multiple applications in bulk within the same project. - -.Procedure - -. Create a file containing a list of the services, each on their own line. - -. Idle the services using the `--resource-names-file` option: -+ -[source,terminal] ----- -$ oc idle --resource-names-file ----- - -[NOTE] -==== -The `idle` command is limited to a single project. For idling applications across -a cluster, run the `idle` command for each project individually. -==== +You can use the `oc idle` command to idle a single service, or use the `--resource-names-file` option to idle multiple services. diff --git a/modules/idle-unidling-applications.adoc b/modules/idle-unidling-applications.adoc index 22700c32581..fa883503ccc 100644 --- a/modules/idle-unidling-applications.adoc +++ b/modules/idle-unidling-applications.adoc @@ -6,21 +6,20 @@ [id="idle-unidling-applications_{context}"] = Unidling applications -Application services become active again when they receive network traffic and -are scaled back up their previous state. This includes both traffic to the -services and traffic passing through routes. +[role="_abstract"] +Restore normal application operations by scaling up the replicas when network traffic is directed back to the idled resources. -Applications can also be manually unidled by scaling up the resources. +Application services become active again when they receive network traffic and are scaled back up to their previous state. This includes both traffic to the services and traffic passing through routes. Applications can also be manually unidled by scaling up the resources. .Procedure -. To scale up a DeploymentConfig, run: +* To scale up a DeploymentConfig, run: + [source,terminal] ---- $ oc scale --replicas=1 dc ---- - ++ [NOTE] ==== Automatic unidling by a router is currently only supported by the default diff --git a/modules/oadp-creating-restore-cr.adoc b/modules/oadp-creating-restore-cr.adoc index f43aafc5399..6ad71a3cd78 100644 --- a/modules/oadp-creating-restore-cr.adoc +++ b/modules/oadp-creating-restore-cr.adoc @@ -13,7 +13,7 @@ When you restore a stateful application that uses the `azurefile-csi` storage cl .Prerequisites -* You must install the OpenShift API for Data Protection (OADP) Operator. +* You must install the {oadp-first} Operator. * The `DataProtectionApplication` CR must be in a `Ready` state. * You must have a Velero `Backup` CR. * The persistent volume (PV) capacity must match the requested size at backup time. Adjust the requested size if needed. diff --git a/modules/oadp-review-backup-restore.adoc b/modules/oadp-review-backup-restore.adoc index 0c4af4857e2..fa228c57633 100644 --- a/modules/oadp-review-backup-restore.adoc +++ b/modules/oadp-review-backup-restore.adoc @@ -15,7 +15,7 @@ Preview the backup and restore resources in advance by doing a dry run of the ba .Prerequisites -* You have installed the OADP Operator. +* You have installed the {oadp-short} Operator. .Procedure diff --git a/modules/pruning-basic-operations.adoc b/modules/pruning-basic-operations.adoc index ebc0d23eabb..bb303fd4768 100644 --- a/modules/pruning-basic-operations.adoc +++ b/modules/pruning-basic-operations.adoc @@ -6,6 +6,9 @@ [id="pruning-basic-operations_{context}"] = Basic pruning operations +[role="_abstract"] +Remove obsolete or unreferenced cluster objects to reclaim cluster storage and maintain optimal API server performance. + The CLI groups prune operations under a common parent command: [source,terminal] diff --git a/modules/pruning-builds.adoc b/modules/pruning-builds.adoc index 2fae3c7faa5..9abdae47a60 100644 --- a/modules/pruning-builds.adoc +++ b/modules/pruning-builds.adoc @@ -6,6 +6,9 @@ [id="pruning-builds_{context}"] = Pruning builds +[role="_abstract"] +Prune obsolete build records and logs from your cluster to reclaim cluster storage and prevent API performance degradation. + To prune builds that are no longer required by the system due to age and status, administrators can run the following command: [source,terminal] @@ -52,7 +55,7 @@ $ oc adm prune builds --orphans --keep-complete=5 --keep-failed=1 \ $ oc adm prune builds --orphans --keep-complete=5 --keep-failed=1 \ --keep-younger-than=60m --confirm ---- - ++ [NOTE] ==== Developers can enable automatic build pruning by modifying their build configuration. diff --git a/modules/pruning-cronjobs.adoc b/modules/pruning-cronjobs.adoc index 3d116bcb982..3022d4839c3 100644 --- a/modules/pruning-cronjobs.adoc +++ b/modules/pruning-cronjobs.adoc @@ -6,8 +6,7 @@ [id="pruning-cronjobs_{context}"] = Pruning cron jobs -Cron jobs can perform pruning of successful jobs, but might not properly handle -failed jobs. Therefore, the cluster administrator should perform regular cleanup of -jobs manually. They should also restrict the access to cron jobs to a small -group of trusted users and set appropriate quota to prevent the cron job from -creating too many jobs and pods. +[role="_abstract"] +Clean up completed and failed Kubernetes jobs manually to prevent resource exhaustion. You can restrict cron job access to authorized users and configure resource quotas to control job and pod creation. + +Cron jobs can perform pruning of successful jobs, but might not properly handle failed jobs. Therefore, the cluster administrator should perform regular cleanup of jobs manually. They should also restrict the access to cron jobs to a small group of trusted users and set appropriate quota to prevent the cron job from creating too many jobs and pods. diff --git a/modules/pruning-deployments.adoc b/modules/pruning-deployments.adoc index 275cef51bd2..32df70d5d00 100644 --- a/modules/pruning-deployments.adoc +++ b/modules/pruning-deployments.adoc @@ -6,6 +6,9 @@ [id="pruning-deployments_{context}"] = Pruning deployment resources +[role="_abstract"] +Delete completed or failed deployment configurations and pod records to free up cluster storage, reduce database clutter, and speed up resource lookups. + You can prune resources associated with deployments that are no longer required by the system, due to age and status. The following command prunes replication controllers associated with `DeploymentConfig` objects: diff --git a/modules/pruning-groups.adoc b/modules/pruning-groups.adoc index 968589d8728..30ee18d21ca 100644 --- a/modules/pruning-groups.adoc +++ b/modules/pruning-groups.adoc @@ -6,6 +6,9 @@ [id="pruning-groups_{context}"] = Pruning groups +[role="_abstract"] +Remove stale user group records from external identity providers by using the group pruner. Pruning orphaned groups keeps user management data accurate, ensures cluster security, and prevents unauthorized access permissions. + To prune groups records from an external provider, administrators can run the following command: diff --git a/modules/pruning-hard-pruning-registry.adoc b/modules/pruning-hard-pruning-registry.adoc index 33a88914f1b..93c6501c412 100644 --- a/modules/pruning-hard-pruning-registry.adoc +++ b/modules/pruning-hard-pruning-registry.adoc @@ -6,7 +6,10 @@ [id="pruning-hard-pruning-registry_{context}"] = Hard pruning the registry -The OpenShift Container Registry can accumulate blobs that are not referenced by +[role="_abstract"] +Hard prune the {product-registry} to remove orphaned image blobs that are not referenced in etcd and reclaim registry storage space when standard image pruning is insufficient. + +The {product-registry} can accumulate blobs that are not referenced by the {product-title} cluster's etcd. The basic pruning images procedure, therefore, is unable to operate on them. These are called _orphaned blobs_. @@ -30,7 +33,7 @@ the image objects referencing them to be removed and the blobs becoming orphans. _Hard pruning_ the registry, a separate procedure from basic image pruning, allows cluster administrators to remove orphaned blobs. You should hard prune if -you are running out of storage space in your OpenShift Container Registry and +you are running out of storage space in your {product-registry} and believe you have orphaned blobs. This should be an infrequent operation and is necessary only when you have @@ -40,20 +43,18 @@ day (depending on the number of images being created). .Procedure -To hard prune orphaned blobs from the registry: - -. *Log in.* +. Log in. + Log in to the cluster with the CLI as `kubeadmin` or another privileged user that has access to the `openshift-image-registry` namespace. -. *Run a basic image prune*. +. Run a basic image prune. + Basic image pruning removes additional images that are no longer needed. The hard prune does not remove images on its own. It only removes blobs stored in the registry storage. Therefore, you should run this just before the hard prune. -. *Switch the registry to read-only mode.* +. Switch the registry to read-only mode. + If the registry is not running in read-only mode, any pushes happening at the same time as the prune will either: @@ -131,7 +132,7 @@ Would free up 2.835 GiB of disk space Use -prune=delete to actually delete the data ---- -. *Run the hard prune.* +. Run the hard prune. + Execute the following command inside one running instance of a `image-registry` pod to run the hard prune. The following example references an image registry pod called `image-registry-3-vhndw`: + @@ -147,7 +148,7 @@ Deleted 13374 blobs Freed up 2.835 GiB of disk space ---- -. *Switch the registry back to read-write mode.* +. Switch the registry back to read-write mode. + After the prune is finished, the registry can be switched back to read-write mode. In `configs.imageregistry.operator.openshift.io/cluster`, set diff --git a/modules/pruning-images-conditions.adoc b/modules/pruning-images-conditions.adoc index f60bce47971..396d0eac892 100644 --- a/modules/pruning-images-conditions.adoc +++ b/modules/pruning-images-conditions.adoc @@ -6,6 +6,9 @@ [id="pruning-images-conditions_{context}"] = Image prune conditions +[role="_abstract"] +Review the prerequisites, dependency checks, and soft-delete conditions required before removing registry images to safely prune image layers without breaking active pod deployments. + {product-title} supports two methodologies for pruning images: . Pruning by age and tag @@ -16,13 +19,12 @@ These methodologies are mutually exclusive. You must choose whether to prune by An image is only pruned if it meets the primary condition *and* is not actively referenced by a system component. -[id="pruning-images-age-tag_{context}"] -== Pruning an image by age and tag +Image pruning by age and tag:: Pruning an image by age and tag is the default pruning strategy. It identifies images for removal by using the `--keep-younger-than` and `--keep-tag-revisions` flags. To prune an image by age and tag, the image must be older than the `--keep-younger-than` threshold, not one of the most recent tag revisions, and cannot be in use by an active workload. - ++ For an image to be pruned by age and tag, *all* of the following conditions must be met: - ++ . The image is managed by {product-title} or has the `openshift.io/image.managed` annotation. . The image is older than the time specified by the `--keep-younger-than` flag. @@ -35,19 +37,18 @@ For an image to be pruned by age and tag, *all* of the following conditions must * Running or pending pods * Deployments, replication controllers, replica sets, or stateful sets. * Builds, build configurations, jobs, or cronjobs. - ++ An image is only removed if it is old, not a recent tag revision, and is confirmed to have no active references by system components. -[id="pruning-images-size-limit_{context}"] -== Pruning an image by size limit +Image pruning by size limit:: Pruning an image by size limit uses the `--prune-over-size-limit` flag. This method is used to bring a project back under its defined image storage limit. - ++ [NOTE] ==== The `--prune-over-size-limit` flag cannot be combined with the `--keep-tag-revisions` flag nor the `--keep-younger-than` flags. Doing so returns information that this operation is not allowed. ==== - ++ For an image to be pruned using this method, all of the following conditions must be true: . The image is part of a project that is currently exceeding its smallest defined size limit. @@ -59,5 +60,5 @@ For an image to be pruned using this method, all of the following conditions mus * Pods that are in a `running` or `pending` state. * Deployments, replication controllers, replica sets, or stateful sets. * Builds, build configurations, jobs, or cronjobs. - ++ With this method, the primary trigger is the project's size, but the safety check to ensure that the image is not actively in use is still performed. \ No newline at end of file diff --git a/modules/pruning-images-manual.adoc b/modules/pruning-images-manual.adoc index 90e25f375a4..edf05b5e56d 100644 --- a/modules/pruning-images-manual.adoc +++ b/modules/pruning-images-manual.adoc @@ -7,14 +7,18 @@ = Manually pruning images // out of scope for this PR - needs to be split into multiple modules, there shouldn't be multiple procedures in one module +[role="_abstract"] +Manually remove orphaned image data from your integrated OpenShift registry to reclaim storage capacity and prevent node disk exhaustion. -The pruning custom resource enables automatic image pruning for the images from the {product-registry}. Administrators can manually prune images with the `oc adm prune images ` command. For example: +The pruning custom resource enables automatic image pruning for the images from the {product-registry}. Administrators can manually prune images with the `oc adm prune images ` command. + +For example: [source,terminal] ---- -$ oc adm prune images <1> +$ oc adm prune images ---- -<1> For more information about available pruning options, see "Manual image pruning command options". +For more information about available pruning options, see "Manual image pruning command options". This command removes images that are no longer required by the system. diff --git a/modules/pruning-images-options.adoc b/modules/pruning-images-options.adoc index b57c9158302..a6929155f08 100644 --- a/modules/pruning-images-options.adoc +++ b/modules/pruning-images-options.adoc @@ -6,6 +6,9 @@ [id="pruning-images-options_{context}"] = Image pruning CLI options +[role="_abstract"] +Review the CLI options for the `oc adm prune images` command to configure flags for age thresholds, tag references, and registry endpoints. + The following table describes the options you can use with the `oc adm prune images ` command. .Manual image pruning command options @@ -66,18 +69,17 @@ API objects and corresponding data in the registry. This option is useful when you are only concerned with removing etcd content, to reduce the number of image objects but are not concerned with cleaning up registry storage, or if you intend to do that separately by hard pruning the registry during an appropriate maintenance window for the registry. |=== -[id="information-about-prune-registry-flag_{context}"] -== Additional information about the --prune-registry flag +Additional information about the `--prune-registry` flag:: You can separate the removal of {product-title} image API objects from the removal of image data in the registry by passing in the `--prune-registry=false` flag. For example, the following command prunes only the API objects, leaving the registry storage untouched: - ++ [source,terminal] ---- $ oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm --prune-registry=false ---- - ++ Then, you can perform a hard prune of the registry to remove the associated image data. This approach can narrow the timing window for race conditions compared to pruning both in a single command. - ++ However, timing windows are not completely eliminated. For example, a pod might still be created that references an image while that image is being identified for pruning. You should track any API objects created during pruning to ensure that they do not reference deleted content. - ++ Re-running the pruning without the `--prune-registry` option, or with `--prune-registry=true`, does not remove the associated registry storage for images previously pruned with `--prune-registry=false`. Those images can only be removed from registry storage by performing a hard prune of the registry. For more information, see "Hard pruning the registry". diff --git a/modules/pruning-images-running-operation.adoc b/modules/pruning-images-running-operation.adoc index 91d38ed2fb9..6cce8846df2 100644 --- a/modules/pruning-images-running-operation.adoc +++ b/modules/pruning-images-running-operation.adoc @@ -6,7 +6,8 @@ [id="pruning-images-running-operation_{context}"] = Running image prune operations -Use the following procedure to run an image prune operation +[role="_abstract"] +Securely remove unused container images from your registry to reclaim the cluster disk space and prevent registry storage exhaustion. .Prerequisites @@ -21,9 +22,9 @@ Use the following procedure to run an image prune operation + [source,terminal] ---- -$ oc adm prune images <1> +$ oc adm prune images ---- -<1> For more information about available pruning options, see "Manual image pruning command options". +For more information about available pruning options, see "Manual image pruning command options". . Review the output to confirm the list of images, image streams, and pods to be removed. diff --git a/modules/pruning-images-secure-insecure.adoc b/modules/pruning-images-secure-insecure.adoc index fd5fc4b9cdb..5987fdaa3f1 100644 --- a/modules/pruning-images-secure-insecure.adoc +++ b/modules/pruning-images-secure-insecure.adoc @@ -6,6 +6,9 @@ [id="pruning-images-secure-insecure_{context}"] = Using secure or insecure connections +[role="_abstract"] +Configure secure or insecure flags when pruning images to communicate with image registries. Setting custom CA certificates or bypassing HTTPS verification prevents connection failures during pruning. + The secure connection is the preferred and recommended approach. It is done over HTTPS protocol with a mandatory certificate verification. The `prune` command always attempts to use it if possible. If it is not possible, in some cases it diff --git a/modules/pruning-images-troubleshooting.adoc b/modules/pruning-images-troubleshooting.adoc index 48c52162724..23f6acd9b3b 100644 --- a/modules/pruning-images-troubleshooting.adoc +++ b/modules/pruning-images-troubleshooting.adoc @@ -4,29 +4,31 @@ :_mod-docs-content-type: REFERENCE [id="pruning-images-troubleshooting_{context}"] -= Image pruning problems += Image pruning issues -[id="pruning-images-not-being-pruned_{context}"] -== Images not being pruned +[role="_abstract"] +Identify the image pruning issues in your cluster and resolve registry connection failures. You can diagnose unpruned images, manage tag revision thresholds, and fix connection or certificate authority errors between the CLI client and registry. + +Images not being pruned:: If your images keep accumulating and the `prune` command removes just a small portion of what you expect, ensure that you understand the image prune conditions that must apply for an image to be considered a candidate for pruning. - ++ Ensure that images you want removed occur at higher positions in each tag history than your chosen tag revisions threshold. For example, consider an old and obsolete image named `sha256:abz`. By running the following command in your namespace, where the image is tagged, the image is tagged three times in a single image stream named `myapp`: - ++ [source,terminal] ---- $ oc get is -n -o go-template='{{range $isi, $is := .items}}{{range $ti, $tag := $is.status.tags}}'\ '{{range $ii, $item := $tag.items}}{{if eq $item.image "sha256:"}}{{$is.metadata.name}}:{{$tag.tag}} at position {{$ii}} out of {{len $tag.items}}\n'\ '{{end}}{{end}}{{end}}{{end}}' ---- - ++ .Example output [source,terminal] ---- @@ -34,11 +36,11 @@ myapp:v2 at position 4 out of 5 myapp:v2.1 at position 2 out of 2 myapp:v2.1-may-2016 at position 0 out of 1 ---- - ++ When default options are used, the image is never pruned because it occurs at position `0` in a history of `myapp:v2.1-may-2016` tag. For an image to be considered for pruning, the administrator must either: - ++ * Specify `--keep-tag-revisions=0` with the `oc adm prune images` command. + [WARNING] @@ -52,56 +54,53 @@ which means `myapp:v2.1` and `myapp:v2.1-may-2016`. * Move the image further in the history, either by running new builds pushing to the same `istag`, or by tagging other image. This is not always desirable for old release tags. - ++ Tags having a date or time of a particular image's build in their names should be avoided, unless the image must be preserved for an undefined amount of time. Such tags tend to have just one image in their history, which prevents them from ever being pruned. -[id="pruning-images-secure-against-insecure_{context}"] -== Using a secure connection against insecure registry +Secure connection to an insecure registry:: If you see a message similar to the following in the output of the `oc adm prune images` command, then your registry is not secured and the `oc adm prune images` client attempts to use a secure connection: - ++ [source,terminal] ---- error: error communicating with registry: Get https://172.30.30.30:5000/healthz: http: server gave HTTP response to HTTPS client ---- - ++ * The recommended solution is to secure the registry. Otherwise, you can force the client to use an insecure connection by appending `--force-insecure` to the command; however, this is not recommended. -[id="pruning-images-insecure-against-secure_{context}"] -== Using an insecure connection against a secured registry +Insecure connection to a secured registry:: If you see one of the following errors in the output of the `oc adm prune images` command, it means that your registry is secured using a certificate signed by a certificate authority other than the one used by `oc adm prune images` client for connection verification: - ++ [source,terminal] ---- error: error communicating with registry: Get http://172.30.30.30:5000/healthz: malformed HTTP response "\x15\x03\x01\x00\x02\x02" error: error communicating with registry: [Get https://172.30.30.30:5000/healthz: x509: certificate signed by unknown authority, Get http://172.30.30.30:5000/healthz: malformed HTTP response "\x15\x03\x01\x00\x02\x02"] ---- - -By default, the certificate authority data stored in the user's configuration files is used; the same is true for communication with the master API. - ++ +By default, the certificate authority data stored in the user's configuration files is used; the same is true for communication with the control plane API. ++ Use the `--certificate-authority` option to provide the right certificate authority for the container image registry server. -[id="pruning-images-wrong-ca_{context}"] -== Using the wrong certificate authority +Wrong certificate authority:: The following error means that the certificate authority used to sign the certificate of the secured container image registry is different from the authority used by the client: - ++ [source,terminal] ---- error: error communicating with registry: Get https://172.30.30.30:5000/: x509: certificate signed by unknown authority ---- - ++ Make sure to provide the right one with the flag `--certificate-authority`. - ++ As a workaround, the `--force-insecure` flag can be added instead. However, this is not recommended. diff --git a/modules/pruning-images.adoc b/modules/pruning-images.adoc index 6f744a0971b..7e70cb465ed 100644 --- a/modules/pruning-images.adoc +++ b/modules/pruning-images.adoc @@ -7,7 +7,9 @@ = Automatically pruning images [role="_abstract"] -To reclaim storage in the {product-registry} in {product-title} and set how long the cluster keeps images, you can configure the automatic image pruner. You set the schedule, suspension, and retention options on the pruning custom resource (CR). +To reclaim storage in the {product-registry} in {product-title} and set how long the cluster keeps images, you can configure the automatic image pruner. + +You set the schedule, suspension, and retention options on the pruning custom resource (CR). .Prerequisites diff --git a/modules/quotas-creating-a-quota.adoc b/modules/quotas-creating-a-quota.adoc index 72c40e7a74c..d4d9c33b5c8 100644 --- a/modules/quotas-creating-a-quota.adoc +++ b/modules/quotas-creating-a-quota.adoc @@ -6,7 +6,8 @@ [id="quotas-creating-a-quota_{context}"] = Creating a quota -You can create a quota to constrain resource usage in a given project. +[role="_abstract"] +Create a defined quota in the project to limit resource consumption and object counts, preventing cluster resource exhaustion. .Procedure diff --git a/modules/quotas-creating-object-count-quotas.adoc b/modules/quotas-creating-object-count-quotas.adoc index 3e705c6470d..481ab85ebf9 100644 --- a/modules/quotas-creating-object-count-quotas.adoc +++ b/modules/quotas-creating-object-count-quotas.adoc @@ -6,38 +6,46 @@ [id="quota-creating-object-count-quotas_{context}"] = Creating object count quotas -You can create an object count quota for all standard namespaced resource types on {product-title}, such as `BuildConfig` and `DeploymentConfig` objects. An object quota count places a defined quota on all standard namespaced resource types. +[role="_abstract"] +Restrict resource consumption and standard object creation in a project by creating an object count quota for standard namespaced resource types. + +You can create an object count quota for all standard namespaced resource types on {product-title}, such as `BuildConfig` and `DeploymentConfig` objects. When using a resource quota, an object is charged against the quota upon creation. These types of quotas are useful to protect against exhaustion of resources. The quota can only be created if there are enough spare resources within the project. .Procedure -To configure an object count quota for a resource: - -. Run the following command: +. To configure an object count quota for a resource, run the following command: + [source,terminal] ---- $ oc create quota \ - --hard=count/.=,count/.= <1> + --hard=count/.=,count/.= ---- -<1> The `` variable is the name of the resource, and `` is the API group, if applicable. Use the `oc api-resources` command for a list of resources and their associated API groups. + +-- +where: + +``:: Specifies the name of the resource +``:: Specifies the API group, if applicable. Use the `oc api-resources` command for a list of resources and their associated API groups. + For example: -+ + [source,terminal] ---- $ oc create quota test \ --hard=count/deployments.apps=2,count/replicasets.apps=4,count/pods=3,count/secrets=4 ---- -+ -.Example output + +The following is an example output: + [source,terminal] ---- resourcequota "test" created ---- -+ + This example limits the listed resources to the hard limit in each project in the cluster. +-- . Verify that the quota was created: + diff --git a/modules/quotas-enforcement.adoc b/modules/quotas-enforcement.adoc index a00104bc114..3cf69384e5d 100644 --- a/modules/quotas-enforcement.adoc +++ b/modules/quotas-enforcement.adoc @@ -2,10 +2,13 @@ // // * applications/quotas/quotas-setting-per-project.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="quota-enforcement_{context}"] = Quota enforcement +[role="_abstract"] +Track project resource usage, such as compute and storage, and automatically deny modifications that exceed defined limits to prevent quota violations. + After a resource quota for a project is first created, the project restricts the ability to create any new resources that may violate a quota constraint until it has calculated updated usage statistics. After a quota is created and usage statistics are updated, the project accepts the creation of new content. When you create or modify resources, your quota usage is incremented immediately upon the request to create or modify the resource. diff --git a/modules/quotas-requests-vs-limits.adoc b/modules/quotas-requests-vs-limits.adoc index c169eff54e0..f786034ff57 100644 --- a/modules/quotas-requests-vs-limits.adoc +++ b/modules/quotas-requests-vs-limits.adoc @@ -2,10 +2,11 @@ // // * applications/quotas/quotas-setting-per-project.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="quotas-requests-vs-limits_{context}"] = Requests versus limits -When allocating compute resources, each container might specify a request and a limit value each for CPU, memory, and ephemeral storage. Quotas can restrict any of these values. +[role="_abstract"] +To manage cluster capacity, use a project quota to restrict container compute resources. When you configure CPU and memory quotas, incoming containers can explicitly request or limit resources to ensure stable performance. If the quota has a value specified for `requests.cpu` or `requests.memory`, then it requires that every incoming container make an explicit request for those resources. If the quota has a value specified for `limits.cpu` or `limits.memory`, then it requires that every incoming container specify an explicit limit for those resources. diff --git a/modules/quotas-requiring-explicit-quota.adoc b/modules/quotas-requiring-explicit-quota.adoc index 149e4661093..295f290a749 100644 --- a/modules/quotas-requiring-explicit-quota.adoc +++ b/modules/quotas-requiring-explicit-quota.adoc @@ -8,6 +8,7 @@ [id="configuring-explicit-resource-quotas_{context}"] = Configuring explicit resource quotas +[role="_abstract"] Configure explicit resource quotas in a project request template to apply specific resource quotas in new projects. .Prerequisites @@ -39,21 +40,23 @@ $ oc adm create-bootstrap-project-template -o yaml > template.yaml namespace: ${PROJECT_NAME} spec: hard: - persistentvolumeclaims: "10" <1> - requests.storage: "50Gi" <2> - gold.storageclass.storage.k8s.io/requests.storage: "10Gi" <3> - silver.storageclass.storage.k8s.io/requests.storage: "20Gi" <4> - silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" <5> - bronze.storageclass.storage.k8s.io/requests.storage: "0" <6> - bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" <7> ----- -<1> The total number of persistent volume claims in a project. -<2> Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value. -<3> Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value. -<4> Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value. -<5> Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value. -<6> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this value is set to `0`, the bronze storage class cannot request storage. -<7> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this value is set to `0`, the bronze storage class cannot create claims. + persistentvolumeclaims: "10" + requests.storage: "50Gi" + gold.storageclass.storage.k8s.io/requests.storage: "10Gi" + silver.storageclass.storage.k8s.io/requests.storage: "20Gi" + silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" + bronze.storageclass.storage.k8s.io/requests.storage: "0" + bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" +---- +where: + +`spec.hard.persistentvolumeclaims`:: The total number of persistent volume claims in a project. +`spec.hard.requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value. +`spec.hard.gold.storageclass.storage.k8s.io/requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value. +`spec.hard.silver.storageclass.storage.k8s.io/requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value. +`spec.hard.silver.storageclass.storage.k8s.io/persistentvolumeclaims`:: Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value. +`spec.hard.bronze.storageclass.storage.k8s.io/requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this value is set to `0`, the bronze storage class cannot request storage. +`spec.hard.bronze.storageclass.storage.k8s.io/persistentvolumeclaims`:: Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this value is set to `0`, the bronze storage class cannot create claims. + .. Create a project request template from the modified `template.yaml` file in the `openshift-config` namespace: + diff --git a/modules/quotas-resources-managed.adoc b/modules/quotas-resources-managed.adoc index a6011f1bf63..cda13119a73 100644 --- a/modules/quotas-resources-managed.adoc +++ b/modules/quotas-resources-managed.adoc @@ -6,7 +6,8 @@ [id="quotas-resources-managed_{context}"] = Resources managed by quotas -The following describes the set of compute resources and object types that can be managed by a quota. +[role="_abstract"] +Review the specific compute resources, storage resources, and object counts that you can manage with a project quota. [NOTE] ==== diff --git a/modules/quotas-sample-resource-quotas-def.adoc b/modules/quotas-sample-resource-quotas-def.adoc index 04b2c5b96b2..8e54c305bbb 100644 --- a/modules/quotas-sample-resource-quotas-def.adoc +++ b/modules/quotas-sample-resource-quotas-def.adoc @@ -2,10 +2,13 @@ // // * applications/quotas/quotas-setting-per-project.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: REFERENCE [id="quotas-sample-resource-quota-definitions_{context}"] = Sample resource quota definitions +[role="_abstract"] +View sample YAML definitions for resource quotas, including specifications for object counts, compute resources, QoS scopes, and storage classes, to configure custom quota manifests for your project. + .`core-object-counts.yaml` [source,yaml] ---- @@ -15,20 +18,21 @@ metadata: name: core-object-counts spec: hard: - configmaps: "10" <1> - persistentvolumeclaims: "4" <2> - replicationcontrollers: "20" <3> - secrets: "10" <4> - services: "10" <5> - services.loadbalancers: "2" <6> + configmaps: "10" + persistentvolumeclaims: "4" + replicationcontrollers: "20" + secrets: "10" + services: "10" + services.loadbalancers: "2" ---- -<1> The total number of `ConfigMap` objects that can exist in the project. -<2> The total number of persistent volume claims (PVCs) that can exist in the -project. -<3> The total number of replication controllers that can exist in the project. -<4> The total number of secrets that can exist in the project. -<5> The total number of services that can exist in the project. -<6> The total number of services of type `LoadBalancer` that can exist in the project. +where: + +`spec.hard.configmaps`:: The total number of `ConfigMap` objects that can exist in the project. +`spec.hard.persistentvolumeclaims`:: The total number of persistent volume claims (PVCs) that can exist in the project. +`spec.hard.replicationcontrollers`:: The total number of replication controllers that can exist in the project. +`spec.hard.secrets`:: The total number of secrets that can exist in the project. +`spec.hard.services`:: The total number of services that can exist in the project. +`spec.hard.services.loadbalancers`:: The total number of services of type `LoadBalancer` that can exist in the project. .`openshift-object-counts.yaml` [source,yaml] @@ -39,9 +43,11 @@ metadata: name: openshift-object-counts spec: hard: - openshift.io/imagestreams: "10" <1> + openshift.io/imagestreams: "10" ---- -<1> The total number of image streams that can exist in the project. +where: + +`spec.hard.openshift.io/imagestreams`:: The total number of image streams that can exist in the project. .`compute-resources.yaml` [source,yaml] @@ -52,18 +58,19 @@ metadata: name: compute-resources spec: hard: - pods: "4" <1> - requests.cpu: "1" <2> - requests.memory: 1Gi <3> - limits.cpu: "2" <4> - limits.memory: 2Gi <5> - + pods: "4" + requests.cpu: "1" + requests.memory: 1Gi + limits.cpu: "2" + limits.memory: 2Gi ---- -<1> The total number of pods in a non-terminal state that can exist in the project. -<2> Across all pods in a non-terminal state, the sum of CPU requests cannot exceed 1 core. -<3> Across all pods in a non-terminal state, the sum of memory requests cannot exceed 1Gi. -<4> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed 2 cores. -<5> Across all pods in a non-terminal state, the sum of memory limits cannot exceed 2Gi. +where: + +`spec.hard.pods`:: The total number of pods in a non-terminal state that can exist in the project. +`spec.hard.requests.cpu`:: Across all pods in a non-terminal state, the sum of CPU requests cannot exceed 1 core. +`spec.hard.requests.memory`:: Across all pods in a non-terminal state, the sum of memory requests cannot exceed 1Gi. +`spec.hard.limits.cpu`:: Across all pods in a non-terminal state, the sum of CPU limits cannot exceed 2 cores. +`spec.hard.limits.memory`:: Across all pods in a non-terminal state, the sum of memory limits cannot exceed 2Gi. .`besteffort.yaml` @@ -75,12 +82,14 @@ metadata: name: besteffort spec: hard: - pods: "1" <1> + pods: "1" scopes: - - BestEffort <2> + - BestEffort ---- -<1> The total number of pods in a non-terminal state with `BestEffort` quality of service that can exist in the project. -<2> Restricts the quota to only matching pods that have `BestEffort` quality of service for either memory or CPU. +where: + +`spec.hard.pods`:: The total number of pods in a non-terminal state with `BestEffort` quality of service that can exist in the project. +`spec.scopes`:: Restricts the quota to only matching pods that have `BestEffort` quality of service for either memory or CPU. .`compute-resources-long-running.yaml` [source,yaml] @@ -91,16 +100,18 @@ metadata: name: compute-resources-long-running spec: hard: - pods: "4" <1> - limits.cpu: "4" <2> - limits.memory: "2Gi" <3> + pods: "4" + limits.cpu: "4" + limits.memory: "2Gi" scopes: - - NotTerminating <4> + - NotTerminating ---- -<1> The total number of pods in a non-terminal state. -<2> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed this value. -<3> Across all pods in a non-terminal state, the sum of memory limits cannot exceed this value. -<4> Restricts the quota to only matching pods where `spec.activeDeadlineSeconds` is set to `nil`. Build pods fall under `NotTerminating` unless the `RestartNever` policy is applied. +where: + +`spec.hard.pods`:: The total number of pods in a non-terminal state. +`spec.hard.limits.cpu`:: Across all pods in a non-terminal state, the sum of CPU limits cannot exceed this value. +`spec.hard.limits.memory`:: Across all pods in a non-terminal state, the sum of memory limits cannot exceed this value. +`spec.scopes`:: Restricts the quota to only matching pods where `spec.activeDeadlineSeconds` is set to `nil`. Build pods fall under `NotTerminating` unless the `RestartNever` policy is applied. .`compute-resources-time-bound.yaml` [source,yaml] @@ -111,16 +122,18 @@ metadata: name: compute-resources-time-bound spec: hard: - pods: "2" <1> - limits.cpu: "1" <2> - limits.memory: "1Gi" <3> + pods: "2" + limits.cpu: "1" + limits.memory: "1Gi" scopes: - - Terminating <4> + - Terminating ---- -<1> The total number of pods in a terminating state. -<2> Across all pods in a terminating state, the sum of CPU limits cannot exceed this value. -<3> Across all pods in a terminating state, the sum of memory limits cannot exceed this value. -<4> Restricts the quota to only matching pods where `spec.activeDeadlineSeconds >=0`. For example, this quota charges for build or deployer pods, but not long running pods like a web server or database. +where: + +`spec.hard.pods`:: The total number of pods in a terminating state. +`spec.hard.limits.cpu`:: Across all pods in a terminating state, the sum of CPU limits cannot exceed this value. +`spec.hard.limits.memory`:: Across all pods in a terminating state, the sum of memory limits cannot exceed this value. +`spec.scopes`:: Restricts the quota to only matching pods where `spec.activeDeadlineSeconds >=0`. For example, this quota charges for build or deployer pods, but not long running pods like a web server or database. .`storage-consumption.yaml` [source,yaml] @@ -131,22 +144,24 @@ metadata: name: storage-consumption spec: hard: - persistentvolumeclaims: "10" <1> - requests.storage: "50Gi" <2> - gold.storageclass.storage.k8s.io/requests.storage: "10Gi" <3> - silver.storageclass.storage.k8s.io/requests.storage: "20Gi" <4> - silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" <5> - bronze.storageclass.storage.k8s.io/requests.storage: "0" <6> - bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" <7> - requests.ephemeral-storage: 2Gi <8> - limits.ephemeral-storage: 4Gi <9> + persistentvolumeclaims: "10" + requests.storage: "50Gi" + gold.storageclass.storage.k8s.io/requests.storage: "10Gi" + silver.storageclass.storage.k8s.io/requests.storage: "20Gi" + silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" + bronze.storageclass.storage.k8s.io/requests.storage: "0" + bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" + requests.ephemeral-storage: 2Gi + limits.ephemeral-storage: 4Gi ---- -<1> The total number of persistent volume claims in a project -<2> Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value. -<3> Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value. -<4> Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value. -<5> Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value. -<6> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot request storage. -<7> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot create claims. -<8> Across all pods in a non-terminal state, the sum of ephemeral storage requests cannot exceed 2Gi. -<9> Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed 4Gi. +where: + +`spec.hard.persistentvolumeclaims`:: The total number of persistent volume claims in a project. +`spec.hard.requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value. +`spec.hard.gold.storageclass.storage.k8s.io/requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value. +`spec.hard.silver.storageclass.storage.k8s.io/requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value. +`spec.hard.silver.storageclass.storage.k8s.io/persistentvolumeclaims`:: Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value. +`spec.hard.bronze.storageclass.storage.k8s.io/requests.storage`:: Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot request storage. +`spec.hard.bronze.storageclass.storage.k8s.io/persistentvolumeclaims`:: Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot create claims. +`spec.hard.requests.ephemeral-storage`:: Across all pods in a non-terminal state, the sum of ephemeral storage requests cannot exceed 2Gi. +`spec.hard.limits.ephemeral-storage`:: Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed 4Gi. diff --git a/modules/quotas-scopes.adoc b/modules/quotas-scopes.adoc index f94adbcae94..19a49daa300 100644 --- a/modules/quotas-scopes.adoc +++ b/modules/quotas-scopes.adoc @@ -2,14 +2,16 @@ // // * applications/quotas/quotas-setting-per-project.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: REFERENCE [id="quotas-scopes_{context}"] = Quota scopes -Each quota can have an associated set of _scopes_. A quota only measures usage for a resource if it matches the intersection of enumerated scopes. +[role="_abstract"] +Measure resource usage with a quota, and add scopes to restrict the allowed set of target resources to prevent validation errors. -Adding a scope to a quota restricts the set of resources to which that quota can apply. Specifying a resource outside of the allowed set results in a validation error. +Each quota can have an associated set of _scopes_. A quota only measures usage for a resource if it matches the intersection of enumerated scopes. +[options="header"] |=== |Scope |Description diff --git a/modules/quotas-selecting-projects.adoc b/modules/quotas-selecting-projects.adoc index 7d687785e47..bc928acc66c 100644 --- a/modules/quotas-selecting-projects.adoc +++ b/modules/quotas-selecting-projects.adoc @@ -6,7 +6,8 @@ [id="quotas-setting-projects_{context}"] = Selecting multiple projects during quota creation -When creating quotas, you can select multiple projects based on annotation selection, label selection, or both. +[role="_abstract"] +To aggregate resource usage and enforce consistent limits across multiple namespaces, you can select target projects by using annotation or label selectors when creating a ClusterResourceQuota object. .Procedure @@ -29,16 +30,16 @@ kind: ClusterResourceQuota metadata: name: for-user spec: - quota: <1> + quota: hard: pods: "10" secrets: "20" selector: - annotations: <2> + annotations: openshift.io/requester: - labels: null <3> + labels: null status: - namespaces: <4> + namespaces: - namespace: ns-one status: hard: @@ -47,7 +48,7 @@ status: used: pods: "1" secrets: "9" - total: <5> + total: hard: pods: "10" secrets: "20" @@ -55,11 +56,13 @@ status: pods: "1" secrets: "9" ---- -<1> The `ResourceQuotaSpec` object that will be enforced over the selected projects. -<2> A simple key-value selector for annotations. -<3> A label selector that can be used to select projects. -<4> A per-namespace map that describes current quota usage in each selected project. -<5> The aggregate usage across all selected projects. +where: + +`spec.quota`:: The `ResourceQuotaSpec` object that will be enforced over the selected projects. +`spec.selector.annotations`:: A simple key-value selector for annotations. +`spec.selector.labels`:: A label selector that can be used to select projects. +`status.namespaces`:: A per-namespace map that describes current quota usage in each selected project. +`status.total`:: The aggregate usage across all selected projects. + This multi-project quota document controls all projects requested by `` using the default project request endpoint. You are limited to 10 pods and 20 secrets. @@ -67,13 +70,17 @@ This multi-project quota document controls all projects requested by ` - --project-label-selector=name=frontend \//<2> +$ oc create clusterresourcequota for-name \ + --project-label-selector=name=frontend \ --hard=pods=10 --hard=secrets=20 ---- + -<1> Both `clusterresourcequota` and `clusterquota` are aliases of the same command. `for-name` is the name of the `ClusterResourceQuota` object. -<2> To select projects by label, provide a key-value pair by using the format `--project-label-selector=key=value`. +-- +where: + +`clusterresourcequota`:: Both `clusterresourcequota` and `clusterquota` are aliases of the same command. `for-name` is the name of the `ClusterResourceQuota` object. +`--project-label-selector`:: To select projects by label, provide a key-value pair by using the format `--project-label-selector=key=value`. +-- + This creates the following `ClusterResourceQuota` object definition: + diff --git a/modules/quotas-selection-granularity.adoc b/modules/quotas-selection-granularity.adoc index 9b25a31a7fc..768755f8739 100644 --- a/modules/quotas-selection-granularity.adoc +++ b/modules/quotas-selection-granularity.adoc @@ -2,11 +2,11 @@ // // * applications/quotas/quotas-setting-across-multiple-projects.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="quotas-selection-granularity_{context}"] = Selection granularity -Because of the locking consideration when claiming quota allocations, the number of -active projects selected by a multi-project quota is an important consideration. -Selecting more than 100 projects under a single multi-project quota can have -detrimental effects on API server responsiveness in those projects. +[role="_abstract"] +When you create a multi-project quota, restrict the number of active projects to avoid degrading API server responsiveness. + +When you configure a multi-project quota using a `ClusterResourceQuota` object, restrict the number of selected active projects to 100 or fewer. Because quota allocation claims require system locking, selecting more than 100 projects under a single multi-project quota can severely degrade API server responsiveness across those projects. diff --git a/modules/quotas-viewing-clusterresourcequotas.adoc b/modules/quotas-viewing-clusterresourcequotas.adoc index ce0b89a3e6e..81b62fa5a28 100644 --- a/modules/quotas-viewing-clusterresourcequotas.adoc +++ b/modules/quotas-viewing-clusterresourcequotas.adoc @@ -6,11 +6,12 @@ [id="quotas-viewing-clusterresourcequotas_{context}"] = Viewing applicable cluster resource quotas -A project administrator is not allowed to create or modify the multi-project quota that limits his or her project, but the administrator is allowed to view the multi-project quota documents that are applied to his or her project. The project administrator can do this via the `AppliedClusterResourceQuota` resource. +[role="_abstract"] +View the multi-project quota documents applied to your project by using the `AppliedClusterResourceQuota` resource. Although, as an administrator, you cannot create or modify multi-project quotas, you can monitor your project's resource limits. .Procedure -. To view quotas applied to a project, run: +* To view quotas applied to a project, run: + [source,terminal] ---- diff --git a/modules/quotas-viewing-quotas.adoc b/modules/quotas-viewing-quotas.adoc index 02b31ef90da..37734403b92 100644 --- a/modules/quotas-viewing-quotas.adoc +++ b/modules/quotas-viewing-quotas.adoc @@ -6,9 +6,10 @@ [id="quota-viewing-quotas_{context}"] = Viewing a quota -You can view usage statistics related to any hard limits defined in a quota for a project by navigating in the web console to the project's *Quota* page. +[role="_abstract"] +View the usage statistics for the hard limits defined in a project quota to monitor resource consumption and plan cluster capacity. -You can also use the CLI to view quota details. +You can view quota usage statistics on the project's *Quota* page in the web console or by using the CLI. .Procedure diff --git a/modules/red-hat-marketplace-features.adoc b/modules/red-hat-marketplace-features.adoc index 643e256a2d4..7e82c83fb07 100644 --- a/modules/red-hat-marketplace-features.adoc +++ b/modules/red-hat-marketplace-features.adoc @@ -6,25 +6,22 @@ [id="red-hat-marketplace-features_{context}"] = Red Hat Marketplace features -Cluster administrators can use link:https://marketplace.redhat.com/en-us/documentation/getting-started[the Red Hat Marketplace] to manage software on {product-title}, give developers self-service access to deploy application instances, and correlate application usage against a quota. +[role="_abstract"] +Cluster administrators can use the Red Hat Marketplace to manage software on {product-title}, give developers self-service access to deploy application instances, and correlate application usage against a quota. -[id="marketplace-clusters_{context}"] -== Connect {product-title} clusters to the Marketplace +Connect {product-title} clusters to the Marketplace:: Cluster administrators can install a common set of applications on {product-title} clusters that connect to the Marketplace. They can also use the Marketplace to track cluster usage against subscriptions or quotas. Users that they add by using the Marketplace have their product usage tracked and billed to their organization. -During the link:https://marketplace.redhat.com/en-us/documentation/clusters[cluster connection process], -a Marketplace Operator is installed that updates the image registry secret, manages the catalog, and reports application usage. +During the cluster connection process, a Marketplace Operator is installed that updates the image registry secret, manages the catalog, and reports application usage. -[id="marketplace-install-applications_{context}"] -== Install applications +Install applications:: -Cluster administrators can link:https://marketplace.redhat.com/en-us/documentation/operators[install Marketplace applications] from within the software catalog in {product-title}, or from the link:https://marketplace.redhat.com[Marketplace web application]. +Cluster administrators can install Marketplace applications from within the software catalog in {product-title}, or from the Marketplace web application. You can access installed applications from the web console by clicking *Ecosystem* -> *Installed Operators*. -[id="marketplace-deploy_{context}"] -== Deploy applications from different perspectives +Deploy applications from different perspectives:: Developers can access newly installed capabilities and deploy Marketplace applications from the web console. @@ -33,6 +30,3 @@ For example, after a database Operator is installed, a developer can create an i Cluster administrators can access Operator installation and application usage information. They can also launch application instances by browsing custom resource definitions (CRDs) in the *Installed Operators* list. include::snippets/snip-unified-perspective-web-console.adoc[] - - - diff --git a/modules/setting-resource-quota-for-extended-resources.adoc b/modules/setting-resource-quota-for-extended-resources.adoc index 89e94fdcdc3..88d02d654e6 100644 --- a/modules/setting-resource-quota-for-extended-resources.adoc +++ b/modules/setting-resource-quota-for-extended-resources.adoc @@ -6,6 +6,9 @@ [id="setting-resource-quota-for-extended-resources_{context}"] = Setting resource quota for extended resources +[role="_abstract"] +Configure extended resources, such as GPUs, in a resource quota file and apply it to a project to enforce strict capacity limits and prevent pods from exceeding available capacity. + Overcommitment of resources is not allowed for extended resources, so you must specify `requests` and `limits` for the same extended resource in a quota. Currently, only quota items with the prefix `requests.` is allowed for extended resources. The following is an example scenario of how to set resource quota for the GPU resource `nvidia.com/gpu`. .Procedure