chore: promote Optimize to top-level Antora module (JTBD Phase 2)

gtrivedi88 · cursoragent · gtrivedi88 · commit 66c3e0b8a2d8 · 2026-07-02T16:55:49.000+05:30
Move image caching and autoscaling content from Administration Guide
into a new modules/optimize/ Antora module, following the CCS
'Optimize' category.

- Create modules/optimize/ with nav, 13 pages, 2 partials
- Move image puller and autoscaling pages from admin-guide
- Add page-aliases for backward-compatible redirects
- Fix fluff word "seamless" -&gt; "uninterrupted" in autoscaling page
- Update cross-module xrefs in end-user-guide, admin-guide
- Remove caching and autoscaling sections from admin-guide nav
- Add modules/optimize/nav.adoc to antora.yml

Mirrors downstream devspaces-documentation Optimize guide structure.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/antora.yml b/antora.yml
@@ -9,6 +9,7 @@ nav:
   - modules/install/nav.adoc
   - modules/end-user-guide/nav.adoc
   - modules/upgrade/nav.adoc
+  - modules/optimize/nav.adoc
   - modules/administration-guide/nav.adoc
   - modules/extensions/nav.adoc
   - modules/glossary/nav.adoc
diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc
@@ -14,9 +14,6 @@
 ** xref:configuring-server-components.adoc[]
 *** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[]
 *** xref:advanced-configuration-options-for-the-che-server-component.adoc[]
-** xref:configuring-autoscaling.adoc[]
-*** xref:configuring-number-of-replicas.adoc[]
-*** xref:configuring-machine-autoscaling.adoc[]
 ** xref:configuring-workspaces-globally.adoc[]
 *** xref:limiting-the-number-of-workspaces-that-a-user-can-keep.adoc[]
 *** xref:limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc[]
@@ -25,16 +22,6 @@
 *** xref:configuring-workspaces-nodeselector.adoc[]
 *** xref:configuring-allowed-urls-for-cloud-development-environments.adoc[]
 *** xref:enabling-container-run-capabilities.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:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[]
 ** xref:configuring-observability.adoc[]
 **** xref:the-woopra-telemetry-plugin.adoc[]
 **** xref:creating-a-telemetry-plugin.adoc[]
diff --git a/modules/administration-guide/pages/configuring-server-components.adoc b/modules/administration-guide/pages/configuring-server-components.adoc
@@ -9,4 +9,4 @@
 
 * xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[]
 * xref:advanced-configuration-options-for-the-che-server-component.adoc[]
-* xref:configuring-number-of-replicas.adoc[]
+* xref:optimize:configuring-number-of-replicas.adoc[]
diff --git a/modules/end-user-guide/pages/troubleshooting-slow-workspaces.adoc b/modules/end-user-guide/pages/troubleshooting-slow-workspaces.adoc
@@ -20,7 +20,7 @@ _Role: Administrator_
 +
 When starting a workspace, {orch-name} pulls the images from the registry. A workspace can include many containers meaning that {orch-name} pulls Pod's images (one per container). Depending on the size of the image and the bandwidth, it can take a long time.
 +
-{image-puller-name-short} is a tool that can cache images on each of {orch-name} nodes. As such, pre-pulling images can improve start times. See xref:administration-guide:caching-images-for-faster-workspace-start.adoc[].
+{image-puller-name-short} is a tool that can cache images on each of {orch-name} nodes. As such, pre-pulling images can improve start times. See xref:optimize:caching-images-for-faster-workspace-start.adoc[].
 
 Choosing better storage type::
 +
diff --git a/modules/optimize/nav.adoc b/modules/optimize/nav.adoc
@@ -0,0 +1,14 @@
+.Optimize performance
+* 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: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[]
diff --git a/modules/optimize/pages/caching-images-for-faster-workspace-start.adoc b/modules/optimize/pages/caching-images-for-faster-workspace-start.adoc
@@ -2,7 +2,7 @@
 :description: Caching images for faster workspace start
 :keywords: administration-guide, caching-images-for-faster-workspace-start
 :navtitle: Caching images for faster workspace start
-:page-aliases: .:caching-images-for-faster-workspace-start.adoc
+: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"]
@@ -12,6 +12,8 @@ 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.
 
+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.
diff --git a/modules/optimize/pages/configuring-autoscaling.adoc b/modules/optimize/pages/configuring-autoscaling.adoc
@@ -2,12 +2,14 @@
 :description: Configuring autoscaling
 :keywords: administration-guide, configuring, autoscaling, autoscale, horizontal, scaling, machine
 :navtitle: Configuring autoscaling
-:page-aliases:
+:page-aliases: administration-guide:configuring-autoscaling.adoc
 
 [id="configuring-autoscaling"]
 = Configuring autoscaling
 
 Learn about different aspects of autoscaling for {prod}.
 
+include::partial$snip_persona-admin.adoc[]
+
 * 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
@@ -2,13 +2,15 @@
 :description: Configuring {image-puller-name-short} to pre-pull additional images
 :keywords: administration-guide, image-puller, CLI
 :navtitle: Configuring {image-puller-name-short} to pre-pull additional images
-:page-aliases:
+: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
 
 You can configure {image-puller-name} to pre-pull additional {prod-short} images.
 
+include::partial$snip_persona-admin.adoc[]
+
 .Prerequisites
 
 * Your organization's instance of {prod-short} is installed and running on {kubernetes} cluster.
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
@@ -2,13 +2,15 @@
 :description: Configuring {image-puller-name-short} to pre-pull custom images
 :keywords: administration-guide, image-puller, CLI
 :navtitle: Configuring {image-puller-name-short} to pre-pull custom images
-:page-aliases:
+: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
 
 You can configure {image-puller-name} to pre-pull custom images.
 
+include::partial$snip_persona-admin.adoc[]
+
 .Prerequisites
 
 * Your organization's instance of {prod-short} is installed and running on {kubernetes} cluster.
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
@@ -2,7 +2,7 @@
 :description: Configuring {image-puller-name-short} to pre-pull default {prod-short} images
 :keywords: administration-guide, image-puller, CLI
 :navtitle: Configuring {image-puller-name-short} to pre-pull default {prod-short} images
-:page-aliases:
+: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
@@ -11,6 +11,8 @@ 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
 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.
diff --git a/modules/optimize/pages/configuring-kubernetes-image-puller.adoc b/modules/optimize/pages/configuring-kubernetes-image-puller.adoc
@@ -8,6 +8,8 @@
 
 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[]
diff --git a/modules/optimize/pages/configuring-machine-autoscaling.adoc b/modules/optimize/pages/configuring-machine-autoscaling.adoc
@@ -2,12 +2,14 @@
 :description: Configuring machine autoscaling
 :keywords: administration guide, machine, autoscaling, scaling
 :navtitle: Configuring machine autoscaling
-:page-aliases:
+:page-aliases: administration-guide:configuring-machine-autoscaling.adoc
 
 [id="configuring-machine-autoscaling"]
 = Configuring machine autoscaling
 
-If you configured the cluster to adjust the number of nodes depending on resource needs, you need additional configuration to maintain the seamless operation of {prod-short} workspaces.
+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[]
 
 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
@@ -2,7 +2,7 @@
 :description: Configuring number of replicas for a {prod} container
 :keywords: administration guide, configuring-number-of-replicas
 :navtitle: Configuring number of replicas for a {prod} container
-:page-aliases:
+:page-aliases: administration-guide:configuring-number-of-replicas.adoc
 
 include::partial$proc_configuring-number-of-replicas.adoc[]
 
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
@@ -2,13 +2,15 @@
 :description: Installing the {image-puller-name} operator on {kubernetes} cluster by using CLI
 :keywords: administration-guide, image-puller, operator, CLI
 :navtitle: Installing the {image-puller-name} operator on {kubernetes} cluster by using CLI
-:page-aliases: .:installing-image-puller-on-openshift-using-openshift-templates.adoc,installing-image-puller-on-openshift-using-openshift-templates.adoc
+: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
 
 You can install the {image-puller-name} operator on {kubernetes} cluster by using CLI.
 
+include::partial$snip_persona-admin.adoc[]
+
 .Prerequisites
 
 * An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
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
@@ -2,13 +2,15 @@
 :description: Installing {image-puller-name-short} on OpenShift by using the web console
 :keywords: administration-guide, image-puller, openshift, operator, operatorhub
 :navtitle: Installing {image-puller-name-short} on OpenShift by using the web console
-:page-aliases: .:installing-image-puller-on-openshift-by-using-operatorhub.adoc, installing-image-puller-on-openshift-using-operatorhub.adoc
+: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
 
 You can install the {image-puller-operator-name} on OpenShift by using the OpenShift web console.
 
+include::partial$snip_persona-admin.adoc[]
+
 .Prerequisites
 
 * An OpenShift web console session by a cluster administrator. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/web_console/web-console.html[Accessing the web console].
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
@@ -9,6 +9,8 @@
 
 You can install the {image-puller-name} on OpenShift by using OpenShift `oc` management tool.
 
+include::partial$snip_persona-admin.adoc[]
+
 [IMPORTANT]
 ====
 If the ImagePuller is installed with the `oc` CLI, it cannot be configured via the `CheCluster` Custom Resource.
diff --git a/modules/optimize/pages/installing-kubernetes-image-puller.adoc b/modules/optimize/pages/installing-kubernetes-image-puller.adoc
@@ -8,6 +8,8 @@
 
 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[]
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
@@ -8,6 +8,8 @@
 
 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[]
+
 
 .Prerequisites
 
diff --git a/modules/optimize/partials/snip_configuring-kubernetes-image-puller.adoc b/modules/optimize/partials/snip_configuring-kubernetes-image-puller.adoc
diff --git a/modules/optimize/partials/snip_installing-kubernetes-image-puller.adoc b/modules/optimize/partials/snip_installing-kubernetes-image-puller.adoc
diff --git a/modules/optimize/partials/snip_persona-admin.adoc b/modules/optimize/partials/snip_persona-admin.adoc
@@ -0,0 +1 @@
+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[].

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ _Role: Administrator_`
`20`	`20`	`+`
`21`	`21`	`When starting a workspace, {orch-name} pulls the images from the registry. A workspace can include many containers meaning that {orch-name} pulls Pod's images (one per container). Depending on the size of the image and the bandwidth, it can take a long time.`
`22`	`22`	`+`
`23`		`-{image-puller-name-short} is a tool that can cache images on each of {orch-name} nodes. As such, pre-pulling images can improve start times. See xref:administration-guide:caching-images-for-faster-workspace-start.adoc[].`
	`23`	`+{image-puller-name-short} is a tool that can cache images on each of {orch-name} nodes. As such, pre-pulling images can improve start times. See xref:optimize:caching-images-for-faster-workspace-start.adoc[].`
`24`	`24`
`25`	`25`	`Choosing better storage type::`
`26`	`26`	`+`