From 047523e38cb82fa7b14b5f59cd1bc88e4268cfbf Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Thu, 16 Jul 2026 06:08:32 +0530 Subject: [PATCH] fix: apply JTBD titles and spreadsheet-aligned Optimize nav Rework the Optimize module for JTBD compliance and TOC mapping: - Rename page and nav titles to user-goal JTBD titles - Align abstracts so the first verb matches the title - Flatten nav to one nest level under each job (Plan-like UI) - Add overview, concept, and verify pages from downstream - Move assembly xrefs into Additional resources - Remove unused Deploy/Configure wrapper pages and snips - Fix Vale CheDocs.Attributes on image-puller wording Zero procedure-command loss versus main; Verification sections retained where already present in the JTBD rework. Co-authored-by: Cursor --- modules/optimize/nav.adoc | 17 +++--- ...ing-images-for-faster-workspace-start.adoc | 29 +++++----- .../pages/configuring-autoscaling.adoc | 13 +++-- ...-puller-to-pre-pull-additional-images.adoc | 28 ++++++--- ...mage-puller-to-pre-pull-custom-images.adoc | 26 ++++++--- ...puller-to-pre-pull-default-che-images.adoc | 21 ++++--- .../configuring-kubernetes-image-puller.adoc | 17 ------ .../configuring-machine-autoscaling.adoc | 10 ++-- .../pages/configuring-number-of-replicas.adoc | 4 +- ...ge-caching-speeds-up-workspace-starts.adoc | 25 ++++++++ ...age-puller-on-kubernetes-by-using-cli.adoc | 14 ++--- ...on-openshift-by-using-the-web-console.adoc | 10 ++-- ...g-image-puller-on-openshift-using-cli.adoc | 10 ++-- .../installing-kubernetes-image-puller.adoc | 17 ------ ...of-images-for-kubernetes-image-puller.adoc | 11 ++-- .../pages/verify-optimization-impact.adoc | 57 +++++++++++++++++++ .../optimize/pages/what-you-can-optimize.adoc | 50 ++++++++++++++++ .../proc_configuring-number-of-replicas.adoc | 34 +++++++---- ...p_configuring-kubernetes-image-puller.adoc | 8 --- ...ip_installing-kubernetes-image-puller.adoc | 8 --- .../optimize/partials/snip_persona-admin.adoc | 1 - 21 files changed, 259 insertions(+), 151 deletions(-) delete mode 100644 modules/optimize/pages/configuring-kubernetes-image-puller.adoc create mode 100644 modules/optimize/pages/how-image-caching-speeds-up-workspace-starts.adoc delete mode 100644 modules/optimize/pages/installing-kubernetes-image-puller.adoc create mode 100644 modules/optimize/pages/verify-optimization-impact.adoc create mode 100644 modules/optimize/pages/what-you-can-optimize.adoc delete mode 100644 modules/optimize/partials/snip_configuring-kubernetes-image-puller.adoc delete mode 100644 modules/optimize/partials/snip_installing-kubernetes-image-puller.adoc delete mode 100644 modules/optimize/partials/snip_persona-admin.adoc diff --git a/modules/optimize/nav.adoc b/modules/optimize/nav.adoc index 8ee0ee21ee..d8b474ec94 100644 --- a/modules/optimize/nav.adoc +++ b/modules/optimize/nav.adoc @@ -1,14 +1,15 @@ .Optimize performance +* xref:what-you-can-optimize.adoc[] * xref:caching-images-for-faster-workspace-start.adoc[] -** xref:installing-kubernetes-image-puller.adoc[] -*** xref:installing-image-puller-on-kubernetes-by-using-cli.adoc[] -*** xref:installing-image-puller-on-openshift-using-cli.adoc[] -*** xref:installing-image-puller-on-openshift-by-using-the-web-console.adoc[] -** xref:configuring-kubernetes-image-puller.adoc[] -*** xref:configuring-image-puller-to-pre-pull-default-che-images.adoc[] -*** xref:configuring-image-puller-to-pre-pull-custom-images.adoc[] -*** xref:configuring-image-puller-to-pre-pull-additional-images.adoc[] +** xref:how-image-caching-speeds-up-workspace-starts.adoc[] +** xref:installing-image-puller-on-kubernetes-by-using-cli.adoc[] +** xref:installing-image-puller-on-openshift-using-cli.adoc[] +** xref:installing-image-puller-on-openshift-by-using-the-web-console.adoc[] +** xref:configuring-image-puller-to-pre-pull-default-che-images.adoc[] +** xref:configuring-image-puller-to-pre-pull-custom-images.adoc[] +** xref:configuring-image-puller-to-pre-pull-additional-images.adoc[] ** xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[] * xref:configuring-autoscaling.adoc[] ** xref:configuring-number-of-replicas.adoc[] ** xref:configuring-machine-autoscaling.adoc[] +* xref:verify-optimization-impact.adoc[] diff --git a/modules/optimize/pages/caching-images-for-faster-workspace-start.adoc b/modules/optimize/pages/caching-images-for-faster-workspace-start.adoc index 2319211134..4d90f76543 100644 --- a/modules/optimize/pages/caching-images-for-faster-workspace-start.adoc +++ b/modules/optimize/pages/caching-images-for-faster-workspace-start.adoc @@ -1,29 +1,26 @@ :_content-type: ASSEMBLY -:description: Caching images for faster workspace start +:description: Speed up workspace starts with image caching :keywords: administration-guide, caching-images-for-faster-workspace-start -:navtitle: Caching images for faster workspace start +:navtitle: Speed up workspace starts with image caching :page-aliases: administration-guide:caching-images-for-faster-workspace-start.adoc, .:caching-images-for-faster-workspace-start.adoc [id="caching-images-for-faster-workspace-start"] -= Caching images for faster workspace start += Speed up workspace starts with image caching -To improve the start time performance of {prod-short} workspaces, -use the {image-puller-name-short}, a community-supported {prod-short}-agnostic component that can be used -to pre-pull images for {platforms-name} clusters. +Speed up workspace starts by deploying the {image-puller-name} to pre-cache container images on cluster nodes so that workspaces start in seconds instead of minutes. -include::partial$snip_persona-admin.adoc[] - -The {image-puller-name-short} is an -additional {platforms-name} deployment which creates a _DaemonSet_ that can be -configured to pre-pull relevant {prod-short} workspace images on each node. -These images would already be available when a {prod-short} workspace starts, -therefore improving the workspace start time. - -include::partial$snip_installing-kubernetes-image-puller.adoc[] -include::partial$snip_configuring-kubernetes-image-puller.adoc[] +For an explanation of how image caching works and for deploy and configure procedures, see Additional resources. +[role="_additional-resources"] .Additional resources +* xref:how-image-caching-speeds-up-workspace-starts.adoc[] +* xref:installing-image-puller-on-kubernetes-by-using-cli.adoc[] +* xref:installing-image-puller-on-openshift-using-cli.adoc[] +* xref:installing-image-puller-on-openshift-by-using-the-web-console.adoc[] +* xref:configuring-image-puller-to-pre-pull-default-che-images.adoc[] +* xref:configuring-image-puller-to-pre-pull-custom-images.adoc[] +* xref:configuring-image-puller-to-pre-pull-additional-images.adoc[] * xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[] * link:https://github.com/che-incubator/{image-puller-repository-name}[{image-puller-name} source code repository] diff --git a/modules/optimize/pages/configuring-autoscaling.adoc b/modules/optimize/pages/configuring-autoscaling.adoc index 9acc72577f..1415faa8c4 100644 --- a/modules/optimize/pages/configuring-autoscaling.adoc +++ b/modules/optimize/pages/configuring-autoscaling.adoc @@ -1,15 +1,18 @@ :_content-type: ASSEMBLY -:description: Configuring autoscaling +:description: Scale the platform automatically :keywords: administration-guide, configuring, autoscaling, autoscale, horizontal, scaling, machine -:navtitle: Configuring autoscaling +:navtitle: Scale the platform automatically :page-aliases: administration-guide:configuring-autoscaling.adoc [id="configuring-autoscaling"] -= Configuring autoscaling += Scale the platform automatically -Learn about different aspects of autoscaling for {prod}. +Scale {prod-short} container replicas and cluster nodes automatically so that the platform grows and shrinks with developer demand. -include::partial$snip_persona-admin.adoc[] +For instructions on scaling replicas and preventing workspace failures during node scaling, see Additional resources. + +[role="_additional-resources"] +.Additional resources * xref:configuring-number-of-replicas.adoc[] * xref:configuring-machine-autoscaling.adoc[] diff --git a/modules/optimize/pages/configuring-image-puller-to-pre-pull-additional-images.adoc b/modules/optimize/pages/configuring-image-puller-to-pre-pull-additional-images.adoc index e51556380a..94b4797182 100644 --- a/modules/optimize/pages/configuring-image-puller-to-pre-pull-additional-images.adoc +++ b/modules/optimize/pages/configuring-image-puller-to-pre-pull-additional-images.adoc @@ -1,15 +1,13 @@ :_content-type: PROCEDURE -:description: Configuring {image-puller-name-short} to pre-pull additional images +:description: Cache additional images for faster starts :keywords: administration-guide, image-puller, CLI -:navtitle: Configuring {image-puller-name-short} to pre-pull additional images +:navtitle: Cache additional images for faster starts :page-aliases: administration-guide:configuring-image-puller-to-pre-pull-additional-images.adoc [id="configuring-image-puller-to-pre-pull-additional-images"] -= Configuring {image-puller-name-short} to pre-pull additional images += Cache additional images for faster starts -You can configure {image-puller-name} to pre-pull additional {prod-short} images. - -include::partial$snip_persona-admin.adoc[] +Cache additional images with {image-puller-name} to reduce workspace startup time by ensuring that required images are already cached on each node. .Prerequisites @@ -39,12 +37,24 @@ metadata: name: k8s-image-puller-images namespace: {image-puller-namespace} spec: - images: "__NAME-1__=__IMAGE-1__;__NAME-2__=__IMAGE-2__" <1> + images: "__NAME-1__=__IMAGE-1__;__NAME-2__=__IMAGE-2__" EOF ---- -<1> The semicolon separated list of images ++ +where: ++ +`images`:: The semicolon-separated list of images in `name=image` format. + +.Verification + +* Verify that the image puller `DaemonSet` is running in the `{image-puller-namespace}` namespace: ++ +[source,shell,subs="+attributes"] +---- +{orch-cli} get daemonset -n {image-puller-namespace} +---- -.Addition resources +.Additional resources * https://github.com/che-incubator/kubernetes-image-puller[{image-puller-name} source code repository] diff --git a/modules/optimize/pages/configuring-image-puller-to-pre-pull-custom-images.adoc b/modules/optimize/pages/configuring-image-puller-to-pre-pull-custom-images.adoc index f1c688ac10..f74b54e1c6 100644 --- a/modules/optimize/pages/configuring-image-puller-to-pre-pull-custom-images.adoc +++ b/modules/optimize/pages/configuring-image-puller-to-pre-pull-custom-images.adoc @@ -1,15 +1,13 @@ :_content-type: PROCEDURE -:description: Configuring {image-puller-name-short} to pre-pull custom images +:description: Cache your organization's custom images :keywords: administration-guide, image-puller, CLI -:navtitle: Configuring {image-puller-name-short} to pre-pull custom images +:navtitle: Cache your organization's custom images :page-aliases: administration-guide:configuring-image-puller-to-pre-pull-custom-images.adoc [id="configuring-image-puller-to-pre-pull-custom-images"] -= Configuring {image-puller-name-short} to pre-pull custom images += Cache your organization's custom images -You can configure {image-puller-name} to pre-pull custom images. - -include::partial$snip_persona-admin.adoc[] +Cache your organization's custom images with {image-puller-name} so that workspaces using organization-specific container images start without waiting for large image downloads. .Prerequisites @@ -34,11 +32,23 @@ include::partial$snip_persona-admin.adoc[] "imagePuller": { "enable": true, "spec": { - "images": "__NAME-1__=__IMAGE-1__;__NAME-2__=__IMAGE-2__" <1> + "images": "__NAME-1__=__IMAGE-1__;__NAME-2__=__IMAGE-2__" } } } } }' ---- -<1> The semicolon separated list of images \ No newline at end of file ++ +where: ++ +`images`:: The semicolon-separated list of images in `name=image` format. + +.Verification + +* Verify that the image puller is configured with the custom images: ++ +[source,shell,subs="+attributes"] +---- +{orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.spec.components.imagePuller.spec.images}' +---- \ No newline at end of file diff --git a/modules/optimize/pages/configuring-image-puller-to-pre-pull-default-che-images.adoc b/modules/optimize/pages/configuring-image-puller-to-pre-pull-default-che-images.adoc index 8655e58422..6deb14b908 100644 --- a/modules/optimize/pages/configuring-image-puller-to-pre-pull-default-che-images.adoc +++ b/modules/optimize/pages/configuring-image-puller-to-pre-pull-default-che-images.adoc @@ -1,18 +1,16 @@ :_content-type: PROCEDURE -:description: Configuring {image-puller-name-short} to pre-pull default {prod-short} images +:description: Cache default {prod-short} images on all nodes :keywords: administration-guide, image-puller, CLI -:navtitle: Configuring {image-puller-name-short} to pre-pull default {prod-short} images +:navtitle: Cache default {prod-short} images on all nodes :page-aliases: administration-guide:configuring-image-puller-to-pre-pull-default-che-images.adoc [id="configuring-image-puller-to-pre-pull-default-che-images"] -= Configuring {image-puller-name-short} to pre-pull default {prod-short} images += Cache default {prod-short} images on all nodes -You can configure {image-puller-name} to pre-pull default {prod-short} images. -{prod} operator will control the list of images to pre-pull and automatically updates them +Cache default {prod-short} images on all nodes by enabling {image-puller-name}. +The {prod} Operator controls the list of images to pre-pull and automatically updates them on {prod-short} upgrade. -include::partial$snip_persona-admin.adoc[] - .Prerequisites * Your organization's instance of {prod-short} is installed and running on {kubernetes} cluster. @@ -41,6 +39,15 @@ include::partial$snip_persona-admin.adoc[] }' ---- +.Verification + +* Verify that the image puller is enabled: ++ +[source,shell,subs="+attributes"] +---- +{orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.spec.components.imagePuller.enable}' +---- + .Additional resources * xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[] diff --git a/modules/optimize/pages/configuring-kubernetes-image-puller.adoc b/modules/optimize/pages/configuring-kubernetes-image-puller.adoc deleted file mode 100644 index 0d8f3b4b17..0000000000 --- a/modules/optimize/pages/configuring-kubernetes-image-puller.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:_content-type: PROCEDURE -:description: Configuring {image-puller-name} -:keywords: overview, configuring, image-puller -:navtitle: Configuring {image-puller-name} - -[id="configuring-{image-puller-name}"] -= Configuring {image-puller-name} - -This section contains instructions for configuring the {image-puller-name} for different use cases. - -include::partial$snip_persona-admin.adoc[] - -== Configuring {image-puller-name} - -* xref:configuring-image-puller-to-pre-pull-default-che-images.adoc[] -* xref:configuring-image-puller-to-pre-pull-custom-images.adoc[] -* xref:configuring-image-puller-to-pre-pull-additional-images.adoc[] \ No newline at end of file diff --git a/modules/optimize/pages/configuring-machine-autoscaling.adoc b/modules/optimize/pages/configuring-machine-autoscaling.adoc index 1a43f9b94b..1e8272a925 100644 --- a/modules/optimize/pages/configuring-machine-autoscaling.adoc +++ b/modules/optimize/pages/configuring-machine-autoscaling.adoc @@ -1,15 +1,13 @@ :_content-type: PROCEDURE -:description: Configuring machine autoscaling +:description: Prevent workspace failures during node scaling :keywords: administration guide, machine, autoscaling, scaling -:navtitle: Configuring machine autoscaling +:navtitle: Prevent workspace failures during node scaling :page-aliases: administration-guide:configuring-machine-autoscaling.adoc [id="configuring-machine-autoscaling"] -= Configuring machine autoscaling += Prevent workspace failures during node scaling -If you configured the cluster to adjust the number of nodes depending on resource needs, you need additional configuration to maintain the uninterrupted operation of {prod-short} workspaces. - -include::partial$snip_persona-admin.adoc[] +Prevent workspace failures during node scaling by configuring {prod-short} startup timeouts and pod annotations to work with the cluster autoscaler. Workspaces need special consideration when the autoscaler adds and removes nodes. diff --git a/modules/optimize/pages/configuring-number-of-replicas.adoc b/modules/optimize/pages/configuring-number-of-replicas.adoc index b58782cf49..14a28d1e08 100644 --- a/modules/optimize/pages/configuring-number-of-replicas.adoc +++ b/modules/optimize/pages/configuring-number-of-replicas.adoc @@ -1,7 +1,7 @@ :_content-type: ASSEMBLY -:description: Configuring number of replicas for a {prod} container +:description: Scale {prod-short} for high availability :keywords: administration guide, configuring-number-of-replicas -:navtitle: Configuring number of replicas for a {prod} container +:navtitle: Scale {prod-short} for high availability :page-aliases: administration-guide:configuring-number-of-replicas.adoc include::partial$proc_configuring-number-of-replicas.adoc[] diff --git a/modules/optimize/pages/how-image-caching-speeds-up-workspace-starts.adoc b/modules/optimize/pages/how-image-caching-speeds-up-workspace-starts.adoc new file mode 100644 index 0000000000..1058334e48 --- /dev/null +++ b/modules/optimize/pages/how-image-caching-speeds-up-workspace-starts.adoc @@ -0,0 +1,25 @@ +:_content-type: CONCEPT +:description: How image caching speeds up workspace starts +:navtitle: How image caching speeds up workspace starts + +[id="how-image-caching-speeds-up-workspace-starts"] += How image caching speeds up workspace starts + +To improve workspace start time, use the {image-puller-name-short}, a community-supported {prod-short}-agnostic component that can be used to pre-pull images for {platforms-name} clusters. + +The {image-puller-name-short} is an additional {platforms-name} deployment which creates a _DaemonSet_ that can be configured to pre-pull relevant {prod-short} workspace images on each node. +These images would already be available when a {prod-short} workspace starts, therefore improving the workspace start time. + +For instructions on deploying, configuring, and reviewing cached images, see Additional resources. + +[role="_additional-resources"] +.Additional resources + +* xref:installing-image-puller-on-kubernetes-by-using-cli.adoc[] +* xref:installing-image-puller-on-openshift-using-cli.adoc[] +* xref:installing-image-puller-on-openshift-by-using-the-web-console.adoc[] +* xref:configuring-image-puller-to-pre-pull-default-che-images.adoc[] +* xref:configuring-image-puller-to-pre-pull-custom-images.adoc[] +* xref:configuring-image-puller-to-pre-pull-additional-images.adoc[] +* xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[] +* link:https://github.com/che-incubator/{image-puller-repository-name}[{image-puller-name} source code repository] diff --git a/modules/optimize/pages/installing-image-puller-on-kubernetes-by-using-cli.adoc b/modules/optimize/pages/installing-image-puller-on-kubernetes-by-using-cli.adoc index c60a8ac153..90d7d3db17 100644 --- a/modules/optimize/pages/installing-image-puller-on-kubernetes-by-using-cli.adoc +++ b/modules/optimize/pages/installing-image-puller-on-kubernetes-by-using-cli.adoc @@ -1,15 +1,13 @@ :_content-type: PROCEDURE -:description: Installing the {image-puller-name} operator on {kubernetes} cluster by using CLI +:description: Deploy {image-puller-name-short} on a {kubernetes} cluster :keywords: administration-guide, image-puller, operator, CLI -:navtitle: Installing the {image-puller-name} operator on {kubernetes} cluster by using CLI +:navtitle: Deploy {image-puller-name-short} on a {kubernetes} cluster :page-aliases: administration-guide:installing-image-puller-on-kubernetes-by-using-cli.adoc, .:installing-image-puller-on-openshift-using-openshift-templates.adoc,installing-image-puller-on-openshift-using-openshift-templates.adoc [id="installing-image-puller-on-kubernetes-cluster-by-using-the-cli"] -= Installing {image-puller-name-short} operator on {kubernetes} cluster by using CLI += Deploy {image-puller-name-short} on a {kubernetes} cluster -You can install the {image-puller-name} operator on {kubernetes} cluster by using CLI. - -include::partial$snip_persona-admin.adoc[] +Deploy the {image-puller-name} operator on a {kubernetes} cluster by using CLI. .Prerequisites @@ -21,6 +19,6 @@ include::partial$snip_persona-admin.adoc[] . Click the `Install` button and follow the instruction. -.Addition resources +.Additional resources -* https://github.com/che-incubator/kubernetes-image-puller-operator[{image-puller-operator-name} source code repository] \ No newline at end of file +* link:https://github.com/che-incubator/kubernetes-image-puller-operator[{image-puller-operator-name} source code repository] \ No newline at end of file diff --git a/modules/optimize/pages/installing-image-puller-on-openshift-by-using-the-web-console.adoc b/modules/optimize/pages/installing-image-puller-on-openshift-by-using-the-web-console.adoc index a7000e4500..d87b5ed83f 100644 --- a/modules/optimize/pages/installing-image-puller-on-openshift-by-using-the-web-console.adoc +++ b/modules/optimize/pages/installing-image-puller-on-openshift-by-using-the-web-console.adoc @@ -1,15 +1,13 @@ :_content-type: PROCEDURE -:description: Installing {image-puller-name-short} on OpenShift by using the web console +:description: Deploy {image-puller-name-short} from the web console :keywords: administration-guide, image-puller, openshift, operator, operatorhub -:navtitle: Installing {image-puller-name-short} on OpenShift by using the web console +:navtitle: Deploy {image-puller-name-short} from the web console :page-aliases: administration-guide:installing-image-puller-on-openshift-by-using-the-web-console.adoc, .:installing-image-puller-on-openshift-by-using-operatorhub.adoc, installing-image-puller-on-openshift-using-operatorhub.adoc [id="installing-image-puller-on-openshift-by-using-the-web-console"] -= Installing {image-puller-name-short} on OpenShift by using the web console += Deploy {image-puller-name-short} from the web console -You can install the {image-puller-operator-name} on OpenShift by using the OpenShift web console. - -include::partial$snip_persona-admin.adoc[] +Deploy the {image-puller-operator-name} on OpenShift by using the OpenShift web console. .Prerequisites diff --git a/modules/optimize/pages/installing-image-puller-on-openshift-using-cli.adoc b/modules/optimize/pages/installing-image-puller-on-openshift-using-cli.adoc index bdd1935520..3057deefb9 100644 --- a/modules/optimize/pages/installing-image-puller-on-openshift-using-cli.adoc +++ b/modules/optimize/pages/installing-image-puller-on-openshift-using-cli.adoc @@ -1,15 +1,13 @@ :_content-type: PROCEDURE -:description: Installing {image-puller-name-short} on OpenShift using CLI +:description: Deploy {image-puller-name-short} from the command line :keywords: administration-guide, image-puller, openshift, openshift-templates, CLI -:navtitle: Installing {image-puller-name-short} on OpenShift using CLI +:navtitle: Deploy {image-puller-name-short} from the command line // :page-aliases: .:installing-image-puller-on-openshift-using-openshift-templates.adoc,installing-image-puller-on-openshift-using-openshift-templates.adoc [id="installing-image-puller-on-openshift-using-the-cli"] -= Installing {image-puller-name-short} on OpenShift by using the CLI += Deploy {image-puller-name-short} from the command line -You can install the {image-puller-name} on OpenShift by using OpenShift `oc` management tool. - -include::partial$snip_persona-admin.adoc[] +Deploy the {image-puller-name} on OpenShift by using the OpenShift `oc` management tool. [IMPORTANT] ==== diff --git a/modules/optimize/pages/installing-kubernetes-image-puller.adoc b/modules/optimize/pages/installing-kubernetes-image-puller.adoc deleted file mode 100644 index 7a67ab7904..0000000000 --- a/modules/optimize/pages/installing-kubernetes-image-puller.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {image-puller-name} -:keywords: overview, installing, image-puller -:navtitle: Installing {image-puller-name} - -[id="installing-{image-puller-name}"] -= Installing {image-puller-name} - -Follow the instructions below to install the {image-puller-name} for different use cases. - -include::partial$snip_persona-admin.adoc[] - -== Installing {image-puller-name} - -* xref:installing-image-puller-on-kubernetes-by-using-cli.adoc[] -* xref:installing-image-puller-on-openshift-by-using-the-web-console.adoc[] -* xref:installing-image-puller-on-openshift-using-cli.adoc[] \ No newline at end of file diff --git a/modules/optimize/pages/retrieving-default-list-of-images-for-kubernetes-image-puller.adoc b/modules/optimize/pages/retrieving-default-list-of-images-for-kubernetes-image-puller.adoc index 5e54172ecb..37bb4c5a26 100644 --- a/modules/optimize/pages/retrieving-default-list-of-images-for-kubernetes-image-puller.adoc +++ b/modules/optimize/pages/retrieving-default-list-of-images-for-kubernetes-image-puller.adoc @@ -1,15 +1,12 @@ :_content-type: PROCEDURE -:description: Retrieving the default list of images for {image-puller-name} +:description: Review the default images cached by {image-puller-name-short} :keywords: administration-guide, image-puller -:navtitle: Retrieving the default list of images for {image-puller-name} +:navtitle: Review the default images cached by {image-puller-name-short} [id="retrieving-default-list-of-images-for-kubernetes-image-puller"] -= Retrieving the default list of images for {image-puller-name} - -Learn how to retrieve the default list of images used by {image-puller-name}. This can be helpful for administrators who want to review and configure {image-puller-name-short} to use only a subset of these images in advance. - -include::partial$snip_persona-admin.adoc[] += Review the default images cached by {image-puller-name-short} +Review the default list of images used by {image-puller-name} to decide which images to pre-cache. This list helps administrators configure {image-puller-name-short} to use only a subset of these images in advance. .Prerequisites diff --git a/modules/optimize/pages/verify-optimization-impact.adoc b/modules/optimize/pages/verify-optimization-impact.adoc new file mode 100644 index 0000000000..736caea5af --- /dev/null +++ b/modules/optimize/pages/verify-optimization-impact.adoc @@ -0,0 +1,57 @@ +:_content-type: PROCEDURE +:description: Verify workspace performance after optimization +:navtitle: Verify workspace performance after optimization + +[id="verify-optimization-impact"] += Verify workspace performance after optimization + +Verify that your optimization changes improved workspace startup speed and platform capacity so that you can confirm the investment is working. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Verify that {prod-short} server components are running with the expected replica count: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} get deployment -n {prod-namespace} \ + -o custom-columns='NAME:.metadata.name,REPLICAS:.spec.replicas,AVAILABLE:.status.availableReplicas' +---- ++ +All components should show the configured number of replicas in the `AVAILABLE` column. + +. If you enabled the {image-puller-name}, verify that the DaemonSet is running on all schedulable nodes: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} get daemonset -n {prod-namespace} -l app=kubernetes-image-puller +---- ++ +The `DESIRED` and `READY` columns should show the same number, matching your schedulable node count. + +. Verify that the pre-cached images are present on a node by checking the DaemonSet pod logs: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} logs -n {prod-namespace} -l app=kubernetes-image-puller --tail=5 +---- + +. Start a workspace and observe the startup time. With image pre-caching enabled, workspaces on nodes that have the DaemonSet pod should start within 30 seconds. + +. Verify overall platform health: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} get pods -n {prod-namespace} -o custom-columns='NAME:.metadata.name,READY:.status.containerStatuses[*].ready,STATUS:.status.phase' +---- ++ +All pods should show `Running` status with all containers ready. + +[role="_additional-resources"] +.Additional resources + +* xref:caching-images-for-faster-workspace-start.adoc[] +* xref:configuring-autoscaling.adoc[] diff --git a/modules/optimize/pages/what-you-can-optimize.adoc b/modules/optimize/pages/what-you-can-optimize.adoc new file mode 100644 index 0000000000..e52757e028 --- /dev/null +++ b/modules/optimize/pages/what-you-can-optimize.adoc @@ -0,0 +1,50 @@ +:_content-type: CONCEPT +:description: What you can optimize in {prod-short} +:navtitle: What you can optimize in {prod-short} + +[id="what-you-can-optimize"] += What you can optimize in {prod-short} + +Identify the performance areas you can tune in {prod-short} so that you choose the right optimization strategy for your deployment. + +A default {prod-short} installation runs all server components with a single replica and no image pre-caching. This configuration works for small teams but can cause slow workspace starts and limited capacity as usage grows. You can optimize two areas independently: + +Workspace startup speed:: +When a developer starts a workspace, {orch-name} pulls container images from the registry. On a cold node, this can take several minutes. The {image-puller-name} pre-caches images on every node so that workspaces start in seconds. For instructions on deploying and configuring the {image-puller-name-short}, see Additional resources. + +Platform scaling:: +By default, each {prod-short} server component runs with one replica. You can increase replicas for high availability and configure cluster autoscaling to add worker nodes when demand exceeds capacity. For instructions on configuring autoscaling, see Additional resources. + +== When to optimize + +Consider optimization when you observe: + +* Workspace startup taking more than 60 seconds on nodes that have not previously run workspaces. +* Dashboard or gateway timeouts during peak usage when many developers start workspaces simultaneously. +* Workspace scheduling failures because of insufficient node resources. + +== What affects workspace startup and platform capacity + +[cols="1,2,1",options="header"] +|=== +| Area | Control | Default + +| Image pre-caching +| `CheCluster` CR field `spec.components.imagePuller.enable` +| `false` (disabled) + +| Server replicas +| `CheCluster` CR field `spec.components..deployment.replicas` +| `1` for each component + +| Node autoscaling +| `MachineAutoscaler` and `ClusterAutoscaler` custom resources +| Not configured +|=== + +[role="_additional-resources"] +.Additional resources + +* xref:caching-images-for-faster-workspace-start.adoc[] +* xref:configuring-autoscaling.adoc[] +* xref:administration-guide:monitoring-che.adoc[] diff --git a/modules/optimize/partials/proc_configuring-number-of-replicas.adoc b/modules/optimize/partials/proc_configuring-number-of-replicas.adoc index de43286ffa..f3d7eef10b 100644 --- a/modules/optimize/partials/proc_configuring-number-of-replicas.adoc +++ b/modules/optimize/partials/proc_configuring-number-of-replicas.adoc @@ -1,11 +1,9 @@ :_content-type: PROCEDURE [id="configuring-number-of-replicas"] -= Configuring the number of replicas += Scale {prod-short} for high availability -To configure the number of replicas for {prod-short} operands using {kubernetes} `HorizontalPodAutoscaler` -(HPA), you can define an `HPA` resource for deployment. The `HPA` dynamically adjusts the number -of replicas based on specified metrics. +Scale {prod-short} for high availability by defining a {kubernetes} `HorizontalPodAutoscaler` (HPA) resource for {prod-short} operands. The HPA dynamically adjusts the number of replicas based on specified metrics. .Procedure @@ -22,18 +20,22 @@ spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment - name: ____ <1> + name: ____ ... ---- -<1> The `` corresponds to the one following deployments: ++ +where: ++ +`____`:: One of the following deployments: ++ * `{prod-deployment}` * `che-gateway` * `{prod-deployment}-dashboard` * `plugin-registry` * `devfile-registry` - -.Create a `HorizontalPodAutoscaler` for {prod-deployment} deployment: -==== ++ +For example: ++ [source,yaml,subs="+attributes,+quotes"] ---- apiVersion: autoscaling/v2 @@ -56,9 +58,17 @@ spec: type: Utilization averageUtilization: 75 ---- -In this example, the HPA is targeting the Deployment named {prod-deployment}, with a minimum of 2 replicas, a maximum of 5 replicas -and scaling based on CPU utilization. -==== ++ +In this example, the HPA targets the `{prod-deployment}` deployment with a minimum of 2 replicas, a maximum of 5 replicas, and scales based on CPU utilization. + +.Verification + +* Verify that the HPA resource is created and targeting the correct deployment: ++ +[source,shell,subs="+quotes,+attributes"] +---- +{orch-cli} get hpa -n {prod-namespace} +---- .Additional resources * link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale[Horizontal Pod Autoscaling] diff --git a/modules/optimize/partials/snip_configuring-kubernetes-image-puller.adoc b/modules/optimize/partials/snip_configuring-kubernetes-image-puller.adoc deleted file mode 100644 index 04f88e3a17..0000000000 --- a/modules/optimize/partials/snip_configuring-kubernetes-image-puller.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:_content-type: SNIPPET - -.Configuring {image-puller-name} - -* xref:configuring-image-puller-to-pre-pull-default-che-images.adoc[] -* xref:configuring-image-puller-to-pre-pull-custom-images.adoc[] -* xref:configuring-image-puller-to-pre-pull-additional-images.adoc[] - diff --git a/modules/optimize/partials/snip_installing-kubernetes-image-puller.adoc b/modules/optimize/partials/snip_installing-kubernetes-image-puller.adoc deleted file mode 100644 index 35e66c6e4c..0000000000 --- a/modules/optimize/partials/snip_installing-kubernetes-image-puller.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:_content-type: SNIPPET - -.Installing {image-puller-name} - -* xref:installing-image-puller-on-kubernetes-by-using-cli.adoc[] -* xref:installing-image-puller-on-openshift-by-using-the-web-console.adoc[] -* xref:installing-image-puller-on-openshift-using-cli.adoc[] - diff --git a/modules/optimize/partials/snip_persona-admin.adoc b/modules/optimize/partials/snip_persona-admin.adoc deleted file mode 100644 index 9857252bbf..0000000000 --- a/modules/optimize/partials/snip_persona-admin.adoc +++ /dev/null @@ -1 +0,0 @@ -This page is for platform administrators who install, configure, and manage {prod-short} on {orch-name} clusters. To learn more about common roles and example tasks referenced in {prod-short} documentation, see xref:discover:roles-and-tasks.adoc[].