From 9ed0524769045565696ad3f038ff2831fdfc30dd Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Sat, 11 Jul 2026 00:05:05 +0530 Subject: [PATCH] fix: JTBD audit Install module -- titles, abstracts, prerequisites, CDE terminology - Apply JTBD user-goal titles to all shared Install pages (downstream parity) - Sync :navtitle: and :description: with new titles - Fix title-abstract verb consistency (Get/Get, Confirm/Confirm, Prepare/Prepare) - Add "see Additional resources" bridge sentences in concept bodies so readers know where to find related links (running-at-scale, con_installation-overview) - Move inline links out of concept body text into Additional resources (running-at-scale: 15+ inline links removed, bridges added) - Use {ocp} attribute instead of hardcoded "OpenShift Container Platform" - JTBD section headings in con_installation-overview ("Which installation method should I use?" / "Which deployment scenario matches my environment?") - CDE terminology in con_next-steps-after-installation body bullets - Convert inline admonitions to block-delimited format (NOTE:/IMPORTANT: -> [NOTE]/[IMPORTANT] with ==== delimiters) in 4 files - Add [role="_additional-resources"] where missing - Remove em dashes from descriptions and abstracts - Add admin access prerequisites where missing - Fix operator namespace in verification: use --all-namespaces instead of {prod-namespace} (operator pod runs in openshift-operators, not eclipse-che) - Reorder nav.adoc: move FQDN topic between verification and next-steps (post-install task, not an installation method) Zero content loss: only metadata (titles, navtitles, descriptions, abstracts) changed, bridge sentences added, inline links moved to AR, and verification command fixed. All procedure steps, code blocks, and technical details preserved verbatim. Co-authored-by: Cursor --- modules/install/nav.adoc | 2 +- ...calculating-che-resource-requirements.adoc | 8 +-- .../pages/con_installation-overview.adoc | 25 +++---- .../con_next-steps-after-installation.adoc | 14 ++-- ...installing-the-chectl-management-tool.adoc | 8 +-- ...-the-fully-qualified-domain-name-fqdn.adoc | 8 +-- ...lling-che-in-a-restricted-environment.adoc | 8 +-- ...talling-che-on-minikube-keycloak-oidc.adoc | 5 +- ...installing-che-on-openshift-using-cli.adoc | 8 +-- ...he-on-openshift-using-the-web-console.adoc | 12 ++-- ...he-on-openshift-with-keycloak-as-oidc.adoc | 17 +++-- ...alling-che-on-red-hat-openshift-local.adoc | 7 +- .../install/pages/proc_uninstalling-che.adoc | 10 +-- .../proc_verifying-the-installation.adoc | 11 ++- ...to-install-che-on-openshift-using-cli.adoc | 8 +-- ...he-on-openshift-using-the-web-console.adoc | 8 +-- modules/install/pages/running-at-scale.adoc | 71 ++++++++++--------- ...r-custom-resource-during-installation.adoc | 9 +-- 18 files changed, 130 insertions(+), 109 deletions(-) diff --git a/modules/install/nav.adoc b/modules/install/nav.adoc index f208e6a9c1..a11b36eebf 100644 --- a/modules/install/nav.adoc +++ b/modules/install/nav.adoc @@ -23,10 +23,10 @@ ** Deploy in a restricted environment *** xref:proc_installing-che-in-a-restricted-environment.adoc[] ** xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -** xref:proc_finding-the-fully-qualified-domain-name-fqdn.adoc[] ** Permissions *** xref:ref_permissions-to-install-che-on-openshift-using-cli.adoc[] *** xref:ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc[] * xref:proc_verifying-the-installation.adoc[] +* xref:proc_finding-the-fully-qualified-domain-name-fqdn.adoc[] * xref:con_next-steps-after-installation.adoc[] * xref:proc_uninstalling-che.adoc[] diff --git a/modules/install/pages/calculating-che-resource-requirements.adoc b/modules/install/pages/calculating-che-resource-requirements.adoc index db1c56602c..5664ee7722 100644 --- a/modules/install/pages/calculating-che-resource-requirements.adoc +++ b/modules/install/pages/calculating-che-resource-requirements.adoc @@ -1,15 +1,15 @@ :_content-type: PROCEDURE -:description: Calculate the CPU and memory requirements for the {prod-short} Operator, {devworkspace} Controller, and user workspaces. Accurate resource estimates ensure your cluster can handle the expected number of concurrent users without performance issues. +:description: Size your cluster by calculating the CPU and memory requirements for the {prod-short} Operator, {devworkspace} Controller, and user workspaces so that your cluster can handle the expected number of concurrent users. :keywords: install, calculating-che-resource-requirements -:navtitle: Calculate {prod-short} resource requirements +:navtitle: Size your cluster for {prod-short} :page-aliases: administration-guide:calculating-che-resource-requirements.adoc, plan:calculating-che-resource-requirements.adoc [id="calculating-{prod-id-short}-resource-requirements"] -= Calculate {prod-short} resource requirements += Size your cluster for {prod-short} [role="_abstract"] -Calculate the CPU and memory requirements for the {prod-short} Operator, {devworkspace} Controller, and user workspaces. Accurate resource estimates ensure your cluster can handle the expected number of concurrent users without performance issues. +Size your cluster by calculating the CPU and memory requirements for the {prod-short} Operator, {devworkspace} Controller, and user workspaces so that your cluster can handle the expected number of concurrent users. The {prod-short} Operator, {devworkspace} Controller, and user workspaces consist of a set of pods. The pods contribute to the resource consumption in CPU and memory limits and requests. diff --git a/modules/install/pages/con_installation-overview.adoc b/modules/install/pages/con_installation-overview.adoc index d9a3d0df7f..c151d5bf9b 100644 --- a/modules/install/pages/con_installation-overview.adoc +++ b/modules/install/pages/con_installation-overview.adoc @@ -1,32 +1,33 @@ :_content-type: CONCEPT -:description: {prod-short} deploys on {orch-name} as an Operator that manages a gateway, dashboard, server, and plug-in registry. The installation method you choose — CLI or web console — depends on your cluster environment, security requirements, and need for configuration control. +:description: {prod-short} deploys on {orch-name} as an Operator that manages a gateway, dashboard, server, and plug-in registry. The installation method you choose depends on your cluster environment and need for configuration control. :keywords: install, overview, deployment, operator -:navtitle: {prod-short} installation overview +:navtitle: How the installation works [id="con_installation-overview"] -= {prod-short} installation overview += How the installation works [role="_abstract"] -{prod-short} deploys on {orch-name} as an Operator that manages a gateway, dashboard, server, and plug-in registry. The installation method you choose — CLI or web console — depends on your cluster environment, security requirements, and need for configuration control. +{prod-short} deploys on {orch-name} as an Operator that manages a gateway, dashboard, server, and plug-in registry. The installation method you choose depends on your cluster environment and need for configuration control. {prod-short} consists of an Operator, a user dashboard, a gateway, and a plug-in registry. The Operator manages the full lifecycle of all server components. You deploy {prod-short} by installing the Operator and creating a `CheCluster` custom resource. -== Installation methods +== Which installation method should I use? -{prod-short} supports two installation methods: +`{prod-cli}` command-line tool:: Choose this method when you need to quickly deploy {prod-short} for evaluation, customize the `CheCluster` configuration during installation, or manage {prod-short} from scripts. -`{prod-cli}` command-line tool:: Install and manage {prod-short} from the command line. This method provides the most control over the installation process and supports advanced configuration options during deployment. +{orch-name} web console:: Choose this method when you prefer a graphical workflow through OperatorHub and do not need advanced configuration options during deployment. -{orch-name} web console:: Install the {prod} Operator from OperatorHub and create a `CheCluster` instance through the web console. This method uses the standard {orch-name} Operator installation workflow. +Both methods produce the same result: an Operator subscription and a `CheCluster` custom resource. For step-by-step deployment instructions, see Additional resources. -== Deployment scenarios +== Which deployment scenario matches my environment? -Standard installation:: Deploy {prod-short} on an {orch-name} cluster with internet access. Both the CLI and web console methods are available. +Standard deployment:: Your {orch-name} cluster has internet access. Both installation methods are available. The Operator pulls container images directly from `registry.redhat.io`. -Restricted environment:: Deploy {prod-short} on an air-gapped or disconnected {orch-name} cluster. This scenario requires mirroring container images to a private registry before installation. +Air-gapped deployment:: Your cluster has no internet access. Mirror the required container images and Operator catalogs to a private registry before installation. -External identity provider:: Deploy {prod-short} with {keycloak} as an external OpenID Connect (OIDC) identity provider instead of the default {orch-name} OAuth. This scenario applies when you need to integrate with an existing identity management system. +External identity provider:: Your organization manages authentication through an existing identity system such as {keycloak}. Deploy {prod-short} with an external OIDC provider instead of the default {orch-name} OAuth. +[role="_additional-resources"] .Additional resources * xref:proc_installing-che-on-openshift-using-cli.adoc[] diff --git a/modules/install/pages/con_next-steps-after-installation.adoc b/modules/install/pages/con_next-steps-after-installation.adoc index afe3fbce36..8519a4b69d 100644 --- a/modules/install/pages/con_next-steps-after-installation.adoc +++ b/modules/install/pages/con_next-steps-after-installation.adoc @@ -1,17 +1,17 @@ :_content-type: CONCEPT -:description: After a successful installation, configure the CheCluster resource, connect Git providers, and create your first workspace. +:description: Prepare {prod-short} for your team by completing these configuration tasks before inviting developers: customize the CheCluster resource, connect Git providers, and verify end-to-end functionality with a first workspace. :keywords: install, next steps, configuration, post-install -:navtitle: Next steps after installation +:navtitle: Prepare {prod-short} for your team [id="con_next-steps-after-installation"] -= Next steps after installation += Prepare {prod-short} for your team [role="_abstract"] -After a successful installation, a few configuration tasks remain before your team can start using {prod-short} — customizing the `CheCluster` resource, connecting Git providers, and verifying end-to-end functionality with a first workspace. +Prepare {prod-short} for your team by completing these configuration tasks before inviting developers: customize the `CheCluster` resource, connect Git providers for credential-free repository access, and verify end-to-end functionality with a first workspace. -* Configure the `CheCluster` custom resource to customize {prod-short} behavior. -* Configure OAuth for Git providers so that users can interact with remote Git repositories. -* Create your first workspace from a Git repository URL. +* Verify the platform end-to-end, configure Git provider OAuth, and share the dashboard URL with developers. +* Customize the `CheCluster` custom resource to adjust {prod-short} behavior for your environment. +* Create your first cloud development environment from a Git repository URL. .Additional resources diff --git a/modules/install/pages/installing-the-chectl-management-tool.adoc b/modules/install/pages/installing-the-chectl-management-tool.adoc index 72c6f57b7c..491b298f7b 100644 --- a/modules/install/pages/installing-the-chectl-management-tool.adoc +++ b/modules/install/pages/installing-the-chectl-management-tool.adoc @@ -1,15 +1,15 @@ :_content-type: ASSEMBLY -:description: Install {prod-cli}, the {prod} CLI management tool, on Linux, macOS, or Windows. The {prod-cli} tool lets you deploy, update, and manage {prod-short} from the command line. +:description: Set up {prod-cli} on Linux, macOS, or Windows so that you can deploy, update, and manage {prod-short} from the command line. :keywords: install, installing-the-chectl-management-tool -:navtitle: Install the {prod-cli} management tool +:navtitle: Set up the {prod-cli} command-line tool :page-aliases: administration-guide:installing-the-chectl-management-tool.adoc, plan:installing-the-chectl-management-tool.adoc, installation-guide:using-the-chectl-management-tool.adoc, overview:using-the-chectl-management-tool.adoc, using-the-chectl-management-tool.adoc [id="installing-the-{prod-cli}-management-tool"] -= Install the {prod-cli} management tool += Set up the {prod-cli} command-line tool [role="_abstract"] -Install `{prod-cli}`, the {prod} CLI management tool, on Linux, macOS, or Windows. The `{prod-cli}` tool lets you deploy, update, and manage {prod-short} from the command line. +Set up `{prod-cli}` on Linux, macOS, or Windows so that you can deploy, update, and manage {prod-short} from the command line. include::example$proc_{project-context}-installing-the-chectl-management-tool-on-windows.adoc[leveloffset=+1] diff --git a/modules/install/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc b/modules/install/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc index 9baea25bd1..7cfda41934 100644 --- a/modules/install/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc +++ b/modules/install/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc @@ -1,14 +1,14 @@ :_content-type: PROCEDURE -:description: Retrieve the {prod-short} dashboard URL from the CheCluster custom resource. You need this URL to open the dashboard in a browser or share the endpoint with your development team. +:description: Get the {prod-short} dashboard URL from the CheCluster custom resource so that you can open the dashboard in a browser or share the endpoint with your development team. :keywords: fqdn, domain, url, dashboard -:navtitle: Find the FQDN +:navtitle: Get the dashboard URL to share with your team :page-aliases: finding-the-fully-qualified-domain-name-fqdn.adoc [id="proc_finding-the-fully-qualified-domain-name-fqdn"] -= Find the fully qualified domain name (FQDN) += Get the dashboard URL to share with your team [role="_abstract"] -Retrieve the {prod-short} dashboard URL from the `CheCluster` custom resource. You need this URL to open the dashboard in a browser or share the endpoint with your development team. +Get the {prod-short} dashboard URL from the `CheCluster` custom resource so that you can open the dashboard in a browser or share the endpoint with your development team. [TIP] ==== diff --git a/modules/install/pages/proc_installing-che-in-a-restricted-environment.adoc b/modules/install/pages/proc_installing-che-in-a-restricted-environment.adoc index c4d0723fc6..4b638aac4b 100644 --- a/modules/install/pages/proc_installing-che-in-a-restricted-environment.adoc +++ b/modules/install/pages/proc_installing-che-in-a-restricted-environment.adoc @@ -1,14 +1,14 @@ :_content-type: PROCEDURE -:description: Deploy {prod-short} on an air-gapped {orch-name} cluster by mirroring the required container images and Operator catalogs to a private registry. This procedure covers the additional steps needed when the cluster has no direct internet access. +:description: Deploy {prod-short} on an {orch-name} cluster with no internet access by mirroring the required container images and Operator catalogs to a private registry. :keywords: install, restricted, air-gapped, disconnected, openshift -:navtitle: Install {prod-short} in a restricted environment +:navtitle: Deploy in an air-gapped environment :page-aliases: installation-guide:installing-che-in-restricted-environment.adoc, installation-guide:installing-che-in-a-restricted-environment.adoc, preparing-a-restricted-environment.adoc, configuring-che-to-run-in-a-restricted-environment.adoc, installing-che-in-a-restricted-environment.adoc [id="proc_installing-che-in-a-restricted-environment"] -= Install {prod-short} in a restricted environment on {orch-name} += Deploy in an air-gapped environment [role="_abstract"] -Deploy {prod-short} on an air-gapped {orch-name} cluster by mirroring the required container images and Operator catalogs to a private registry. This procedure covers the additional steps needed when the cluster has no direct internet access. +Deploy {prod-short} on an {orch-name} cluster with no internet access by mirroring the required container images and Operator catalogs to a private registry. On a restricted network, deploying {prod-short} and running workspaces requires the following public resources: diff --git a/modules/install/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc b/modules/install/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc index 2d1af3b578..cde485d6d2 100644 --- a/modules/install/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc +++ b/modules/install/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc @@ -246,7 +246,10 @@ minikube start \ . Configure Keycloak to create the realm, client, and user: + -IMPORTANT: Repeat this step each time you start the Minikube cluster. +[IMPORTANT] +==== +Repeat this step each time you start the Minikube cluster. +==== + [source,bash,subs="+attributes"] ---- diff --git a/modules/install/pages/proc_installing-che-on-openshift-using-cli.adoc b/modules/install/pages/proc_installing-che-on-openshift-using-cli.adoc index 9c5ac3884b..b11e57ca9a 100644 --- a/modules/install/pages/proc_installing-che-on-openshift-using-cli.adoc +++ b/modules/install/pages/proc_installing-che-on-openshift-using-cli.adoc @@ -1,14 +1,14 @@ :_content-type: PROCEDURE -:description: Install the {prod-short} Operator and create a CheCluster instance from the command line by using the {prod-cli} management tool. The CLI method provides full control over configuration options during deployment. +:description: Deploy {prod-short} from the command line using the {prod-cli} management tool so that you have full control over configuration options and can automate the installation. :keywords: install, openshift, cli, chectl -:navtitle: Install {prod-short} on OpenShift using CLI +:navtitle: Deploy using the CLI :page-aliases: installation-guide:installing-che-on-openshift-4-using-cli.adoc, overview:installing-che-on-openshift-4-using-cli.adoc, installing-che-on-openshift-4-using-cli.adoc, installing-che-on-openshift-using-cli.adoc [id="proc_installing-che-on-openshift-using-cli"] -= Install {prod-short} on OpenShift using CLI += Deploy using the CLI [role="_abstract"] -Install the {prod-short} Operator and create a `CheCluster` instance from the command line by using the `{prod-cli}` management tool. The CLI method provides full control over configuration options during deployment. +Deploy {prod-short} from the command line using the `{prod-cli}` management tool so that you have full control over configuration options and can automate the installation. .Prerequisites diff --git a/modules/install/pages/proc_installing-che-on-openshift-using-the-web-console.adoc b/modules/install/pages/proc_installing-che-on-openshift-using-the-web-console.adoc index c7dbf0c751..b93e807339 100644 --- a/modules/install/pages/proc_installing-che-on-openshift-using-the-web-console.adoc +++ b/modules/install/pages/proc_installing-che-on-openshift-using-the-web-console.adoc @@ -1,14 +1,14 @@ :_content-type: PROCEDURE -:description: Deploy the {prod} Operator from OperatorHub and create a CheCluster instance through the {orch-name} web console. This method uses the standard Operator workflow and is suitable when you do not need advanced CLI configuration options. +:description: Deploy {prod-short} through the {orch-name} web console using the standard OperatorHub workflow so that you can install without command-line access. :keywords: install, openshift, web console, operatorhub -:navtitle: Install {prod-short} on OpenShift using the web console +:navtitle: Deploy using the web console :page-aliases: installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc, overview:installing-che-on-openshift-4-using-operatorhub.adoc, creating-an-instance-of-the-che-operator.adoc, installing-che-on-openshift-4-using-operatorhub.adoc, installing-che-on-openshift-using-the-web-console.adoc [id="proc_installing-che-on-openshift-using-the-web-console"] -= Install {prod-short} on OpenShift using the web console += Deploy using the web console [role="_abstract"] -Deploy the {prod} Operator from OperatorHub and create a `CheCluster` instance through the {orch-name} web console. This method uses the standard Operator workflow and is suitable when you do not need advanced CLI configuration options. +Deploy {prod-short} through the {orch-name} web console using the standard OperatorHub workflow so that you can install without command-line access. .Prerequisites @@ -59,11 +59,11 @@ See link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/user .Verification -pass:[] +// vale RedHat.Spelling = NO . In *{prod} instance Specification*, go to *{prod-checluster}*, landing on the *Details* tab. -pass:[] +// vale RedHat.Spelling = YES . Under *Message*, check that there is *None*, which means no errors. diff --git a/modules/install/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc b/modules/install/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc index 833ef7c264..7bcfd9c2b6 100644 --- a/modules/install/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc +++ b/modules/install/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc @@ -1,14 +1,14 @@ :_content-type: PROCEDURE -:description: To enable centralized user authentication through an external identity provider, install {prod-short} on {orch-name} with {keycloak} as the OIDC provider. +:description: Deploy {prod-short} with {keycloak} as the OIDC provider so that you can manage user authentication through your organization's existing identity infrastructure instead of {orch-name} OAuth. :keywords: install, openshift, keycloak, oidc, identity provider -:navtitle: Install {prod-short} on OpenShift with {keycloak} as external identity provider +:navtitle: Deploy using an external identity provider :page-aliases: installing-che-on-openshift-with-keycloak-as-oidc.adoc [id="proc_installing-che-on-openshift-with-keycloak-as-oidc"] -= Install {prod-short} on OpenShift with {keycloak} as external identity provider += Deploy using an external identity provider [role="_abstract"] -To enable centralized user authentication through an external identity provider, install {prod-short} on {orch-name} with {keycloak} as the OIDC provider. +Deploy {prod-short} with {keycloak} as the OIDC provider so that you can manage user authentication through your organization's existing identity infrastructure instead of {orch-name} OAuth. .Prerequisites @@ -36,8 +36,10 @@ To enable centralized user authentication through an external identity provider, + ... Enter `{prod-short}` redirect URL in the *Valid redirect URIs* field. + -NOTE: Run the following command to obtain the `{prod}` redirect URL: -+ +[NOTE] +==== +Run the following command to obtain the `{prod}` redirect URL: + [source,bash,subs="+quotes,+attributes"] ---- echo "$( @@ -45,7 +47,8 @@ echo "$( sed 's|console-openshift-console|{prod-id}|g' )/oauth/callback" ---- - +==== ++ ... Click *Save*. .. Navigate to the *Credentials* tab of the newly created client and copy the *Client secret* value for use when applying the OAuth client secret. diff --git a/modules/install/pages/proc_installing-che-on-red-hat-openshift-local.adoc b/modules/install/pages/proc_installing-che-on-red-hat-openshift-local.adoc index 669900ab42..c91a709dec 100644 --- a/modules/install/pages/proc_installing-che-on-red-hat-openshift-local.adoc +++ b/modules/install/pages/proc_installing-che-on-red-hat-openshift-local.adoc @@ -12,6 +12,8 @@ To evaluate {prod-short} on a local {orch-name} cluster, deploy {prod-short} by .Prerequisites +* You have an active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. + * You have `{prod-cli}` installed. See xref:installing-the-chectl-management-tool.adoc[]. * You have a running instance of {rh-os-local}. See link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local} overview]. @@ -45,7 +47,10 @@ $ crc setup $ crc start --memory 12288 --disk-size=64 --pull-secret-file ____ ---- + -NOTE: Take note of the password for the `kubeadmin` user displayed at the end of the {rh-os-local} initiation. +[NOTE] +==== +Take note of the password for the `kubeadmin` user displayed at the end of the {rh-os-local} initiation. +==== . Enable access to the `oc` command line interface embedded in {rh-os-local}: + diff --git a/modules/install/pages/proc_uninstalling-che.adoc b/modules/install/pages/proc_uninstalling-che.adoc index 076f1ce7ca..54332ac4dd 100644 --- a/modules/install/pages/proc_uninstalling-che.adoc +++ b/modules/install/pages/proc_uninstalling-che.adoc @@ -1,14 +1,14 @@ :_content-type: PROCEDURE -:description: Remove {prod-short} and all related user data from an {orch-name} cluster by using the {prod-cli} management tool. +:description: Remove {prod-short} and all related user data from your {orch-name} cluster when you no longer need the platform or want to perform a clean reinstallation. :keywords: uninstall, remove, delete -:navtitle: Uninstall {prod-short} +:navtitle: Remove {prod-short} from your cluster :page-aliases: installation-guide:uninstalling-che.adoc, installation-guide:uninstalling-che-after-operatorhub-installation.adoc, uninstalling-che-on-openshift.adoc, installation-guide:uninstalling-che-after-chectl-installation.adoc, uninstalling-che-by-using-chectl.adoc, uninstalling-che.adoc [id="proc_uninstalling-che"] -= Uninstall {prod-short} += Remove {prod-short} from your cluster [role="_abstract"] -Remove {prod-short} and all related user data from an {orch-name} cluster by using the `{prod-cli}` management tool. +Remove {prod-short} and all related user data from your {orch-name} cluster when you no longer need the platform or want to perform a clean reinstallation. [WARNING] ==== @@ -17,6 +17,8 @@ Uninstalling {prod-short} removes all {prod-short}-related user data. .Prerequisites +* You have an active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. + * You have the `{prod-cli}` management tool installed. See xref:installing-the-chectl-management-tool.adoc[]. .Procedure diff --git a/modules/install/pages/proc_verifying-the-installation.adoc b/modules/install/pages/proc_verifying-the-installation.adoc index 93ae6b395b..0078418b53 100644 --- a/modules/install/pages/proc_verifying-the-installation.adoc +++ b/modules/install/pages/proc_verifying-the-installation.adoc @@ -1,10 +1,10 @@ :_content-type: PROCEDURE :description: Confirm that {prod-short} is operational before onboarding users by checking the Operator pod, the CheCluster status, and the dashboard URL. :keywords: install, verify, check, status -:navtitle: Verify the {prod-short} installation +:navtitle: Confirm {prod-short} is running [id="proc_verifying-the-installation"] -= Verify the {prod-short} installation += Confirm {prod-short} is running [role="_abstract"] Confirm that {prod-short} is operational before onboarding users by checking the Operator pod, the `CheCluster` status, and the dashboard URL. @@ -20,8 +20,13 @@ Confirm that {prod-short} is operational before onboarding users by checking the + [source,bash,subs="+attributes"] ---- -{orch-cli} get pods -n {prod-namespace} -l app.kubernetes.io/component={prod-id-short}-operator +{orch-cli} get pods --all-namespaces -l app.kubernetes.io/component={prod-id-short}-operator ---- ++ +[NOTE] +==== +On {orch-name}, the Operator pod runs in the namespace where the Subscription was created (typically `openshift-operators` for a cluster-wide installation), not in `{prod-namespace}`. +==== . Verify that the `CheCluster` custom resource reports no errors: + diff --git a/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc b/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc index 01d72ec9bc..933cb32b0b 100644 --- a/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc +++ b/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc @@ -1,14 +1,14 @@ :_content-type: REFERENCE -:description: The following ClusterRole defines the minimum permissions required for a {prod-cli}-based installation of {prod-short}. Apply this role to the service account or user of the installation program before running {prod-cli} server:deploy. +:description: Apply this ClusterRole to the service account or user to grant the minimum permissions required for a {prod-cli}-based installation of {prod-short}. :keywords: permissions, rbac, cli, install -:navtitle: Permissions for CLI installation +:navtitle: Permissions required for CLI installation :page-aliases: permissions-to-install-che-on-openshift-using-cli.adoc [id="ref_permissions-to-install-che-on-openshift-using-cli"] -= Permissions to install {prod-short} on OpenShift using CLI += Permissions required for CLI installation [role="_abstract"] -The following `ClusterRole` defines the minimum permissions required for a `{prod-cli}`-based installation of {prod-short}. Apply this role to the service account or user of the installation program before running `{prod-cli} server:deploy`. +Apply this `ClusterRole` to the service account or user to grant the minimum permissions required for a `{prod-cli}`-based installation of {prod-short}. [source,yaml,subs="+quotes,+attributes"] ---- diff --git a/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc b/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc index cc4433005c..67594756b1 100644 --- a/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc +++ b/modules/install/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc @@ -1,14 +1,14 @@ :_content-type: REFERENCE -:description: The following ClusterRole defines the minimum permissions required for a web-console-based installation of {prod-short}. Apply this role to the user of the installation program before installing the Operator from OperatorHub. +:description: Apply this ClusterRole to the service account or user to grant the minimum permissions required for installing {prod-short} through the {orch-name} web console. :keywords: permissions, rbac, web console, install -:navtitle: Permissions for web console installation +:navtitle: Permissions required for web console installation :page-aliases: permissions-to-install-che-on-openshift-using-the-web-console.adoc [id="ref_permissions-to-install-che-on-openshift-using-the-web-console"] -= Permissions to install {prod-short} on OpenShift using web console += Permissions required for web console installation [role="_abstract"] -The following `ClusterRole` defines the minimum permissions required for a web-console-based installation of {prod-short}. Apply this role to the user of the installation program before installing the Operator from OperatorHub. +Apply this `ClusterRole` to the service account or user to grant the minimum permissions required for installing {prod-short} through the {orch-name} web console. [source,yaml,subs="+quotes,+attributes"] ---- diff --git a/modules/install/pages/running-at-scale.adoc b/modules/install/pages/running-at-scale.adoc index 155b008995..7059d702ca 100644 --- a/modules/install/pages/running-at-scale.adoc +++ b/modules/install/pages/running-at-scale.adoc @@ -1,26 +1,26 @@ :_content-type: CONCEPT -:description: Scaling cloud development environments (CDEs) to thousands of concurrent workspaces imposes high infrastructure demands on etcd storage, Operator memory, and worker node capacity. This topic covers the bottlenecks, tested maximums, and architectural patterns — including multi-cluster deployments — that address these challenges. +:description: Scaling cloud development environments (CDEs) to thousands of concurrent workspaces imposes high infrastructure demands on etcd storage, Operator memory, and worker node capacity. This topic covers the bottlenecks, tested maximums, and architectural patterns, including multi-cluster deployments, that address these challenges. :keywords: install, scale, infrastructure, workload, scalability, CDE, cloud -:navtitle: {prod-short} scalability +:navtitle: Can {prod-short} handle my team's scale? :page-aliases: administration-guide:running-at-scale.adoc, plan:running-at-scale.adoc [id="running-at-scale"] -= {prod-short} scalability += Can {prod-short} handle my team's scale? [role="_abstract"] -Scaling cloud development environments (CDEs) to thousands of concurrent workspaces imposes high infrastructure demands on etcd storage, Operator memory, and worker node capacity. This topic covers the bottlenecks, tested maximums, and architectural patterns — including multi-cluster deployments — that address these challenges. +Scaling cloud development environments (CDEs) to thousands of concurrent workspaces imposes high infrastructure demands on etcd storage, Operator memory, and worker node capacity. This topic covers the bottlenecks, tested maximums, and architectural patterns, including multi-cluster deployments, that address these challenges. Such a scale imposes high infrastructure demands and introduces potential bottlenecks that can impact performance and stability. Addressing these challenges requires meticulous planning, strategic architectural choices, monitoring, and continuous optimization. -CDE workloads are particularly complex to scale. The underlying IDE solutions, such as link:https://github.com/microsoft/vscode[Visual Studio Code - Open Source ("Code - OSS")] or link:https://www.jetbrains.com/remote-development/gateway/[JetBrains Gateway], are designed as single-user applications, not as multitenant services. +CDE workloads are particularly complex to scale. The underlying IDE solutions, such as Visual Studio Code - Open Source ("Code - OSS") or JetBrains Gateway, are designed as single-user applications, not as multitenant services. -== Resource quantity and object maximums +== Tested cluster maximums that constrain scaling -While there is no strict limit on the number of resources in a {kubernetes} cluster, there are certain link:https://kubernetes.io/docs/setup/best-practices/cluster-large/[considerations for large clusters] to remember. +While there is no strict limit on the number of resources in a {kubernetes} cluster, there are certain considerations for large clusters to remember. -link:https://www.redhat.com/en/technologies/cloud-computing/openshift[OpenShift Container Platform], a certified distribution of {kubernetes}, provides a set of tested maximums for various resources. These maximums can serve as an initial guideline for planning your environment: +{ocp}, a certified distribution of {kubernetes}, provides a set of tested maximums for various resources. These maximums can serve as an initial guideline for planning your environment: -.OpenShift Container Platform tested cluster maximums +.{ocp} tested cluster maximums [%header,format=csv] |=== Resource type, Tested maximum @@ -33,21 +33,21 @@ Number of secrets,80000 Number of config maps,90000 |=== -For more details on OpenShift Container Platform tested object maximums, see the link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/scalability_and_performance/planning-your-environment-according-to-object-maximums#planning-your-environment-according-to-object-maximums[OpenShift Container Platform scalability and performance documentation]. +For more details on {ocp} tested object maximums, see Additional resources. For example, it is generally not recommended to have more than 10,000 namespaces due to potential performance and management overhead. In {prod}, each user is allocated a namespace. If you expect the user base to be large, consider spreading workloads across multiple "fit-for-purpose" clusters and potentially using solutions for multi-cluster orchestration. -== Resource requirements +== How workspace size determines cluster capacity When deploying {prod} on {kubernetes}, accurately calculate the resource requirements for each CDE, including memory and CPU or GPU needs. This determines the right sizing of the cluster. In general, the CDE size is limited by and cannot be bigger than the worker node size. The resource requirements for CDEs can vary significantly based on the specific workloads and configurations. A simple CDE might require only a few hundred megabytes of memory. A more complex one might need several gigabytes of memory and multiple CPU cores. -include::example$snip_{project-context}-running-at-scale-calculate-resources.adoc[] +For details about calculating resource requirements, see Additional resources. -== Using etcd +== Why etcd is the primary scaling bottleneck -The primary datastore of {kubernetes} cluster configuration and state is link:https://etcd.io/[etcd]. It holds information about nodes, pods, services, and custom resources. +The primary datastore of {kubernetes} cluster configuration and state is etcd. It holds information about nodes, pods, services, and custom resources. As a distributed key-value store, etcd does not scale well past a certain threshold. As the size of etcd grows, so does the load on the cluster, risking its stability. @@ -56,7 +56,7 @@ As a distributed key-value store, etcd does not scale well past a certain thresh The default etcd size is 2 GB, and the recommended maximum is 8 GB. Exceeding the maximum limit can make the {kubernetes} cluster unstable and unresponsive. Even though the data stored in a `ConfigMap` cannot exceed 1 MiB by design, a few thousand relatively large `ConfigMap` objects can overload etcd storage. ==== -== Object size as a factor +== How large Kubernetes objects strain etcd The size of the objects stored in etcd is also a critical factor. Each object consumes space, and as the number of objects increases, the overall size of etcd grows. The larger the object, the more space it takes. For example, etcd can be overloaded with only a few thousand large {kubernetes} objects. @@ -72,7 +72,7 @@ spec: disableWorkspaceCaBundleMount: true ---- -== {devworkspace} objects +== How DevWorkspace objects affect etcd storage For large {kubernetes} deployments, particularly those involving a high number of custom resources such as `DevWorkspace` objects, which represent CDEs, etcd can become a significant performance bottleneck. @@ -103,9 +103,9 @@ retainTime:: By default, if a workspace was not started for more than 30 days, i schedule:: By default, the pruner runs once per month. -== OLMConfig +== Reduce etcd usage by disabling Copied CSVs -When an Operator is installed by the link:https://olm.operatorframework.io/[Operator Lifecycle Manager (OLM)], a stripped-down copy of its CSV is created in every {namespace} the Operator watches. These “Copied CSVs” communicate which controllers are reconciling resource events in a given namespace. +When an Operator is installed by the Operator Lifecycle Manager (OLM), a stripped-down copy of its CSV is created in every {namespace} the Operator watches. These “Copied CSVs” communicate which controllers are reconciling resource events in a given namespace. On large clusters with hundreds or thousands of namespaces, Copied CSVs consume an unsustainable amount of resources, including OLM memory, etcd storage, and network bandwidth. To eliminate the CSVs copied to every namespace, configure the `OLMConfig` object: @@ -120,67 +120,68 @@ spec: disableCopiedCSVs: true ---- -Additional information about the `disableCopiedCSVs` feature is available in its original link:https://github.com/operator-framework/enhancements/blob/master/enhancements/olm-toggle-copied-csvs.md[enhancement proposal]. +For more information about the `disableCopiedCSVs` feature, see Additional resources. In clusters with many namespaces and cluster-wide Operators, Copied CSVs increase etcd storage usage and memory consumption. Disabling Copied CSVs significantly reduces the data stored in etcd and improves cluster performance and stability. Disabling Copied CSVs also reduces the memory footprint of OLM, as it no longer maintains these additional resources. -For more details about disabling Copied CSVs, see the link:https://olm.operatorframework.io/docs/advanced-tasks/configuring-olm/#disabling-copied-csvs[OLM documentation]. +For more details about disabling Copied CSVs, see Additional resources. -== Cluster Autoscaling +== Scale worker nodes to match workspace demand Although cluster autoscaling is a powerful {kubernetes} feature, you cannot always rely on it. Consider predictive scaling by analyzing load data to detect daily or weekly usage patterns. If your workloads follow a pattern with dramatic peaks throughout the day, provision worker nodes accordingly. For example, if workspaces increase during business hours and decrease during off-hours, predictive scaling adjusts the number of worker nodes. This ensures enough resources are available during peak load while minimizing costs during off-peak hours. -You can also use open-source solutions such as link:https://karpenter.sh/[Karpenter] for configuration and lifecycle management of the worker nodes. Karpenter can dynamically provision and optimize worker nodes based on the specific requirements of the workloads. This helps improve resource utilization and reduce costs. +You can also use open-source solutions such as Karpenter for configuration and lifecycle management of the worker nodes. Karpenter can dynamically provision and optimize worker nodes based on the specific requirements of the workloads. This helps improve resource utilization and reduce costs. -== Multi-cluster +== Distribute workloads across multiple clusters By design, {prod} is not multi-cluster aware. You can only have one instance per cluster. However, you can run {prod} in a multi-cluster environment by deploying {prod} in each cluster. Use a load balancer or Domain Name System (DNS)-based routing to direct traffic to the appropriate instance. This approach distributes the workload across clusters and provides redundancy in case of cluster failures. -== Developer Sandbox example +== How Developer Sandbox runs Dev Spaces across clusters -You can test running {prod-short} in a multi-cluster environment by using the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox], a free trial environment by Red Hat. +You can test running {prod-short} in a multi-cluster environment by using the Developer Sandbox, a free trial environment by Red Hat. -From an infrastructure perspective, the Developer Sandbox consists of multiple link:https://www.redhat.com/en/technologies/cloud-computing/openshift/aws[Red Hat OpenShift Service on AWS (ROSA)] clusters. On each cluster, the productized version of {prod} is installed and configured using link:https://argo-cd.readthedocs.io/en/stable/[Argo CD]. The link:https://workspaces.openshift.com/[workspaces.openshift.com] URL is used as a single entry point to the {prod} instances across clusters. +From an infrastructure perspective, the Developer Sandbox consists of multiple Red Hat OpenShift Service on AWS (ROSA) clusters. On each cluster, the productized version of {prod} is installed and configured using Argo CD. The workspaces.openshift.com URL is used as a single entry point to the {prod} instances across clusters. image::running-at-scale/snip_{project-context}-multi-cluster.png[Scheme of a multi-cluster environment] -You can find implementation details about the multicluster redirector in the link:https://github.com/codeready-toolchain/crw-multicluster-redirector[crw-multicluster-redirector GitHub repository]. +For implementation details about the multicluster redirector, see Additional resources. [IMPORTANT] ==== -The multi-cluster architecture of link:https://workspaces.openshift.com/[workspaces.openshift.com] is part of the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox]. It is a Developer Sandbox-specific solution that cannot be reused as-is in other environments. However, you can use it as a reference for implementing a similar solution well-tailored to your specific multicluster needs. +The multi-cluster architecture of workspaces.openshift.com is part of the Developer Sandbox. It is a Developer Sandbox-specific solution that cannot be reused as-is in other environments. However, you can use it as a reference for implementing a similar solution well-tailored to your specific multicluster needs. ==== -== The multicluster redirector solution for OpenShift Container Platform +== Route developers to the correct cluster automatically -Red Hat offers an open-source, Quarkus-based service that acts as a single gateway for developers. This service automatically redirects users to the correct {prod} instance on the appropriate cluster based on their OpenShift Container Platform group membership. The community-supported version is available in the link:https://github.com/redhat-developer/devspaces-multicluster-redirector[devspaces-multicluster-redirector GitHub repository]. +Red Hat offers an open-source, Quarkus-based service that acts as a single gateway for developers. This service automatically redirects users to the correct {prod} instance on the appropriate cluster based on their {ocp} group membership. For the community-supported version, see Additional resources. -== Architecture and requirements +== What the redirector requires A critical requirement for the multicluster redirector is that all users are provisioned to the host cluster where the redirector is deployed. Users authenticate through the OAuth flow of this cluster, even if they never run workloads there. The host cluster’s OpenShift Container Platform groups determine the routing logic. See the link:https://github.com/redhat-developer/devspaces-multicluster-redirector?tab=readme-ov-file#-deploying-to-openshift[devspaces-multicluster-redirector documentation] for deployment instructions. -== Configuration +== Map OpenShift groups to cluster URLs The routing configuration uses a `ConfigMap` that contains JSON to map OpenShift Container Platform groups to {prod} URLs. The redirector uses this file to update routing tables in real-time without requiring restarts. -== Operational flow +== How authentication and routing work The routing process follows these steps: . Authenticate by using OAuth through a proxy sidecar. . Pass identity and group information through HTTP headers. -. Verify group memberships by using OpenShift Container Platform API queries. +. Verify group memberships by using {ocp} API queries. . Determine the appropriate {prod} URL by using a mapping lookup. . Redirect the user to the designated cluster instance. -If users belong to multiple OpenShift Container Platform groups, they can choose their desired {prod} instance from a selection dashboard. +If users belong to multiple {ocp} groups, they can choose their desired {prod} instance from a selection dashboard. +[role="_additional-resources"] .Additional resources * link:https://che.eclipseprojects.io/2025/04/29/@ilya.buziuk-running-at-scale.html[Running at scale] diff --git a/modules/install/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/install/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc index 4ff59b0789..b50ef1cf75 100644 --- a/modules/install/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc +++ b/modules/install/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -1,13 +1,14 @@ :_content-type: PROCEDURE -:description: Using {prod-cli} to configure the `CheCluster` Custom Resource during installation +:description: Customize the CheCluster Custom Resource during installation so that {prod-short} deploys with your organization's specific settings instead of Operator defaults. :keywords: administration guide -:navtitle: Using {prod-cli} to configure the `CheCluster` Custom Resource during installation +:navtitle: Customize settings during deployment :page-aliases: installation-guide:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc [id="using-{prod-cli}-to-configure-the-checluster-custom-resource-during-installation"] -= Using {prod-cli} to configure the `CheCluster` Custom Resource during installation += Customize settings during deployment -To deploy {prod-short} with a suitable configuration, edit the `CheCluster` Custom Resource YAML file during the installation of {prod-short}. Otherwise, the {prod-short} deployment uses the default configuration parameterized by the Operator. +[role="_abstract"] +Customize the `CheCluster` Custom Resource during installation so that {prod-short} deploys with your organization's specific settings instead of Operator defaults. .Prerequisites