From 64c697ccb1ec09b1098f12c664a249f9e7047ccb Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Mon, 6 Jul 2026 16:10:54 +0530 Subject: [PATCH] chore: promote Configure to top-level Antora module (JTBD Phase 4) Create modules/configure/ with 37 pages moved from administration-guide. Full JTBD checklist applied: cluster-validated user journey (DS 3.28.2 on ROSA), titles rewritten to user goals, abstracts fixed, persona callouts added. Nav structure (9 user-goal sections, max 2 levels): - Customize the central configuration - Inject configuration into server components - Customize the developer dashboard - Organize workspace namespaces - Set workspace policies for all users - Set up network access for workspaces - Control where workspace data is stored - Enable fuse-overlayfs for container builds - Back up workspaces 6 empty container pages deleted (configuring-che, configuring-networking, configuring-storage, configuring-server-components, configuring-dashboard, configuring-workspaces-globally). page-aliases preserved on redirect targets. Replaces stale PR #3132. Co-authored-by: Cursor --- antora.yml | 1 + .../proc_che-configuring-ingresses.adoc | 4 +- ...ncealing-editors-additional-resources.adoc | 2 +- .../examples/snip_che-curated-access.adoc | 2 +- ...ring-che-with-self-signed-certificate.adoc | 2 +- modules/administration-guide/nav.adoc | 86 +++++------------- .../pages/adding-labels-and-annotations.adoc | 12 --- .../pages/concealing-editors.adoc | 2 +- .../pages/configuring-che.adoc | 10 -- .../pages/configuring-dashboard.adoc | 23 ----- .../pages/configuring-networking.adoc | 16 ---- .../pages/configuring-server-components.adoc | 12 --- .../pages/configuring-server-logging.adoc | 4 +- .../pages/configuring-storage.adoc | 28 ------ ...configuring-the-open-vsx-registry-url.adoc | 2 +- .../configuring-workspaces-globally.adoc | 24 ----- .../pages/creating-a-telemetry-plugin.adoc | 4 +- ...ions-for-microsoft-visual-studio-code.adoc | 2 +- .../pages/show-deprecated-editors.adoc | 4 +- .../pages/the-woopra-telemetry-plugin.adoc | 4 +- .../partials/con_logging-http-traffic.adoc | 4 +- ...roc_enabling-and-exposing-che-metrics.adoc | 2 +- .../proc_che-configuring-ingresses.adoc | 31 +++++++ ...ring-che-with-self-signed-certificate.adoc | 1 + .../tools-container-example.png | Bin modules/configure/nav.adoc | 50 ++++++++++ .../pages/adding-labels-and-annotations.adoc | 14 +++ ...-options-for-the-che-server-component.adoc | 12 +-- ...ster-custom-resource-fields-reference.adoc | 17 ++-- .../pages/con_persistent-user-home.adoc | 9 +- .../pages/configuring-a-user-namespace.adoc | 21 +++-- ...ls-for-cloud-development-environments.adoc | 18 +++- .../pages/configuring-che-hostname.adoc | 10 +- ...ring-che-with-self-signed-certificate.adoc | 11 ++- .../pages/configuring-fuse.adoc | 17 ++-- .../configuring-getting-started-samples.adoc | 10 +- ...netes-namespace-creation-on-openshift.adoc | 7 +- .../configuring-namespace-provisioning.adoc | 9 +- .../pages/configuring-network-policies.adoc | 11 ++- .../pages/configuring-proxy.adoc | 17 +++- .../pages/configuring-storage-classes.adoc | 16 +++- .../pages/configuring-storage-sizes.adoc | 14 ++- .../configuring-the-storage-strategy.adoc | 13 ++- ...onfiguring-workspace-target-namespace.adoc | 13 ++- ...ring-workspaces-endpoints-base-domain.adoc | 17 +++- .../configuring-workspaces-nodeselector.adoc | 15 ++- ...omizing-openshift-che-branding-images.adoc | 9 +- ...itories-with-self-signed-certificates.adoc | 12 ++- ...-backup-integrated-openshift-registry.adoc | 15 ++- ...workspace-backup-regular-oci-registry.adoc | 14 ++- .../pages/devworkspace-backup.adoc | 9 +- ...ling-access-to-dev-fuse-for-openshift.adoc | 12 ++- .../enabling-container-run-capabilities.adoc | 7 +- .../enabling-fuse-for-all-workspaces.adoc | 14 ++- ...un-multiple-workspaces-simultaneously.adoc | 12 ++- .../importing-untrusted-tls-certificates.adoc | 10 +- ...er-of-workspaces-that-a-user-can-keep.adoc | 11 ++- ...that-all-users-can-run-simultaneously.adoc | 15 ++- ...ng-workloads-using-the-che-server-api.adoc | 13 ++- ...environment-variable-into-a-container.adoc | 19 ++-- .../provisioning-namespaces-in-advance.adoc | 14 ++- ...anding-the-checluster-custom-resource.adoc | 17 ++-- ...figure-the-checluster-custom-resource.adoc | 10 +- ...ing-che-server-advanced-configuration.adoc | 13 +-- .../partials/proc_configuring-routes.adoc | 2 +- .../proc_configuring-server-logging.adoc | 10 +- ...-configmap-as-a-file-into-a-container.adoc | 10 +- ...nfigmap-as-a-subpath-into-a-container.adoc | 10 +- ...environment-variable-into-a-container.adoc | 26 ++---- ...ip_defining-dwo-namespace-for-backups.adoc | 0 ...ecret-or-a-configmap-into-a-container.adoc | 21 ++--- modules/discover/pages/che-operator.adoc | 2 +- modules/discover/pages/che-server.adoc | 2 +- modules/discover/pages/roles-and-tasks.adoc | 2 +- .../end-user-guide/pages/accessing-fuse.adoc | 4 +- .../enabling-overlay-with-a-configmap.adoc | 2 +- .../restoring-workspaces-from-backups.adoc | 2 +- .../using-a-git-provider-access-token.adoc | 4 +- ...using-the-fuse-overlay-storage-driver.adoc | 2 +- .../partials/proc_creating-workspaces.adoc | 2 +- .../con_next-steps-after-installation.adoc | 2 +- ...lling-che-in-a-restricted-environment.adoc | 2 +- ...talling-che-on-minikube-keycloak-oidc.adoc | 2 +- .../proc_installing-che-on-minikube.adoc | 2 +- ...r-custom-resource-during-installation.adoc | 4 +- .../configuring-advanced-authorization.adoc | 2 +- ...user-data-in-compliance-with-the-gdpr.adoc | 4 +- .../secure/pages/security-best-practices.adoc | 2 +- 88 files changed, 499 insertions(+), 451 deletions(-) delete mode 100644 modules/administration-guide/pages/adding-labels-and-annotations.adoc delete mode 100644 modules/administration-guide/pages/configuring-che.adoc delete mode 100644 modules/administration-guide/pages/configuring-dashboard.adoc delete mode 100644 modules/administration-guide/pages/configuring-networking.adoc delete mode 100644 modules/administration-guide/pages/configuring-server-components.adoc delete mode 100644 modules/administration-guide/pages/configuring-storage.adoc delete mode 100644 modules/administration-guide/pages/configuring-workspaces-globally.adoc create mode 100644 modules/configure/examples/proc_che-configuring-ingresses.adoc create mode 100644 modules/configure/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc rename modules/{administration-guide => configure}/images/persistent-user-home/tools-container-example.png (100%) create mode 100644 modules/configure/nav.adoc create mode 100644 modules/configure/pages/adding-labels-and-annotations.adoc rename modules/{administration-guide => configure}/pages/advanced-configuration-options-for-the-che-server-component.adoc (56%) rename modules/{administration-guide => configure}/pages/checluster-custom-resource-fields-reference.adoc (95%) rename modules/{administration-guide => configure}/pages/con_persistent-user-home.adoc (90%) rename modules/{administration-guide => configure}/pages/configuring-a-user-namespace.adoc (94%) rename modules/{administration-guide => configure}/pages/configuring-allowed-urls-for-cloud-development-environments.adoc (56%) rename modules/{administration-guide => configure}/pages/configuring-che-hostname.adoc (87%) rename modules/{administration-guide => configure}/pages/configuring-che-with-self-signed-certificate.adoc (79%) rename modules/{administration-guide => configure}/pages/configuring-fuse.adoc (59%) rename modules/{administration-guide => configure}/pages/configuring-getting-started-samples.adoc (83%) rename modules/{administration-guide => configure}/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc (86%) rename modules/{administration-guide => configure}/pages/configuring-namespace-provisioning.adoc (77%) rename modules/{administration-guide => configure}/pages/configuring-network-policies.adoc (92%) rename modules/{administration-guide => configure}/pages/configuring-proxy.adoc (84%) rename modules/{administration-guide => configure}/pages/configuring-storage-classes.adoc (78%) rename modules/{administration-guide => configure}/pages/configuring-storage-sizes.adoc (85%) rename modules/{administration-guide => configure}/pages/configuring-the-storage-strategy.adoc (66%) rename modules/{administration-guide => configure}/pages/configuring-workspace-target-namespace.adoc (78%) rename modules/{administration-guide => configure}/pages/configuring-workspaces-endpoints-base-domain.adoc (67%) rename modules/{administration-guide => configure}/pages/configuring-workspaces-nodeselector.adoc (79%) rename modules/{administration-guide => configure}/pages/customizing-openshift-che-branding-images.adoc (88%) rename modules/{administration-guide => configure}/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc (89%) rename modules/{administration-guide => configure}/pages/devworkspace-backup-integrated-openshift-registry.adoc (69%) rename modules/{administration-guide => configure}/pages/devworkspace-backup-regular-oci-registry.adoc (83%) rename modules/{administration-guide => configure}/pages/devworkspace-backup.adoc (96%) rename modules/{administration-guide => configure}/pages/enabling-access-to-dev-fuse-for-openshift.adoc (94%) rename modules/{administration-guide => configure}/pages/enabling-container-run-capabilities.adoc (91%) rename modules/{administration-guide => configure}/pages/enabling-fuse-for-all-workspaces.adoc (83%) rename modules/{administration-guide => configure}/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc (83%) rename modules/{administration-guide => configure}/pages/importing-untrusted-tls-certificates.adoc (96%) rename modules/{administration-guide => configure}/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc (82%) rename modules/{administration-guide => configure}/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc (72%) rename modules/{administration-guide => configure}/pages/managing-workloads-using-the-che-server-api.adoc (66%) rename modules/{administration-guide => configure}/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc (60%) rename modules/{administration-guide => configure}/pages/provisioning-namespaces-in-advance.adoc (72%) rename modules/{administration-guide => configure}/pages/understanding-the-checluster-custom-resource.adoc (75%) rename modules/{administration-guide => configure}/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc (78%) rename modules/{administration-guide => configure}/partials/con_understanding-che-server-advanced-configuration.adoc (75%) rename modules/{administration-guide => configure}/partials/proc_configuring-routes.adoc (95%) rename modules/{administration-guide => configure}/partials/proc_configuring-server-logging.adoc (67%) rename modules/{administration-guide => configure}/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc (93%) rename modules/{administration-guide => configure}/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc (93%) rename modules/{administration-guide => configure}/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc (87%) rename modules/{administration-guide => configure}/partials/snip_defining-dwo-namespace-for-backups.adoc (100%) rename modules/{administration-guide => configure}/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc (84%) diff --git a/antora.yml b/antora.yml index 3fdc2afb7c..4a40348cf1 100644 --- a/antora.yml +++ b/antora.yml @@ -11,6 +11,7 @@ nav: - modules/upgrade/nav.adoc - modules/secure/nav.adoc - modules/optimize/nav.adoc + - modules/configure/nav.adoc - modules/administration-guide/nav.adoc - modules/extensions/nav.adoc - modules/glossary/nav.adoc diff --git a/modules/administration-guide/examples/proc_che-configuring-ingresses.adoc b/modules/administration-guide/examples/proc_che-configuring-ingresses.adoc index 072aa083be..eeaf036413 100644 --- a/modules/administration-guide/examples/proc_che-configuring-ingresses.adoc +++ b/modules/administration-guide/examples/proc_che-configuring-ingresses.adoc @@ -12,7 +12,7 @@ You can configure {orch-ingress} labels and annotations, if your organization re .Procedure -* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +* Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml,subs="+quotes,+attributes"] ---- @@ -28,4 +28,4 @@ spec: * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc b/modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc index 3c98c8da29..ee60818e09 100644 --- a/modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc +++ b/modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc @@ -4,6 +4,6 @@ * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] * {editor-definition-samples-link} diff --git a/modules/administration-guide/examples/snip_che-curated-access.adoc b/modules/administration-guide/examples/snip_che-curated-access.adoc index 0e75123a69..f75cde5fe9 100644 --- a/modules/administration-guide/examples/snip_che-curated-access.adoc +++ b/modules/administration-guide/examples/snip_che-curated-access.adoc @@ -1,4 +1,4 @@ With this setup, you achieve a curated access to {prod-short}, where cluster administrators control provisioning for each user and can explicitly configure various settings including resource limits and quotas. -Learn more about project provisioning in the xref:administration-guide:provisioning-namespaces-in-advance.adoc[]. +Learn more about project provisioning in the xref:configure:provisioning-namespaces-in-advance.adoc[]. diff --git a/modules/administration-guide/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc b/modules/administration-guide/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc index 2665522d6d..7c1614c126 100644 --- a/modules/administration-guide/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc +++ b/modules/administration-guide/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc @@ -1 +1 @@ -* xref:configuring-che-with-self-signed-certificate.adoc[] \ No newline at end of file +* xref:configure:configuring-che-with-self-signed-certificate.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 844c4820c7..0b5a2d7b84 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -1,69 +1,19 @@ .Administration Guide -* xref:configuring-che.adoc[] -** xref:understanding-the-checluster-custom-resource.adoc[] -*** xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -*** xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] -*** xref:checluster-custom-resource-fields-reference.adoc[] -** xref:configuring-namespace-provisioning.adoc[] -*** xref:configuring-workspace-target-namespace.adoc[] -*** xref:provisioning-namespaces-in-advance.adoc[] -*** xref:configuring-a-user-namespace.adoc[] -*** xref:configuring-kubernetes-namespace-creation-on-openshift.adoc[] -** 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-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[] -*** xref:enabling-users-to-run-multiple-workspaces-simultaneously.adoc[] -*** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] -*** xref:configuring-workspaces-nodeselector.adoc[] -*** xref:configuring-allowed-urls-for-cloud-development-environments.adoc[] -*** xref:enabling-container-run-capabilities.adoc[] -** xref:configuring-observability.adoc[] -**** xref:the-woopra-telemetry-plugin.adoc[] -**** xref:creating-a-telemetry-plugin.adoc[] -*** xref:configuring-server-logging.adoc[] -*** xref:collecting-logs-using-chectl.adoc[] -**** xref:monitoring-the-dev-workspace-operator.adoc[] -**** xref:monitoring-che.adoc[] -** xref:configuring-networking.adoc[] -*** xref:configuring-network-policies.adoc[] -*** xref:configuring-che-hostname.adoc[] -*** xref:configuring-che-with-self-signed-certificate.adoc[] -*** xref:importing-untrusted-tls-certificates.adoc[] -*** xref:adding-labels-and-annotations.adoc[] -*** xref:configuring-workspaces-endpoints-base-domain.adoc[] -*** xref:configuring-proxy.adoc[] -** xref:configuring-storage.adoc[] -*** xref:configuring-storage-classes.adoc[] -*** xref:configuring-the-storage-strategy.adoc[] -*** xref:configuring-storage-sizes.adoc[] -*** xref:con_persistent-user-home.adoc[] -** xref:configuring-dashboard.adoc[] -*** xref:configuring-getting-started-samples.adoc[] -*** xref:configuring-editors-definitions.adoc[] -*** xref:show-deprecated-editors.adoc[] -*** xref:configuring-default-editor.adoc[] -*** xref:concealing-editors.adoc[] -*** xref:configuring-editors-download-urls.adoc[] -*** xref:configuring-ai-providers.adoc[] -**** xref:ai-provider-api-key-secret-reference.adoc[] -*** xref:customizing-openshift-che-branding-images.adoc[] -** xref:configuring-oauth-for-git-providers.adoc[] -*** xref:configuring-oauth-2-for-github.adoc[] -*** xref:configuring-oauth-2-for-gitlab.adoc[] -*** xref:configuring-oauth-2-for-a-bitbucket-server.adoc[] -*** xref:configuring-oauth-2-for-the-bitbucket-cloud.adoc[] -*** xref:configuring-oauth-1-for-a-bitbucket-server.adoc[] -*** xref:configuring-oauth-2-for-microsoft-azure-devops-services.adoc[] -** xref:configuring-fuse.adoc[] -*** xref:enabling-access-to-dev-fuse-for-openshift.adoc[] -*** xref:enabling-fuse-for-all-workspaces.adoc[] -** xref:devworkspace-backup.adoc[] -*** xref:devworkspace-backup-integrated-openshift-registry.adoc[] -*** xref:devworkspace-backup-regular-oci-registry.adoc[] +* xref:configuring-observability.adoc[] +** xref:the-woopra-telemetry-plugin.adoc[] +** xref:creating-a-telemetry-plugin.adoc[] +** xref:configuring-server-logging.adoc[] +** xref:collecting-logs-using-chectl.adoc[] +** xref:monitoring-the-dev-workspace-operator.adoc[] +** xref:monitoring-che.adoc[] +* xref:configuring-oauth-for-git-providers.adoc[] +** xref:configuring-oauth-2-for-github.adoc[] +** xref:configuring-oauth-2-for-gitlab.adoc[] +** xref:configuring-oauth-2-for-a-bitbucket-server.adoc[] +** xref:configuring-oauth-2-for-the-bitbucket-cloud.adoc[] +** xref:configuring-oauth-1-for-a-bitbucket-server.adoc[] +** xref:configuring-oauth-2-for-microsoft-azure-devops-services.adoc[] * xref:managing-ide-extensions.adoc[] ** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[] ** xref:configuring-the-open-vsx-registry-url.adoc[] @@ -78,4 +28,10 @@ ** xref:default-extensions-for-microsoft-visual-studio-code.adoc[] ** xref:manage-extension-installation.adoc[] ** xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] -* xref:managing-workloads-using-the-che-server-api.adoc[] +* xref:configuring-editors-definitions.adoc[] +** xref:show-deprecated-editors.adoc[] +** xref:configuring-default-editor.adoc[] +** xref:concealing-editors.adoc[] +** xref:configuring-editors-download-urls.adoc[] +** xref:configuring-ai-providers.adoc[] +*** xref:ai-provider-api-key-secret-reference.adoc[] diff --git a/modules/administration-guide/pages/adding-labels-and-annotations.adoc b/modules/administration-guide/pages/adding-labels-and-annotations.adoc deleted file mode 100644 index db72ee4c51..0000000000 --- a/modules/administration-guide/pages/adding-labels-and-annotations.adoc +++ /dev/null @@ -1,12 +0,0 @@ -:_content-type: ASSEMBLY -:description: Adding labels and annotations -:keywords: administration-guide, labels, annotations -:navtitle: Adding labels and annotations -:page-aliases: - -[id="adding-labels-and-annotations"] -= Adding labels and annotations - -include::example$proc_{project-context}-configuring-ingresses.adoc[leveloffset=+1] -include::partial$proc_configuring-routes.adoc[leveloffset=+1] - diff --git a/modules/administration-guide/pages/concealing-editors.adoc b/modules/administration-guide/pages/concealing-editors.adoc index e4c0160410..1108b59a89 100644 --- a/modules/administration-guide/pages/concealing-editors.adoc +++ b/modules/administration-guide/pages/concealing-editors.adoc @@ -18,7 +18,7 @@ Learn how to conceal {prod-short} editors. This is useful when you want to hide include::example$snip_che-editor-id-list.adoc[] -. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +. Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml] ---- diff --git a/modules/administration-guide/pages/configuring-che.adoc b/modules/administration-guide/pages/configuring-che.adoc deleted file mode 100644 index f8de904c0c..0000000000 --- a/modules/administration-guide/pages/configuring-che.adoc +++ /dev/null @@ -1,10 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring methods for {prod-short} -:keywords: administration guide, configuring, configuration -:navtitle: Configuring {prod-short} -:page-aliases: installation-guide:configuring-che.adoc, installation-guide:advanced-configuration.adoc, installation-guide:advanced-configuration-options.adoc, installation-guide:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc, installation-guide:configuring-communication-between-che-components.adoc, installation-guide:configuring-storage-strategies.adoc, installation-guide:configuring-storage-types.adoc, installation-guide:configuring-the-number-of-workspaces-that-a-user-can-run.adoc, installation-guide:configuring-workspace-exposure-strategies.adoc, installation-guide:enabling-dev-workspace-operator.adoc, running-custom-registries.adoc, building-custom-registry-images.adoc, customizing-the-registries.adoc, advanced-configuration.adoc - -[id="configuring-che"] -= Configuring {prod-short} - -This section describes configuration methods and options for {prod}. diff --git a/modules/administration-guide/pages/configuring-dashboard.adoc b/modules/administration-guide/pages/configuring-dashboard.adoc deleted file mode 100644 index 56047f6105..0000000000 --- a/modules/administration-guide/pages/configuring-dashboard.adoc +++ /dev/null @@ -1,23 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring dashboard -:keywords: administration-guide, configuring, dashboard -:navtitle: Configuring dashboard -:page-aliases: - -[id="configuring-dashboard"] -= Configuring dashboard - -* xref:configuring-getting-started-samples.adoc[] - -* xref:configuring-editors-definitions.adoc[] - -* xref:configuring-editors-download-urls.adoc[] - -* xref:show-deprecated-editors.adoc[] - -* xref:configuring-default-editor.adoc[] - -* xref:concealing-editors.adoc[] - -* xref:customizing-openshift-che-branding-images.adoc[] - diff --git a/modules/administration-guide/pages/configuring-networking.adoc b/modules/administration-guide/pages/configuring-networking.adoc deleted file mode 100644 index 97e104a987..0000000000 --- a/modules/administration-guide/pages/configuring-networking.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring networking -:keywords: administration-guide, configuring, networking -:navtitle: Configuring networking -:page-aliases: - -[id="configuring-networking"] -= Configuring networking - -* xref:configuring-network-policies.adoc[] -* xref:configuring-che-hostname.adoc[] -include::example$snip_{project-context}-xref-configuring-che-with-self-signed-certificate.adoc[] -* xref:importing-untrusted-tls-certificates.adoc[] -* xref:adding-labels-and-annotations.adoc[] -* xref:configuring-workspaces-endpoints-base-domain.adoc[] -* xref:configuring-proxy.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/configuring-server-components.adoc b/modules/administration-guide/pages/configuring-server-components.adoc deleted file mode 100644 index 3ed019623a..0000000000 --- a/modules/administration-guide/pages/configuring-server-components.adoc +++ /dev/null @@ -1,12 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring server components -:keywords: administration-guide, configuring, server components -:navtitle: Configuring server components -:page-aliases: - -[id="configuring-server-components"] -= Configuring server components - -* 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:optimize:configuring-number-of-replicas.adoc[] diff --git a/modules/administration-guide/pages/configuring-server-logging.adoc b/modules/administration-guide/pages/configuring-server-logging.adoc index e6da6efc07..cded364d12 100644 --- a/modules/administration-guide/pages/configuring-server-logging.adoc +++ b/modules/administration-guide/pages/configuring-server-logging.adoc @@ -9,14 +9,14 @@ It is possible to fine-tune the log levels of individual loggers available in the {prod-short} server. -The log level of the whole {prod-short} server is configured globally using the `cheLogLevel` configuration property of the Operator. See xref:checluster-custom-resource-fields-reference.adoc[]. +The log level of the whole {prod-short} server is configured globally using the `cheLogLevel` configuration property of the Operator. See xref:configure:checluster-custom-resource-fields-reference.adoc[]. To set the global log level in installations not managed by the Operator, specify the `CHE_LOG_LEVEL` environment variable in the `che` ConfigMap. It is possible to configure the log levels of the individual loggers in the {prod-short} server using the `CHE_LOGGER_CONFIG` environment variable. -include::partial$proc_configuring-server-logging.adoc[leveloffset=+1] +include::configure:partial$proc_configuring-server-logging.adoc[] include::partial$con_logger-naming.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/configuring-storage.adoc b/modules/administration-guide/pages/configuring-storage.adoc deleted file mode 100644 index 5ef860496d..0000000000 --- a/modules/administration-guide/pages/configuring-storage.adoc +++ /dev/null @@ -1,28 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring storage -:keywords: administration-guide, configuring, storage -:navtitle: Configuring storage -:page-aliases: - -[id="configuring-storage"] -= Configuring storage - -[role="_abstract"] -Configure storage classes, strategies, sizes, and persistent user home to control how {prod-short} workspaces store project files and user data. - -[IMPORTANT] -==== -{prod} workspaces require storage with **volumeMode: FileSystem** because the development environment is designed to store project files, code, and configurations in a standard, hierarchical directory structure (such as /projects). - -While Network File System (NFS) is one of the few protocols that natively supports the necessary **ReadWriteMany (RWX)** access mode for running concurrent workspaces (the Per-User strategy), standard {Kubernetes} NFS provisioning presents certain operational challenges: - -* *Quota Enforcement Failure:* Kubernetes Persistent Volume Claims (PVCs) cannot reliably enforce storage quotas on a generic NFS volume. This limitation means a single workspace could exceed its allocated storage, potentially consuming the entire shared volume and leading to resource exhaustion, which causes widespread instability for all other users. -* *Stability and Concurrency:* Generic NFS implementations often lack the robust locking and cache coherency required to maintain data integrity when multiple cluster nodes access the same volume concurrently, potentially leading to workspace instability. - -To overcome these stability and quota issues, it is recommended to use certified **clustered or managed storage solutions** that provide robust CSI drivers. These solutions use the NFS protocol but enforce enterprise-grade features, including strict quota enforcement and high-performance RWX file access, ensuring reliable operation for the Per-User strategy. Examples include community-supported distributed storage projects or third-party CSI drivers offered by most cloud providers. -==== - -* xref:configuring-storage-classes.adoc[] -* xref:configuring-the-storage-strategy.adoc[] -* xref:configuring-storage-sizes.adoc[] -* xref:con_persistent-user-home.adoc[] diff --git a/modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc b/modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc index 5d76369db7..5334af84b6 100644 --- a/modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc +++ b/modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc @@ -68,5 +68,5 @@ Due to the dedicated Microsoft link:https://cdn.vsassets.io/v/M190_20210811.1/_c [role="_additional-resources"] .Additional resources -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] * link:https://open-vsx.org/[Open VSX registry] diff --git a/modules/administration-guide/pages/configuring-workspaces-globally.adoc b/modules/administration-guide/pages/configuring-workspaces-globally.adoc deleted file mode 100644 index 12ea472c39..0000000000 --- a/modules/administration-guide/pages/configuring-workspaces-globally.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring workspaces globally -:keywords: administration-guide, configuring, workspaces -:navtitle: Configuring workspaces globally -:page-aliases: - -[id="configuring-workspaces-globally"] -= Configuring workspaces globally - -This section describes how an administrator can configure workspaces globally. - -* 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[] - -* xref:enabling-users-to-run-multiple-workspaces-simultaneously.adoc[] - -* xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] - -* xref:configuring-workspaces-nodeselector.adoc[] - -* xref:configuring-allowed-urls-for-cloud-development-environments.adoc[] - -* xref:enabling-container-run-capabilities.adoc[] diff --git a/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc b/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc index 6dc82233db..64e483a3f0 100644 --- a/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc +++ b/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc @@ -386,7 +386,7 @@ image::creating-a-telemetry-plugin/devworkspace_telemetry_plugin.png[{devworkspa Set the telemetry plugin as a default plugin. Default plugins are applied on {devworkspace} startup for new and existing {devworkspace}s. -* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +* Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + ---- spec: @@ -402,7 +402,7 @@ spec: .Additional resources -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. .Verification steps diff --git a/modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc index dee52b966e..49b1f5d490 100644 --- a/modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc @@ -89,7 +89,7 @@ data: Make sure that the Configmap contains data in a valid JSON format. ==== -TIP: Consider adding the ConfigMap to the {prod-namespace} namespace. By adding it to the namespace, you replicate the ConfigMap across all user namespaces while preventing modifications within user's namespaces. See xref:configuring-a-user-namespace.adoc[]. +TIP: Consider adding the ConfigMap to the {prod-namespace} namespace. By adding it to the namespace, you replicate the ConfigMap across all user namespaces while preventing modifications within user's namespaces. See xref:configure:configuring-a-user-namespace.adoc[]. .Verification . Verify that settings defined in the ConfigMap are applied using one of the following methods: diff --git a/modules/administration-guide/pages/show-deprecated-editors.adoc b/modules/administration-guide/pages/show-deprecated-editors.adoc index 54eb992c5b..0b99de8363 100644 --- a/modules/administration-guide/pages/show-deprecated-editors.adoc +++ b/modules/administration-guide/pages/show-deprecated-editors.adoc @@ -25,7 +25,7 @@ Learn how to show deprecated {prod-short} editors on the Dashboard. By default, -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '[.[] | select(.metadata.tags != null) | select(.metadata.tags[] | contains("Deprecate")) | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"]' ---- -. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +. Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml] ---- @@ -43,4 +43,4 @@ spec: * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc b/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc index 14076e5ac1..2c996516bc 100644 --- a/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc +++ b/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc @@ -24,7 +24,7 @@ To enable the Woopra plugin on the {prod} installation: * Deploy the `plugin.yaml` devfile v2 file to an HTTP server with the environment variables set correctly. -. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +. Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml] ---- @@ -42,4 +42,4 @@ spec: * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/partials/con_logging-http-traffic.adoc b/modules/administration-guide/partials/con_logging-http-traffic.adoc index 3f780d3c13..1e3d43e9e4 100644 --- a/modules/administration-guide/partials/con_logging-http-traffic.adoc +++ b/modules/administration-guide/partials/con_logging-http-traffic.adoc @@ -5,7 +5,7 @@ .Procedure -* To log the HTTP traffic between the {prod-short} server and the API server of the {kubernetes} or OpenShift cluster, configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +* To log the HTTP traffic between the {prod-short} server and the API server of the {kubernetes} or OpenShift cluster, configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml] ---- @@ -20,5 +20,5 @@ spec: * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc b/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc index ae1669ce81..2dd275da18 100644 --- a/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc +++ b/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc @@ -8,7 +8,7 @@ You can configure this behaviour. .Procedure -* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +* Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml,subs="+attributes,+quotes"] ---- diff --git a/modules/configure/examples/proc_che-configuring-ingresses.adoc b/modules/configure/examples/proc_che-configuring-ingresses.adoc new file mode 100644 index 0000000000..c5fcc36ec9 --- /dev/null +++ b/modules/configure/examples/proc_che-configuring-ingresses.adoc @@ -0,0 +1,31 @@ + +[id="adding-labels-and-annotations-to-ingresses"] +== Add labels and annotations to {orch-ingress} + +You can configure {orch-ingress} labels and annotations, if your organization requires them. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* An instance of {prod-short} running in {orch-name}. + +.Procedure + +* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. ++ +[source,yaml,subs="+quotes,+attributes"] +---- +spec: + networking: + labels: ____ <1> + annotations: ____ <2> +---- +<1> An unstructured key value map of labels for {orch-ingress}. +<2> An unstructured key value map of annotations for {orch-ingress}. + +.Additional resources + +* xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] + +* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/configure/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc b/modules/configure/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc new file mode 100644 index 0000000000..2665522d6d --- /dev/null +++ b/modules/configure/examples/snip_che-xref-configuring-che-with-self-signed-certificate.adoc @@ -0,0 +1 @@ +* xref:configuring-che-with-self-signed-certificate.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/images/persistent-user-home/tools-container-example.png b/modules/configure/images/persistent-user-home/tools-container-example.png similarity index 100% rename from modules/administration-guide/images/persistent-user-home/tools-container-example.png rename to modules/configure/images/persistent-user-home/tools-container-example.png diff --git a/modules/configure/nav.adoc b/modules/configure/nav.adoc new file mode 100644 index 0000000000..eeead56e21 --- /dev/null +++ b/modules/configure/nav.adoc @@ -0,0 +1,50 @@ +.Configure +* Configure the platform +** Customize the central configuration +*** xref:understanding-the-checluster-custom-resource.adoc[] +*** xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +*** xref:checluster-custom-resource-fields-reference.adoc[] +** Inject configuration into server components +*** 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[] +** Customize the developer dashboard +*** xref:configuring-getting-started-samples.adoc[] +*** xref:customizing-openshift-che-branding-images.adoc[] +** xref:managing-workloads-using-the-che-server-api.adoc[] +* Configure workspaces +** Organize workspace namespaces +*** xref:configuring-namespace-provisioning.adoc[] +*** xref:configuring-workspace-target-namespace.adoc[] +*** xref:provisioning-namespaces-in-advance.adoc[] +*** xref:configuring-a-user-namespace.adoc[] +*** xref:configuring-kubernetes-namespace-creation-on-openshift.adoc[] +** Set workspace policies for all users +*** 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[] +*** xref:enabling-users-to-run-multiple-workspaces-simultaneously.adoc[] +*** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] +*** xref:configuring-workspaces-nodeselector.adoc[] +*** xref:configuring-allowed-urls-for-cloud-development-environments.adoc[] +*** xref:enabling-container-run-capabilities.adoc[] +* Configure networking and storage +** Set up network access for workspaces +*** xref:configuring-network-policies.adoc[] +*** xref:configuring-che-hostname.adoc[] +*** xref:configuring-che-with-self-signed-certificate.adoc[] +*** xref:importing-untrusted-tls-certificates.adoc[] +*** xref:adding-labels-and-annotations.adoc[] +*** xref:configuring-workspaces-endpoints-base-domain.adoc[] +*** xref:configuring-proxy.adoc[] +** Control where workspace data is stored +*** xref:configuring-storage-classes.adoc[] +*** xref:configuring-the-storage-strategy.adoc[] +*** xref:configuring-storage-sizes.adoc[] +*** xref:con_persistent-user-home.adoc[] +** Enable fuse-overlayfs for container builds +*** xref:configuring-fuse.adoc[] +*** xref:enabling-access-to-dev-fuse-for-openshift.adoc[] +*** xref:enabling-fuse-for-all-workspaces.adoc[] +** Back up workspaces +*** xref:devworkspace-backup.adoc[] +*** xref:devworkspace-backup-integrated-openshift-registry.adoc[] +*** xref:devworkspace-backup-regular-oci-registry.adoc[] diff --git a/modules/configure/pages/adding-labels-and-annotations.adoc b/modules/configure/pages/adding-labels-and-annotations.adoc new file mode 100644 index 0000000000..106b8c5e0a --- /dev/null +++ b/modules/configure/pages/adding-labels-and-annotations.adoc @@ -0,0 +1,14 @@ +:_content-type: ASSEMBLY +:description: Add labels and annotations to workspace routes +:keywords: administration-guide, labels, annotations, ingress, route +:navtitle: Add labels and annotations to workspace routes +:page-aliases: administration-guide:adding-labels-and-annotations.adoc + +[id="adding-labels-and-annotations"] += Add labels and annotations to workspace routes + +Add custom labels and annotations to workspace {orch-ingress} and OpenShift Routes when your organization requires them for ingress controllers, router sharding, or network policies. + +include::example$proc_{project-context}-configuring-ingresses.adoc[] + +include::partial$proc_configuring-routes.adoc[] diff --git a/modules/administration-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc b/modules/configure/pages/advanced-configuration-options-for-the-che-server-component.adoc similarity index 56% rename from modules/administration-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc rename to modules/configure/pages/advanced-configuration-options-for-the-che-server-component.adoc index fc40c2613a..164b029d11 100644 --- a/modules/administration-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc +++ b/modules/configure/pages/advanced-configuration-options-for-the-che-server-component.adoc @@ -1,17 +1,15 @@ :_content-type: ASSEMBLY -:description: Advanced deployment and configuration methods for the {prod-short} server component. +:description: Fine-tune the {prod-short} server :keywords: administration guide, configuring, configuration, {prod-short} server -:navtitle: Advanced configuration options for {prod-short} server +:navtitle: Fine-tune the {prod-short} server :page-aliases: installation-guide:advanced-configuration-options-for-the-che-server-component.adoc, installation-guide:configuring-system-variables.adoc [id="advanced-configuration-options-for-the-{prod-id-short}-server-component"] -= Advanced configuration options for the {prod-short} server component += Fine-tune the {prod-short} server +Fine-tune the {prod-short} server by setting environment variables, JVM options, and component-level configuration that the standard CheCluster fields do not expose. -The following section describes advanced deployment and configuration methods for the {prod-short} server component. - -include::partial$con_understanding-che-server-advanced-configuration.adoc[leveloffset=+1] +include::partial$con_understanding-che-server-advanced-configuration.adoc[] // include::partial$ref_che-server-component-system-properties-reference.adoc[leveloffset=+1] - diff --git a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc b/modules/configure/pages/checluster-custom-resource-fields-reference.adoc similarity index 95% rename from modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc rename to modules/configure/pages/checluster-custom-resource-fields-reference.adoc index 2d4a2989e3..1d2b4c7133 100644 --- a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc +++ b/modules/configure/pages/checluster-custom-resource-fields-reference.adoc @@ -7,7 +7,8 @@ [id="checluster-custom-resources-fields-reference"] = `CheCluster` Custom Resource fields reference -This section describes all fields available to customize the `CheCluster` Custom Resource. + +Reference for all fields in the `CheCluster` Custom Resource. Use this to find the exact field path and valid values when editing the CR. * xref:a-minimal-checluster-custom-resource-example[] * xref:checluster-custom-resource-devEnvironments-settings[] @@ -99,10 +100,10 @@ spec: ---- ==== -include::example$checluster-properties/checluster-properties.adoc[leveloffset=+1] +include::administration-guide:example$checluster-properties/checluster-properties.adoc[leveloffset=+1] [id="ai-tool-registry-configmap-reference"] -== AI tool registry ConfigMap +== Configure AI tool providers AI providers and tools are configured through a {kubernetes} `ConfigMap` in the `{prod-namespace}` namespace, not through the `{prod-checluster}` custom resource. The ConfigMap must have the following labels to be discovered by the dashboard: @@ -111,7 +112,7 @@ AI providers and tools are configured through a {kubernetes} `ConfigMap` in the The ConfigMap contains a `registry.json` key with three sections: `providers`, `tools`, and `defaultAiProviders`. -=== Provider fields +=== Define a provider [cols="1,1,3",options="header"] |=== @@ -142,7 +143,7 @@ The ConfigMap contains a `registry.json` key with three sections: `providers`, ` | URL to the provider's SVG icon. |=== -=== Tool fields +=== Define a tool [cols="1,1,3",options="header"] |=== @@ -185,11 +186,11 @@ The ConfigMap contains a `registry.json` key with three sections: `providers`, ` | One-time setup command run in the editor container at postStart. |=== -=== defaultAiProviders +=== Set default AI providers Optional. A JSON array of provider `id` values that are pre-selected in the AI Selector widget for new workspaces. .Additional resources -* xref:configuring-ai-providers.adoc[] -* xref:ai-provider-api-key-secret-reference.adoc[] +* xref:administration-guide:configuring-ai-providers.adoc[] +* xref:administration-guide:ai-provider-api-key-secret-reference.adoc[] diff --git a/modules/administration-guide/pages/con_persistent-user-home.adoc b/modules/configure/pages/con_persistent-user-home.adoc similarity index 90% rename from modules/administration-guide/pages/con_persistent-user-home.adoc rename to modules/configure/pages/con_persistent-user-home.adoc index 58f15d24c5..e949cf6ff8 100644 --- a/modules/administration-guide/pages/con_persistent-user-home.adoc +++ b/modules/configure/pages/con_persistent-user-home.adoc @@ -1,15 +1,18 @@ :_content-type: CONCEPT :description: Persistent user home preserves the /home/user directory across workspace restarts :keywords: administration guide, {prod-id-short}, persistent, user, home -:navtitle: Persistent user home +:navtitle: How workspace files persist across restarts :page-aliases: about-persistent-user-home.adoc [id="persistent-user-home"] -= Persistent user home += How workspace files persist across restarts + [role="_abstract"] {prod} preserves the `/home/user` directory across workspace restarts for each non-ephemeral workspace, so that user-specific configurations, shell history, and tooling settings persist between sessions. +This page is for platform administrators who manage the persistent home feature, and for developers who build custom workspace images that must meet specific directory layout requirements. To learn more about common roles and example tasks, see xref:discover:roles-and-tasks.adoc[]. + This feature is enabled by default. To disable it, set `spec.devEnvironments.persistUserHome.enabled` to `false` in the CheCluster custom resource. For newly started workspaces, this feature creates a persistent volume claim (PVC) mounted to the `/home/user` path of the tools container. @@ -55,7 +58,7 @@ If the tooling image is updated with additional binaries or files, they are not To rerun `stow`, delete the `/home/user/.stow_completed` file and restart the workspace. ==== -== `persistUserHome` tools image requirements +== Tools image requirements for persistent home The `persistUserHome` depends on the tools image used for the workspace. By default {prod-short} uses the Universal Developer Image (UDI) for sample workspaces, which supports `persistUserHome` out of the box. diff --git a/modules/administration-guide/pages/configuring-a-user-namespace.adoc b/modules/configure/pages/configuring-a-user-namespace.adoc similarity index 94% rename from modules/administration-guide/pages/configuring-a-user-namespace.adoc rename to modules/configure/pages/configuring-a-user-namespace.adoc index a67f0d99cc..a3dea90e93 100644 --- a/modules/administration-guide/pages/configuring-a-user-namespace.adoc +++ b/modules/configure/pages/configuring-a-user-namespace.adoc @@ -1,17 +1,14 @@ :_content-type: PROCEDURE -:description: Configuring a user namespace +:description: Synchronize resources across user namespaces :keywords: administration guide, configuring, user, namespace -:navtitle: Configuring a user namespace -:page-aliases: +:navtitle: Synchronize resources across user namespaces +:page-aliases: administration-guide:configuring-a-user-namespace.adoc [id="configuring-a-user-namespace"] -= Configuring a user namespace += Synchronize resources across user namespaces -Learn how to use {prod-short} -to synchronize `ConfigMaps`, `Secrets`, `PersistentVolumeClaim` and other {kubernetes} objects -from `{prod-namespace}` namespace to numerous user-specific namespaces. -The {prod-short} automates the synchronization of important configuration data, such as -shared credentials, configuration files, and certificates to user namespaces. + +Synchronize ConfigMaps, Secrets, and PVCs from a central {orch-namespace} to every user {orch-namespace}, so developers automatically receive shared resources. If you make changes to a {kubernetes} resource in an {prod-namespace} namespace, {prod-short} will immediately synchronize the changes across all users namespaces. @@ -25,6 +22,12 @@ Applying or modifying a `Secret` or `ConfigMap` with the `controller.devfile.io/ To mount the `Secret` or `ConfigMap` only at workspace start and prevent automatic restarts, add the `controller.devfile.io/mount-on-start: 'true'` annotation. ==== +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* The {kubernetes} resources (ConfigMaps, Secrets, or PVCs) that you want to distribute to all user namespaces are prepared. + .Procedure . Create the `ConfigMap` below to create and mount it into every workspace. diff --git a/modules/administration-guide/pages/configuring-allowed-urls-for-cloud-development-environments.adoc b/modules/configure/pages/configuring-allowed-urls-for-cloud-development-environments.adoc similarity index 56% rename from modules/administration-guide/pages/configuring-allowed-urls-for-cloud-development-environments.adoc rename to modules/configure/pages/configuring-allowed-urls-for-cloud-development-environments.adoc index 9ece02cd8a..b1f63a7dd2 100644 --- a/modules/administration-guide/pages/configuring-allowed-urls-for-cloud-development-environments.adoc +++ b/modules/configure/pages/configuring-allowed-urls-for-cloud-development-environments.adoc @@ -1,12 +1,21 @@ +:page-aliases: administration-guide:configuring-allowed-urls-for-cloud-development-environments.adoc :_content-type: PROCEDURE -:description: Configuring allowed URLs for Cloud Development Environments +:description: Restrict which URLs can create workspaces :keywords: administration guide, configuring-allowed-sources -:navtitle: Configuring allowed URLs for Cloud Development Environments +:navtitle: Restrict which URLs can create workspaces [id="configuring-allowed-urls-for-cloud-development-environments"] -= Configuring allowed URLs for Cloud Development Environments += Restrict which URLs can create workspaces -Allowed URLs play an important role in securing the initiation of Cloud Development Environments (CDEs), ensuring that they can only be launched from authorized sources. By utilizing wildcard support, such as `*`, organizations can implement flexible URL patterns, allowing for dynamic and secure CDE initiation across various paths within a domain. + +Restrict which source URLs can create Cloud Development Environments (CDEs), so that workspaces can only be launched from authorized repositories. Wildcard patterns such as `https://example.com/*` allow all paths within a domain. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + + +.Procedure . Configure allowed sources: + @@ -26,6 +35,7 @@ Allowed URLs play an important role in securing the initiation of Cloud Developm } }' ---- + <1> The array of approved URLs for starting Cloud Development Environments (CDEs). CDEs can only be initiated from these URLs. Wildcards `\*` are supported in URLs. For example, `https://example.com/*` would allow CDEs to be initiated from any path within `example.com`. .Additional resources diff --git a/modules/administration-guide/pages/configuring-che-hostname.adoc b/modules/configure/pages/configuring-che-hostname.adoc similarity index 87% rename from modules/administration-guide/pages/configuring-che-hostname.adoc rename to modules/configure/pages/configuring-che-hostname.adoc index f524526c10..2d9d222200 100644 --- a/modules/administration-guide/pages/configuring-che-hostname.adoc +++ b/modules/configure/pages/configuring-che-hostname.adoc @@ -1,13 +1,15 @@ :_content-type: PROCEDURE -:description: Configuring {prod-short} to use custom hostname +:description: Use a custom hostname for the dashboard :keywords: administration guide, configuring, {prod}, {prod-short}, hostname -:navtitle: Configuring {prod-short} hostname +:navtitle: Use a custom hostname for the dashboard :page-aliases: installation-guide:configuring-che-hostname.adoc [id="configuring-{prod-id-short}-server-hostname"] -= Configuring {prod} server hostname += Use a custom hostname for the dashboard + + +Use a custom hostname to override the auto-detected dashboard URL with a hostname that matches your organization's DNS and TLS certificate. -This procedure describes how to configure {prod-short} to use custom hostname. .Prerequisites diff --git a/modules/administration-guide/pages/configuring-che-with-self-signed-certificate.adoc b/modules/configure/pages/configuring-che-with-self-signed-certificate.adoc similarity index 79% rename from modules/administration-guide/pages/configuring-che-with-self-signed-certificate.adoc rename to modules/configure/pages/configuring-che-with-self-signed-certificate.adoc index f657cd5046..192d2ff52d 100644 --- a/modules/administration-guide/pages/configuring-che-with-self-signed-certificate.adoc +++ b/modules/configure/pages/configuring-che-with-self-signed-certificate.adoc @@ -1,14 +1,15 @@ :_content-type: PROCEDURE -:description: Configuring {prod-short} with self-signed certificates +:description: Deploy with a self-signed TLS certificate :keywords: administration guide, configuring, {prod}, {prod-short}, self-signed, certificate -:navtitle: Configuring {prod-short} with self-signed certificates +:navtitle: Deploy with a self-signed TLS certificate :page-aliases: installation-guide:configuring-che-with-self-signed-certificate.adoc [id="configuring-{prod-id-short}-with-self-signed-certificate"] -= Configuring {prod} with self-signed certificate += Deploy with a self-signed TLS certificate + + +Deploy {prod-short} with a custom self-signed TLS certificate instead of the auto-generated one. By default, `{prod-cli}` creates a {kubernetes} Job to generate a self-signed certificate automatically. -By default `{prod-cli}` creates a {kubernetes} Job to generate self-signed certificate to deploy {prod-short} with. -This procedure describes how to configure a custom self-signed certificate on prior of deploying {prod-short}. .Prerequisites diff --git a/modules/administration-guide/pages/configuring-fuse.adoc b/modules/configure/pages/configuring-fuse.adoc similarity index 59% rename from modules/administration-guide/pages/configuring-fuse.adoc rename to modules/configure/pages/configuring-fuse.adoc index b6da34436e..5bdc3b1480 100644 --- a/modules/administration-guide/pages/configuring-fuse.adoc +++ b/modules/configure/pages/configuring-fuse.adoc @@ -1,21 +1,24 @@ :_content-type: ASSEMBLY -:description: Configuring fuse for workspaces -:keywords: administration-guide, configuring-fuse -:navtitle: Configuring fuse-overlayfs -:page-aliases: +:description: When to enable fuse-overlayfs for container builds +:keywords: administration-guide, fuse-overlayfs, podman, buildah, container builds +:navtitle: When to enable fuse-overlayfs +:page-aliases: administration-guide:configuring-fuse.adoc [id="configuring-fuse-overlayfs"] -= Configuring fuse-overlayfs += When to enable fuse-overlayfs + By default, the Universal Developer Image (UDI) contains Podman and Buildah which you can use to build and push container images within a workspace. However, Podman and Buildah in the UDI are configured to use the `vfs` storage driver which does not provide copy-on-write support. For more efficient image management, use the fuse-overlayfs storage driver which supports copy-on-write in rootless environments. -To enable fuse-overlayfs for workspaces for OpenShift versions older than 4.15, the administrator must first enable `/dev/fuse` access on the cluster by following xref:administration-guide:enabling-access-to-dev-fuse-for-openshift.adoc[]. +This page is for platform administrators who enable fuse-overlayfs cluster-wide, and for developers who want to enable it for individual workspaces. To learn more about common roles and example tasks, see xref:discover:roles-and-tasks.adoc[]. + +To enable fuse-overlayfs for workspaces for OpenShift versions older than 4.15, the administrator must first enable `/dev/fuse` access on the cluster by following xref:enabling-access-to-dev-fuse-for-openshift.adoc[]. This is not necessary for OpenShift versions 4.15 and later, since the `/dev/fuse` device is available by default. See link:https://docs.openshift.com/container-platform/4.15/release_notes/ocp-4-15-release-notes.html#ocp-4-15-nodes-dev-fuse[Release Notes]. After enabling `/dev/fuse` access, fuse-overlayfs can be enabled in two ways: -. For all user workspaces within the cluster. See xref:administration-guide:enabling-fuse-for-all-workspaces.adoc[]. +. For all user workspaces within the cluster. See xref:enabling-fuse-for-all-workspaces.adoc[]. . For workspaces belonging to certain users. See xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[]. diff --git a/modules/administration-guide/pages/configuring-getting-started-samples.adoc b/modules/configure/pages/configuring-getting-started-samples.adoc similarity index 83% rename from modules/administration-guide/pages/configuring-getting-started-samples.adoc rename to modules/configure/pages/configuring-getting-started-samples.adoc index 0e2463c4a3..8241e4577f 100644 --- a/modules/administration-guide/pages/configuring-getting-started-samples.adoc +++ b/modules/configure/pages/configuring-getting-started-samples.adoc @@ -1,13 +1,15 @@ :_content-type: PROCEDURE -:description: Configuring getting started samples +:description: Customize the dashboard samples for your team :keywords: administration guide, configuring, dashboard, samples -:navtitle: Configuring getting started samples +:navtitle: Customize the dashboard samples for your team :page-aliases: installation-guide:configuring-getting-started-samples.adoc [id="configuring-getting-started-samples"] -= Configuring getting started samples += Customize the dashboard samples for your team + + +Customize the Getting Started samples by replacing the defaults on the dashboard with repositories relevant to your team's projects and technology stack. -This procedure describes how to configure {prod-short} Dashboard to display custom samples. .Prerequisites diff --git a/modules/administration-guide/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc b/modules/configure/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc similarity index 86% rename from modules/administration-guide/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc rename to modules/configure/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc index f43b975cea..08591f0d4f 100644 --- a/modules/administration-guide/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc +++ b/modules/configure/pages/configuring-kubernetes-namespace-creation-on-openshift.adoc @@ -1,11 +1,12 @@ :_content-type: PROCEDURE -:description: Configuring {prod-short} to create standard {kubernetes} Namespaces directly on {ocp} instead of using the ProjectRequest API +:description: Use {kubernetes} namespaces instead of {orch-name} projects :keywords: administration guide, configuring, namespace, openshift, project, projectrequest -:navtitle: Configuring direct namespace creation on OpenShift +:navtitle: Use {kubernetes} namespaces instead of {orch-name} projects :page-aliases: [id="configuring-kubernetes-namespace-creation-on-openshift"] -= Configuring {kubernetes} namespace creation on OpenShift += Use {kubernetes} namespaces instead of {orch-name} projects + By default, on {ocp} clusters, {prod-short} uses the ProjectRequest API to create projects. This triggers cluster-specific link:https://docs.openshift.com/container-platform/latest/applications/projects/configuring-project-creation.html[Project Templates], which can apply additional resources or policies. diff --git a/modules/administration-guide/pages/configuring-namespace-provisioning.adoc b/modules/configure/pages/configuring-namespace-provisioning.adoc similarity index 77% rename from modules/administration-guide/pages/configuring-namespace-provisioning.adoc rename to modules/configure/pages/configuring-namespace-provisioning.adoc index 0502e2f333..825f70c50b 100644 --- a/modules/administration-guide/pages/configuring-namespace-provisioning.adoc +++ b/modules/configure/pages/configuring-namespace-provisioning.adoc @@ -1,17 +1,18 @@ :_content-type: CONCEPT -:description: Configuring user {orch-namespace} provisioning +:description: How workspace namespaces are organized :keywords: administration guide, configuring, namespace -:navtitle: Configuring {orch-namespace}s +:navtitle: How workspace namespaces are organized :page-aliases: installation-guide:configuring-namespace-strategies.adoc, configuring-namespace-strategies.adoc [id="configuring-user-{orch-namespace}-provisioning"] -= Configuring user {orch-namespace} provisioning += How workspace namespaces are organized + For each user, {prod-short} isolates workspaces in a {orch-namespace}. {prod-short} identifies the user {orch-namespace} by the presence of labels and annotations. When starting a workspace, if the required {orch-namespace} doesn't exist, {prod-short} creates the {orch-namespace} using a template name. -You can modify {prod-short} behavior by: +Platform administrators can modify {prod-short} behavior by: * xref:configuring-workspace-target-namespace.adoc[] * xref:provisioning-namespaces-in-advance.adoc[] diff --git a/modules/administration-guide/pages/configuring-network-policies.adoc b/modules/configure/pages/configuring-network-policies.adoc similarity index 92% rename from modules/administration-guide/pages/configuring-network-policies.adoc rename to modules/configure/pages/configuring-network-policies.adoc index 762c8cd804..955e7646af 100644 --- a/modules/administration-guide/pages/configuring-network-policies.adoc +++ b/modules/configure/pages/configuring-network-policies.adoc @@ -1,16 +1,19 @@ :_content-type: CONCEPT -:description: Configuring network policies +:description: Restrict network traffic between workspaces :keywords: administration guide, configuring, namespace, network policy, network policies, multitenant isolation -:navtitle: Configuring network policies +:navtitle: Restrict network traffic between workspaces :page-aliases: installation-guide:configuring-network-policies.adoc [id="configuring-networking-policies"] -= Configuring network policies += Restrict network traffic between workspaces -By default, all Pods in a {orch-name} cluster can communicate with each other even if they are in different namespaces. + +Restrict network traffic between workspace Pods. By default, all Pods in a {orch-name} cluster can communicate with each other even if they are in different namespaces. In the context of {prod-short}, this makes it possible for a workspace Pod in one user {orch-namespace} to send traffic to another workspace Pod in a different user {orch-namespace}. + For security, multitenant isolation could be configured by using NetworkPolicy objects to restrict all incoming communication to Pods in a user {orch-namespace}. + However, Pods in the {prod-short} {orch-namespace} must be able to communicate with Pods in user {orch-namespace}s. .Prerequisites diff --git a/modules/administration-guide/pages/configuring-proxy.adoc b/modules/configure/pages/configuring-proxy.adoc similarity index 84% rename from modules/administration-guide/pages/configuring-proxy.adoc rename to modules/configure/pages/configuring-proxy.adoc index 9582e46d72..babd0aba25 100644 --- a/modules/administration-guide/pages/configuring-proxy.adoc +++ b/modules/configure/pages/configuring-proxy.adoc @@ -1,16 +1,23 @@ :_content-type: PROCEDURE -:description: Configuring proxy +:description: Route traffic through a proxy :keywords: administration guide, proxy, networking -:navtitle: Configuring proxy +:navtitle: Route traffic through a proxy :page-aliases: [id="configuring-proxy"] -= Configuring proxy += Route traffic through a proxy -Learn how to configure a proxy for {prod}. The steps include creating a {kubernetes} Secret for proxy credentials and configuring the necessary proxy settings in the CheCluster custom resource. The proxy settings are propagated to the operands and workspaces through environment variables. + +Route {prod-short} traffic through a corporate proxy when direct internet access is restricted. Create a proxy credentials Secret and configure the CheCluster Custom Resource. On OpenShift cluster, you do not need to configure proxy settings. {prod-short} Operator automatically uses OpenShift cluster-wide proxy configuration. However, you can override the proxy settings by specifying them in the CheCluster custom resource. +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* The proxy server URL, port, and (if the proxy requires authentication) the username and password. + .Procedure . (OPTIONAL) Create a Secret in the {prod-namespace} {namespace} that contains a user and password for a proxy server. The secret must have the `app.kubernetes.io/part-of=che.eclipse.org` label. Skip this step if the proxy server does not require authentication. @@ -56,7 +63,7 @@ EOF <4> Protocol and domain of the proxy server. -.Verification steps +.Verification . Start a workspace diff --git a/modules/administration-guide/pages/configuring-storage-classes.adoc b/modules/configure/pages/configuring-storage-classes.adoc similarity index 78% rename from modules/administration-guide/pages/configuring-storage-classes.adoc rename to modules/configure/pages/configuring-storage-classes.adoc index 9724420c40..a80f1f9424 100644 --- a/modules/administration-guide/pages/configuring-storage-classes.adoc +++ b/modules/configure/pages/configuring-storage-classes.adoc @@ -1,13 +1,15 @@ :_content-type: PROCEDURE -:description: Configuring storage classes +:description: Use a custom storage provisioner :keywords: administration guide, configuring, {prod-id-short}, storage class, storage classes -:navtitle: Configuring storage classes +:navtitle: Use a custom storage provisioner :page-aliases: installation-guide:configuring-storage-classes.adoc [id="configuring-storage-classes"] -= Configuring storage classes += Use a custom storage provisioner + + +Use a custom storage class to bind workspace persistent volumes to specific infrastructure storage, install {prod-short} using storage classes. This is especially useful when you want to bind a persistent volume provided by a non-default provisioner. -To configure {prod-short} to use a configured infrastructure storage, install {prod-short} using storage classes. This is especially useful when you want to bind a persistent volume provided by a non-default provisioner. {prod-short} has one component that requires persistent volumes to store data: @@ -26,6 +28,12 @@ Persistent volume claims facts: + Define a storage class name in the {prod-short} configuration to use the storage classes feature in the {prod-short} PVC. +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* A `StorageClass` resource already provisioned in the cluster. You need the exact name of the storage class to configure. + .Procedure Use CheCluster Custom Resource definition to define storage classes: diff --git a/modules/administration-guide/pages/configuring-storage-sizes.adoc b/modules/configure/pages/configuring-storage-sizes.adoc similarity index 85% rename from modules/administration-guide/pages/configuring-storage-sizes.adoc rename to modules/configure/pages/configuring-storage-sizes.adoc index 80d7922ae1..e6c80e387a 100644 --- a/modules/administration-guide/pages/configuring-storage-sizes.adoc +++ b/modules/configure/pages/configuring-storage-sizes.adoc @@ -1,11 +1,19 @@ :_content-type: PROCEDURE -:description: Configuring storage sizes +:description: Adjust workspace storage capacity :keywords: administration guide, configuring, {prod-id-short}, storage sizes, PVC size, pvc -:navtitle: Configuring storage sizes +:navtitle: Adjust workspace storage capacity :page-aliases: installation-guide:configuring-storage-sizes.adoc [id="configuring-storage-sizes"] -= Configuring storage sizes += Adjust workspace storage capacity + + +Adjust the persistent volume claim (PVC) size for workspaces to allocate more or less disk space depending on project requirements and available cluster storage. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + pass:[] diff --git a/modules/administration-guide/pages/configuring-the-storage-strategy.adoc b/modules/configure/pages/configuring-the-storage-strategy.adoc similarity index 66% rename from modules/administration-guide/pages/configuring-the-storage-strategy.adoc rename to modules/configure/pages/configuring-the-storage-strategy.adoc index dcbc6256b9..bd752b145d 100644 --- a/modules/administration-guide/pages/configuring-the-storage-strategy.adoc +++ b/modules/configure/pages/configuring-the-storage-strategy.adoc @@ -1,13 +1,14 @@ :_content-type: PROCEDURE -:description: Configuring the storage strategy +:description: Choose how workspace data is persisted :keywords: administration guide, configuring, {prod-short}, storage, strategy, per-user, per-workspace, ephemeral -:navtitle: Configuring the storage strategy +:navtitle: Choose how workspace data is persisted :page-aliases: installation-guide:configuring-the-storage-strategy.adoc [id="configuring-the-storage-strategy"] -= Configuring the storage strategy += Choose how workspace data is persisted -{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:end-user-guide:url-parameter-for-the-workspace-storage.adoc[URL parameter]. + +Choose a storage strategy that controls whether workspace data persists after a restart. The selected storage strategy applies to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:end-user-guide:url-parameter-for-the-workspace-storage.adoc[URL parameter]. Available storage strategies: @@ -17,6 +18,10 @@ Available storage strategies: The default storage strategy used in {prod-short} is `per-user`. +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + .Procedure . Set the `pvcStrategy` field in the Che Cluster Custom Resource to `per-user`, `per-workspace` or `ephemeral`. diff --git a/modules/administration-guide/pages/configuring-workspace-target-namespace.adoc b/modules/configure/pages/configuring-workspace-target-namespace.adoc similarity index 78% rename from modules/administration-guide/pages/configuring-workspace-target-namespace.adoc rename to modules/configure/pages/configuring-workspace-target-namespace.adoc index 09957b1453..add9d231a1 100644 --- a/modules/administration-guide/pages/configuring-workspace-target-namespace.adoc +++ b/modules/configure/pages/configuring-workspace-target-namespace.adoc @@ -1,13 +1,18 @@ :_content-type: PROCEDURE -:description: Configuring a user {orch-namespace} name for automatic provisioning +:description: Set the workspace namespace naming convention :keywords: administration guide, configuring, namespace -:navtitle: Configuring {orch-namespace} name +:navtitle: Set the workspace namespace naming convention :page-aliases: [id="configuring-a-user-{orch-namespace}-name-for-automatic-provisioning"] -= Configuring a user {orch-namespace} name for automatic provisioning += Set the workspace namespace naming convention -You can configure the {orch-namespace} name template that {prod-short} uses to create the required {orch-namespace} when starting a workspace. + +Set the {orch-namespace} name template that {prod-short} uses when creating a workspace {orch-namespace}. This controls the naming convention for all auto-provisioned user namespaces. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. A valid {orch-namespace} name template follows these conventions: diff --git a/modules/administration-guide/pages/configuring-workspaces-endpoints-base-domain.adoc b/modules/configure/pages/configuring-workspaces-endpoints-base-domain.adoc similarity index 67% rename from modules/administration-guide/pages/configuring-workspaces-endpoints-base-domain.adoc rename to modules/configure/pages/configuring-workspaces-endpoints-base-domain.adoc index b5302164ec..37bf12695b 100644 --- a/modules/administration-guide/pages/configuring-workspaces-endpoints-base-domain.adoc +++ b/modules/configure/pages/configuring-workspaces-endpoints-base-domain.adoc @@ -1,13 +1,21 @@ :_content-type: PROCEDURE -:description: Configuring workspace endpoints base domain +:description: Set a custom domain for workspace URLs :keywords: administration guide, workspaces, networking, endpoints, domain -:navtitle: Configuring workspace endpoints base domain +:navtitle: Set a custom domain for workspace URLs :page-aliases: [id="configuring-workspaces-endpoints-base-domain"] -= Configuring workspace endpoints base domain += Set a custom domain for workspace URLs + + +Set the base domain used for workspace endpoint URLs when you need workspace routes served from a different domain than the dashboard. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* A DNS domain name configured to resolve to the cluster ingress where workspace routes will be served. -Learn how to configure the base domain for workspace endpoints. By default, {prod-short} Operator automatically detects the base domain. To change it, you need to configure the `CHE_INFRA_OPENSHIFT_ROUTE_HOST_DOMAIN__SUFFIX` property in the `CheCluster` Custom Resource. [source,yaml,subs="+quotes"] ---- @@ -18,6 +26,7 @@ spec: CHE_INFRA_OPENSHIFT_ROUTE_HOST_DOMAIN__SUFFIX: "<...>" <1> ---- + <1> Workspace endpoints base domain, for example, `my-{prod-id-short}.example.com`. .Procedure diff --git a/modules/administration-guide/pages/configuring-workspaces-nodeselector.adoc b/modules/configure/pages/configuring-workspaces-nodeselector.adoc similarity index 79% rename from modules/administration-guide/pages/configuring-workspaces-nodeselector.adoc rename to modules/configure/pages/configuring-workspaces-nodeselector.adoc index 156732bc74..d546a449aa 100644 --- a/modules/administration-guide/pages/configuring-workspaces-nodeselector.adoc +++ b/modules/configure/pages/configuring-workspaces-nodeselector.adoc @@ -1,13 +1,20 @@ :_content-type: PROCEDURE -:description: Configuring workspaces nodeSelector +:description: Control which nodes run workspaces :keywords: administration guide, configuring-workspaces-nodeselector -:navtitle: Configuring workspaces nodeSelector +:navtitle: Control which nodes run workspaces :page-aliases: installation-guide:configuring-workspaces-nodeselector.adoc [id="configuring-workspaces-nodeselector"] -= Configuring workspaces nodeSelector += Control which nodes run workspaces -This section describes how to configure link:https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/[`nodeSelector`] for Pods of {prod-short} workspaces. + +Control which cluster nodes run workspace Pods by setting a `nodeSelector` or tolerations in the CheCluster Custom Resource. Use this to isolate workspaces on dedicated hardware. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* The target nodes are labeled or tainted according to the scheduling rules you want to apply. .Procedure .. Using NodeSelector diff --git a/modules/administration-guide/pages/customizing-openshift-che-branding-images.adoc b/modules/configure/pages/customizing-openshift-che-branding-images.adoc similarity index 88% rename from modules/administration-guide/pages/customizing-openshift-che-branding-images.adoc rename to modules/configure/pages/customizing-openshift-che-branding-images.adoc index 31a81b476d..5816a9ab07 100644 --- a/modules/administration-guide/pages/customizing-openshift-che-branding-images.adoc +++ b/modules/configure/pages/customizing-openshift-che-branding-images.adoc @@ -1,13 +1,14 @@ :_content-type: PROCEDURE -:description: Customizing OpenShift Eclipse Che branding images +:description: Apply your organization's branding to the dashboard :keywords: administration guide, customizing, branding, images -:navtitle: Customizing OpenShift Eclipse Che branding images +:navtitle: Apply your organization's branding to the dashboard :page-aliases: installation-guide:customizing-openshift-che-consolelink-icon.adoc, customizing-openshift-che-consolelink-icon.adoc [id="customizing-openshift-che-branding-images"] -= Customizing {ocp} {prod} branding images += Apply your organization's branding to the dashboard -Customize the branding images for the {prod} dashboard by overriding the default images in the `assets/branding` directory. The following images can be customized: + +Apply your organization's branding to the {prod} dashboard by overriding the default images in the `assets/branding` directory. The following images can be customized: * `che-logo.svg` — the logo displayed in the dashboard header. * `loader.svg` — the loader icon displayed during dashboard loading. The loader image supports the following formats, in priority order: `jpg`, `jpeg`, `png`, `gif`, `webp`, `svg`. The `svg` format is used as the default fallback. diff --git a/modules/administration-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc b/modules/configure/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc similarity index 89% rename from modules/administration-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc rename to modules/configure/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc index bfa9f9edf1..e6728736a8 100644 --- a/modules/administration-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc +++ b/modules/configure/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc @@ -1,13 +1,15 @@ :_content-type: PROCEDURE -:description: Deploying {prod-short} with support for Git repositories with self-signed certificates +:description: Trust self-signed Git server certificates :keywords: administration guide, deploying-che-with-support-for-git-repositories-with-self-signed-certificates -:navtitle: Git with self-signed certificates +:navtitle: Trust self-signed Git server certificates :page-aliases: installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc [id="deploying-{prod-id-short}-with-support-for-git-repositories-with-self-signed-certificates"] -= Deploying {prod-short} with support for Git repositories with self-signed certificates += Trust self-signed Git server certificates + + +Trust self-signed certificates from your internal Git server so that workspaces can clone and push to repositories secured by internal certificate authorities. -You can configure {prod-short} to support operations on Git providers that use self-signed certificates. .Prerequisites @@ -55,7 +57,7 @@ spec: gitTrustedCertsConfigMapName: che-git-self-signed-cert ---- -.Verification steps +.Verification * Create and start a new workspace. Every container used by the workspace mounts a special volume that contains a file with the self-signed certificate. The container's `/etc/gitconfig` file contains information about the Git server host (its URL) and the path to the certificate in the `http` section (see Git documentation about link:https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslCAInfo[git-config]). + diff --git a/modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc b/modules/configure/pages/devworkspace-backup-integrated-openshift-registry.adoc similarity index 69% rename from modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc rename to modules/configure/pages/devworkspace-backup-integrated-openshift-registry.adoc index f84d79eeb9..bd79180409 100644 --- a/modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc +++ b/modules/configure/pages/devworkspace-backup-integrated-openshift-registry.adoc @@ -1,13 +1,20 @@ :_content-type: PROCEDURE -:description: Configuring DevWorkspace backup with the integrated OpenShift container registry +:description: Configure backup with the integrated {orch-name} registry :keywords: backup, storage, openshift, registry -:navtitle: Integrated OpenShift container registry +:navtitle: Configure backup with the integrated {orch-name} registry //:page-aliases: [id="devworkspace-backup-integrated-openshift-registry"] -= Configuring backup with the integrated OpenShift container registry += Configure backup with the integrated {orch-name} registry -This option is available only on OpenShift clusters with https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp4-ver}/html/registry/setting-up-and-configuring-the-registry[integrated container registry] enabled and requires no additional configuration. + +Configure the {devworkspace} backup to use the integrated {orch-name} container registry, available on clusters with the https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp4-ver}/html/registry/setting-up-and-configuring-the-registry[integrated container registry] enabled. This option requires no additional credentials configuration. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* The https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp4-ver}/html/registry/setting-up-and-configuring-the-registry[integrated container registry] is enabled on the cluster. To enable the backup use following configuration in the global DWOC: diff --git a/modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc b/modules/configure/pages/devworkspace-backup-regular-oci-registry.adoc similarity index 83% rename from modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc rename to modules/configure/pages/devworkspace-backup-regular-oci-registry.adoc index 12aa7b9009..aae32131f8 100644 --- a/modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc +++ b/modules/configure/pages/devworkspace-backup-regular-oci-registry.adoc @@ -1,17 +1,24 @@ :_content-type: PROCEDURE -:description: Configuring DevWorkspace backup with a regular OCI-compatible registry +:description: Configure backup with a regular OCI-compatible registry :keywords: backup, storage, oci, registry, quay -:navtitle: Regular OCI-compatible registry +:navtitle: Configure backup with a regular OCI-compatible registry //:page-aliases: [id="devworkspace-backup-regular-oci-registry"] -= Configuring backup with a regular OCI-compatible registry += Configure backup with a regular OCI-compatible registry + To use a regular OCI-compatible registry for backups, you need to provide registry credentials. Depending on your RBAC policy, the token can be provided via a secret in the Operator {namespace} or in each {devworkspace} {namespace}. Having the secret in the {devworkspace} {namespace} allows for using different registry accounts per {namespace} with more granular access control. +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +* Credentials (username and token) for an OCI-compatible registry such as link:https://quay.io[Quay.io] with push permissions to the target repository path. + [source,yaml,subs="+attributes,+quotes"] ---- kind: DevWorkspaceOperatorConfig @@ -31,6 +38,7 @@ config: schedule: '0 */4 * * *' imagePullPolicy: Always ---- + <1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview]. The `authSecret` must be named `devworkspace-backup-registry-auth`. It must reference a {kubernetes} Secret of type `kubernetes.io/dockerconfigjson` that contains credentials to access the registry. diff --git a/modules/administration-guide/pages/devworkspace-backup.adoc b/modules/configure/pages/devworkspace-backup.adoc similarity index 96% rename from modules/administration-guide/pages/devworkspace-backup.adoc rename to modules/configure/pages/devworkspace-backup.adoc index c4fc4ef0aa..5e0aa1bf66 100644 --- a/modules/administration-guide/pages/devworkspace-backup.adoc +++ b/modules/configure/pages/devworkspace-backup.adoc @@ -1,17 +1,20 @@ :_content-type: ASSEMBLY -:description: DevWorkspace backup +:description: Back up workspaces :keywords: backup, storage -:navtitle: DevWorkspace backup +:navtitle: Back up workspaces //:page-aliases: [id="devworkspace-backup"] -= Workspace backup for {prod} += Back up workspaces + The {devworkspace} backup job provides periodic backups of {devworkspace} data to a specified location. After you enable and configure the job, it runs at defined intervals to create backups of {devworkspace} data. The backup controller requires an OCI-compliant registry, such as the e.g., link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp4-ver}/html/registry/registry-overview#registry-integrated-openshift-registry_registry-overview[Red Hat OpenShift built-in registry] integrated registry or link:https://quay.io[Quay.io], to store backup archives as image artifacts. + + The backup makes a snapshot of *stopped* Workspace PVCs and stores them as tar.gz archives in the specified OCI registry. Users can restore backups from the {prod-short} dashboard. See xref:end-user-guide:restoring-workspaces-from-backups.adoc[]. diff --git a/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc b/modules/configure/pages/enabling-access-to-dev-fuse-for-openshift.adoc similarity index 94% rename from modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc rename to modules/configure/pages/enabling-access-to-dev-fuse-for-openshift.adoc index f0ede58afc..c1465dc99f 100644 --- a/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc +++ b/modules/configure/pages/enabling-access-to-dev-fuse-for-openshift.adoc @@ -1,14 +1,16 @@ :_content-type: PROCEDURE -:description: Enabling access to /dev/fuse for OpenShift version older than 4.15 containers +:description: Enable access to /dev/fuse for {orch-name} versions older than 4.15 :keywords: administration-guide, configuring, fuse, /dev/fuse -:navtitle: Enabling access to for OpenShift version older than 4.15 +:navtitle: Enable access to /dev/fuse for {orch-name} versions older than 4.15 :page-aliases: [id="enabling-container-access-to-dev-fuse-for-openshift"] -= Enabling container access to /dev/fuse for OpenShift older than 4.15 += Enable access to /dev/fuse for {orch-name} versions older than 4.15 + To use fuse-overlayfs, you must make `/dev/fuse` accessible to workspace containers first. + [NOTE] ==== This procedure is not necessary for OpenShift versions 4.15 and later, since the `/dev/fuse` device is available by default. See link:https://docs.openshift.com/container-platform/4.15/release_notes/ocp-4-15-release-notes.html#ocp-4-15-nodes-dev-fuse[Release Notes]. @@ -115,7 +117,7 @@ io.openshift.podman-fuse: '' io.kubernetes.cri-o.Devices: /dev/fuse ---- -.Verification steps +.Verification . Get the name of a node with a `worker` role: + @@ -138,5 +140,5 @@ $ oc debug node/____ sh-4.4# stat /host/etc/crio/crio.conf.d/99-podman-fuse ---- -== Using fuse-overlayfs for Podman and Buildah within a workspace +== Use fuse-overlayfs for Podman and Buildah in a workspace Users can follow xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[] to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah. diff --git a/modules/administration-guide/pages/enabling-container-run-capabilities.adoc b/modules/configure/pages/enabling-container-run-capabilities.adoc similarity index 91% rename from modules/administration-guide/pages/enabling-container-run-capabilities.adoc rename to modules/configure/pages/enabling-container-run-capabilities.adoc index dc653bb351..88dfdfde52 100644 --- a/modules/administration-guide/pages/enabling-container-run-capabilities.adoc +++ b/modules/configure/pages/enabling-container-run-capabilities.adoc @@ -1,11 +1,12 @@ :_content-type: PROCEDURE -:description: Enabling container run capabilities +:description: Enable container run capabilities :keywords: administration-guide, container, podman, nested containers -:navtitle: Enabling container run capabilities +:navtitle: Enable container run capabilities :page-aliases: [id="enabling-container-run-capabilities"] -= Enabling container run capabilities += Enable container run capabilities + You can enable container run capabilities in {prod-short} workspaces to allow running nested containers using tools like Podman. This feature leverages Linux kernel diff --git a/modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc b/modules/configure/pages/enabling-fuse-for-all-workspaces.adoc similarity index 83% rename from modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc rename to modules/configure/pages/enabling-fuse-for-all-workspaces.adoc index 7be77ede2f..b9b8f697fe 100644 --- a/modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc +++ b/modules/configure/pages/enabling-fuse-for-all-workspaces.adoc @@ -1,15 +1,19 @@ :_content-type: PROCEDURE -:description: Enabling fuse-overlayfs for all workspaces +:description: Enable fuse-overlayfs for all workspaces :keywords: administration-guide, enable, fuse, all, workspaces -:navtitle: Enabling fuse-overlayfs for all workspaces +:navtitle: Enable fuse-overlayfs for all workspaces :page-aliases: [id="enabling-fuse-overlayfs-for-all-workspaces"] -= Enabling fuse-overlayfs for all workspaces += Enable fuse-overlayfs for all workspaces + + +Enable the fuse-overlayfs storage driver for all workspaces on the cluster by adding the required pod annotation to the CheCluster Custom Resource. + .Prerequisites -* The xref:administration-guide:enabling-access-to-dev-fuse-for-openshift.adoc[] section has been completed. This is not required for OpenShift versions 4.15 and later. +* The xref:enabling-access-to-dev-fuse-for-openshift.adoc[] section has been completed. This is not required for OpenShift versions 4.15 and later. * An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}. @@ -53,7 +57,7 @@ fi ---- ==== -.Verification steps +.Verification . Start a workspace and verify that the storage driver is `overlay`. + diff --git a/modules/administration-guide/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc b/modules/configure/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc similarity index 83% rename from modules/administration-guide/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc rename to modules/configure/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc index 689c4a3de4..72d2d34340 100644 --- a/modules/administration-guide/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc +++ b/modules/configure/pages/enabling-users-to-run-multiple-workspaces-simultaneously.adoc @@ -1,14 +1,20 @@ :_content-type: PROCEDURE -:description: Enabling users to run multiple workspaces simultaneously +:description: Enable users to run multiple workspaces simultaneously :keywords: administration guide, number, workspaces -:navtitle: Enabling users to run multiple workspaces simultaneously +:navtitle: Enable users to run multiple workspaces simultaneously :page-aliases: [id="enabling-users-to-run-multiple-workspaces-simultaneously"] -= Enabling users to run multiple workspaces simultaneously += Enable users to run multiple workspaces simultaneously + By default, a user can run only one workspace at a time. You can enable users to run multiple workspaces simultaneously. +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + + NOTE: If using the default storage method, users might experience problems when concurrently running workspaces if pods are distributed across nodes in a multi-node cluster. Switching from the per-user `common` storage strategy to the `per-workspace` storage strategy or using the `ephemeral` storage type can avoid or solve those problems. This configuration is part of the `CheCluster` Custom Resource: diff --git a/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc b/modules/configure/pages/importing-untrusted-tls-certificates.adoc similarity index 96% rename from modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc rename to modules/configure/pages/importing-untrusted-tls-certificates.adoc index 2145770da2..83cd176148 100644 --- a/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc +++ b/modules/configure/pages/importing-untrusted-tls-certificates.adoc @@ -1,11 +1,12 @@ :_content-type: CONCEPT -:description: Importing untrusted TLS certificates to {prod-short} +:description: Trust custom TLS certificates for external services :keywords: administration guide, tls, certificate -:navtitle: Importing untrusted TLS certificates to {prod-short} +:navtitle: Trust custom TLS certificates for external services :page-aliases: installation-guide:importing-untrusted-tls-certificates.adoc, installation-guide:importing-untrusted-tls-certificates-old.adoc [id="importing-untrusted-tls-certificates"] -= Importing untrusted TLS certificates to {prod-short} += Trust custom TLS certificates for external services + {prod-short} components communications with external services are encrypted with TLS. They require TLS certificates signed by trusted Certificate Authorities (CA). @@ -15,6 +16,7 @@ Therefore, you must import into {prod-short} all untrusted CA chains in use by a * An identity provider (OIDC) * A source code repositories provider (Git) + {prod-short} uses labeled ConfigMaps in {prod-short} {orch-namespace} as sources for TLS certificates. The ConfigMaps can have an arbitrary amount of keys with an arbitrary amount of certificates each. All certificates are mounted into: @@ -81,7 +83,7 @@ Otherwise, wait until the rollout of {prod-short} components finishes. . Restart running workspaces for the changes to take effect. -.Verification steps +.Verification . Verify that the ConfigMap contains your custom CA certificates. This command returns CA bundle certificates in PEM format: + diff --git a/modules/administration-guide/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc b/modules/configure/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc similarity index 82% rename from modules/administration-guide/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc rename to modules/configure/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc index 9a1a59b08c..05b6562cca 100644 --- a/modules/administration-guide/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc +++ b/modules/configure/pages/limiting-the-number-of-workspaces-that-a-user-can-keep.adoc @@ -1,14 +1,19 @@ :_content-type: PROCEDURE -:description: Limiting the number of workspaces that a user can keep +:description: Limit the number of workspaces that a user can keep :keywords: administration guide, number, workspaces -:navtitle: Limiting the number of workspaces that a user can keep +:navtitle: Limit the number of workspaces that a user can keep :page-aliases: configuring-the-number-of-workspaces-that-a-user-can-create.adoc [id="limiting-the-number-of-workspaces-that-a-user-can-keep"] -= Limiting the number of workspaces that a user can keep += Limit the number of workspaces that a user can keep + By default, users can keep an unlimited number of workspaces in the dashboard, but you can limit this number to reduce demand on the cluster. +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + This configuration is part of the `CheCluster` Custom Resource: [source,yaml,subs="+quotes"] diff --git a/modules/administration-guide/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc b/modules/configure/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc similarity index 72% rename from modules/administration-guide/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc rename to modules/configure/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc index 5367744706..9cdb837b6c 100644 --- a/modules/administration-guide/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc +++ b/modules/configure/pages/limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously.adoc @@ -1,13 +1,20 @@ :_content-type: PROCEDURE -:description: Limiting the number of workspaces that all users can run simultaneously +:description: Limit the number of workspaces that all users can run simultaneously :keywords: administration guide, number, workspaces -:navtitle: Limiting the number of workspaces that all users can run simultaneously +:navtitle: Limit the number of workspaces that all users can run simultaneously :page-aliases: [id="limiting-the-number-of-workspaces-that-all-users-can-run-simultaneously"] -= Limiting the number of workspaces that all users can run simultaneously += Limit the number of workspaces that all users can run simultaneously -By default, all users can run unlimited number of workspaces. You can limit the number of workspaces that all users can run simultaneously. This configuration is part of the `CheCluster` Custom Resource: + +By default, all users can run unlimited number of workspaces. You can limit the number of workspaces that all users can run simultaneously. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +This configuration is part of the `CheCluster` Custom Resource: [source,yaml,subs="+quotes"] ---- diff --git a/modules/administration-guide/pages/managing-workloads-using-the-che-server-api.adoc b/modules/configure/pages/managing-workloads-using-the-che-server-api.adoc similarity index 66% rename from modules/administration-guide/pages/managing-workloads-using-the-che-server-api.adoc rename to modules/configure/pages/managing-workloads-using-the-che-server-api.adoc index a30623710a..7f95e0db4d 100644 --- a/modules/administration-guide/pages/managing-workloads-using-the-che-server-api.adoc +++ b/modules/configure/pages/managing-workloads-using-the-che-server-api.adoc @@ -1,14 +1,19 @@ :_content-type: PROCEDURE -:description: Managing {prod-short} server and {prod-short} dashboard workloads using the API +:description: Use the {prod-short} server API :keywords: administration-guide, api -:navtitle: Using the {prod-short} server API +:navtitle: Use the {prod-short} server API :page-aliases: [id="managing-workloads-using-the-{prod-id-short}-server-api"] -= Managing {prod-short} server and {prod-short} dashboard workloads using the API += Use the {prod-short} server API + To manage {prod-short} server and {prod-short} dashboard workloads, use the Swagger web user interface to navigate the API. +.Prerequisites + +* Access to the {prod-short} dashboard URL with administrative privileges. + .Procedure * Navigate to the Swagger API web user interface: @@ -19,4 +24,4 @@ IMPORTANT: DevWorkspace is a k8s object and manipulations should happen on the K .Additional resources -* link:https://swagger.io/[Swagger] +* link:https://swagger.io/[Swagger API framework] (used by {prod-short} for interactive API documentation) diff --git a/modules/administration-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc b/modules/configure/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc similarity index 60% rename from modules/administration-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc rename to modules/configure/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc index dfacaf2559..d43d22933c 100644 --- a/modules/administration-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc +++ b/modules/configure/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc @@ -1,21 +1,18 @@ :_content-type: ASSEMBLY -:description: Mounting a Secret or a ConfigMap as a file or an environment variable into a {prod} container +:description: Inject files from Secrets and ConfigMaps into containers :keywords: administration guide, mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container -:navtitle: Mounting a Secret or a ConfigMap as a file or an environment variable into a {prod} container +:navtitle: Inject files from Secrets and ConfigMaps into containers :page-aliases: installation-guide:mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container.adoc, installation-guide:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc [id="mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container"] -= Mounting a Secret or a ConfigMap as a file or an environment variable into a {prod-short} container += Inject files from Secrets and ConfigMaps into containers -Secrets are {platforms-name} objects that store sensitive data such as: +Inject configuration from {platforms-name} Secrets and ConfigMaps into workspace containers as files or environment variables, so that workspaces have access to credentials, tokens, and settings without hardcoding them in devfiles. -* usernames -* passwords -* authentication tokens -in an encrypted form. +Secrets are {platforms-name} objects that store sensitive data (usernames, passwords, authentication tokens) in an encrypted form. Users can mount a {platforms-name} Secret that contains sensitive data or a ConfigMap that contains configuration in a {prod-short} managed containers as: @@ -24,9 +21,9 @@ Users can mount a {platforms-name} Secret that contains sensitive data or a Conf The mounting process uses the standard {platforms-name} mounting mechanism, but it requires additional annotations and labeling. -include::partial$proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc[leveloffset=+1] +include::partial$proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc[] -include::partial$proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc[leveloffset=+1] +include::partial$proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc[] -include::partial$proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc[leveloffset=+1] +include::partial$proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc[] diff --git a/modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc b/modules/configure/pages/provisioning-namespaces-in-advance.adoc similarity index 72% rename from modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc rename to modules/configure/pages/provisioning-namespaces-in-advance.adoc index e4c7a95a85..95dce7cd9a 100644 --- a/modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc +++ b/modules/configure/pages/provisioning-namespaces-in-advance.adoc @@ -1,13 +1,19 @@ :_content-type: PROCEDURE -:description: Provisioning {orch-namespace}s in advance +:description: Provision projects in advance :keywords: administration guide, provisioning, {orch-namespace} -:navtitle: Provisioning {orch-namespace}s in advance +:navtitle: Provision projects in advance :page-aliases: [id="preprovisioning-{orch-namespace}s"] -= Provisioning {orch-namespace}s in advance += Provision projects in advance + + +Provision workspace {orch-namespace}s in advance, rather than relying on automatic provisioning. Repeat the procedure for each user. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. -You can provision workspaces {orch-namespace}s in advance, rather than relying on automatic provisioning. Repeat the procedure for each user. .Procedure diff --git a/modules/administration-guide/pages/understanding-the-checluster-custom-resource.adoc b/modules/configure/pages/understanding-the-checluster-custom-resource.adoc similarity index 75% rename from modules/administration-guide/pages/understanding-the-checluster-custom-resource.adoc rename to modules/configure/pages/understanding-the-checluster-custom-resource.adoc index 2b4f043b24..b87202bdc8 100644 --- a/modules/administration-guide/pages/understanding-the-checluster-custom-resource.adoc +++ b/modules/configure/pages/understanding-the-checluster-custom-resource.adoc @@ -1,26 +1,27 @@ :_content-type: CONCEPT -:description: Understanding the `CheCluster` Custom Resource +:description: How the central configuration works :keywords: administration guide, understanding-the-checluster-custom-resource, configuring-che -:navtitle: Understanding the `CheCluster` Custom Resource -:page-aliases: installation-guide:understanding-the-checluster-custom-resource.adoc, installation-guide:configuring-the-che-installation.adoc +:navtitle: How the central configuration works +:page-aliases: installation-guide:understanding-the-checluster-custom-resource.adoc, installation-guide:configuring-the-che-installation.adoc, administration-guide:configuring-che.adoc, installation-guide:configuring-che.adoc, installation-guide:advanced-configuration.adoc, installation-guide:advanced-configuration-options.adoc [id="understanding-the-checluster-custom-resource"] -= Understanding the `CheCluster` Custom Resource += How the central configuration works + A default deployment of {prod-short} consists of a `CheCluster` Custom Resource parameterized by the {prod} Operator. + The `CheCluster` Custom Resource is a {kubernetes} object. You can configure it by editing the `CheCluster` Custom Resource YAML file. This file contains sections to configure each component: `devWorkspace`, `cheServer`, `pluginRegistry`, `devfileRegistry`, `dashboard` and `imagePuller`. The {prod} Operator translates the `CheCluster` Custom Resource into a config map usable by each component of the {prod-short} installation. The {orch-name} platform applies the configuration to each component, and creates the necessary Pods. When {orch-name} detects changes in the configuration of a component, it restarts the Pods accordingly. -.Configuring the main properties of the {prod-short} server component -==== +For example, to configure the main properties of the {prod-short} server component: + . Apply the `CheCluster` Custom Resource YAML file with suitable modifications in the `cheServer` component section. -. The Operator generates the `che` `ConfigMap`. +. The Operator generates the `che` `ConfigMap`. . {orch-name} detects changes in the `ConfigMap` and triggers a restart of the {prod-short} Pod. -==== .Additional resources diff --git a/modules/administration-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc b/modules/configure/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc similarity index 78% rename from modules/administration-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc rename to modules/configure/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc index 4cf4c4069e..626a7aaec1 100644 --- a/modules/administration-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc +++ b/modules/configure/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc @@ -1,13 +1,15 @@ :_content-type: PROCEDURE -:description: Using the CLI to configure the CheCluster Custom Resource +:description: Edit the central configuration from the command line :keywords: administration guide -:navtitle: Using the CLI to configure the CheCluster Custom Resource +:navtitle: Edit the central configuration from the command line :page-aliases: installation-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc, installation-guide:using-cli-to-configure-the-checluster-custom-resource.adoc [id="using-the-cli-to-configure-the-checluster-custom-resource"] -= Using the CLI to configure the CheCluster Custom Resource += Edit the central configuration from the command line + + +Edit the `CheCluster` Custom Resource YAML file to configure a running instance of {prod-short} from the command line. -To configure a running instance of {prod-short}, edit the `CheCluster` Custom Resource YAML file. .Prerequisites diff --git a/modules/administration-guide/partials/con_understanding-che-server-advanced-configuration.adoc b/modules/configure/partials/con_understanding-che-server-advanced-configuration.adoc similarity index 75% rename from modules/administration-guide/partials/con_understanding-che-server-advanced-configuration.adoc rename to modules/configure/partials/con_understanding-che-server-advanced-configuration.adoc index cff4e5de04..e20cc458a9 100644 --- a/modules/administration-guide/partials/con_understanding-che-server-advanced-configuration.adoc +++ b/modules/configure/partials/con_understanding-che-server-advanced-configuration.adoc @@ -3,11 +3,9 @@ // advanced-configuration-options [id="understanding-{prod-id-short}-server-advanced-configuration"] -= Understanding {prod-short} server advanced configuration +== When to use advanced server configuration -The following section describes the {prod-short} server component advanced configuration method for a deployment. - -Advanced configuration is necessary to: +Advanced configuration is necessary when you need to: * Add environment variables not automatically generated by the Operator from the standard `CheCluster` Custom Resource fields. * Override the properties automatically generated by the Operator from the standard `CheCluster` Custom Resource fields. @@ -16,10 +14,8 @@ Advanced configuration is necessary to: The `customCheProperties` field, part of the `CheCluster` Custom Resource `server` settings, contains a map of additional environment variables to apply to the {prod-short} server component. -.Override the default memory limit for workspaces -==== -* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. -+ +For example, to override the default log format, configure the `CheCluster` Custom Resource: + [source,yaml,subs="+quotes,+attributes,+macros"] ---- apiVersion: org.eclipse.che/v2 @@ -30,7 +26,6 @@ spec: extraProperties: CHE_LOGS_APPENDERS_IMPL: json ---- -==== [NOTE] ==== diff --git a/modules/administration-guide/partials/proc_configuring-routes.adoc b/modules/configure/partials/proc_configuring-routes.adoc similarity index 95% rename from modules/administration-guide/partials/proc_configuring-routes.adoc rename to modules/configure/partials/proc_configuring-routes.adoc index 8e74a48c60..96fe98662d 100644 --- a/modules/administration-guide/partials/proc_configuring-routes.adoc +++ b/modules/configure/partials/proc_configuring-routes.adoc @@ -1,6 +1,6 @@ [id="configuring-routes"] -= Configuring OpenShift Route to work with Router Sharding +== Route workspace traffic through a shared ingress controller You can configure labels, annotations, and domains for OpenShift Route to work with link:https://docs.openshift.com/container-platform/4.7/networking/ingress-operator.html#nw-ingress-sharding_configuring-ingress[Router Sharding]. diff --git a/modules/administration-guide/partials/proc_configuring-server-logging.adoc b/modules/configure/partials/proc_configuring-server-logging.adoc similarity index 67% rename from modules/administration-guide/partials/proc_configuring-server-logging.adoc rename to modules/configure/partials/proc_configuring-server-logging.adoc index ef0e740b58..9bd7e47752 100644 --- a/modules/administration-guide/partials/proc_configuring-server-logging.adoc +++ b/modules/configure/partials/proc_configuring-server-logging.adoc @@ -1,11 +1,15 @@ // configuring-server-logging [id="configuring-log-levels"] -= Configuring log levels +== Set server log levels + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. .Procedure -* Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +* Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml,subs="+attributes,+quotes"] ---- @@ -34,5 +38,5 @@ spec: * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc b/modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc similarity index 93% rename from modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc rename to modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc index f93ab15069..18cc5f0283 100644 --- a/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc +++ b/modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc @@ -4,7 +4,7 @@ [id="mounting-a-secret-or-a-configmap-as-a-file-into-a-container"] -= Mounting a Secret or a ConfigMap as a file into a {prod-short} container +== Inject files from Secrets and ConfigMaps .Prerequisites @@ -13,14 +13,15 @@ .Procedure -include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1] +include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[] . Configure the annotation values. Annotations must indicate that the given object is mounted as a file: + +-- * `che.eclipse.org/mount-as: file` - To indicate that a object is mounted as a file. * `che.eclipse.org/mount-path: __` - To provide a required mount path. -.Example: +.Secret and ConfigMap with file-mount annotations ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -55,7 +56,7 @@ metadata: The {orch-name} object can contain several items whose names must match the desired file name mounted into the container. -.Example: +.Secret with a data key that maps to a filename ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -93,6 +94,7 @@ data: This results in a file named `ca.crt` being mounted at the `/data` path of the {prod-short} container. IMPORTANT: To make the changes in the {prod-short} container visible, re-create the Secret or the ConfigMap object entirely. +-- .Additional resources diff --git a/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc b/modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc similarity index 93% rename from modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc rename to modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc index 65ea99bdc1..4392bcba57 100644 --- a/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc +++ b/modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container.adoc @@ -4,7 +4,7 @@ [id="mounting-a-secret-or-a-configmap-as-a-subpath-into-a-container"] -= Mounting a Secret or a ConfigMap as a subPath into a {prod-short} container +== Add individual files without replacing directories .Prerequisites @@ -13,14 +13,15 @@ .Procedure -include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1] +include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[] . Configure the annotation values. Annotations must indicate that the given object is mounted as a subPath.: + +-- * `che.eclipse.org/mount-as: subpath` - To indicate that an object is mounted as a subPath. * `che.eclipse.org/mount-path: __` - To provide a required mount path. -.Example: +.Secret and ConfigMap with subPath annotations ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -55,7 +56,7 @@ metadata: The {orch-name} object can contain several items whose names must match the file name mounted into the container. -.Example: +.Secret with a data key mounted as subPath ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -93,6 +94,7 @@ data: This results in a file named `ca.crt` being mounted at the `/data` path of {prod-short} container. IMPORTANT: To make the changes in a {prod-short} container visible, re-create the Secret or the ConfigMap object entirely. +-- .Additional resources diff --git a/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc b/modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc similarity index 87% rename from modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc rename to modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc index 11ab0058c0..32d03d324a 100644 --- a/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc +++ b/modules/configure/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc @@ -4,7 +4,7 @@ [id="mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container"] -= Mounting a Secret or a ConfigMap as an environment variable into {prod-short} container +== Inject environment variables from Secrets and ConfigMaps .Prerequisites @@ -13,14 +13,15 @@ .Procedure -include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1] +include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[] . Configure the annotation values. Annotations must indicate that the given object is mounted as an environment variable: + +-- * `che.eclipse.org/mount-as: env` - to indicate that a object is mounted as an environment variable * `che.eclipse.org/env-name: __` - to provide an environment variable name, which is required to mount a object key value -.Example: +.Secret and ConfigMap with environment variable annotations ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -55,17 +56,11 @@ data: ---- ==== -This results in two environment variables: - -* `FOO_ENV` - -* `myvalue` - -being provisioned into the {prod-short} container. +This results in two environment variables `FOO_ENV` and `myvalue` being provisioned into the {prod-short} container. If the object provides more than one data item, the environment variable name must be provided for each of the data keys as follows: -.Example: +.Secret with multiple environment variable mappings ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -104,17 +99,12 @@ data: ---- ==== -This results in two environment variables: - -* `FOO_ENV` - -* `OTHER_ENV` - -being provisioned into a {prod-short} container. +This results in two environment variables `FOO_ENV` and `OTHER_ENV` being provisioned into a {prod-short} container. NOTE: The maximum length of annotation names in a {orch-name} object is 63 characters, where 9 characters are reserved for a prefix that ends with `/`. This acts as a restriction for the maximum length of the key that can be used for the object. IMPORTANT: To make the changes in the {prod-short} container visible, re-create the Secret or the ConfigMap object entirely. +-- .Additional resources diff --git a/modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc b/modules/configure/partials/snip_defining-dwo-namespace-for-backups.adoc similarity index 100% rename from modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc rename to modules/configure/partials/snip_defining-dwo-namespace-for-backups.adoc diff --git a/modules/administration-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc b/modules/configure/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc similarity index 84% rename from modules/administration-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc rename to modules/configure/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc index 3937dd7b6b..e780464794 100644 --- a/modules/administration-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc +++ b/modules/configure/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc @@ -8,29 +8,21 @@ . Create a new {platforms-name} Secret or a ConfigMap in the {platforms-name} {orch-namespace} where {prod-short} is deployed. The labels of the object that is about to be created must match the set of labels: + +-- * `app.kubernetes.io/part-of: che.eclipse.org` * `app.kubernetes.io/component: -` -+ -* The `` corresponds to the one following deployments: +Where: + +* `` is one of the following: ** `{prod-deployment}-dashboard` ** `devfile-registry` ** `plugin-registry` ** `{prod-deployment}` -+ -and -+ -* `` is either: -+ -** `secret` -+ -or -+ -** `configmap` -// The following content is downstream friendly +* `` is either `secret` or `configmap` -.Example: +.Secret and ConfigMap with required labels ==== [source,yaml,subs="+quotes,attributes"] ---- @@ -56,3 +48,4 @@ metadata: ... ---- ==== +-- diff --git a/modules/discover/pages/che-operator.adoc b/modules/discover/pages/che-operator.adoc index 920f08eb05..e09772d4ec 100644 --- a/modules/discover/pages/che-operator.adoc +++ b/modules/discover/pages/che-operator.adoc @@ -33,5 +33,5 @@ On a cluster with the {prod-short} operator, it is possible to create a `CheClus .Additional resources -* xref:administration-guide:understanding-the-checluster-custom-resource.adoc[] +* xref:configure:understanding-the-checluster-custom-resource.adoc[] * xref:install:installing-che.adoc[] diff --git a/modules/discover/pages/che-server.adoc b/modules/discover/pages/che-server.adoc index 81bd09b7be..bfd41af4ea 100644 --- a/modules/discover/pages/che-server.adoc +++ b/modules/discover/pages/che-server.adoc @@ -28,6 +28,6 @@ image::architecture/{project-context}-server-interactions.png[{prod-short} serve .Additional resources -* xref:administration-guide:advanced-configuration-options-for-the-che-server-component.adoc[] +* xref:configure:advanced-configuration-options-for-the-che-server-component.adoc[] include::example$snip_{project-context}-che-server-additional-resources.adoc[] diff --git a/modules/discover/pages/roles-and-tasks.adoc b/modules/discover/pages/roles-and-tasks.adoc index c487c1a27b..bedd4687ef 100644 --- a/modules/discover/pages/roles-and-tasks.adoc +++ b/modules/discover/pages/roles-and-tasks.adoc @@ -17,7 +17,7 @@ Platform administrators deploy, configure, secure, upgrade, and monitor {prod-sh Common tasks include: * Deploy {prod-short} on a cluster. See xref:install:installing-che.adoc[]. -* Configure the `CheCluster` custom resource. See xref:administration-guide:understanding-the-checluster-custom-resource.adoc[]. +* Configure the `CheCluster` custom resource. See xref:configure:understanding-the-checluster-custom-resource.adoc[]. * Set up OAuth for Git providers. See xref:administration-guide:configuring-oauth-for-git-providers.adoc[]. * Upgrade to the latest version. See xref:administration-guide:upgrading-che.adoc[]. * Monitor metrics and logs. See xref:administration-guide:configuring-observability.adoc[]. diff --git a/modules/end-user-guide/pages/accessing-fuse.adoc b/modules/end-user-guide/pages/accessing-fuse.adoc index 0ae1cf5d92..7e88703cd0 100644 --- a/modules/end-user-guide/pages/accessing-fuse.adoc +++ b/modules/end-user-guide/pages/accessing-fuse.adoc @@ -11,12 +11,12 @@ You must have access to `/dev/fuse` to use fuse-overlayfs. This section describe .Prerequisites -* For OpenShift versions older than 4.15, the administrator has enabled access to `/dev/fuse` by following xref:administration-guide:configuring-fuse.adoc[]. +* For OpenShift versions older than 4.15, the administrator has enabled access to `/dev/fuse` by following xref:configure:configuring-fuse.adoc[]. * Determine a workspace to use fuse-overlayfs with. .Procedure -. Use the `pod-overrides` attribute to add the required annotations defined in xref:administration-guide:configuring-fuse.adoc[] to the workspace. The `pod-overrides` attribute allows merging certain fields in the workspace pod's `spec`. +. Use the `pod-overrides` attribute to add the required annotations defined in xref:configure:configuring-fuse.adoc[] to the workspace. The `pod-overrides` attribute allows merging certain fields in the workspace pod's `spec`. + For OpenShift versions older than 4.15: + diff --git a/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc b/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc index 8726c0853d..2f0e08e42e 100644 --- a/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc +++ b/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc @@ -35,7 +35,7 @@ Otherwise, you can update the `/home/user/.config/containers/storage.conf` for a .Prerequisites -* For OpenShift versions older than 4.15, the administrator has enabled access to `/dev/fuse` by following xref:administration-guide:configuring-fuse.adoc[]. +* For OpenShift versions older than 4.15, the administrator has enabled access to `/dev/fuse` by following xref:configure:configuring-fuse.adoc[]. * A workspace with the required annotations are set by following xref:accessing-fuse.adoc[] diff --git a/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc b/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc index b320e23e5f..3b77ef5f31 100644 --- a/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc +++ b/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc @@ -10,7 +10,7 @@ When backups are enabled for {devworkspace} instances on your cluster, a cron job backs up workspace data for stopped workspaces. Backup storage, registry access, and schedules are configured cluster-wide by administrators in the {devworkspace} Operator. -For administrator steps, see xref:administration-guide:devworkspace-backup.adoc[]. +For administrator steps, see xref:configure:devworkspace-backup.adoc[]. Backing up and restoring workspaces allows you to recover uncommitted source code changes. Restored workspaces use a minimal devfile rather than the original project devfile. diff --git a/modules/end-user-guide/pages/using-a-git-provider-access-token.adoc b/modules/end-user-guide/pages/using-a-git-provider-access-token.adoc index bcf5f14d37..8abaf37653 100644 --- a/modules/end-user-guide/pages/using-a-git-provider-access-token.adoc +++ b/modules/end-user-guide/pages/using-a-git-provider-access-token.adoc @@ -7,7 +7,6 @@ [id="using-a-git-provider-access-token"] = Using a Git-provider access token -pass:[] OAuth for GitHub, GitLab, Bitbucket, or Microsoft Azure Repos needs to be xref:administration-guide:configuring-oauth-for-git-providers.adoc[configured by the administrator] of your organization's {prod-short} instance. If your administrator could not configure it for {prod-short} users, the workaround is for you to use a personal access token. You can configure personal access tokens on the *User Preferences* page of your {prod-short} dashboard: `pass:c,a,q[{prod-url}]/dashboard/#/user-preferences?tab=personal-access-tokens`, or apply it manually as a {kubernetes} Secret in the namespace. @@ -144,10 +143,9 @@ The `extraheader` configuration is needed for remote git operations to Azure Dev .Additional resources -* xref:administration-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[Deploying Che with support for Git repositories with self-signed certificates] +* xref:configure:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[Deploying Che with support for Git repositories with self-signed certificates] * link:https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on[Authorizing a personal access token for use with SAML single sign-on] -pass:[] diff --git a/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc b/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc index 54ec0af6f5..b3bed9a04c 100644 --- a/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc +++ b/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc @@ -17,7 +17,7 @@ For more efficient image management, use the fuse-overlayfs storage driver which You must meet the following requirements to use fuse-overlayfs in a workspace: -. For OpenShift versions older than 4.15, the administrator has enabled `/dev/fuse` access on the cluster by following xref:administration-guide:configuring-fuse.adoc[]. +. For OpenShift versions older than 4.15, the administrator has enabled `/dev/fuse` access on the cluster by following xref:configure:configuring-fuse.adoc[]. . The workspace has the necessary annotations for using the `/dev/fuse` device. See xref:accessing-fuse.adoc[]. . The `storage.conf` file in the workspace container has been configured to use fuse-overlayfs. See xref:enabling-overlay-with-a-configmap.adoc[]. diff --git a/modules/end-user-guide/partials/proc_creating-workspaces.adoc b/modules/end-user-guide/partials/proc_creating-workspaces.adoc index abd1d59e8d..a024314e25 100644 --- a/modules/end-user-guide/partials/proc_creating-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_creating-workspaces.adoc @@ -38,7 +38,7 @@ TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your On OpenShift, you can use the command-line `oc` tool to link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[display your current namespace or switch to a namespace]. ==== + -NOTE: {prod-short} administrators who intend to create workspaces for other users must create the `DevWorkspace` custom resource in a user namespace that is provisioned by {prod-short} or by the administrator. See xref:administration-guide:configuring-namespace-provisioning.adoc[]. +NOTE: {prod-short} administrators who intend to create workspaces for other users must create the `DevWorkspace` custom resource in a user namespace that is provisioned by {prod-short} or by the administrator. See xref:configure:configuring-namespace-provisioning.adoc[]. .Procedure diff --git a/modules/install/pages/con_next-steps-after-installation.adoc b/modules/install/pages/con_next-steps-after-installation.adoc index e554ee453a..69d840c816 100644 --- a/modules/install/pages/con_next-steps-after-installation.adoc +++ b/modules/install/pages/con_next-steps-after-installation.adoc @@ -15,6 +15,6 @@ After a successful installation, a few configuration tasks remain before your te .Additional resources -* xref:administration-guide:understanding-the-checluster-custom-resource.adoc[] +* xref:configure:understanding-the-checluster-custom-resource.adoc[] * xref:administration-guide:configuring-oauth-for-git-providers.adoc[] * xref:end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc[] 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..c5dc610bb6 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 @@ -37,7 +37,7 @@ $ {prod-cli} server:deploy \ --che-operator-cr-patch-yaml=che-operator-cr-patch.yaml ---- -. Allow incoming traffic from the {prod-short} namespace to all Pods in the user {orch-namespace}s. See: xref:administration-guide:configuring-network-policies.adoc[]. +. Allow incoming traffic from the {prod-short} namespace to all Pods in the user {orch-namespace}s. See: xref:configure:configuring-network-policies.adoc[]. .Verification 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..f144a0b040 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 @@ -367,4 +367,4 @@ sleep 5s && \ [role="_additional-resources"] .Additional resources -* xref:administration-guide:configuring-che-with-self-signed-certificate.adoc[] +* xref:configure:configuring-che-with-self-signed-certificate.adoc[] diff --git a/modules/install/pages/proc_installing-che-on-minikube.adoc b/modules/install/pages/proc_installing-che-on-minikube.adoc index 13cd49848d..fac62d026d 100644 --- a/modules/install/pages/proc_installing-che-on-minikube.adoc +++ b/modules/install/pages/proc_installing-che-on-minikube.adoc @@ -58,4 +58,4 @@ $ {prod-cli} dashboard:open [role="_additional-resources"] .Additional resources -* xref:administration-guide:configuring-che-with-self-signed-certificate.adoc[] +* xref:configure:configuring-che-with-self-signed-certificate.adoc[] 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..c5ba0eac8d 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 @@ -49,6 +49,6 @@ $ oc get configmap che -o jsonpath='{.data.__}' \ [role="_additional-resources"] .Additional resources -* xref:administration-guide:checluster-custom-resource-fields-reference.adoc[]. +* xref:configure:checluster-custom-resource-fields-reference.adoc[]. -* xref:administration-guide:advanced-configuration-options-for-the-che-server-component.adoc[]. +* xref:configure:advanced-configuration-options-for-the-che-server-component.adoc[]. diff --git a/modules/secure/pages/configuring-advanced-authorization.adoc b/modules/secure/pages/configuring-advanced-authorization.adoc index e2d862a990..a233078aa9 100644 --- a/modules/secure/pages/configuring-advanced-authorization.adoc +++ b/modules/secure/pages/configuring-advanced-authorization.adoc @@ -17,7 +17,7 @@ include::partial$snip_persona-admin.adoc[] .Procedure -. Configure the `CheCluster` Custom Resource. See xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +. Configure the `CheCluster` Custom Resource. See xref:configure:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. + [source,yaml,subs="+quotes,+attributes"] ---- diff --git a/modules/secure/pages/removing-user-data-in-compliance-with-the-gdpr.adoc b/modules/secure/pages/removing-user-data-in-compliance-with-the-gdpr.adoc index dc301f49b2..5070070a61 100644 --- a/modules/secure/pages/removing-user-data-in-compliance-with-the-gdpr.adoc +++ b/modules/secure/pages/removing-user-data-in-compliance-with-the-gdpr.adoc @@ -36,6 +36,6 @@ $ oc delete user .Additional resources -* xref:administration-guide:managing-workloads-using-the-che-server-api.adoc[] -* xref:administration-guide:configuring-workspace-target-namespace.adoc[] +* xref:configure:managing-workloads-using-the-che-server-api.adoc[] +* xref:configure:configuring-workspace-target-namespace.adoc[] * xref:install:proc_uninstalling-che.adoc[] diff --git a/modules/secure/pages/security-best-practices.adoc b/modules/secure/pages/security-best-practices.adoc index 20fa72080c..538f19bf68 100644 --- a/modules/secure/pages/security-best-practices.adoc +++ b/modules/secure/pages/security-best-practices.adoc @@ -240,7 +240,7 @@ When configuring network policies for {prod}, ensure that pods in the {prod-short} namespace can still communicate with pods in user namespaces, as this is required for proper functionality. -For detailed instructions on implementing network policies with {prod}, see xref:administration-guide:configuring-network-policies.adoc[]. +For detailed instructions on implementing network policies with {prod}, see xref:configure:configuring-network-policies.adoc[]. .Disconnected environment