From 583425b1391803172849c8c9eb7a89b64d6272f8 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> Date: Mon, 11 May 2026 20:57:12 +0530 Subject: [PATCH] chore: restructure Install category with JTBD and CQA 2.1 compliance (#3077) Reorganize the Install section of the Administration Guide using Jobs-to-Be-Done methodology and Red Hat CQA 2.1 editorial standards. Changes: - Rename 14 install files with CQA content type prefixes (proc_, ref_) - Apply CQA to 8 shared files using downstream CQA-compliant content - Apply CQA from scratch to 6 upstream-only files - Restructure nav.adoc into job-based groups: Deploy on OpenShift, Deploy on Kubernetes, Deploy locally, Deploy in restricted environment - Rewrite all abstracts with WHY-first JTBD framing - Fix titles to imperative form, prerequisites to user-first declarative - Standardize source blocks, verification sections, additional resources - Add page-aliases for all renamed files to preserve backward compat - Remove thin wrapper pages (installing-che-in-the-cloud, installing-che-locally) - Update all xrefs across nav.adoc, snippets, and referencing pages Co-authored-by: Claude Opus 4.6 --- .../examples/snip_che-installing-che.adoc | 16 +-- modules/administration-guide/nav.adoc | 31 +++-- ...-the-fully-qualified-domain-name-fqdn.adoc | 26 ---- ...lling-che-in-a-restricted-environment.adoc | 41 ------ .../pages/installing-che-in-the-cloud.adoc | 26 ---- .../pages/installing-che-locally.adoc | 24 ---- ...-on-amazon-elastic-kubernetes-service.adoc | 23 ++-- .../installing-che-on-microsoft-azure.adoc | 17 ++- .../pages/installing-che-on-minikube.adoc | 54 -------- ...installing-che-on-openshift-using-cli.adoc | 57 -------- ...he-on-openshift-using-the-web-console.adoc | 65 --------- ...alling-che-on-red-hat-openshift-local.adoc | 80 ----------- .../pages/installing-che.adoc | 16 ++- .../pages/permissions-to-install-che.adoc | 4 +- ...-the-fully-qualified-domain-name-fqdn.adoc | 40 ++++++ ...lling-che-in-a-restricted-environment.adoc | 55 ++++++++ ...alling-che-on-minikube-keycloak-oidc.adoc} | 61 +++++---- .../proc_installing-che-on-minikube.adoc | 61 +++++++++ ...installing-che-on-openshift-using-cli.adoc | 56 ++++++++ ...he-on-openshift-using-the-web-console.adoc | 77 +++++++++++ ...e-on-openshift-with-keycloak-as-oidc.adoc} | 102 +++++++------- ...alling-che-on-red-hat-openshift-local.adoc | 83 ++++++++++++ ...he-on-the-virtual-kubernetes-cluster.adoc} | 126 +++++++++--------- .../pages/proc_uninstalling-che.adoc | 46 +++++++ ...o-install-che-on-openshift-using-cli.adoc} | 19 ++- ...e-on-openshift-using-the-web-console.adoc} | 21 +-- ...user-data-in-compliance-with-the-gdpr.adoc | 2 +- .../pages/uninstalling-che.adoc | 38 ------ ...gement-tool-in-restricted-environment.adoc | 2 +- ...-on-amazon-elastic-kubernetes-service.adoc | 2 +- .../snip_che-setting-up-ansible-sample.adoc | 0 .../pages/introduction-to-eclipse-che.adoc | 2 +- 32 files changed, 657 insertions(+), 616 deletions(-) delete mode 100644 modules/administration-guide/pages/finding-the-fully-qualified-domain-name-fqdn.adoc delete mode 100644 modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc delete mode 100644 modules/administration-guide/pages/installing-che-in-the-cloud.adoc delete mode 100644 modules/administration-guide/pages/installing-che-locally.adoc delete mode 100644 modules/administration-guide/pages/installing-che-on-minikube.adoc delete mode 100644 modules/administration-guide/pages/installing-che-on-openshift-using-cli.adoc delete mode 100644 modules/administration-guide/pages/installing-che-on-openshift-using-the-web-console.adoc delete mode 100644 modules/administration-guide/pages/installing-che-on-red-hat-openshift-local.adoc create mode 100644 modules/administration-guide/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc create mode 100644 modules/administration-guide/pages/proc_installing-che-in-a-restricted-environment.adoc rename modules/administration-guide/pages/{installing-che-on-minikube-keycloak-oidc.adoc => proc_installing-che-on-minikube-keycloak-oidc.adoc} (80%) create mode 100644 modules/administration-guide/pages/proc_installing-che-on-minikube.adoc create mode 100644 modules/administration-guide/pages/proc_installing-che-on-openshift-using-cli.adoc create mode 100644 modules/administration-guide/pages/proc_installing-che-on-openshift-using-the-web-console.adoc rename modules/administration-guide/pages/{installing-che-on-openshift-with-keycloak-as-oidc.adoc => proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc} (54%) create mode 100644 modules/administration-guide/pages/proc_installing-che-on-red-hat-openshift-local.adoc rename modules/administration-guide/pages/{installing-che-on-the-virtual-kubernetes-cluster.adoc => proc_installing-che-on-the-virtual-kubernetes-cluster.adoc} (81%) create mode 100644 modules/administration-guide/pages/proc_uninstalling-che.adoc rename modules/administration-guide/pages/{permissions-to-install-che-on-openshift-using-cli.adoc => ref_permissions-to-install-che-on-openshift-using-cli.adoc} (56%) rename modules/administration-guide/pages/{permissions-to-install-che-on-openshift-using-the-web-console.adoc => ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc} (55%) delete mode 100644 modules/administration-guide/pages/uninstalling-che.adoc delete mode 100644 modules/administration-guide/partials/snip_che-setting-up-ansible-sample.adoc diff --git a/modules/administration-guide/examples/snip_che-installing-che.adoc b/modules/administration-guide/examples/snip_che-installing-che.adoc index 85aba42271..52a4263973 100644 --- a/modules/administration-guide/examples/snip_che-installing-che.adoc +++ b/modules/administration-guide/examples/snip_che-installing-che.adoc @@ -10,17 +10,17 @@ The installation method depends on the target platform and the environment restr You can deploy only one instance of {prod-short} per cluster. -* xref:installing-che-on-openshift-using-cli.adoc[] -* xref:installing-che-on-openshift-using-the-web-console.adoc[] -* xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[] -* xref:installing-che-in-a-restricted-environment.adoc[] +* xref:proc_installing-che-on-openshift-using-cli.adoc[] +* xref:proc_installing-che-on-openshift-using-the-web-console.adoc[] +* xref:proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc[] +* xref:proc_installing-che-in-a-restricted-environment.adoc[] * xref:installing-che-on-microsoft-azure.adoc[] * xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[] .Installing {prod-short} on a local single-node cluster -Single-node clusters are suited only for testing or development. Do *not* use such clusters to run {prod-short} for organizations or developer teams. +Single-node clusters are suited only for testing or development. Do not use such clusters to run {prod-short} for organizations or developer teams. -* xref:installing-che-on-red-hat-openshift-local.adoc[] -* xref:installing-che-on-minikube.adoc[] -* xref:installing-che-on-minikube-keycloak-oidc.adoc[] +* xref:proc_installing-che-on-red-hat-openshift-local.adoc[] +* xref:proc_installing-che-on-minikube.adoc[] +* xref:proc_installing-che-on-minikube-keycloak-oidc.adoc[] diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 4cea07a1cd..536596fc4a 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -16,23 +16,26 @@ *** xref:user-workspaces.adoc[] ** xref:calculating-che-resource-requirements.adoc[] * xref:running-at-scale.adoc[] +// Install * xref:installing-che.adoc[] -** xref:installing-che-on-the-virtual-kubernetes-cluster.adoc[] -** xref:installing-che-in-the-cloud.adoc[] -*** xref:installing-che-on-openshift-using-cli.adoc[] -*** xref:installing-che-on-openshift-using-the-web-console.adoc[] -*** xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[] -*** xref:installing-che-in-a-restricted-environment.adoc[] +** Deploy on OpenShift +*** xref:proc_installing-che-on-openshift-using-cli.adoc[] +*** xref:proc_installing-che-on-openshift-using-the-web-console.adoc[] +*** xref:proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc[] +** Deploy on {kubernetes} *** xref:installing-che-on-microsoft-azure.adoc[] *** xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[] -** xref:installing-che-locally.adoc[] -*** xref:installing-che-on-red-hat-openshift-local.adoc[] -*** xref:installing-che-on-minikube.adoc[] -*** xref:installing-che-on-minikube-keycloak-oidc.adoc[] -** xref:finding-the-fully-qualified-domain-name-fqdn.adoc[] +*** xref:proc_installing-che-on-the-virtual-kubernetes-cluster.adoc[] +** Deploy locally +*** xref:proc_installing-che-on-red-hat-openshift-local.adoc[] +*** xref:proc_installing-che-on-minikube.adoc[] +*** xref:proc_installing-che-on-minikube-keycloak-oidc.adoc[] +** Deploy in a restricted environment +*** xref:proc_installing-che-in-a-restricted-environment.adoc[] +** xref:proc_finding-the-fully-qualified-domain-name-fqdn.adoc[] ** xref:permissions-to-install-che.adoc[] -*** xref:permissions-to-install-che-on-openshift-using-cli.adoc[] -*** xref:permissions-to-install-che-on-openshift-using-the-web-console.adoc[] +*** xref:ref_permissions-to-install-che-on-openshift-using-cli.adoc[] +*** xref:ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc[] * xref:configuring-che.adoc[] ** xref:understanding-the-checluster-custom-resource.adoc[] *** xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] @@ -134,4 +137,4 @@ ** xref:upgrading-che-using-the-cli-management-tool.adoc[] ** xref:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[] ** xref:repairing-the-devworkspace-operator-on-openshift.adoc[] -* xref:uninstalling-che.adoc[] +* xref:proc_uninstalling-che.adoc[] diff --git a/modules/administration-guide/pages/finding-the-fully-qualified-domain-name-fqdn.adoc b/modules/administration-guide/pages/finding-the-fully-qualified-domain-name-fqdn.adoc deleted file mode 100644 index b587fddd00..0000000000 --- a/modules/administration-guide/pages/finding-the-fully-qualified-domain-name-fqdn.adoc +++ /dev/null @@ -1,26 +0,0 @@ -:_content-type: PROCEDURE -:description: Finding the fully qualified domain name (FQDN) -:keywords: administration-guide, FQDN, URL -:navtitle: Finding the fully qualified domain name (FQDN) -//:page-aliases: - -[id="finding-the-fully-qualified-domain-name-fqdn"] -= Finding the fully qualified domain name (FQDN) - -You can get the fully qualified domain name (FQDN) of your organization's instance of {prod-short} on the command line or in the OpenShift web console. - -TIP: You can find the FQDN for your organization's {prod-short} instance in the *Administrator* view of the OpenShift web console as follows. Go to *Operators* -> *Installed Operators* -> *{prod} instance Specification* -> *{prod-checluster}* -> *{prod} URL*. - - -.Prerequisites - -* An active `oc` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. - -.Procedure - -. Run the following command: -+ -[source,bash,subs="+attributes,+quotes"] ----- -{orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}' ----- diff --git a/modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc b/modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc deleted file mode 100644 index b456b48fca..0000000000 --- a/modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc +++ /dev/null @@ -1,41 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {prod-short} in a restricted environment -:keywords: administration guide, installing-che-in-a-restricted-environment, installing-che-in-restricted-environment -:navtitle: Installing {prod-short} in a restricted environment -:page-aliases: installation-guide:installing-che-in-restricted-environment.adoc, installation-guide:installing-che-in-a-restricted-environment.adoc, preparing-a-restricted-environment.adoc, configuring-che-to-run-in-a-restricted-environment.adoc - -[id="installing-{prod-id-short}-in-a-restricted-environment-on-openshift"] -= Installing {prod-short} in a restricted environment on OpenShift - -On an OpenShift cluster operating in a restricted network, public resources are not available. - -However, deploying {prod-short} and running workspaces requires the following public resources: - -* Operator catalog -* Container images -* Sample projects - -To make these resources available, you can replace them with their copy in a registry accessible by the OpenShift cluster. - -.Prerequisites - -include::partial$snip_preparing-images-for-a-restricted-environment.adoc[] - -. Install {prod-short} with the configuration set in the `che-operator-cr-patch.yaml` during the previous step: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:deploy \ - --platform=openshift \ - --olm-channel stable \ - --catalog-source-name={prod-operator-package-name}-disconnected-install \ - --catalog-source-namespace=openshift-marketplace \ - --skip-devworkspace-operator \ - --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:configuring-network-policies.adoc[]. - -include::partial$snip_installing-che-in-a-restricted-environment-additional-resources.adoc[] - -include::partial$snip_{project-context}-setting-up-ansible-sample.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/installing-che-in-the-cloud.adoc b/modules/administration-guide/pages/installing-che-in-the-cloud.adoc deleted file mode 100644 index ac922b6f8a..0000000000 --- a/modules/administration-guide/pages/installing-che-in-the-cloud.adoc +++ /dev/null @@ -1,26 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {prod-short} in the cloud -:keywords: overview, running-che-in-the-cloud, installing-che-in-the-cloud -:navtitle: Installing {prod-short} in the cloud - -[id="installing-{prod-id-short}-in-the-cloud"] -= Installing {prod-short} in the cloud - -Deploy and run {prod} in the cloud. - -.Prerequisites - -* A {platforms-name} cluster to deploy {prod-short} on. - -* `{prod-cli}`: The command line tool for {prod}. See: xref:installing-the-chectl-management-tool.adoc[]. - -== Deploying {prod-short} in the cloud - -Follow the instructions below to start the {prod-short} Server in the cloud by using the `{prod-cli}` tool. - -* xref:installing-che-on-openshift-using-cli.adoc[] -* xref:installing-che-on-openshift-using-the-web-console.adoc[] -* xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[] -* xref:installing-che-in-a-restricted-environment.adoc[] -* xref:installing-che-on-microsoft-azure.adoc[] -* xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[] diff --git a/modules/administration-guide/pages/installing-che-locally.adoc b/modules/administration-guide/pages/installing-che-locally.adoc deleted file mode 100644 index a72cb7efc4..0000000000 --- a/modules/administration-guide/pages/installing-che-locally.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {prod-short} locally -:keywords: overview, running-che-locally, installing-che-locally -:navtitle: Installing {prod-short} locally -:page-aliases: installation-guide:running-che-locally.adoc, installation-guide:installing-che-in-tls-mode-with-self-signed-certificates.adoc, overview:running-che-locally.adoc, installation-guide:installing-che-locally.adoc - -[id="installing-{prod-id-short}-locally"] -= Installing {prod-short} locally - -This section contains instructions for deploying and running {prod} locally, on a personal workstation. - -.Prerequisites - -* A {platforms-name} cluster to deploy {prod-short} on. - -* `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[]. - -== Deploying {prod-short} locally using {prod-cli} - -Choose one of the following procedures to deploy the {prod-short} using the `{prod-cli}` tool. - -* xref:installing-che-on-red-hat-openshift-local.adoc[] -* xref:installing-che-on-minikube.adoc[] -* xref:installing-che-on-minikube-keycloak-oidc.adoc[] diff --git a/modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc index 55ff4ccc21..e179cdc752 100644 --- a/modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc +++ b/modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc @@ -1,24 +1,23 @@ :_content-type: ASSEMBLY -:description: Installing {prod-short} on {eks} -:keywords: overview, installing-{prod-id-short}-on-amazon-elastic-kubernetes-service.adoc -:navtitle: Installing {prod-short} on {eks} +:description: To provide cloud development environments on AWS, deploy {prod-short} on an Amazon EKS cluster with DNS, TLS certificates, and Keycloak as the OIDC identity provider. +:keywords: overview, installing-{prod-id-short}-on-amazon-elastic-kubernetes-service +:navtitle: Install {prod-short} on {eks} -[id="installing-{prod-id-short}-on-amazon-elastic-kubernetes-service.adoc"] -= Installing {prod-short} on {eks} +[id="installing-{prod-id-short}-on-amazon-elastic-kubernetes-service"] += Install {prod-short} on {eks} -{eks} (Amazon EKS) is a managed {kubernetes} service to run {kubernetes} in the AWS cloud and on-premises data centers. - -Follow the instructions below to install and enable {prod-short} on {eks-short}. +[role="_abstract"] +To provide cloud development environments on AWS, deploy {prod-short} on an Amazon EKS cluster by configuring DNS, TLS certificates, and Keycloak as the OIDC identity provider. .Prerequisites -* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm]. +* You have `helm` installed. See link:https://helm.sh/docs/intro/install/[Installing Helm]. -* `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[]. +* You have `{prod-cli}` installed. See xref:installing-the-chectl-management-tool.adoc[]. -* `aws`: The AWS Command Line Interface. See: link:https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html[AWS CLI install and update instructions] +* You have the `aws` CLI installed. See link:https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html[AWS CLI install and update instructions]. -* `eksctl`: The Command Line Interface for creating and managing {kubernetes} clusters on {eks-short}. See: link:https://eksctl.io/installation/[Installing eksctl] +* You have `eksctl` installed. See link:https://eksctl.io/installation/[Installing eksctl]. include::partial$configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/installing-che-on-microsoft-azure.adoc b/modules/administration-guide/pages/installing-che-on-microsoft-azure.adoc index 2400fc3c57..e52f031ae6 100644 --- a/modules/administration-guide/pages/installing-che-on-microsoft-azure.adoc +++ b/modules/administration-guide/pages/installing-che-on-microsoft-azure.adoc @@ -1,22 +1,21 @@ :_content-type: ASSEMBLY -:description: Installing {prod-short} on Microsoft Azure +:description: To provide cloud development environments on Microsoft Azure, deploy {prod-short} on an AKS cluster with DNS, TLS certificates, and Keycloak as the OIDC identity provider. :keywords: overview, installing-che-on-microsoft-azure -:navtitle: Installing {prod-short} on Microsoft Azure +:navtitle: Install {prod-short} on Microsoft Azure [id="installing-{prod-id-short}-on-microsoft-azure"] -= Installing {prod-short} on Microsoft Azure += Install {prod-short} on Microsoft Azure -Microsoft Azure is a cloud computing service for building, testing, deploying, and managing applications and services through Microsoft-managed data centers. - -Follow the instructions below to install and enable {prod-short} on Microsoft Azure. +[role="_abstract"] +To provide cloud development environments on Microsoft Azure, deploy {prod-short} on an AKS cluster by configuring DNS, TLS certificates, and Keycloak as the OIDC identity provider. .Prerequisites -* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm]. +* You have `helm` installed. See link:https://helm.sh/docs/intro/install/[Installing Helm]. -* `az`: The Microsoft Azure CLI command line tool. See: link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest[How to install Microsoft Azure CLI]. +* You have the `az` CLI installed. See link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest[How to install Microsoft Azure CLI]. -* `kubelogin`: The credential plugin. See: link:https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-install-cli[How to install kubelogin]. +* You have `kubelogin` installed. See link:https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-install-cli[How to install kubelogin]. include::partial$proc_preparing-microsoft-azure-for-installing-che.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/installing-che-on-minikube.adoc b/modules/administration-guide/pages/installing-che-on-minikube.adoc deleted file mode 100644 index bdf6853240..0000000000 --- a/modules/administration-guide/pages/installing-che-on-minikube.adoc +++ /dev/null @@ -1,54 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {prod-short} on Minikube -:keywords: overview, installing-che-on-minikube -:navtitle: Installing {prod-short} on Minikube -:page-aliases: installation-guide:installing-che-on-minikube.adoc, overview:installing-che-on-minikube.adoc - -[id="installing-{prod-id-short}-on-minikube"] -= Installing {prod-short} on Minikube - -This article explains how to create a single-node {kubernetes} cluster with Minikube to deploy {prod-short}. - -WARNING: Remember that single-node {kubernetes} clusters are suited only for testing or development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. - -.Prerequisites - -* Minikube stable release. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. - -* `{orch-cli}` stable release. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing `{orch-cli}`]. - -* `{prod-cli}`. See xref:installing-the-chectl-management-tool.adoc[]. - -.Procedure - -. Start Minikube with required add-ons and sufficient resources: -+ ----- -$ minikube start --addons=ingress,dashboard --vm=true --memory=10240 --cpus=4 --disk-size=50GB --kubernetes-version=v1.23.9 ----- - -. Create the {prod-short} instance: -+ -[subs="+attributes"] ----- -$ {prod-cli} server:deploy --platform minikube ----- - -.Verification steps - -. Verify the {prod-short} instance status: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:status ----- - -. Navigate to the {prod-short} cluster instance: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} dashboard:open ----- -.Additional resources - -* xref:configuring-che-with-self-signed-certificate.adoc[] diff --git a/modules/administration-guide/pages/installing-che-on-openshift-using-cli.adoc b/modules/administration-guide/pages/installing-che-on-openshift-using-cli.adoc deleted file mode 100644 index 6dba0983d5..0000000000 --- a/modules/administration-guide/pages/installing-che-on-openshift-using-cli.adoc +++ /dev/null @@ -1,57 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {prod-short} on OpenShift using CLI -:keywords: overview, installing-che-on-openshift-4-using-cli -:navtitle: Installing {prod-short} on OpenShift using CLI -:page-aliases: installation-guide:installing-che-on-openshift-4-using-cli.adoc, overview:installing-che-on-openshift-4-using-cli.adoc, installing-che-on-openshift-4-using-cli.adoc - -[id="installing-{prod-id-short}-on-openshift-using-the-cli-management-tool"] -= Installing {prod-short} on OpenShift using the `{prod-cli}` management tool - -You can install {prod-short} on OpenShift. - -.Prerequisites - -include::example$snip_{project-context}-supported-platforms-cli.adoc[] - -* An active `oc` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. - -* `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[]. - - -.Procedure - -. Optional: If you previously deployed {prod-short} on this OpenShift cluster, ensure that the previous {prod-short} instance is removed: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:delete ----- - -. Create the {prod-short} instance: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:deploy --platform openshift ----- - -.Verification steps - -. Verify the {prod-short} instance status: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:status ----- - -. Navigate to the {prod-short} cluster instance: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} dashboard:open ----- - -include::example$snip_che-arm64-openshift-gateway-images.adoc[] - -.Additional resources - -* xref:permissions-to-install-che-on-openshift-using-cli.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/installing-che-on-openshift-using-the-web-console.adoc b/modules/administration-guide/pages/installing-che-on-openshift-using-the-web-console.adoc deleted file mode 100644 index 15f1c266c7..0000000000 --- a/modules/administration-guide/pages/installing-che-on-openshift-using-the-web-console.adoc +++ /dev/null @@ -1,65 +0,0 @@ -:_content-type: PROCEDURE -:description: Installing {prod-short} on OpenShift using the web console -:keywords: overview, installing, openshift, web console -:navtitle: Installing {prod-short} on OpenShift using the web console -:page-aliases: installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc, overview:installing-che-on-openshift-4-using-operatorhub.adoc, creating-an-instance-of-the-che-operator.adoc, installing-che-on-openshift-4-using-operatorhub.adoc - -[id="installing-{prod-id-short}-on-openshift-using-the-web-console"] -= Installing {prod-short} on OpenShift using the web console - -If you have trouble xref:installing-che-on-openshift-using-cli.adoc[installing {prod-short} on the command line], you can install it through the OpenShift web console. - -.Prerequisites - -* An OpenShift web console session by a cluster administrator. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/web_console/web-console.html[Accessing the web console]. - -* An active `oc` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. - -* For a repeat installation on the same OpenShift cluster: you uninstalled the previous {prod-short} instance according to xref:uninstalling-che.adoc[]. - -.Procedure - -. In the *Administrator* view of the OpenShift web console, go to *Operators* -> *OperatorHub* and search for `{prod}`. - -. Install the {prod} Operator. -+ -TIP: See link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/admin/olm-adding-operators-to-cluster.html#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster[Installing from OperatorHub using the web console]. -+ -CAUTION: The {prod} Operator depends on the {devworkspace} Operator. If you install the {prod} Operator manually to a non-default namespace, ensure that the {devworkspace} Operator is also installed in the same namespace. This is required as the Operator Lifecycle Manager will attempt to install the {devworkspace} Operator as a dependency within the {prod} Operator namespace, potentially resulting in two conflicting installations of the {devworkspace} Operator if the latter is installed in a different namespace. - -CAUTION: If you want to onboard link:https://docs.openshift.com/container-platform/4.14/web_console/web_terminal/installing-web-terminal.html[Web Terminal Operator] on the cluster make sure to use the same installation namespace as {prod} Operator since both depend on {devworkspace} Operator. Web Terminal Operator, {prod} Operator, and {devworkspace} Operator must be installed in the same namespace. - -. Create the `{prod-namespace}` project in OpenShift as follows: -+ -[subs="+attributes"] ----- -oc create namespace {prod-namespace} ----- - -. Go to *Operators* -> *Installed Operators* -> *{prod} instance Specification* -> *Create CheCluster* -> *YAML view*. - -. In the *YAML view*, replace `namespace: openshift-operators` with `namespace: {prod-namespace}`. - -. Select *Create*. -+ -TIP: See link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/user/olm-creating-apps-from-installed-operators.html[Creating applications from installed Operators]. - -.Verification - -pass:[] - -. In *{prod} instance Specification*, go to *{prod-checluster}*, landing on the *Details* tab. - -pass:[] - -. Under *Message*, check that there is *None*, which means no errors. - -. Under *{prod} URL*, wait until the URL of the {prod-short} instance appears, and then open the URL to check the {prod-short} dashboard. - -. In the *Resources* tab, view the resources for the {prod-short} deployment and their status. - -include::example$snip_che-arm64-openshift-gateway-images.adoc[] - -.Additional resources - -* xref:permissions-to-install-che-on-openshift-using-the-web-console.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/installing-che-on-red-hat-openshift-local.adoc b/modules/administration-guide/pages/installing-che-on-red-hat-openshift-local.adoc deleted file mode 100644 index 9e9a5bfd95..0000000000 --- a/modules/administration-guide/pages/installing-che-on-red-hat-openshift-local.adoc +++ /dev/null @@ -1,80 +0,0 @@ -:_content-type: PROCEDURE -:description: You can create a single-node OpenShift cluster for deploying a {prod-short} instance using {rh-os-local}. -:keywords: overview, installing, installation, local -:navtitle: Installing {prod-short} on {rh-os-local} -:page-aliases: installation-guide:installing-che-on-codeready-containers.adoc, overview:installing-che-on-codeready-containers.adoc, installing-che-on-codeready-containers.adoc - -[id="installing-{prod-id-short}-on-red-hat-openshift-local"] -= Installing {prod-short} on {rh-os-local} - - -You can create a single-node OpenShift cluster for deploying a {prod-short} instance using {rh-os-local}. - -.Prerequisites - -* `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[]. - -* A running instance of {rh-os-local}. See link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local} overview].``` - -* The file path of the user's {rh-os-local} pull secret. - -* Available memory is 12 GB or more. - -* Available disk size is 64 GB or more. - -.Procedure - -. Remove the previous cluster: -+ -[source,terminal] ----- -$ crc delete ----- - -. Configure your host machine for {rh-os-local}: -+ ----- -$ crc setup ----- - -. Start the {rh-os-local} virtual machine with at least 12 GB of memory and 64 GB of disk space. Also, specify the path to your pull secret and take note of the password for the `kubeadmin` user displayed at the end of the {rh-os-local} initiation: -+ -[subs="+quotes"] ----- -$ crc start --memory 12288 --disk-size=64 --pull-secret-file ____ ----- - -. Enable access to the `oc` command line interface embedded in {rh-os-local}: -+ ----- -$ eval $(crc oc-env) ----- - -. Install the {prod-short} instance using {prod-cli}: -+ -[subs="+attributes"] ----- -$ {prod-cli} server:deploy --platform crc ----- - -.Verification steps - -. Verify the {prod-short} instance status: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:status ----- - -. Navigate to the {prod-short} cluster instance: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} dashboard:open ----- - - - -.Additional resources - -* link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local}]. diff --git a/modules/administration-guide/pages/installing-che.adoc b/modules/administration-guide/pages/installing-che.adoc index 663cdd90e0..a29cbdb73d 100644 --- a/modules/administration-guide/pages/installing-che.adoc +++ b/modules/administration-guide/pages/installing-che.adoc @@ -1,12 +1,18 @@ :_content-type: ASSEMBLY -:description: Installing {prod-short} -:keywords: administration guide, installing-che -:navtitle: Installing {prod-short} +:description: Provide your development team with consistent, browser-based cloud development environments by deploying {prod-short} on {orch-name}, {kubernetes}, or a local single-node cluster. +:keywords: administration guide, installing-che, install, deploy +:navtitle: Install {prod-short} :page-aliases: installation-guide:installing-che.adoc, installation-guide:3-minutes-to-che.adoc, overview:3-minutes-to-che.adoc, installation-guide:quick-starts.adoc, installation-guide:che-quick-starts.adoc, .:quick-start.html, overview:che-quick-start.adoc, installation-guide:installing-che-on-aws.adoc, installation-guide:installing-che-on-docker-desktop.adoc, installation-guide:installing-che-on-google-cloud-platform.adoc, installation-guide:installing-che-on-kind.adoc, installation-guide:installing-che-on-kubespray.adoc, installation-guide:installing-che-on-microsoft-azure.adoc, installation-guide:installing-che-on-openshift-3-using-the-operator.adoc [id="installing-{prod-id-short}"] -= Installing {prod-short} += Install {prod-short} -This section contains instructions to install {prod}. +[role="_abstract"] +To provide your development team with consistent, browser-based cloud development environments, deploy {prod-short} on {orch-name}, {kubernetes}, or a local single-node cluster. Choose the deployment method that matches your target platform and environment. + +[NOTE] +==== +You can deploy only one instance of {prod-short} per cluster. +==== include::example$snip_{project-context}-installing-che.adoc[] diff --git a/modules/administration-guide/pages/permissions-to-install-che.adoc b/modules/administration-guide/pages/permissions-to-install-che.adoc index ee5532f4b5..12f0d350ad 100644 --- a/modules/administration-guide/pages/permissions-to-install-che.adoc +++ b/modules/administration-guide/pages/permissions-to-install-che.adoc @@ -9,6 +9,6 @@ Learn about the permissions required to install {prod} on different {kubernetes} clusters. -* xref:permissions-to-install-che-on-openshift-using-cli.adoc[] +* xref:ref_permissions-to-install-che-on-openshift-using-cli.adoc[] -* xref:permissions-to-install-che-on-openshift-using-the-web-console.adoc[] +* xref:ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc[] diff --git a/modules/administration-guide/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc b/modules/administration-guide/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc new file mode 100644 index 0000000000..344eeb993b --- /dev/null +++ b/modules/administration-guide/pages/proc_finding-the-fully-qualified-domain-name-fqdn.adoc @@ -0,0 +1,40 @@ +:_content-type: PROCEDURE +:description: Finding the FQDN of a {prod-short} instance +:keywords: fqdn, domain, url, dashboard +:navtitle: Find the FQDN +:page-aliases: finding-the-fully-qualified-domain-name-fqdn.adoc + +[id="proc_finding-the-fully-qualified-domain-name-fqdn"] += Find the fully qualified domain name (FQDN) + +[role="_abstract"] +Retrieve the fully qualified domain name (FQDN) of your organization's instance of {prod-short} on the command line to access the {prod-short} dashboard URL. + +[TIP] +==== +You can find the FQDN for your organization's {prod-short} instance in the *Administrator* view of the {orch-name} web console as follows. Go to *Operators* -> *Installed Operators* -> *{prod} instance Specification* -> *{prod-checluster}* -> *{prod} URL*. +==== + +.Prerequisites + +* You have an active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. + +.Procedure + +. Run the following command: ++ +[source,bash,subs="+attributes,+quotes"] +---- +{orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}' +---- + +.Verification + +* Open the returned URL in a web browser and verify that the {prod-short} dashboard loads. + +[role="_additional-resources"] +.Additional resources + +* xref:proc_installing-che-on-openshift-using-cli.adoc[] +* xref:proc_installing-che-on-openshift-using-the-web-console.adoc[] +* xref:proc_installing-che-in-a-restricted-environment.adoc[] diff --git a/modules/administration-guide/pages/proc_installing-che-in-a-restricted-environment.adoc b/modules/administration-guide/pages/proc_installing-che-in-a-restricted-environment.adoc new file mode 100644 index 0000000000..937d4aa27a --- /dev/null +++ b/modules/administration-guide/pages/proc_installing-che-in-a-restricted-environment.adoc @@ -0,0 +1,55 @@ +:_content-type: PROCEDURE +:description: To provide cloud development environments on an air-gapped {orch-name} cluster, mirror the required images and operator catalogs, then deploy {prod-short}. +:keywords: install, restricted, air-gapped, disconnected, openshift +:navtitle: Install {prod-short} in a restricted environment +:page-aliases: installation-guide:installing-che-in-restricted-environment.adoc, installation-guide:installing-che-in-a-restricted-environment.adoc, preparing-a-restricted-environment.adoc, configuring-che-to-run-in-a-restricted-environment.adoc, installing-che-in-a-restricted-environment.adoc + +[id="proc_installing-che-in-a-restricted-environment"] += Install {prod-short} in a restricted environment on {orch-name} + +[role="_abstract"] +To provide cloud development environments on an air-gapped {orch-name} cluster, mirror the required images and operator catalogs to a registry within the restricted network, then deploy {prod-short}. + +On a restricted network, deploying {prod-short} and running workspaces requires the following public resources: + +* Operator catalog +* Container images +* Sample projects + +To make these resources available, you can replace them with their copy in a registry accessible by the {orch-name} cluster. + +.Prerequisites + +include::partial$snip_preparing-images-for-a-restricted-environment.adoc[] + +.Procedure + +. Install {prod-short} with the configuration set in the `che-operator-cr-patch.yaml` during the previous step: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:deploy \ + --platform=openshift \ + --olm-channel stable \ + --catalog-source-name={prod-operator-package-name}-disconnected-install \ + --catalog-source-namespace=openshift-marketplace \ + --skip-devworkspace-operator \ + --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:configuring-network-policies.adoc[]. + +.Verification + +* Verify that the {prod-short} instance is running: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:status +---- + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm-rh-catalogs.html[Red Hat-provided Operator catalogs] +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/admin/olm-managing-custom-catalogs.html[Managing custom catalogs] diff --git a/modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc b/modules/administration-guide/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc similarity index 80% rename from modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc rename to modules/administration-guide/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc index 4ce5954092..4ac905f2e6 100644 --- a/modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc +++ b/modules/administration-guide/pages/proc_installing-che-on-minikube-keycloak-oidc.adoc @@ -1,38 +1,42 @@ :_content-type: PROCEDURE -:navtitle: Installing {prod-short} on Minikube with Keycloak as the OIDC provider -:description: Installing {prod-short} on Minikube with Keycloak as the OIDC provider +:navtitle: Install {prod-short} on Minikube with Keycloak as the OIDC provider +:description: To test {prod-short} with centralized authentication locally, deploy {prod-short} on Minikube with Keycloak as the OpenID Connect (OIDC) identity provider. :keywords: overview, installing-che-on-minikube-keycloak-oidc -:page-aliases: installation-guide:installing-che-on-minikube-keycloak-oidc, overview:installing-che-on-minikube-keycloak-oidc +:page-aliases: installation-guide:installing-che-on-minikube-keycloak-oidc, overview:installing-che-on-minikube-keycloak-oidc, installing-che-on-minikube-keycloak-oidc.adoc [id="installing-{prod-id-short}-on-minikube-keycloak-oidc"] -= Installing {prod-short} on Minikube with Keycloak as the OIDC provider += Install {prod-short} on Minikube with Keycloak as the OIDC provider -You can create a single-node {kubernetes} cluster with Minikube to deploy {prod-short} and configure it to use Keycloak as the OpenID Connect (OIDC) provider. +[role="_abstract"] +To test {prod-short} with centralized authentication locally, deploy {prod-short} on a single-node {kubernetes} cluster with Minikube and configure Keycloak as the OpenID Connect (OIDC) identity provider. -WARNING: Single-node {kubernetes} clusters are suited only for testing or development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams! +[WARNING] +==== +Single-node {kubernetes} clusters are suited only for testing or development. Do not use such clusters to run {prod-short} for organizations or developer teams. +==== .Prerequisites -* Minikube stable release. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. +* You have Minikube installed. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. -* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm]. +* You have `helm` installed. See link:https://helm.sh/docs/intro/install/[Installing Helm]. -* `{orch-cli}` stable release. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing `{orch-cli}`]. +* You have `{orch-cli}` installed. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing `{orch-cli}`]. -* `{prod-cli}`. See xref:installing-the-chectl-management-tool.adoc[]. +* You have `{prod-cli}` installed. See xref:installing-the-chectl-management-tool.adoc[]. .Procedure . Start Minikube. Allocate at least 8GB of RAM and 4 CPU cores: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- minikube start --addons=ingress --vm=true --memory=8192 --cpus=4 ---- -. Install link:https://cert-manager.io[cert-manager] +. Install link:https://cert-manager.io[cert-manager]: + -[source,shell,subs="attributes+"] +[source,bash,subs="attributes+"] ---- helm repo add jetstack https://charts.jetstack.io helm repo update @@ -44,9 +48,9 @@ helm install cert-manager jetstack/cert-manager \ --set installCRDs=true ---- -. Install https://www.keycloak.org/[Keycloak]: +. Install link:https://www.keycloak.org/[Keycloak]: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} apply -f - < keycloak-ca.crt ---- . Copy Keycloak CA certificate into Minikube: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- minikube ssh sudo "mkdir -p /etc/ca-certificates" && \ minikube cp keycloak-ca.crt /etc/ca-certificates/keycloak-ca.crt @@ -224,7 +228,7 @@ minikube cp keycloak-ca.crt /etc/ca-certificates/keycloak-ca.crt . Configure Minikube to use Keycloak as the OIDC provider: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- minikube start \ --extra-config=apiserver.oidc-issuer-url=https://keycloak.$(minikube ip).nip.io/realms/che \ @@ -235,16 +239,16 @@ minikube start \ . Wait until the Keycloak pod is ready: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} wait --for=condition=ready pod -l app=keycloak -n keycloak --timeout=120s ---- . Configure Keycloak to create the realm, client, and user: + -IMPORTANT: You must do this each time you start the Minikube cluster. +IMPORTANT: Repeat this step each time you start the Minikube cluster. + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} exec deploy/keycloak -n keycloak -- bash -c \ "/opt/keycloak/bin/kcadm.sh config credentials \ @@ -279,7 +283,7 @@ IMPORTANT: You must do this each time you start the Minikube cluster. . Copy Keycloak CA certificate into the `{prod-namespace}` namespace: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} create namespace {prod-namespace} && \ {orch-cli} create configmap keycloak-certs \ @@ -293,7 +297,7 @@ IMPORTANT: You must do this each time you start the Minikube cluster. . Prepare the `CheCluster` patch: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- cat > che-patch.yaml << EOF kind: CheCluster @@ -322,14 +326,14 @@ EOF . Create the {prod-short} instance with `{prod-cli}`: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {prod-cli} server:deploy --platform k8s --domain $(minikube ip).nip.io --che-operator-cr-patch-yaml che-patch.yaml --skip-cert-manager ---- + Alternatively, use the link:https://artifacthub.io/packages/helm/eclipse-che/eclipse-che[{prod}] Helm Charts: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- helm install che \ --namespace eclipse-che \ @@ -342,24 +346,25 @@ sleep 5s && \ {orch-cli} patch checluster/eclipse-che --patch '{"spec": {"networking": {"auth": {"gateway": {"deployment": {"containers": [{"name": "oauth-proxy", "env":[{"name": "OAUTH2_PROXY_BACKEND_LOGOUT_URL", "value": "http://keycloak.$(minikube ip).nip.io/realms/che/protocol/openid-connect/logout?id_token_hint=\{id_token}"}]}]}}}}}}' --type=merge -n eclipse-che ---- -.Verification steps +.Verification . Verify the {prod-short} instance status: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {prod-cli} server:status ---- . Navigate to the {prod-short} cluster instance: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {prod-cli} dashboard:open ---- . Log in to the {prod-short} instance with *Username:* `test` and *Password:* `test`. +[role="_additional-resources"] .Additional resources * xref:configuring-che-with-self-signed-certificate.adoc[] diff --git a/modules/administration-guide/pages/proc_installing-che-on-minikube.adoc b/modules/administration-guide/pages/proc_installing-che-on-minikube.adoc new file mode 100644 index 0000000000..e106fdf2f5 --- /dev/null +++ b/modules/administration-guide/pages/proc_installing-che-on-minikube.adoc @@ -0,0 +1,61 @@ +:_content-type: PROCEDURE +:description: To evaluate {prod-short} in a local development environment, create a single-node {kubernetes} cluster with Minikube and deploy {prod-short}. +:keywords: overview, installing-che-on-minikube +:navtitle: Install {prod-short} on Minikube +:page-aliases: installation-guide:installing-che-on-minikube.adoc, overview:installing-che-on-minikube.adoc, installing-che-on-minikube.adoc + +[id="installing-{prod-id-short}-on-minikube"] += Install {prod-short} on Minikube + +[role="_abstract"] +To evaluate {prod-short} in a local development environment, create a single-node {kubernetes} cluster with Minikube and deploy {prod-short}. + +[WARNING] +==== +Single-node {kubernetes} clusters are suited only for testing or development. Do not use such clusters to run {prod-short} for organizations or developer teams. +==== + +.Prerequisites + +* You have Minikube installed. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. + +* You have `{orch-cli}` installed. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing `{orch-cli}`]. + +* You have `{prod-cli}` installed. See xref:installing-the-chectl-management-tool.adoc[]. + +.Procedure + +. Start Minikube with required add-ons and sufficient resources: ++ +[source,bash] +---- +$ minikube start --addons=ingress,dashboard --vm=true --memory=10240 --cpus=4 --disk-size=50GB --kubernetes-version=v1.23.9 +---- + +. Create the {prod-short} instance: ++ +[source,bash,subs="+attributes"] +---- +$ {prod-cli} server:deploy --platform minikube +---- + +.Verification + +. Verify the {prod-short} instance status: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:status +---- + +. Navigate to the {prod-short} cluster instance: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} dashboard:open +---- + +[role="_additional-resources"] +.Additional resources + +* xref:configuring-che-with-self-signed-certificate.adoc[] diff --git a/modules/administration-guide/pages/proc_installing-che-on-openshift-using-cli.adoc b/modules/administration-guide/pages/proc_installing-che-on-openshift-using-cli.adoc new file mode 100644 index 0000000000..b4f9c2f28d --- /dev/null +++ b/modules/administration-guide/pages/proc_installing-che-on-openshift-using-cli.adoc @@ -0,0 +1,56 @@ +:_content-type: PROCEDURE +:description: To set up cloud development environments for your team on an OpenShift cluster, deploy {prod-short} by using the {prod-cli} CLI management tool. +:keywords: install, openshift, cli, chectl +:navtitle: Install {prod-short} on OpenShift using CLI +:page-aliases: installation-guide:installing-che-on-openshift-4-using-cli.adoc, overview:installing-che-on-openshift-4-using-cli.adoc, installing-che-on-openshift-4-using-cli.adoc, installing-che-on-openshift-using-cli.adoc + +[id="proc_installing-che-on-openshift-using-cli"] += Install {prod-short} on OpenShift using CLI + +[role="_abstract"] +To set up cloud development environments for your team on an {orch-name} cluster, deploy {prod-short} by using the `{prod-cli}` CLI management tool. + +.Prerequisites + +* You have an {ocp} {ocp4-ver} or later cluster. + +* You have an active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. + +* You have the `{prod-cli}` management tool installed. See xref:installing-the-chectl-management-tool.adoc[]. + +.Procedure + +. Optional: If you previously deployed {prod-short} on this {orch-name} cluster, ensure that the previous {prod-short} instance is removed: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:delete +---- + +. Create the {prod-short} instance: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:deploy --platform openshift +---- + +.Verification + +. Verify the {prod-short} instance status: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:status +---- + +. Navigate to the {prod-short} cluster instance: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} dashboard:open +---- + +[role="_additional-resources"] +.Additional resources + +* xref:ref_permissions-to-install-che-on-openshift-using-cli.adoc[] diff --git a/modules/administration-guide/pages/proc_installing-che-on-openshift-using-the-web-console.adoc b/modules/administration-guide/pages/proc_installing-che-on-openshift-using-the-web-console.adoc new file mode 100644 index 0000000000..85b35b631d --- /dev/null +++ b/modules/administration-guide/pages/proc_installing-che-on-openshift-using-the-web-console.adoc @@ -0,0 +1,77 @@ +:_content-type: PROCEDURE +:description: To set up cloud development environments for your team on an OpenShift cluster, deploy {prod-short} through the web console by using OperatorHub. +:keywords: install, openshift, web console, operatorhub +:navtitle: Install {prod-short} on OpenShift using the web console +:page-aliases: installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc, overview:installing-che-on-openshift-4-using-operatorhub.adoc, creating-an-instance-of-the-che-operator.adoc, installing-che-on-openshift-4-using-operatorhub.adoc, installing-che-on-openshift-using-the-web-console.adoc + +[id="proc_installing-che-on-openshift-using-the-web-console"] += Install {prod-short} on OpenShift using the web console + +[role="_abstract"] +To set up cloud development environments for your team on an {orch-name} cluster, deploy {prod-short} through the web console by using OperatorHub and creating a `CheCluster` instance. + +.Prerequisites + +* You have an {orch-name} web console session as a cluster administrator. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/web_console/web-console.html[Accessing the web console]. + +* You have an active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. + +* For a repeat installation: you have uninstalled the previous {prod-short} instance according to xref:proc_uninstalling-che.adoc[]. + +.Procedure + +. In the *Administrator* view of the {orch-name} web console, go to *Operators* -> *OperatorHub* and search for `{prod}`. + +. Install the {prod} Operator. ++ +[TIP] +==== +See link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/admin/olm-adding-operators-to-cluster.html#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster[Installing from OperatorHub using the web console]. +==== ++ +[IMPORTANT] +==== +The {prod} Operator depends on the {devworkspace} Operator. If you install the {prod} Operator manually to a non-default namespace, ensure that the {devworkspace} Operator is also installed in the same namespace. The Operator Lifecycle Manager installs the {devworkspace} Operator as a dependency within the {prod} Operator namespace. If the {devworkspace} Operator is already installed in a different namespace, two conflicting installations can result. +==== ++ +[IMPORTANT] +==== +If you want to onboard link:https://docs.openshift.com/container-platform/{ocp4-ver}/web_console/web_terminal/installing-web-terminal.html[Web Terminal Operator] on the cluster, use the same installation namespace as the {prod} Operator. Both operators depend on the {devworkspace} Operator, so all three must be installed in the same namespace. +==== + +. Create the `{prod-namespace}` project in {orch-name} as follows: ++ +[source,bash,subs="+attributes"] +---- +{orch-cli} create namespace {prod-namespace} +---- + +. Go to *Operators* -> *Installed Operators* -> *{prod} instance Specification* -> *Create CheCluster* -> *YAML view*. + +. In the *YAML view*, replace `namespace: openshift-operators` with `namespace: {prod-namespace}`. + +. Select *Create*. ++ +[TIP] +==== +See link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/user/olm-creating-apps-from-installed-operators.html[Creating applications from installed Operators]. +==== + +.Verification + +pass:[] + +. In *{prod} instance Specification*, go to *{prod-checluster}*, landing on the *Details* tab. + +pass:[] + +. Under *Message*, check that there is *None*, which means no errors. + +. Under *{prod} URL*, wait until the URL of the {prod-short} instance appears, and then open the URL to check the {prod-short} dashboard. + +. In the *Resources* tab, view the resources for the {prod-short} deployment and their status. + +[role="_additional-resources"] +.Additional resources + +* xref:ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc[] diff --git a/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc b/modules/administration-guide/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc similarity index 54% rename from modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc rename to modules/administration-guide/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc index 2d23ad72e2..dfebd7d3f5 100644 --- a/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc +++ b/modules/administration-guide/pages/proc_installing-che-on-openshift-with-keycloak-as-oidc.adoc @@ -1,41 +1,42 @@ :_content-type: PROCEDURE -:description: Installing {prod-short} on Red Hat OpenShift with {keycloak} as external identity provider -:keywords: overview, installing, openshift, keycloak, oidc -:navtitle: Installing {prod-short} on OpenShift with {keycloak} as external identity provider +:description: To manage user authentication through a centralized identity provider, deploy {prod-short} on OpenShift with {keycloak} as the external OIDC provider. +:keywords: install, openshift, keycloak, oidc, identity provider +:navtitle: Install {prod-short} on OpenShift with {keycloak} as external identity provider +:page-aliases: installing-che-on-openshift-with-keycloak-as-oidc.adoc - -[id="installing-che-on-openshift-with-keycloak-as-oidc"] +[id="proc_installing-che-on-openshift-with-keycloak-as-oidc"] = Install {prod-short} on OpenShift with {keycloak} as external identity provider -Install {prod-short} on an OpenShift cluster that uses {keycloak} as an external OIDC identity provider for centralized user authentication. +[role="_abstract"] +To manage user authentication through a centralized identity provider, deploy {prod-short} on an {orch-name} cluster with {keycloak} as the external OpenID Connect (OIDC) provider. .Prerequisites -* An active `{orch-cli}` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. +* You have an active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. -* {keycloak} is configured as an external identity provider for OpenShift. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/authentication_and_authorization/external-auth[Enabling direct authentication with an external OIDC identity provider]. +* You have {keycloak} configured as an external identity provider for {orch-name}. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp4-ver}/html/authentication_and_authorization/external-auth[Enabling direct authentication with an external OIDC identity provider]. .Procedure . Define the environment variables: + -[source,shell,subs="+quotes,+attributes"] +[source,bash,subs="+quotes,+attributes"] ---- -# The {keycloak} realm used for OpenShift authentication: -OPENSHIFT_REALM=____ +# The {keycloak} realm used for {orch-name} authentication: +OPENSHIFT_REALM=____ # The {keycloak} URL: -KEYCLOAK_URL=____ +KEYCLOAK_URL=____ ---- -. Create a `{prod-id}` client in the {keycloak} Admin Console: +. Create a `{prod-id-short}` client in the {keycloak} Admin Console: + -- -.. Within the realm used for OpenShift authentication, select *Clients* on the left side of the navigation bar. +.. Within the realm used for {orch-name} authentication, select *Clients* on the left side of the navigation bar. .. Select the *Create client* button. .. On the *General Settings* page: + -... Enter `{prod-id}` in the *Client ID* field. +... Enter `{prod-id-short}` in the *Client ID* field. ... Optional: Enter a *Name* and *Description* for the OAuth client. ... Click *Next*. .. On the *Capability config* page: @@ -47,9 +48,9 @@ KEYCLOAK_URL=____ .. Navigate to the *Credentials* tab of the newly created client and copy the *Client secret* value for use when applying the OAuth client secret. -- -. Add the `{prod-id}` client to the audiences list in the OpenShift authentication configuration: +. Add the `{prod-id-short}` client to the audiences list in the {orch-name} authentication configuration: + -[source,shell,subs="+quotes,+attributes"] +[source,bash,subs="+quotes,+attributes"] ---- {orch-cli} patch authentication.config/cluster \ --type='json' \ @@ -57,20 +58,19 @@ KEYCLOAK_URL=____ { "op": "add", "path": "/spec/oidcProviders/0/issuer/audiences/-", - "value": "{prod-id}" + "value": "{prod-id-short}" } ]' ---- + [NOTE] ==== -If you have multiple OIDC providers configured, adjust the array index in the path -(currently 0) to match your {keycloak} provider's position in the configuration. +If you have multiple OIDC providers configured, adjust the array index in the path (currently 0) to match your {keycloak} provider's position in the configuration. ==== . Wait for the `kube-apiserver` cluster Operator to roll out the configuration changes: + -[source,shell,subs="+quotes,+attributes"] +[source,bash,subs="+quotes,+attributes"] ---- watch {orch-cli} get co kube-apiserver ---- @@ -95,15 +95,17 @@ metadata: labels: app.kubernetes.io/part-of: che.eclipse.org stringData: - oAuthSecret: ____ <1> + oAuthSecret: ____ EOF ---- -<1> The client secret value from the `{prod-id}` client in {keycloak}. - ++ +where: ++ +`____`:: The client secret value from the `{prod-id-short}` client in {keycloak}. -. Optional: Create the `ConfigMap` with a {keycloak} certificate in the `{prod-namespace}` namespace. If {keycloak} uses a certificate that is already trusted by OpenShift, skip this step. +. Optional: Create the `ConfigMap` with a {keycloak} certificate in the `{prod-namespace}` namespace. If {keycloak} uses a certificate that is already trusted by {orch-name}, skip this step. + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- openssl s_client \ -connect "$(echo "$KEYCLOAK_URL" | sed 's|https://||'):443" \ @@ -122,7 +124,7 @@ openssl s_client \ . Prepare the `CheCluster` patch: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- cat > che-patch.yaml << EOF kind: CheCluster @@ -130,7 +132,7 @@ apiVersion: org.eclipse.che/v2 spec: networking: auth: - oAuthClientName: {prod-id} + oAuthClientName: {prod-id-short} oAuthSecret: oauth-secret identityProviderURL: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM" gateway: @@ -147,63 +149,69 @@ spec: components: cheServer: extraProperties: - CHE_OIDC_GROUPS__CLAIM: '' <1> - CHE_OIDC_GROUPS__PREFIX: '' <2> - CHE_OIDC_USERNAME__CLAIM: '' <3> - CHE_OIDC_USERNAME__PREFIX: '' <4> + CHE_OIDC_GROUPS__CLAIM: '' + CHE_OIDC_GROUPS__PREFIX: '' + CHE_OIDC_USERNAME__CLAIM: '' + CHE_OIDC_USERNAME__PREFIX: '' EOF ---- -<1> The claim to use for extracting user groups. -<2> The prefix to add to group names. Empty string means no prefix. -<3> The claim to use for extracting the username. -<4> The prefix to add to usernames. Empty string means no prefix. ++ +where: ++ +`CHE_OIDC_GROUPS__CLAIM`:: The claim to use for extracting user groups. ++ +`CHE_OIDC_GROUPS__PREFIX`:: The prefix to add to group names. Empty string means no prefix. ++ +`CHE_OIDC_USERNAME__CLAIM`:: The claim to use for extracting the username. ++ +`CHE_OIDC_USERNAME__PREFIX`:: The prefix to add to usernames. Empty string means no prefix. + [NOTE] ==== These values must match the corresponding claim and prefix settings configured in the `authentication.config/cluster` resource. To view the current cluster configuration, run: -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} get authentication.config/cluster -o yaml ---- ==== -+ + . Create the {prod-short} instance with `{prod-cli}`: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {prod-cli} server:deploy \ --platform openshift \ --che-operator-cr-patch-yaml che-patch.yaml ---- -. Update the `{prod-id}` client to set the {prod-short} redirect URI and web origin: +. Update the `{prod-id-short}` client to set the {prod-short} redirect URI and web origin. + -Obtain the {prod} URL with the following command: +Obtain the {prod} URL: + -[source,shell,subs="+quotes,+attributes"] +[source,bash,subs="+quotes,+attributes"] ---- echo "$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}')" ---- + -- -... In the *Valid redirect URIs* field, entry the URL above with `/oauth/callback` appended -... In the *Web origins* field, entry the URL above. -... Click *Save*. +.. In the *Valid redirect URIs* field, enter the URL above with `/oauth/callback` appended. +.. In the *Web origins* field, enter the URL above. +.. Click *Save*. -- .Verification . Verify the {prod-short} instance status: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {prod-cli} server:status ---- . Navigate to the {prod-short} cluster instance: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {prod-cli} dashboard:open ---- diff --git a/modules/administration-guide/pages/proc_installing-che-on-red-hat-openshift-local.adoc b/modules/administration-guide/pages/proc_installing-che-on-red-hat-openshift-local.adoc new file mode 100644 index 0000000000..669900ab42 --- /dev/null +++ b/modules/administration-guide/pages/proc_installing-che-on-red-hat-openshift-local.adoc @@ -0,0 +1,83 @@ +:_content-type: PROCEDURE +:description: To evaluate {prod-short} on a local {orch-name} cluster, deploy {prod-short} by using {rh-os-local}. +:keywords: overview, installing, installation, local +:navtitle: Install {prod-short} on {rh-os-local} +:page-aliases: installation-guide:installing-che-on-codeready-containers.adoc, overview:installing-che-on-codeready-containers.adoc, installing-che-on-codeready-containers.adoc, installing-che-on-red-hat-openshift-local.adoc + +[id="installing-{prod-id-short}-on-red-hat-openshift-local"] += Install {prod-short} on {rh-os-local} + +[role="_abstract"] +To evaluate {prod-short} on a local {orch-name} cluster, deploy {prod-short} by using {rh-os-local} for development and testing. + +.Prerequisites + +* You have `{prod-cli}` installed. See xref:installing-the-chectl-management-tool.adoc[]. + +* You have a running instance of {rh-os-local}. See link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local} overview]. + +* You know the file path of your {rh-os-local} pull secret. + +* You have at least 12 GB of available memory. + +* You have at least 64 GB of available disk space. + +.Procedure + +. Remove the previous cluster: ++ +[source,bash] +---- +$ crc delete +---- + +. Configure your host machine for {rh-os-local}: ++ +[source,bash] +---- +$ crc setup +---- + +. Start the {rh-os-local} virtual machine with at least 12 GB of memory and 64 GB of disk space. Specify the path to your pull secret: ++ +[source,bash,subs="+quotes"] +---- +$ crc start --memory 12288 --disk-size=64 --pull-secret-file ____ +---- ++ +NOTE: Take note of the password for the `kubeadmin` user displayed at the end of the {rh-os-local} initiation. + +. Enable access to the `oc` command line interface embedded in {rh-os-local}: ++ +[source,bash] +---- +$ eval $(crc oc-env) +---- + +. Install the {prod-short} instance using {prod-cli}: ++ +[source,bash,subs="+attributes"] +---- +$ {prod-cli} server:deploy --platform crc +---- + +.Verification + +. Verify the {prod-short} instance status: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:status +---- + +. Navigate to the {prod-short} cluster instance: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} dashboard:open +---- + +[role="_additional-resources"] +.Additional resources + +* link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local}]. diff --git a/modules/administration-guide/pages/installing-che-on-the-virtual-kubernetes-cluster.adoc b/modules/administration-guide/pages/proc_installing-che-on-the-virtual-kubernetes-cluster.adoc similarity index 81% rename from modules/administration-guide/pages/installing-che-on-the-virtual-kubernetes-cluster.adoc rename to modules/administration-guide/pages/proc_installing-che-on-the-virtual-kubernetes-cluster.adoc index 863e8d5197..0e35b96b55 100644 --- a/modules/administration-guide/pages/installing-che-on-the-virtual-kubernetes-cluster.adoc +++ b/modules/administration-guide/pages/proc_installing-che-on-the-virtual-kubernetes-cluster.adoc @@ -1,38 +1,36 @@ :_content-type: PROCEDURE -:navtitle: Installing {prod-short} on the virtual {kubernetes} cluster -:description: Installing {prod-short} on the virtual {kubernetes} cluster -:keywords: installing-{prod-short}-on-the-virtual-kubernetes-cluster -:page-aliases: +:navtitle: Install {prod-short} on the virtual {kubernetes} cluster +:description: To deploy {prod-short} when the host cluster version is incompatible or lacks external OIDC support, use a virtual {kubernetes} cluster (vCluster). +:keywords: installing-{prod-id-short}-on-the-virtual-kubernetes-cluster +:page-aliases: installing-che-on-the-virtual-kubernetes-cluster.adoc -[id="installing-{prod-short}-on-the-virtual-kubernetes-cluster.adoc"] -= Installing {prod-short} on the virtual {kubernetes} cluster +[id="installing-{prod-id-short}-on-the-virtual-kubernetes-cluster"] += Install {prod-short} on the virtual {kubernetes} cluster - -Virtual clusters are fully working {kubernetes} clusters that run on top of other {kubernetes} clusters. Compared to fully separate "real" clusters, virtual clusters reuse worker nodes and networking of the host cluster. They have their own control plane and schedule all workloads into a single {namespace} of the host cluster. Similar to virtual machines, virtual clusters partition a single physical cluster into multiple separate ones. - -`vCluster` offers a solution for deploying {prod-short} in scenarios where it normally would be impossible. This includes situations where the {kubernetes} cluster version is incompatible with {prod-short}, or when the cloud service provider lacks support for external OIDC. Utilizing `vClusters` allows bypassing these constraints and enables {prod-short} to function as needed. +[role="_abstract"] +To deploy {prod-short} when the host cluster version is incompatible or lacks external OIDC support, use a virtual {kubernetes} cluster (vCluster) to bypass these constraints. .Prerequisites -* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm]. +* You have `helm` installed. See link:https://helm.sh/docs/intro/install/[Installing Helm]. -* `vcluster`: The command line tool for managing virtual {kubernetes} clusters. See link:https://www.vcluster.com/docs/getting-started/setup[Installing vCluster CLI]. +* You have `vcluster` CLI installed. See link:https://www.vcluster.com/docs/getting-started/setup[Installing vCluster CLI]. -* `{orch-cli}`: The Kubernetes command-line tool. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing {orch-cli}]. +* You have `{orch-cli}` installed. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing {orch-cli}]. -* `kubelogin`: The plugin for `kubectl` also known as `kubectl oidc-login`. See https://github.com/int128/kubelogin[Installing kubelogin]. +* You have `kubelogin` installed. See link:https://github.com/int128/kubelogin[Installing kubelogin]. -* `{prod-cli}`: The command line tool for {prod}. See: xref:installing-the-chectl-management-tool.adoc[]. +* You have `{prod-cli}` installed. See xref:installing-the-chectl-management-tool.adoc[]. -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. +* You have an active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. .Procedure . Define the cluster domain name. + -[source,shell] +[source,bash,subs="+quotes"] ---- -DOMAIN_NAME= +DOMAIN_NAME=____ ---- . Install link:https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/[Ingress Controller]. @@ -42,7 +40,7 @@ Check your {kubernetes} provider documentation on how to install it. ==== Use the following command to install link:https://docs.nginx.com/nginx-ingress-controller/[NGINX Ingress Controller] on Azure Kubernetes Service cluster: -[source,shell,subs="attributes+"] +[source,bash,subs="attributes+"] ---- helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update @@ -57,7 +55,7 @@ helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \ . Install the link:https://cert-manager.io[cert-manager]: + -[source,shell,subs="attributes+"] +[source,bash,subs="attributes+"] ---- helm repo add jetstack https://charts.jetstack.io helm repo update @@ -71,24 +69,24 @@ helm install cert-manager jetstack/cert-manager \ . Define the `Keycloak` host: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- KEYCLOAK_HOST=keycloak.$\{DOMAIN_NAME} ---- + [IMPORTANT] ==== -If you use a registrar such as GoDaddy, you will need to add the following DNS record +If you use a registrar such as GoDaddy, add the following DNS record in your registrar and point it to the IP address of the ingress controller: -* type: `**A**` -* name: `**keycloak**` +* type: `A` +* name: `keycloak` ==== + [TIP] ==== -Use the following command to figure out the external IP address of the NGINX Ingress Controller: -[source,shell,subs="attributes+"] +Run the following command to find the external IP address of the NGINX Ingress Controller: +[source,bash,subs="attributes+"] ---- {orch-cli} get services ingress-nginx-controller \ --namespace ingress-nginx \ @@ -99,7 +97,7 @@ Use the following command to figure out the external IP address of the NGINX Ing [TIP] ==== Use the following command to wait until `Keycloak` host is known: -[source,shell,subs="attributes+"] +[source,bash,subs="attributes+"] ---- until ping -c1 $\{KEYCLOAK_HOST} >/dev/null 2>&1; do :; done ---- @@ -107,7 +105,7 @@ until ping -c1 $\{KEYCLOAK_HOST} >/dev/null 2>&1; do :; done . Install link:https://www.keycloak.org/[Keycloak] with a self-signed certificate: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} apply -f - < /tmp/vcluster-values.yaml << EOF api: @@ -460,7 +458,7 @@ EOF . Install `vCluster`: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- helm repo add loft-sh https://charts.loft.sh helm repo update @@ -473,7 +471,7 @@ helm install vcluster loft-sh/vcluster-k8s \ . Mount `Keycloak` CA certificate into the `vcluster` pod: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} get secret ca.crt \ --output "jsonpath={.data['ca\.crt']}" \ @@ -507,22 +505,22 @@ helm install vcluster loft-sh/vcluster-k8s \ ---- . Wait until `vc-vcluster` secret is created: -[source,shell,subs="+attributes"] + +[source,bash,subs="+attributes"] ---- timeout 120 bash -c 'while :; do {orch-cli} get secret vc-vcluster -n vcluster && break || sleep 5; done' ---- . Verify the `vCluster` cluster status: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- vcluster list ---- . Update `kubeconfig` file: -[source,shell,subs="+attributes"] + +[source,bash,subs="+attributes"] ---- {orch-cli} config set-credentials vcluster \ --exec-api-version=client.authentication.k8s.io/v1beta1 \ @@ -548,21 +546,18 @@ get-token,\ ---- . Use `vcluster` `kubeconfig` context: -[source,shell,subs="+attributes"] + +[source,bash,subs="+attributes"] ---- {orch-cli} config use-context vcluster ---- -. View the pods in the cluster. By running the following command, you will be redirected to the authenticate page: +. View the pods in the cluster. Running this command redirects to the authentication page: + -[source,shell,subs="+attributes"] +[source,bash,subs="+attributes"] ---- {orch-cli} get pods --all-namespaces ---- -. Verification -+ -All pods in the running state are displayed. . Install link:https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/[Ingress Controller] on the virtual {kubernetes} cluster. + @@ -570,7 +565,7 @@ All pods in the running state are displayed. ==== Use the following command to install link:https://docs.nginx.com/nginx-ingress-controller/[NGINX Ingress Controller] on Azure Kubernetes Service cluster: -[source,shell,subs="attributes+"] +[source,bash,subs="attributes+"] ---- helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update @@ -585,16 +580,16 @@ helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \ + [IMPORTANT] ==== -If you use a registrar such as GoDaddy, you will need to add the following two DNS records in your registrar and point them to the IP address of the ingress controller: +If you use a registrar such as GoDaddy, add the following two DNS records in your registrar and point them to the IP address of the ingress controller: -* type: `**A**` -* name: `**@**` and `*****` +* type: `A` +* name: `@` and `*` ==== + [TIP] ==== -Use the following command to figure out the external IP address of the NGINX Ingress Controller: -[source,shell,subs="attributes+"] +Run the following command to find the external IP address of the NGINX Ingress Controller: +[source,bash,subs="attributes+"] ---- {orch-cli} get services ingress-nginx-controller \ --namespace ingress-nginx \ @@ -605,7 +600,7 @@ Use the following command to figure out the external IP address of the NGINX Ing [TIP] ==== Use the following command to wait until {kubernetes} host is known: -[source,shell,subs="attributes+"] +[source,bash,subs="attributes+"] ---- until ping -c1 $\{DOMAIN_NAME} >/dev/null 2>&1; do :; done ---- @@ -613,7 +608,7 @@ until ping -c1 $\{DOMAIN_NAME} >/dev/null 2>&1; do :; done . Create `CheCluster` patch YAML file and replace `CHE_PRIVATE_CLIENT_SECRET` saved above: + -[source,shell,subs="+attributes,+quotes"] +[source,bash,subs="+attributes,+quotes"] ---- cat > /tmp/che-patch.yaml << EOF kind: CheCluster @@ -643,14 +638,14 @@ EOF . Create `{prod-namespace}` namespace: + -[source,shell,subs="+attributes,"] +[source,bash,subs="+attributes"] ---- {orch-cli} create namespace {prod-namespace} ---- . Copy `Keycloak` CA certificate into the `{prod-namespace}` namespace: + -[source,shell,subs="+attributes,"] +[source,bash,subs="+attributes"] ---- {orch-cli} create configmap keycloak-certs \ --from-file=keycloak-ca.crt=/tmp/keycloak-ca.crt \ @@ -664,7 +659,7 @@ EOF . Deploy {prod-short}: + -[source,shell,subs="+attributes,"] +[source,bash,subs="+attributes"] ---- {prod-cli} server:deploy \ --platform k8s \ @@ -672,18 +667,27 @@ EOF --che-operator-cr-patch-yaml /tmp/che-patch.yaml ---- -.Verification steps +.Verification + +. Verify that all pods are in the running state: ++ +[source,bash,subs="+attributes"] +---- +{orch-cli} get pods --all-namespaces +---- + . Verify the {prod-short} instance status: + -[source,shell,subs="+attributes,"] +[source,bash,subs="+attributes"] ---- {prod-cli} server:status ---- . Navigate to the {prod-short} cluster instance: + -[source,shell,subs="+attributes,"] +[source,bash,subs="+attributes"] ---- {prod-cli} dashboard:open ---- + . Log in to the {prod-short} instance with *Username:* `che` and *Password:* `che`. diff --git a/modules/administration-guide/pages/proc_uninstalling-che.adoc b/modules/administration-guide/pages/proc_uninstalling-che.adoc new file mode 100644 index 0000000000..ec1436bbfa --- /dev/null +++ b/modules/administration-guide/pages/proc_uninstalling-che.adoc @@ -0,0 +1,46 @@ +:_content-type: PROCEDURE +:description: Uninstalling {prod-short} +:keywords: uninstall, remove, delete +:navtitle: Uninstall {prod-short} +:page-aliases: installation-guide:uninstalling-che.adoc, installation-guide:uninstalling-che-after-operatorhub-installation.adoc, uninstalling-che-on-openshift.adoc, installation-guide:uninstalling-che-after-chectl-installation.adoc, uninstalling-che-by-using-chectl.adoc, uninstalling-che.adoc + +[id="proc_uninstalling-che"] += Uninstall {prod-short} + +[role="_abstract"] +Use `{prod-cli}` to uninstall the {prod-short} instance and remove all {prod-short}-related user data from the cluster. + +[WARNING] +==== +Uninstalling {prod-short} removes all {prod-short}-related user data. +==== + +.Prerequisites + +* You have the `{prod-cli}` management tool installed. See xref:installing-the-chectl-management-tool.adoc[]. + +.Procedure + +. Remove the {prod-short} instance: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ {prod-cli} server:delete +---- ++ +[TIP] +==== +The `--delete-namespace` option removes the {prod-short} namespace. + +The `--delete-all` option removes the {devworkspace} Operator and the related resources. +==== ++ +[IMPORTANT] +==== +Standard operating procedure (SOP) for removing {devworkspace} Operator manually without `{prod-cli}` is available in the {ocp} link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp4-ver}/html/web_console/web-terminal#removing-devworkspace-operator_uninstalling-web-terminal[official documentation]. +==== + +[role="_additional-resources"] +.Additional resources + +* xref:installing-the-chectl-management-tool.adoc[] diff --git a/modules/administration-guide/pages/permissions-to-install-che-on-openshift-using-cli.adoc b/modules/administration-guide/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc similarity index 56% rename from modules/administration-guide/pages/permissions-to-install-che-on-openshift-using-cli.adoc rename to modules/administration-guide/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc index 435ae6ef44..81968ec5c1 100644 --- a/modules/administration-guide/pages/permissions-to-install-che-on-openshift-using-cli.adoc +++ b/modules/administration-guide/pages/ref_permissions-to-install-che-on-openshift-using-cli.adoc @@ -1,12 +1,16 @@ :_content-type: REFERENCE -:description: Minimum set of permissions required to install {prod-short} on OpenShift using CLI -:keywords: permissions, openshift, installing, cli -:navtitle: Permissions to install {prod-short} on OpenShift using CLI +:description: Permissions required to install {prod-short} on OpenShift using CLI +:keywords: permissions, rbac, cli, install +:navtitle: Permissions for CLI installation +:page-aliases: permissions-to-install-che-on-openshift-using-cli.adoc -[id="permissions-to-install-che-on-openshift-using-cli"] +[id="ref_permissions-to-install-che-on-openshift-using-cli"] = Permissions to install {prod-short} on OpenShift using CLI -Below is the minimal set of permissions required to install {prod-short} on an OpenShift cluster using {prod-cli}: +[role="_abstract"] +A specific set of permissions is required to install {prod-short} on an {orch-name} cluster using the {prod-cli} CLI tool. + +The following YAML shows the minimal set of permissions required to install {prod-short} on an {orch-name} cluster using {prod-cli}: [source,yaml,subs="+quotes,+attributes"] ---- @@ -45,7 +49,8 @@ rules: verbs: ["get", "list"] ---- +[role="_additional-resources"] .Additional resources -* https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-apply[`oc apply` command] -* link:https://docs.openshift.com/container-platform/4.17/cli_reference/openshift_cli/administrator-cli-commands.html#oc-adm-policy-add-cluster-role-to-user[`oc adm policy` command] +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/developer-cli-commands.html#oc-apply[`oc apply` command] +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/administrator-cli-commands.html#oc-adm-policy-add-cluster-role-to-user[`oc adm policy` command] diff --git a/modules/administration-guide/pages/permissions-to-install-che-on-openshift-using-the-web-console.adoc b/modules/administration-guide/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc similarity index 55% rename from modules/administration-guide/pages/permissions-to-install-che-on-openshift-using-the-web-console.adoc rename to modules/administration-guide/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc index cd030c3bb6..8cfef56f41 100644 --- a/modules/administration-guide/pages/permissions-to-install-che-on-openshift-using-the-web-console.adoc +++ b/modules/administration-guide/pages/ref_permissions-to-install-che-on-openshift-using-the-web-console.adoc @@ -1,12 +1,16 @@ :_content-type: REFERENCE -:description: Minimum set of permissions required to install {prod-short} on OpenShift using the web console -:keywords: permissions, openshift, installing -:navtitle: Permissions to install {prod-short} on OpenShift using web console +:description: Permissions required to install {prod-short} on OpenShift using the web console +:keywords: permissions, rbac, web console, install +:navtitle: Permissions for web console installation +:page-aliases: permissions-to-install-che-on-openshift-using-the-web-console.adoc -[id="permissions-to-install-che-on-openshift-using-the-web-console"] -= Permissions to install {prod-short} on OpenShift using the web console +[id="ref_permissions-to-install-che-on-openshift-using-the-web-console"] += Permissions to install {prod-short} on OpenShift using web console -Below is the minimal set of permissions required to install {prod-short} on an OpenShift cluster using the web console: +[role="_abstract"] +A specific set of permissions is required to install {prod-short} on an {orch-name} cluster using the web console. + +The following YAML shows the minimal set of permissions required to install {prod-short} on an {orch-name} cluster using the web console: [source,yaml,subs="+quotes,+attributes"] ---- @@ -46,7 +50,8 @@ rules: verbs: ["get", "list", "watch"] ---- +[role="_additional-resources"] .Additional resources -* https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-apply[`oc apply` command] -* link:https://docs.openshift.com/container-platform/4.17/cli_reference/openshift_cli/administrator-cli-commands.html#oc-adm-policy-add-cluster-role-to-user[`oc adm policy` command] \ No newline at end of file +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/developer-cli-commands.html#oc-apply[`oc apply` command] +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/administrator-cli-commands.html#oc-adm-policy-add-cluster-role-to-user[`oc adm policy` command] diff --git a/modules/administration-guide/pages/removing-user-data-in-compliance-with-the-gdpr.adoc b/modules/administration-guide/pages/removing-user-data-in-compliance-with-the-gdpr.adoc index b065b55293..9595f66811 100644 --- a/modules/administration-guide/pages/removing-user-data-in-compliance-with-the-gdpr.adoc +++ b/modules/administration-guide/pages/removing-user-data-in-compliance-with-the-gdpr.adoc @@ -36,4 +36,4 @@ $ oc delete user * xref:managing-workloads-using-the-che-server-api.adoc[] * xref:configuring-workspace-target-namespace.adoc[] -* xref:uninstalling-che.adoc[] +* xref:proc_uninstalling-che.adoc[] diff --git a/modules/administration-guide/pages/uninstalling-che.adoc b/modules/administration-guide/pages/uninstalling-che.adoc deleted file mode 100644 index 8a593da1fc..0000000000 --- a/modules/administration-guide/pages/uninstalling-che.adoc +++ /dev/null @@ -1,38 +0,0 @@ -:_content-type: PROCEDURE -:description: Uninstalling {prod-short} -:keywords: administration guide, uninstalling-che -:navtitle: Uninstalling {prod-short} -:page-aliases: installation-guide:uninstalling-che.adoc, installation-guide:uninstalling-che-after-operatorhub-installation.adoc, uninstalling-che-on-openshift.adoc, installation-guide:uninstalling-che-after-chectl-installation.adoc, uninstalling-che-by-using-chectl.adoc - - -[id="uninstalling-{prod-id-short}"] -= Uninstalling {prod-short} - -WARNING: Uninstalling {prod-short} removes all {prod-short}-related user data! - -Use `{prod-cli}` to uninstall the {prod-short} instance. - -.Prerequisites - -* `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[]. - -.Procedure - -* Remove the {prod-short} instance: -+ -[subs="+attributes,quotes"] ----- -$ {prod-cli} server:delete ----- - -[TIP] -==== -The `--delete-namespace` option removes the {prod-short} namespace. - -The `--delete-all` option removes the {devworkspace} Operator and the related resources. -==== - -[IMPORTANT] -==== -Standard operating procedure (SOP) for removing {devworkspace} Operator manually without `{prod-cli}` is available in the OpenShift Container Platform link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/web_console/web-terminal#removing-devworkspace-operator_uninstalling-web-terminal[official documentation]. -==== diff --git a/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc index b7aa25d834..0b6a664c53 100644 --- a/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc +++ b/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc @@ -11,7 +11,7 @@ This section describes how to upgrade {prod} and perform minor version updates b .Prerequisites -* The {prod-short} instance was installed on OpenShift using the `{prod-cli} --installer operator` method in the `{prod-namespace}` project. See xref:installing-che-in-a-restricted-environment.adoc[]. +* The {prod-short} instance was installed on OpenShift using the `{prod-cli} --installer operator` method in the `{prod-namespace}` project. See xref:proc_installing-che-in-a-restricted-environment.adoc[]. include::partial$snip_preparing-images-for-a-restricted-environment.adoc[] diff --git a/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc index 67f7f08bff..f45d7428f6 100644 --- a/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc +++ b/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc @@ -2,7 +2,7 @@ // // installing-{prod-id-short}-on-amazon-elastic-kubernetes-service -[id="installing-che-on-amazon-elastic-kubernetes-service"] +[id="installing-{prod-id-short}-on-amazon-elastic-kubernetes-service-procedure"] = Installing {prod-short} on {eks-short} Follow these instructions to install {prod-short} on {eks-short}. diff --git a/modules/administration-guide/partials/snip_che-setting-up-ansible-sample.adoc b/modules/administration-guide/partials/snip_che-setting-up-ansible-sample.adoc deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/overview/pages/introduction-to-eclipse-che.adoc b/modules/overview/pages/introduction-to-eclipse-che.adoc index 36d41ab4ad..1319cda5a0 100644 --- a/modules/overview/pages/introduction-to-eclipse-che.adoc +++ b/modules/overview/pages/introduction-to-eclipse-che.adoc @@ -23,7 +23,7 @@ * xref:what-is-{prod-id-short}[] * xref:architecture-overview.adoc[] * xref:hosted-che:hosted-che.adoc[] -* xref:administration-guide:installing-che-locally.adoc[] +* xref:administration-guide:installing-che.adoc[] * xref:administration-guide:supported-platforms.adoc[] * xref:administration-guide:calculating-che-resource-requirements.adoc[]