From f7fd96b426c8e12ef1f9dad4b45930182259bc96 Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Tue, 9 Nov 2021 07:31:42 +0000
Subject: [PATCH 01/18] Add doc about migration CHE from stable to stable all
 namespace CHE using OLM.

Signed-off-by: Oleksandr Andriienko <oandriie@redhat.com>
---
 modules/administration-guide/nav.adoc         |   2 +
 ...table-channel-to-stable-all-namespace.adoc |   7 +
 ...table_channel_to_stable_all_namespace.adoc | 273 ++++++++++++++++++
 3 files changed, 282 insertions(+)
 create mode 100644 modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc
 create mode 100644 modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc

diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc
index a4aeb35a60..30b6c34031 100644
--- a/modules/administration-guide/nav.adoc
+++ b/modules/administration-guide/nav.adoc
@@ -34,6 +34,8 @@
 
 * xref:migration-from-postgresql-9-to-postgresql-13.adoc[]
 
+* xref:migration-olm-stable-channel-to-stable-all-namespace.adoc[]
+
 * xref:caching-images-for-faster-workspace-start.adoc[]
 ** xref:defining-the-list-of-images-to-pull.adoc[]
 ** xref:defining-the-memory-parameters-for-the-image-puller.adoc[]
diff --git a/modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc b/modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc
new file mode 100644
index 0000000000..0788968efd
--- /dev/null
+++ b/modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc
@@ -0,0 +1,7 @@
+[id="migration_olm_stable_channel_to_stable_all_namespace"]
+
+:navtitle: Migration OLM "stable" channel to "stable-all-namespace"
+:keywords: administration-guide, migration
+:page-aliases: .:olm-migration
+
+include::partial$proc_migration_olm_stable_channel_to_stable_all_namespace.adoc[]
diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
new file mode 100644
index 0000000000..3cfb4a103b
--- /dev/null
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -0,0 +1,273 @@
+
+[id="migration-olm-stable-channel-to-stable-all-namespace_{context}"]
+= Migration {prod} from "che-server" workspace engine to "dev-workspace" using OLM 
+
+For {prod} instances installed using Operator lifecycle manager(OLM) with "stable" channel
+there is opportunity to make migration with new channel "tech-preview-stable-all-namespaces".
+"stable" OLM channel provides {prod} with old "che-server" engine.
+This engine is not under active development any more.
+"tech-preview-stable-all-namespaces" channel provides {prod-short} with modern "dev-workspace" engine.
+
+> Warning: Migration process is not back compatible. All previously created workspaces will be
+not working any more after migration. Before this procedure all users should be notified to save their source code
+changes to prevent losing data.
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* An instance of {prod-short} running in Openshift 4 cluster.
+
+.Procedure
+
+Scale {prod-deployment} deployment to zero to stop users interaction with this service:
+
+[subs="+quotes,+attributes"]
+----
+{orch-cli} scale deployment {prod-deployment} --replicas=0 -n {prod-namespace}
+----
+
+If you have enabled Openshift OAuth you have to migrate existed users. This migration is required to reuse existed Openshift users with "dev-workspace" native authentication mode.
+
+> Warning: If your {prod} instance didn't use OAuth, then you can't migrate users.
+There is no mechanism to migrate native Keycloak users to Openshift users.
+
+## Migrate Openshift OAuth users
+
+Create {prod} backup using the xref:managing-backups-using-chectl.adoc[] or che-operator itself xref:managing-backups-using-custom-resources.adoc[].
+
+Create migration script MigrateUsers.sh:
+
+[subs="+quotes,+attributes"]
+----
+$ touch MigrateUsers.sh && chmod +x MigrateUsers.sh
+----
+
+MigrateUsers.sh script content
+[source,shell,subs="+attributes"]
+----
+#!/bin/bash
+
+while [[ "$#" -gt 0 ]]; do
+  case $1 in
+    '--n') namespace=$2; shift 1;;
+    '--cr') clusterName=$2; shift 1;;
+  esac
+  shift 1
+done
+
+if [ -z "${namespace}" ]; then
+  echo "[ERROR] You have to specify namespace using '--n' flag"
+  exit 11
+fi
+
+if [ -z "${clusterName}" ]; then
+  echo "[ERROR] You have to specify custom resource name using '--cr' flag"
+  exit 11
+fi
+
+namespace="eclipse-che"
+clusterName="eclipse-che"
+# Keycloak admin name
+keycloakAdmin=admin
+realm="che"
+
+identityURL=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.status.keycloakURL}" )
+echo "[INFO] Identity url is: '${identityURL}'"
+identitySecretName=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.auth.identityProviderSecret}")
+echo "[INFO] Secret with identity auth info is: '${identitySecretName}'"
+password=$(oc get secret "${identitySecretName}" -n "$namespace" -o jsonpath="{.data.password}" | base64 -d)
+
+# Get admin token to retrieve users information.
+updateToken() {
+    TOKEN=$(curl -k \
+    -d "client_id=admin-cli" \
+    -d "username=${keycloakAdmin}" \
+    -d "password=${password}" \
+    -d "grant_type=password" \
+    "${identityURL}/realms/master/protocol/openid-connect/token" | jq -r ".access_token")
+}
+
+updateToken
+
+userIds=($(curl -k -H "Authorization: bearer ${TOKEN}" "${identityURL}/${keycloakAdmin}/realms/${realm}/users" | jq ".[] | .id" | tr "\r\n" " "))
+
+usersIdToMigrate=""
+for userId in "${userIds[@]}"; do
+    updateToken
+
+    userId=$(echo "${userId}" | tr -d "\"")
+    echo "${userId}"
+    echo "${identityURL}/${keycloakAdmin}/realms/${realm}/users/${userId}/federated-identity"
+    userFederation=$(curl -k -H "Authorization: bearer ${TOKEN}" "${identityURL}/${keycloakAdmin}/realms/${realm}/users/${userId}/federated-identity")
+    provider=$(echo "${userFederation}" | jq -r ".[] | select(.identityProvider == \"openshift-v4\")")
+    if [ -n "${provider}" ]; then
+        openshiftUserId=$(echo "${provider}" | jq ".userId" | tr -d "\"")
+        usersIdToMigrate="${usersIdToMigrate} ${userId}@${openshiftUserId}"
+    fi
+done
+
+echo "[INFO] Migration stuff: ${usersIdToMigrate}"
+
+# check that postgre is non external
+postgreImage=$(kubectl get deployment postgres -n "$namespace" -o jsonpath="{.spec.template.spec.containers[0].image}")
+podIP=$(oc get pod -l component=postgres -n "$namespace" -o jsonpath="{.items[0].status.podIP}")
+
+cat <<EOF | oc apply -n "$namespace" -f -
+kind: Job
+apiVersion: batch/v1
+metadata:
+  name: migrate-users-db
+spec:
+  parallelism: 1
+  completions: 1
+  backoffLimit: 6
+  template:
+    metadata:
+      name: migrate-users-db
+    spec:
+      volumes:
+        - name: postgres-data
+          persistentVolumeClaim:
+            claimName: postgres-data
+      containers:
+        - name: postgre
+          image: >-
+            ${postgreImage}
+          env:
+            - name: POSTGRESQL_USER
+              valueFrom:
+                secretKeyRef:
+                  name: che-postgres-secret
+                  key: user
+            - name: POSTGRESQL_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: che-postgres-secret
+                  key: password
+            - name: USER_IDS_TO_MIGRATE
+              value: "${usersIdToMigrate}"
+            - name: POSTGRESQL_POD_IP
+              value: "${podIP}"
+          command:
+            - /bin/bash
+          args:
+            - "-c"
+            - >-
+              DUMP_FILE="/tmp/dbdump.sql";
+              DB_NAME="dbche";
+              DB_OWNER="pgche";
+              touch "\${DUMP_FILE}";
+              echo "[INFO] Create database dump: \${DUMP_FILE}";
+              export PGPASSWORD="\$(POSTGRESQL_PASSWORD)";
+              pg_dump -d \${DB_NAME} -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) > "\${DUMP_FILE}";
+              userMappings=(\$(USER_IDS_TO_MIGRATE));
+              echo "[INFO] Mappings array is:  \${userMappings[@]}";
+              for userIdMapping in "\${userMappings[@]}"; do
+                currentUserId=\${userIdMapping%@*}
+                openshiftUserId=\${userIdMapping#*@}
+                echo "[INFO] Replace \${currentUserId} to \${openshiftUserId} in the dump."
+                sed -i "s|\${currentUserId}|\${openshiftUserId}|g" "\${DUMP_FILE}"
+              done;
+              echo "[INFO] Replace database dump...";
+              echo "[INFO] Set up connection limit: 0";
+              psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d template1 -c "ALTER DATABASE \${DB_NAME} CONNECTION LIMIT 0;";
+              echo "Disconnect database: '\${DB_NAME}'";
+              psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d template1 -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '\${DB_NAME}';";
+              echo "Drop database... '\${DB_NAME}'";
+              psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d template1 -c "DROP DATABASE \${DB_NAME};";
+              echo "[INFO] Create an empty database '\${DB_NAME}'";
+              createdb -h \${POSTGRESQL_POD_IP} -U \${POSTGRESQL_USER} "\${DB_NAME}" --owner="\${DB_OWNER}";
+              echo "[INFO] Apply database dump.";
+              psql -h \${POSTGRESQL_POD_IP} -U \${POSTGRESQL_USER} "\${DB_NAME}" < "\${DUMP_FILE}";
+              rm -f "\${DUMP_FILE}";
+              echo "done!";
+          imagePullPolicy: IfNotPresent
+          volumeMounts:
+            - name: postgres-data
+              mountPath: /var/lib/pgsql/data
+          securityContext:
+            capabilities:
+              drop:
+                - ALL
+                - KILL
+                - MKNOD
+                - SETGID
+                - SETUID
+            # runAsUser: 1000620000
+      terminationMessagePolicy: File
+      restartPolicy: OnFailure
+      terminationGracePeriodSeconds: 30
+      dnsPolicy: ClusterFirst
+      schedulerName: default-scheduler
+EOF
+----
+
+Execute script to migration existed Openshift OAuth users. This script will execute migration job.
+
+[subs="+quotes,+attributes"]
+----
+$ ./MigrateUsers.sh --n {prod-namespace} --cr {prod-checluster}
+----
+
+Where are:
+
+- `--n` namespace
+- `--cr` custom resource name
+
+To track when migration job will be completed use the command:
+
+[subs="+quotes,+attributes"]
+---- 
+$ kubectl wait --for=condition=complete job/migrate-users-db -n {prod-namespace}
+----
+
+If migration job was successfull cli should provide output:
+
+[subs="+quotes,+attributes"]
+----
+job.batch/migrate-users-db condition met
+----
+
+# Switch from "stable" OLM channel to the "tech-preview-stable-all-namespaces" channel.
+
+Delete OLM subscription "{prod-checluster}":
+
+[subs="+quotes,+attributes"]
+----
+$ oc delete subscription {prod-checluster} -n {prod-namespace}
+----
+
+Delete current cluster service version by name:
+
+[subs="+quotes,+attributes"]
+----
+$ CSV_VERSION_NAME=$(oc get clusterserviceversion -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
+$ oc delete clusterserviceversion "${CSV_VERSION_NAME}" -n {prod-namespace}
+----
+
+Create new subscription:
+
+[subs="+quotes,+attributes"]
+----
+$ oc apply -f - <<EOF
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: {prod-checluster}
+  namespace: openshift-operators
+spec:
+  channel: tech-preview-stable-all-namespaces
+  installPlanApproval: Automatic
+  name: {prod-checluster}
+  source: community-operators
+  sourceNamespace: openshift-marketplace
+EOF
+----
+
+Enable "dev-workspace" engine in the custom resource:
+
+[subs="+quotes,+attributes"]
+----
+$ oc patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
+'[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}]'
+----

From 2f8e7639abac1f225cf036b65b7d2886d5980b00 Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Tue, 9 Nov 2021 10:09:15 +0000
Subject: [PATCH 02/18] Fix up.

Signed-off-by: Oleksandr Andriienko <oandriie@redhat.com>
---
 ...ion_olm_stable_channel_to_stable_all_namespace.adoc | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index 3cfb4a103b..78d48e9eb5 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -230,18 +230,12 @@ job.batch/migrate-users-db condition met
 
 # Switch from "stable" OLM channel to the "tech-preview-stable-all-namespaces" channel.
 
-Delete OLM subscription "{prod-checluster}":
+Delete OLM subscription "{prod-checluster}" and current cluster service version by name:
 
 [subs="+quotes,+attributes"]
 ----
+$ CSV_VERSION_NAME=$(oc get subscription {prod-checluster} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
 $ oc delete subscription {prod-checluster} -n {prod-namespace}
-----
-
-Delete current cluster service version by name:
-
-[subs="+quotes,+attributes"]
-----
-$ CSV_VERSION_NAME=$(oc get clusterserviceversion -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
 $ oc delete clusterserviceversion "${CSV_VERSION_NAME}" -n {prod-namespace}
 ----
 

From b252cd8846abd98d7b11ed0e44026c48020bcf5b Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Tue, 9 Nov 2021 13:34:27 +0000
Subject: [PATCH 03/18] Fix migrate script to set up minimal user profile info.

Signed-off-by: Oleksandr Andriienko <oandriie@redhat.com>
---
 ...igration_olm_stable_channel_to_stable_all_namespace.adoc | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index 78d48e9eb5..80413adc9f 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -180,6 +180,11 @@ spec:
               echo "[INFO] Apply database dump.";
               psql -h \${POSTGRESQL_POD_IP} -U \${POSTGRESQL_USER} "\${DB_NAME}" < "\${DUMP_FILE}";
               rm -f "\${DUMP_FILE}";
+              for userIdMapping in "\${userMappings[@]}"; do
+                openshiftUserId=\${userIdMapping#*@}
+                echo "[INFO] Update user profile info for user with id \${openshiftUserId}."
+                psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d \${DB_NAME} -c "insert into profile(userid) values ('\${openshiftUserId}');";
+              done;
               echo "done!";
           imagePullPolicy: IfNotPresent
           volumeMounts:
@@ -193,7 +198,6 @@ spec:
                 - MKNOD
                 - SETGID
                 - SETUID
-            # runAsUser: 1000620000
       terminationMessagePolicy: File
       restartPolicy: OnFailure
       terminationGracePeriodSeconds: 30

From 79f3fe8094dd3a8a81c1fcb7507c72cbf618788d Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Mon, 22 Nov 2021 16:12:48 +0200
Subject: [PATCH 04/18] Update
 modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc

Co-authored-by: Ilya Buziuk <ilyabuziuk@gmail.com>
---
 ...oc_migration_olm_stable_channel_to_stable_all_namespace.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index 80413adc9f..ff2a562a50 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -8,7 +8,7 @@ there is opportunity to make migration with new channel "tech-preview-stable-all
 This engine is not under active development any more.
 "tech-preview-stable-all-namespaces" channel provides {prod-short} with modern "dev-workspace" engine.
 
-> Warning: Migration process is not back compatible. All previously created workspaces will be
+> Warning: The migration process is not backward compatible. All previously created workspaces will be
 not working any more after migration. Before this procedure all users should be notified to save their source code
 changes to prevent losing data.
 

From e0402d297829e902ddcc2644056fe13e5a15d387 Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Mon, 22 Nov 2021 16:18:55 +0200
Subject: [PATCH 05/18] Update
 modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc

---
 ...oc_migration_olm_stable_channel_to_stable_all_namespace.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index ff2a562a50..34e990449a 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -6,7 +6,7 @@ For {prod} instances installed using Operator lifecycle manager(OLM) with "stabl
 there is opportunity to make migration with new channel "tech-preview-stable-all-namespaces".
 "stable" OLM channel provides {prod} with old "che-server" engine.
 This engine is not under active development any more.
-"tech-preview-stable-all-namespaces" channel provides {prod-short} with modern "dev-workspace" engine.
+"tech-preview-stable-all-namespaces" channel provides {prod-short} with modern {devworkspace} engine.
 
 > Warning: The migration process is not backward compatible. All previously created workspaces will be
 not working any more after migration. Before this procedure all users should be notified to save their source code

From 473968623f6b128a7da5775fc18104e3bbb15a12 Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Mon, 22 Nov 2021 14:27:41 +0000
Subject: [PATCH 06/18] Use dev workspace reference.

Signed-off-by: Oleksandr Andriienko <oandriie@redhat.com>
---
 ...igration_olm_stable_channel_to_stable_all_namespace.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index 34e990449a..8bc6c3a9a5 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -1,6 +1,6 @@
 
 [id="migration-olm-stable-channel-to-stable-all-namespace_{context}"]
-= Migration {prod} from "che-server" workspace engine to "dev-workspace" using OLM 
+= Migration {prod} from "che-server" workspace engine to "{devworkspace}" using OLM 
 
 For {prod} instances installed using Operator lifecycle manager(OLM) with "stable" channel
 there is opportunity to make migration with new channel "tech-preview-stable-all-namespaces".
@@ -26,7 +26,7 @@ Scale {prod-deployment} deployment to zero to stop users interaction with this s
 {orch-cli} scale deployment {prod-deployment} --replicas=0 -n {prod-namespace}
 ----
 
-If you have enabled Openshift OAuth you have to migrate existed users. This migration is required to reuse existed Openshift users with "dev-workspace" native authentication mode.
+If you have enabled Openshift OAuth you have to migrate existed users. This migration is required to reuse existed Openshift users with "{devworkspace}" native authentication mode.
 
 > Warning: If your {prod} instance didn't use OAuth, then you can't migrate users.
 There is no mechanism to migrate native Keycloak users to Openshift users.
@@ -262,7 +262,7 @@ spec:
 EOF
 ----
 
-Enable "dev-workspace" engine in the custom resource:
+Enable {devworkspace} engine in the custom resource:
 
 [subs="+quotes,+attributes"]
 ----

From 4848a2e522b521d580c166fe48aa258e3938f85b Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Wed, 24 Nov 2021 19:36:51 +0000
Subject: [PATCH 07/18] Set single host and set -e for migrate script.

Signed-off-by: Oleksandr Andriienko <oandriie@redhat.com>
---
 ..._stable_channel_to_stable_all_namespace.adoc | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index 8bc6c3a9a5..70e25bd290 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -19,6 +19,8 @@ changes to prevent losing data.
 
 .Procedure
 
+.Migrate Openshift OAuth users
+
 Scale {prod-deployment} deployment to zero to stop users interaction with this service:
 
 [subs="+quotes,+attributes"]
@@ -31,8 +33,6 @@ If you have enabled Openshift OAuth you have to migrate existed users. This migr
 > Warning: If your {prod} instance didn't use OAuth, then you can't migrate users.
 There is no mechanism to migrate native Keycloak users to Openshift users.
 
-## Migrate Openshift OAuth users
-
 Create {prod} backup using the xref:managing-backups-using-chectl.adoc[] or che-operator itself xref:managing-backups-using-custom-resources.adoc[].
 
 Create migration script MigrateUsers.sh:
@@ -46,7 +46,7 @@ MigrateUsers.sh script content
 [source,shell,subs="+attributes"]
 ----
 #!/bin/bash
-
+set -e
 while [[ "$#" -gt 0 ]]; do
   case $1 in
     '--n') namespace=$2; shift 1;;
@@ -153,6 +153,7 @@ spec:
           args:
             - "-c"
             - >-
+              set -e;
               DUMP_FILE="/tmp/dbdump.sql";
               DB_NAME="dbche";
               DB_OWNER="pgche";
@@ -231,15 +232,15 @@ If migration job was successfull cli should provide output:
 ----
 job.batch/migrate-users-db condition met
 ----
-
-# Switch from "stable" OLM channel to the "tech-preview-stable-all-namespaces" channel.
+.Switch from "stable" OLM channel to the "tech-preview-stable-all-namespaces" channel.
 
 Delete OLM subscription "{prod-checluster}" and current cluster service version by name:
 
 [subs="+quotes,+attributes"]
 ----
-$ CSV_VERSION_NAME=$(oc get subscription {prod-checluster} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
-$ oc delete subscription {prod-checluster} -n {prod-namespace}
+$ SUBSCRIPTION=$(oc get subscription -n {prod-namespace} -o custom-columns=POD:.metadata.name --no-headers | grep eclipse-che)
+$ CSV_VERSION_NAME=$(oc get subscription ${SUBSCRIPTION} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
+$ oc delete subscription ${SUBSCRIPTION} -n {prod-namespace}
 $ oc delete clusterserviceversion "${CSV_VERSION_NAME}" -n {prod-namespace}
 ----
 
@@ -267,5 +268,5 @@ Enable {devworkspace} engine in the custom resource:
 [subs="+quotes,+attributes"]
 ----
 $ oc patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
-'[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}]'
+'[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}, {"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "single-host"}]'
 ----

From 16753883192aa4ce2b300368a568706c48d94378 Mon Sep 17 00:00:00 2001
From: Oleksandr Andriienko <oandriie@redhat.com>
Date: Fri, 26 Nov 2021 07:51:04 +0000
Subject: [PATCH 08/18] Make doc and script compatible with CRW.

Signed-off-by: Oleksandr Andriienko <oandriie@redhat.com>
---
 antora.yml                                    |  3 +
 ...table_channel_to_stable_all_namespace.adoc | 71 ++++++++++---------
 2 files changed, 42 insertions(+), 32 deletions(-)

diff --git a/antora.yml b/antora.yml
index be73499f7f..911ef6470b 100644
--- a/antora.yml
+++ b/antora.yml
@@ -106,3 +106,6 @@ asciidoc:
     theia-endpoint-image: eclipse/che-theia-endpoint-runtime:next
     url-devfile-registry-repo: https://github.com/eclipse/che-devfile-registry
     url-plug-in-registry-repo: https://github.com/eclipse/che-plugin-registry
+    all-namespaces-olm-channel: tech-preview-stable-all-namespaces
+    all-namespaces-olm-package: eclipse-che
+    stable-olm-catalog-source: community-operators
diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
index 70e25bd290..ddfd871c6e 100644
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
@@ -3,7 +3,7 @@
 = Migration {prod} from "che-server" workspace engine to "{devworkspace}" using OLM 
 
 For {prod} instances installed using Operator lifecycle manager(OLM) with "stable" channel
-there is opportunity to make migration with new channel "tech-preview-stable-all-namespaces".
+you can make migration with new channel "tech-preview-stable-all-namespaces".
 "stable" OLM channel provides {prod} with old "che-server" engine.
 This engine is not under active development any more.
 "tech-preview-stable-all-namespaces" channel provides {prod-short} with modern {devworkspace} engine.
@@ -15,11 +15,11 @@ changes to prevent losing data.
 .Prerequisites
 
 * The `{orch-cli}` tool is available.
-* An instance of {prod-short} running in Openshift 4 cluster.
+* An instance of {prod-short} running in OpenShift 4 cluster.
 
 .Procedure
 
-.Migrate Openshift OAuth users
+.Migrate OpenShift OAuth users
 
 Scale {prod-deployment} deployment to zero to stop users interaction with this service:
 
@@ -28,12 +28,12 @@ Scale {prod-deployment} deployment to zero to stop users interaction with this s
 {orch-cli} scale deployment {prod-deployment} --replicas=0 -n {prod-namespace}
 ----
 
-If you have enabled Openshift OAuth you have to migrate existed users. This migration is required to reuse existed Openshift users with "{devworkspace}" native authentication mode.
+If you have enabled OpenShift OAuth you have to migrate existed users. This migration is required to reuse existed OpenShift users with "{devworkspace}" native authentication mode.
 
 > Warning: If your {prod} instance didn't use OAuth, then you can't migrate users.
-There is no mechanism to migrate native Keycloak users to Openshift users.
+There is no mechanism to migrate native Keycloak users to OpenShift users.
 
-Create {prod} backup using the xref:managing-backups-using-chectl.adoc[] or che-operator itself xref:managing-backups-using-custom-resources.adoc[].
+Create {prod} backup using the xref:managing-backups-using-chectl.adoc[] or {prod-operator} itself xref:managing-backups-using-custom-resources.adoc[].
 
 Create migration script MigrateUsers.sh:
 
@@ -55,27 +55,34 @@ while [[ "$#" -gt 0 ]]; do
   shift 1
 done
 
-if [ -z "${namespace}" ]; then
-  echo "[ERROR] You have to specify namespace using '--n' flag"
-  exit 11
+if [ -z "$namespace" ]; then
+  namespace="openshift-workspaces"
+  oc get "namespace/$namespace" > /dev/null 2>&1
+  exitCode="$?"
+  if [[ ! "${exitCode}" -eq "0" ]]; then
+      echo "[ERROR] You have to specify namespace using '--n' flag"
+      exit 11
+  fi
 fi
 
 if [ -z "${clusterName}" ]; then
-  echo "[ERROR] You have to specify custom resource name using '--cr' flag"
-  exit 11
+    clusterName="codeready-workspaces"
+    oc get checluster "${clusterName}" -n "$namespace" > /dev/null 2>&1
+    exitCode="$?"
+    if [[ ! "${exitCode}" -eq "0" ]]; then
+      echo "[ERROR] You have to specify custom resource name using '--cr' flag"
+      exit 11
+    fi
 fi
 
-namespace="eclipse-che"
-clusterName="eclipse-che"
-# Keycloak admin name
-keycloakAdmin=admin
-realm="che"
-
-identityURL=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.status.keycloakURL}" )
+identityURL=$(oc get checluster "${clusterName}" -n "${namespace}" -o jsonpath="{.status.keycloakURL}" )
 echo "[INFO] Identity url is: '${identityURL}'"
 identitySecretName=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.auth.identityProviderSecret}")
 echo "[INFO] Secret with identity auth info is: '${identitySecretName}'"
+keycloakAdmin=$(oc get secret "${identitySecretName}" -n "$namespace" -o jsonpath="{.data.user}" | base64 -d)
 password=$(oc get secret "${identitySecretName}" -n "$namespace" -o jsonpath="{.data.password}" | base64 -d)
+realm=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.auth.identityProviderRealm}")
+postgreSecret=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.database.chePostgresSecret}")
 
 # Get admin token to retrieve users information.
 updateToken() {
@@ -137,12 +144,12 @@ spec:
             - name: POSTGRESQL_USER
               valueFrom:
                 secretKeyRef:
-                  name: che-postgres-secret
+                  name: ${postgreSecret}
                   key: user
             - name: POSTGRESQL_PASSWORD
               valueFrom:
                 secretKeyRef:
-                  name: che-postgres-secret
+                  name: ${postgreSecret}
                   key: password
             - name: USER_IDS_TO_MIGRATE
               value: "${usersIdToMigrate}"
@@ -207,7 +214,7 @@ spec:
 EOF
 ----
 
-Execute script to migration existed Openshift OAuth users. This script will execute migration job.
+Execute script to migration existed OpenShift OAuth users. This script will execute migration job.
 
 [subs="+quotes,+attributes"]
 ----
@@ -223,10 +230,10 @@ To track when migration job will be completed use the command:
 
 [subs="+quotes,+attributes"]
 ---- 
-$ kubectl wait --for=condition=complete job/migrate-users-db -n {prod-namespace}
+$ {orch-cli} wait --for=condition=complete job/migrate-users-db -n {prod-namespace}
 ----
 
-If migration job was successfull cli should provide output:
+If migration job was successful {orch-cli} should provide output:
 
 [subs="+quotes,+attributes"]
 ----
@@ -234,31 +241,31 @@ job.batch/migrate-users-db condition met
 ----
 .Switch from "stable" OLM channel to the "tech-preview-stable-all-namespaces" channel.
 
-Delete OLM subscription "{prod-checluster}" and current cluster service version by name:
+Delete OLM subscription and current cluster service version by name:
 
 [subs="+quotes,+attributes"]
 ----
-$ SUBSCRIPTION=$(oc get subscription -n {prod-namespace} -o custom-columns=POD:.metadata.name --no-headers | grep eclipse-che)
+$ SUBSCRIPTION=$(oc get subscription -n {prod-namespace} -o custom-columns=POD:.metadata.name --no-headers | grep {prod-checluster})
 $ CSV_VERSION_NAME=$(oc get subscription ${SUBSCRIPTION} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
-$ oc delete subscription ${SUBSCRIPTION} -n {prod-namespace}
-$ oc delete clusterserviceversion "${CSV_VERSION_NAME}" -n {prod-namespace}
+$ {orch-cli} delete subscription ${SUBSCRIPTION} -n {prod-namespace}
+$ {orch-cli} delete clusterserviceversion "${CSV_VERSION_NAME}" -n {prod-namespace}
 ----
 
 Create new subscription:
 
 [subs="+quotes,+attributes"]
 ----
-$ oc apply -f - <<EOF
+$ {orch-cli} apply -f - <<EOF
 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: {prod-checluster}
   namespace: openshift-operators
 spec:
-  channel: tech-preview-stable-all-namespaces
+  channel: {all-namespaces-olm-channel}
   installPlanApproval: Automatic
-  name: {prod-checluster}
-  source: community-operators
+  name: {all-namespaces-olm-package}
+  source: {stable-olm-catalog-source}
   sourceNamespace: openshift-marketplace
 EOF
 ----
@@ -267,6 +274,6 @@ Enable {devworkspace} engine in the custom resource:
 
 [subs="+quotes,+attributes"]
 ----
-$ oc patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
+$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
 '[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}, {"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "single-host"}]'
 ----

From c75d2a5ce2674e3e2872614d9c1a5482624ebceb Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Fri, 26 Nov 2021 17:33:24 +0200
Subject: [PATCH 09/18] Doc refactoring

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 antora.yml                                    |   7 +-
 modules/administration-guide/nav.adoc         |   2 +-
 ...table-channel-to-stable-all-namespace.adoc |   7 -
 .../migration-to-devworkspace-engine.adoc     |   7 +
 ...proc_migration-to-devworkspace-engine.adoc | 173 +++++++++++
 ...table_channel_to_stable_all_namespace.adoc | 279 ------------------
 .../partials/snip_creating-che-database.adoc  |   6 +
 .../partials/snip_droping-che-database.adoc   |   6 +
 .../partials/snip_dumping-che-database.adoc   |   7 +
 .../snip_finding-che-database-name.adoc       |   7 +
 .../partials/snip_finding-che-user-name.adoc  |   2 +
 .../partials/snip_finding-postgresql-pod.adoc |   6 +
 .../partials/snip_restoring-che-database.adoc |   6 +
 .../partials/snip_scaling-down-che.adoc       |   6 +
 .../partials/snip_scaling-down-keycloak.adoc  |   6 +
 15 files changed, 237 insertions(+), 290 deletions(-)
 delete mode 100644 modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc
 create mode 100644 modules/administration-guide/pages/migration-to-devworkspace-engine.adoc
 create mode 100644 modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
 delete mode 100644 modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
 create mode 100644 modules/administration-guide/partials/snip_creating-che-database.adoc
 create mode 100644 modules/administration-guide/partials/snip_droping-che-database.adoc
 create mode 100644 modules/administration-guide/partials/snip_dumping-che-database.adoc
 create mode 100644 modules/administration-guide/partials/snip_finding-che-database-name.adoc
 create mode 100644 modules/administration-guide/partials/snip_finding-che-user-name.adoc
 create mode 100644 modules/administration-guide/partials/snip_finding-postgresql-pod.adoc
 create mode 100644 modules/administration-guide/partials/snip_restoring-che-database.adoc
 create mode 100644 modules/administration-guide/partials/snip_scaling-down-che.adoc
 create mode 100644 modules/administration-guide/partials/snip_scaling-down-keycloak.adoc

diff --git a/antora.yml b/antora.yml
index 911ef6470b..2d3a907c3a 100644
--- a/antora.yml
+++ b/antora.yml
@@ -106,6 +106,7 @@ asciidoc:
     theia-endpoint-image: eclipse/che-theia-endpoint-runtime:next
     url-devfile-registry-repo: https://github.com/eclipse/che-devfile-registry
     url-plug-in-registry-repo: https://github.com/eclipse/che-plugin-registry
-    all-namespaces-olm-channel: tech-preview-stable-all-namespaces
-    all-namespaces-olm-package: eclipse-che
-    stable-olm-catalog-source: community-operators
+    prod-channel: stable
+    prod-tech-preview-channel: tech-preview-stable-all-namespaces
+    prod-catalog-source: community-operators
+    prod-tech-preview-olm-package: eclipse-che
diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc
index 30b6c34031..2daf869cad 100644
--- a/modules/administration-guide/nav.adoc
+++ b/modules/administration-guide/nav.adoc
@@ -34,7 +34,7 @@
 
 * xref:migration-from-postgresql-9-to-postgresql-13.adoc[]
 
-* xref:migration-olm-stable-channel-to-stable-all-namespace.adoc[]
+* xref:migration-to-devworkspace-engine.adoc[]
 
 * xref:caching-images-for-faster-workspace-start.adoc[]
 ** xref:defining-the-list-of-images-to-pull.adoc[]
diff --git a/modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc b/modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc
deleted file mode 100644
index 0788968efd..0000000000
--- a/modules/administration-guide/pages/migration-olm-stable-channel-to-stable-all-namespace.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-[id="migration_olm_stable_channel_to_stable_all_namespace"]
-
-:navtitle: Migration OLM "stable" channel to "stable-all-namespace"
-:keywords: administration-guide, migration
-:page-aliases: .:olm-migration
-
-include::partial$proc_migration_olm_stable_channel_to_stable_all_namespace.adoc[]
diff --git a/modules/administration-guide/pages/migration-to-devworkspace-engine.adoc b/modules/administration-guide/pages/migration-to-devworkspace-engine.adoc
new file mode 100644
index 0000000000..85e4dbd2e3
--- /dev/null
+++ b/modules/administration-guide/pages/migration-to-devworkspace-engine.adoc
@@ -0,0 +1,7 @@
+[id="migration-to-devworkspace-engine"]
+
+:navtitle: Migration to DevWorkspace engine
+:keywords: administration-guide, migration, devworkspace
+:page-aliases: .:migration-to-devworskpace-engine
+
+include::partial$proc_migration-to-devworkspace-engine.adoc[]
diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
new file mode 100644
index 0000000000..0c247ae332
--- /dev/null
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -0,0 +1,173 @@
+
+[id="migration-to-devworkspace-engine_{context}"]
+= Migration to {devworkspace} engine.
+
+This procedure describes how to migration to {devworkspace} engine using https://docs.openshift.com/container-platform/latest/operators/understanding/olm/olm-understanding-olm.html[OLM] to support the Devfile 2.0.0 file format and mentions how to do so on existing instances.
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* An instance of {prod-short} running in OpenShift 4 cluster.
+* OpenShift OAuth is enabled. See xref:configuring-openshift-oauth.adoc[].
+
+.Procedure
+
+. Save and push changes back to the Git repositories for all running workspaces of the {prod-short} instance.
+
+. Stop all workspaces in the {prod-short} instance.
+
+. Backup {prod-short} data. See xref:managing-backups-using-chectl.adoc[].
+
+include::partial$snip_scaling-down-che.adoc[]
+
+include::partial$snip_finding-postgresql-pod.adoc[]
+
+. Create the migration script
++
+[source,shell,subs="+attributes"]
+----
+cat >migration.sh<<EOF
+#!/bin/bash
+set -e
+
+IDENTITY_PROVIDER_URL=\$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath="{.status.keycloakURL}" )
+IDENTITY_PROVIDER_SECRET=\$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderSecret}")
+IDENTITY_PROVIDER_PASSWORD=\$(if [ -z "\$IDENTITY_PROVIDER_SECRET" ] || [ \$IDENTITY_PROVIDER_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster}  -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderPassword}"; else {orch-cli} get secret \$IDENTITY_PROVIDER_SECRET -n {prod-namespace} -o jsonpath="{.data.password}" | base64 -d; fi)
+IDENTITY_PROVIDER_USERNAME=\$(if [ -z "\$IDENTITY_PROVIDER_SECRET" ] || [ \$IDENTITY_PROVIDER_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster}  -n {prod-namespace} -o jsonpath="{.spec.auth.IdentityProviderAdminUserName}"; else {orch-cli} get secret \$IDENTITY_PROVIDER_SECRET -n {prod-namespace} -o jsonpath="{.data.user}" | base64 -d; fi)
+IDENTITY_PROVIDER_REALM=\$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderRealm}")
+
+init() {
+  unset DUMP
+  unset ADD_PROFILES
+  unset MIGRATE_USERS
+
+  while [[ "\$#" -gt 0 ]]; do
+    case \$1 in
+      '--dump') DUMP="\$2"; shift 1;;
+      '--add-profiles'|'-p') ADD_PROFILES=TRUE;;
+      '--migrate-users'|'-i') MIGRATE_USERS=TRUE;;
+    esac
+    shift 1
+  done
+}
+
+refreshToken() {
+    IDENTITY_PROVIDER_TOKEN=\$(curl -ks \
+    -d "client_id=admin-cli" \
+    -d "username=\${IDENTITY_PROVIDER_USERNAME}" \
+    -d "password=\${IDENTITY_PROVIDER_PASSWORD}" \
+    -d "grant_type=password" \
+    "\${IDENTITY_PROVIDER_URL}/realms/master/protocol/openid-connect/token" | jq -r ".access_token")
+}
+
+run() {
+  refreshToken
+  USER_IDS=(\$(curl -ks  -H "Authorization: bearer \${IDENTITY_PROVIDER_TOKEN}" "\${IDENTITY_PROVIDER_URL}/\${IDENTITY_PROVIDER_USERNAME}/realms/\${IDENTITY_PROVIDER_REALM}/users" | jq ".[] | .id" | tr "\r\n" " "))
+
+  for USER_ID in "\${USER_IDS[@]}"; do
+      refreshToken
+
+      USER_ID=\$(echo "\${USER_ID}" | tr -d "\"")
+      FEDERATED_IDENTITY=\$(curl -ks -H "Authorization: bearer \${IDENTITY_PROVIDER_TOKEN}" "\${IDENTITY_PROVIDER_URL}/\${IDENTITY_PROVIDER_USERNAME}/realms/\${IDENTITY_PROVIDER_REALM}/users/\${USER_ID}/federated-identity")
+      IDENTITY_PROVIDER=\$(echo "\${FEDERATED_IDENTITY}" | jq -r ".[] | select(.identityProvider == \"openshift-v4\")")
+      if [ -n "\${IDENTITY_PROVIDER}" ]; then
+        OPENSHIFT_USER_ID=\$(echo "\${IDENTITY_PROVIDER}" | jq ".userId" | tr -d "\"")
+
+        if [[ \${MIGRATE_USER}} == TRUE ]]; then
+          sed -i "s|\${USER_ID}|\${OPENSHIFT_USER_ID}|g" "\${DUMP}"
+          echo "[INFO] Migrated User ID from \"\${USER_ID}\" to \"\${OPENSHIFT_USER_ID}\""
+        elif [[ \${ADD_PROFILES} == TRUE ]]; then
+          {orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql \${CHE_POSTGRES_DB} -tAc \"insert into profile(userid) values ('\${OPENSHIFT_USER_ID}');\""
+          echo "[INFO] Added profile for User ID \"\${OPENSHIFT_USER_ID}\""
+        fi
+      fi
+  done
+}
+
+init
+run
+echo "[INFO] Done."
+EOF
+----
+
+include::partial$snip_finding-che-database-name.adoc[]
+
+include::partial$snip_dumping-che-database.adoc[]
+
+include::partial$snip_droping-che-database.adoc[]
+
+include::partial$snip_creating-che-database.adoc[]
+
+. Migrate Users ID:
++
+[subs="+quotes,+attributes"]
+----
+bash migration.sh --migrate-users --dump che.sql
+----
+
+include::partial$snip_restoring-che-database.adoc[]
+
+. Add Users Profiles:
++
+[subs="+quotes,+attributes"]
+----
+bash migration.sh --add-profiles
+----
+
+. Find Cluster Service Version name:
++
+[subs="+quotes,+attributes"]
+----
+CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
+----
+
+. Delete Subscription from `{prod-channel}` channel:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} delete subscription {prod-id} -n {prod-namespace}
+----
+
+. Delete Cluster Service Version:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} delete csv ${CSV} -n {prod-namespace}
+----
+
+. Enable {devworkspace} engine:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
+'[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}]'
+----
+
+. Set single-host exposure strategy:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
+'[{"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "single-host"}]'
+----
+
+. Create a OLM new subscription to `{prod-tech-preview-channel}` channel:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} apply -f - <<EOF
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: {prod-id}
+  namespace: openshift-operators
+spec:
+  channel: {prod-tech-preview-channel}
+  installPlanApproval: Automatic
+  name: {prod-tech-preview-olm-package}
+  source: {prod-catalog-source}
+  sourceNamespace: openshift-marketplace
+EOF
+----
+
+
diff --git a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc b/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
deleted file mode 100644
index ddfd871c6e..0000000000
--- a/modules/administration-guide/partials/proc_migration_olm_stable_channel_to_stable_all_namespace.adoc
+++ /dev/null
@@ -1,279 +0,0 @@
-
-[id="migration-olm-stable-channel-to-stable-all-namespace_{context}"]
-= Migration {prod} from "che-server" workspace engine to "{devworkspace}" using OLM 
-
-For {prod} instances installed using Operator lifecycle manager(OLM) with "stable" channel
-you can make migration with new channel "tech-preview-stable-all-namespaces".
-"stable" OLM channel provides {prod} with old "che-server" engine.
-This engine is not under active development any more.
-"tech-preview-stable-all-namespaces" channel provides {prod-short} with modern {devworkspace} engine.
-
-> Warning: The migration process is not backward compatible. All previously created workspaces will be
-not working any more after migration. Before this procedure all users should be notified to save their source code
-changes to prevent losing data.
-
-.Prerequisites
-
-* The `{orch-cli}` tool is available.
-* An instance of {prod-short} running in OpenShift 4 cluster.
-
-.Procedure
-
-.Migrate OpenShift OAuth users
-
-Scale {prod-deployment} deployment to zero to stop users interaction with this service:
-
-[subs="+quotes,+attributes"]
-----
-{orch-cli} scale deployment {prod-deployment} --replicas=0 -n {prod-namespace}
-----
-
-If you have enabled OpenShift OAuth you have to migrate existed users. This migration is required to reuse existed OpenShift users with "{devworkspace}" native authentication mode.
-
-> Warning: If your {prod} instance didn't use OAuth, then you can't migrate users.
-There is no mechanism to migrate native Keycloak users to OpenShift users.
-
-Create {prod} backup using the xref:managing-backups-using-chectl.adoc[] or {prod-operator} itself xref:managing-backups-using-custom-resources.adoc[].
-
-Create migration script MigrateUsers.sh:
-
-[subs="+quotes,+attributes"]
-----
-$ touch MigrateUsers.sh && chmod +x MigrateUsers.sh
-----
-
-MigrateUsers.sh script content
-[source,shell,subs="+attributes"]
-----
-#!/bin/bash
-set -e
-while [[ "$#" -gt 0 ]]; do
-  case $1 in
-    '--n') namespace=$2; shift 1;;
-    '--cr') clusterName=$2; shift 1;;
-  esac
-  shift 1
-done
-
-if [ -z "$namespace" ]; then
-  namespace="openshift-workspaces"
-  oc get "namespace/$namespace" > /dev/null 2>&1
-  exitCode="$?"
-  if [[ ! "${exitCode}" -eq "0" ]]; then
-      echo "[ERROR] You have to specify namespace using '--n' flag"
-      exit 11
-  fi
-fi
-
-if [ -z "${clusterName}" ]; then
-    clusterName="codeready-workspaces"
-    oc get checluster "${clusterName}" -n "$namespace" > /dev/null 2>&1
-    exitCode="$?"
-    if [[ ! "${exitCode}" -eq "0" ]]; then
-      echo "[ERROR] You have to specify custom resource name using '--cr' flag"
-      exit 11
-    fi
-fi
-
-identityURL=$(oc get checluster "${clusterName}" -n "${namespace}" -o jsonpath="{.status.keycloakURL}" )
-echo "[INFO] Identity url is: '${identityURL}'"
-identitySecretName=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.auth.identityProviderSecret}")
-echo "[INFO] Secret with identity auth info is: '${identitySecretName}'"
-keycloakAdmin=$(oc get secret "${identitySecretName}" -n "$namespace" -o jsonpath="{.data.user}" | base64 -d)
-password=$(oc get secret "${identitySecretName}" -n "$namespace" -o jsonpath="{.data.password}" | base64 -d)
-realm=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.auth.identityProviderRealm}")
-postgreSecret=$(oc get checluster "${clusterName}" -n "$namespace" -o jsonpath="{.spec.database.chePostgresSecret}")
-
-# Get admin token to retrieve users information.
-updateToken() {
-    TOKEN=$(curl -k \
-    -d "client_id=admin-cli" \
-    -d "username=${keycloakAdmin}" \
-    -d "password=${password}" \
-    -d "grant_type=password" \
-    "${identityURL}/realms/master/protocol/openid-connect/token" | jq -r ".access_token")
-}
-
-updateToken
-
-userIds=($(curl -k -H "Authorization: bearer ${TOKEN}" "${identityURL}/${keycloakAdmin}/realms/${realm}/users" | jq ".[] | .id" | tr "\r\n" " "))
-
-usersIdToMigrate=""
-for userId in "${userIds[@]}"; do
-    updateToken
-
-    userId=$(echo "${userId}" | tr -d "\"")
-    echo "${userId}"
-    echo "${identityURL}/${keycloakAdmin}/realms/${realm}/users/${userId}/federated-identity"
-    userFederation=$(curl -k -H "Authorization: bearer ${TOKEN}" "${identityURL}/${keycloakAdmin}/realms/${realm}/users/${userId}/federated-identity")
-    provider=$(echo "${userFederation}" | jq -r ".[] | select(.identityProvider == \"openshift-v4\")")
-    if [ -n "${provider}" ]; then
-        openshiftUserId=$(echo "${provider}" | jq ".userId" | tr -d "\"")
-        usersIdToMigrate="${usersIdToMigrate} ${userId}@${openshiftUserId}"
-    fi
-done
-
-echo "[INFO] Migration stuff: ${usersIdToMigrate}"
-
-# check that postgre is non external
-postgreImage=$(kubectl get deployment postgres -n "$namespace" -o jsonpath="{.spec.template.spec.containers[0].image}")
-podIP=$(oc get pod -l component=postgres -n "$namespace" -o jsonpath="{.items[0].status.podIP}")
-
-cat <<EOF | oc apply -n "$namespace" -f -
-kind: Job
-apiVersion: batch/v1
-metadata:
-  name: migrate-users-db
-spec:
-  parallelism: 1
-  completions: 1
-  backoffLimit: 6
-  template:
-    metadata:
-      name: migrate-users-db
-    spec:
-      volumes:
-        - name: postgres-data
-          persistentVolumeClaim:
-            claimName: postgres-data
-      containers:
-        - name: postgre
-          image: >-
-            ${postgreImage}
-          env:
-            - name: POSTGRESQL_USER
-              valueFrom:
-                secretKeyRef:
-                  name: ${postgreSecret}
-                  key: user
-            - name: POSTGRESQL_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: ${postgreSecret}
-                  key: password
-            - name: USER_IDS_TO_MIGRATE
-              value: "${usersIdToMigrate}"
-            - name: POSTGRESQL_POD_IP
-              value: "${podIP}"
-          command:
-            - /bin/bash
-          args:
-            - "-c"
-            - >-
-              set -e;
-              DUMP_FILE="/tmp/dbdump.sql";
-              DB_NAME="dbche";
-              DB_OWNER="pgche";
-              touch "\${DUMP_FILE}";
-              echo "[INFO] Create database dump: \${DUMP_FILE}";
-              export PGPASSWORD="\$(POSTGRESQL_PASSWORD)";
-              pg_dump -d \${DB_NAME} -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) > "\${DUMP_FILE}";
-              userMappings=(\$(USER_IDS_TO_MIGRATE));
-              echo "[INFO] Mappings array is:  \${userMappings[@]}";
-              for userIdMapping in "\${userMappings[@]}"; do
-                currentUserId=\${userIdMapping%@*}
-                openshiftUserId=\${userIdMapping#*@}
-                echo "[INFO] Replace \${currentUserId} to \${openshiftUserId} in the dump."
-                sed -i "s|\${currentUserId}|\${openshiftUserId}|g" "\${DUMP_FILE}"
-              done;
-              echo "[INFO] Replace database dump...";
-              echo "[INFO] Set up connection limit: 0";
-              psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d template1 -c "ALTER DATABASE \${DB_NAME} CONNECTION LIMIT 0;";
-              echo "Disconnect database: '\${DB_NAME}'";
-              psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d template1 -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '\${DB_NAME}';";
-              echo "Drop database... '\${DB_NAME}'";
-              psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d template1 -c "DROP DATABASE \${DB_NAME};";
-              echo "[INFO] Create an empty database '\${DB_NAME}'";
-              createdb -h \${POSTGRESQL_POD_IP} -U \${POSTGRESQL_USER} "\${DB_NAME}" --owner="\${DB_OWNER}";
-              echo "[INFO] Apply database dump.";
-              psql -h \${POSTGRESQL_POD_IP} -U \${POSTGRESQL_USER} "\${DB_NAME}" < "\${DUMP_FILE}";
-              rm -f "\${DUMP_FILE}";
-              for userIdMapping in "\${userMappings[@]}"; do
-                openshiftUserId=\${userIdMapping#*@}
-                echo "[INFO] Update user profile info for user with id \${openshiftUserId}."
-                psql -h \$(POSTGRESQL_POD_IP) -U \$(POSTGRESQL_USER) -q -d \${DB_NAME} -c "insert into profile(userid) values ('\${openshiftUserId}');";
-              done;
-              echo "done!";
-          imagePullPolicy: IfNotPresent
-          volumeMounts:
-            - name: postgres-data
-              mountPath: /var/lib/pgsql/data
-          securityContext:
-            capabilities:
-              drop:
-                - ALL
-                - KILL
-                - MKNOD
-                - SETGID
-                - SETUID
-      terminationMessagePolicy: File
-      restartPolicy: OnFailure
-      terminationGracePeriodSeconds: 30
-      dnsPolicy: ClusterFirst
-      schedulerName: default-scheduler
-EOF
-----
-
-Execute script to migration existed OpenShift OAuth users. This script will execute migration job.
-
-[subs="+quotes,+attributes"]
-----
-$ ./MigrateUsers.sh --n {prod-namespace} --cr {prod-checluster}
-----
-
-Where are:
-
-- `--n` namespace
-- `--cr` custom resource name
-
-To track when migration job will be completed use the command:
-
-[subs="+quotes,+attributes"]
----- 
-$ {orch-cli} wait --for=condition=complete job/migrate-users-db -n {prod-namespace}
-----
-
-If migration job was successful {orch-cli} should provide output:
-
-[subs="+quotes,+attributes"]
-----
-job.batch/migrate-users-db condition met
-----
-.Switch from "stable" OLM channel to the "tech-preview-stable-all-namespaces" channel.
-
-Delete OLM subscription and current cluster service version by name:
-
-[subs="+quotes,+attributes"]
-----
-$ SUBSCRIPTION=$(oc get subscription -n {prod-namespace} -o custom-columns=POD:.metadata.name --no-headers | grep {prod-checluster})
-$ CSV_VERSION_NAME=$(oc get subscription ${SUBSCRIPTION} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
-$ {orch-cli} delete subscription ${SUBSCRIPTION} -n {prod-namespace}
-$ {orch-cli} delete clusterserviceversion "${CSV_VERSION_NAME}" -n {prod-namespace}
-----
-
-Create new subscription:
-
-[subs="+quotes,+attributes"]
-----
-$ {orch-cli} apply -f - <<EOF
-apiVersion: operators.coreos.com/v1alpha1
-kind: Subscription
-metadata:
-  name: {prod-checluster}
-  namespace: openshift-operators
-spec:
-  channel: {all-namespaces-olm-channel}
-  installPlanApproval: Automatic
-  name: {all-namespaces-olm-package}
-  source: {stable-olm-catalog-source}
-  sourceNamespace: openshift-marketplace
-EOF
-----
-
-Enable {devworkspace} engine in the custom resource:
-
-[subs="+quotes,+attributes"]
-----
-$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \
-'[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}, {"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "single-host"}]'
-----
diff --git a/modules/administration-guide/partials/snip_creating-che-database.adoc b/modules/administration-guide/partials/snip_creating-che-database.adoc
new file mode 100644
index 0000000000..907b4fe982
--- /dev/null
+++ b/modules/administration-guide/partials/snip_creating-che-database.adoc
@@ -0,0 +1,6 @@
+. Create {prod-short} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql postgres -tAc \"CREATE DATABASE $CHE_POSTGRES_DB\""
+----
diff --git a/modules/administration-guide/partials/snip_droping-che-database.adoc b/modules/administration-guide/partials/snip_droping-che-database.adoc
new file mode 100644
index 0000000000..6113072b6b
--- /dev/null
+++ b/modules/administration-guide/partials/snip_droping-che-database.adoc
@@ -0,0 +1,6 @@
+. Drop {prod-short} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "dropdb $CHE_POSTGRES_DB"
+----
diff --git a/modules/administration-guide/partials/snip_dumping-che-database.adoc b/modules/administration-guide/partials/snip_dumping-che-database.adoc
new file mode 100644
index 0000000000..b4f7539ee0
--- /dev/null
+++ b/modules/administration-guide/partials/snip_dumping-che-database.adoc
@@ -0,0 +1,7 @@
+. Dump {prod-short} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "pg_dump $CHE_POSTGRES_DB > /tmp/che.sql"
+{orch-cli} cp {prod-namespace}/$POSTGRES_POD:/tmp/che.sql che.sql
+----
diff --git a/modules/administration-guide/partials/snip_finding-che-database-name.adoc b/modules/administration-guide/partials/snip_finding-che-database-name.adoc
new file mode 100644
index 0000000000..34f9e54161
--- /dev/null
+++ b/modules/administration-guide/partials/snip_finding-che-database-name.adoc
@@ -0,0 +1,7 @@
+. Find {prod-short} database name:
++
+[subs="+quotes,+attributes"]
+----
+CHE_POSTGRES_DB=$({orch-cli} get cm/che -n {prod-namespace} -o json  | jq -r '.data.CHE_JDBC_URL' | awk -F '/' '{print $NF}')
+if [ -z "$CHE_POSTGRES_DB" ] || [ $CHE_POSTGRES_DB = "null" ]; then CHE_POSTGRES_DB="dbche"; fi
+----
diff --git a/modules/administration-guide/partials/snip_finding-che-user-name.adoc b/modules/administration-guide/partials/snip_finding-che-user-name.adoc
new file mode 100644
index 0000000000..f4204c2554
--- /dev/null
+++ b/modules/administration-guide/partials/snip_finding-che-user-name.adoc
@@ -0,0 +1,2 @@
+POSTGRES_SECRET=$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o json | jq -r '.spec.database.chePostgresSecret')
+CHE_USER_NAME=$(if [ -z "$POSTGRES_SECRET" ] || [ $POSTGRES_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster}  -n {prod-namespace} -o json | jq -r '.spec.database.chePostgresUser'; else {orch-cli} get secret $POSTGRES_SECRET -n {prod-namespace} -o json | jq -r '.data.user' | base64 -d; fi)
diff --git a/modules/administration-guide/partials/snip_finding-postgresql-pod.adoc b/modules/administration-guide/partials/snip_finding-postgresql-pod.adoc
new file mode 100644
index 0000000000..a1f36ae4fc
--- /dev/null
+++ b/modules/administration-guide/partials/snip_finding-postgresql-pod.adoc
@@ -0,0 +1,6 @@
+. Find PostgreSQL pod:
++
+[subs="+quotes,+attributes"]
+----
+POSTGRES_POD=$({orch-cli} get pods -n {prod-namespace} | grep postgres | awk '{print $1}')
+----
diff --git a/modules/administration-guide/partials/snip_restoring-che-database.adoc b/modules/administration-guide/partials/snip_restoring-che-database.adoc
new file mode 100644
index 0000000000..84a3dc6f32
--- /dev/null
+++ b/modules/administration-guide/partials/snip_restoring-che-database.adoc
@@ -0,0 +1,6 @@
+. Restore {prod-short} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql $CHE_POSTGRES_DB < /tmp/che.sql"
+----
diff --git a/modules/administration-guide/partials/snip_scaling-down-che.adoc b/modules/administration-guide/partials/snip_scaling-down-che.adoc
new file mode 100644
index 0000000000..52b53b6a08
--- /dev/null
+++ b/modules/administration-guide/partials/snip_scaling-down-che.adoc
@@ -0,0 +1,6 @@
+. Scale down the {prod-short} deployment:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} scale deployment {prod-deployment} --replicas=0 -n {prod-namespace}
+----
diff --git a/modules/administration-guide/partials/snip_scaling-down-keycloak.adoc b/modules/administration-guide/partials/snip_scaling-down-keycloak.adoc
new file mode 100644
index 0000000000..0538d06b0a
--- /dev/null
+++ b/modules/administration-guide/partials/snip_scaling-down-keycloak.adoc
@@ -0,0 +1,6 @@
+. Scale down the {identity-provider} deployment:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} scale deployment keycloak --replicas=0 -n {prod-namespace}
+----

From 13fdc85b1f197c0069d2f27ca916f3a08a36cfc6 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Mon, 29 Nov 2021 11:59:54 +0200
Subject: [PATCH 10/18] Fixes

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 ...proc_migration-to-devworkspace-engine.adoc | 107 +++++++++++-------
 .../partials/snip_dumping-che-database.adoc   |   6 +
 .../partials/snip_restoring-che-database.adoc |   7 ++
 3 files changed, 82 insertions(+), 38 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 0c247ae332..2940aba666 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -20,37 +20,21 @@ This procedure describes how to migration to {devworkspace} engine using https:/
 
 include::partial$snip_scaling-down-che.adoc[]
 
-include::partial$snip_finding-postgresql-pod.adoc[]
-
-. Create the migration script
+. Create the script to get all {prod-short} users:
 +
 [source,shell,subs="+attributes"]
 ----
-cat >migration.sh<<EOF
+cat >get-all-{prod-id}-users.sh<<EOF
 #!/bin/bash
 set -e
 
+ALL_USERS={prod-id}-users.txt
 IDENTITY_PROVIDER_URL=\$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath="{.status.keycloakURL}" )
 IDENTITY_PROVIDER_SECRET=\$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderSecret}")
 IDENTITY_PROVIDER_PASSWORD=\$(if [ -z "\$IDENTITY_PROVIDER_SECRET" ] || [ \$IDENTITY_PROVIDER_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster}  -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderPassword}"; else {orch-cli} get secret \$IDENTITY_PROVIDER_SECRET -n {prod-namespace} -o jsonpath="{.data.password}" | base64 -d; fi)
 IDENTITY_PROVIDER_USERNAME=\$(if [ -z "\$IDENTITY_PROVIDER_SECRET" ] || [ \$IDENTITY_PROVIDER_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster}  -n {prod-namespace} -o jsonpath="{.spec.auth.IdentityProviderAdminUserName}"; else {orch-cli} get secret \$IDENTITY_PROVIDER_SECRET -n {prod-namespace} -o jsonpath="{.data.user}" | base64 -d; fi)
 IDENTITY_PROVIDER_REALM=\$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderRealm}")
 
-init() {
-  unset DUMP
-  unset ADD_PROFILES
-  unset MIGRATE_USERS
-
-  while [[ "\$#" -gt 0 ]]; do
-    case \$1 in
-      '--dump') DUMP="\$2"; shift 1;;
-      '--add-profiles'|'-p') ADD_PROFILES=TRUE;;
-      '--migrate-users'|'-i') MIGRATE_USERS=TRUE;;
-    esac
-    shift 1
-  done
-}
-
 refreshToken() {
     IDENTITY_PROVIDER_TOKEN=\$(curl -ks \
     -d "client_id=admin-cli" \
@@ -61,6 +45,7 @@ refreshToken() {
 }
 
 run() {
+  rm -f \${ALL_USERS}
   refreshToken
   USER_IDS=(\$(curl -ks  -H "Authorization: bearer \${IDENTITY_PROVIDER_TOKEN}" "\${IDENTITY_PROVIDER_URL}/\${IDENTITY_PROVIDER_USERNAME}/realms/\${IDENTITY_PROVIDER_REALM}/users" | jq ".[] | .id" | tr "\r\n" " "))
 
@@ -72,46 +57,65 @@ run() {
       IDENTITY_PROVIDER=\$(echo "\${FEDERATED_IDENTITY}" | jq -r ".[] | select(.identityProvider == \"openshift-v4\")")
       if [ -n "\${IDENTITY_PROVIDER}" ]; then
         OPENSHIFT_USER_ID=\$(echo "\${IDENTITY_PROVIDER}" | jq ".userId" | tr -d "\"")
-
-        if [[ \${MIGRATE_USER}} == TRUE ]]; then
-          sed -i "s|\${USER_ID}|\${OPENSHIFT_USER_ID}|g" "\${DUMP}"
-          echo "[INFO] Migrated User ID from \"\${USER_ID}\" to \"\${OPENSHIFT_USER_ID}\""
-        elif [[ \${ADD_PROFILES} == TRUE ]]; then
-          {orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql \${CHE_POSTGRES_DB} -tAc \"insert into profile(userid) values ('\${OPENSHIFT_USER_ID}');\""
-          echo "[INFO] Added profile for User ID \"\${OPENSHIFT_USER_ID}\""
-        fi
+        echo "[INFO] Find {prod-short} user: \${USER_ID} and corresponding OpenShift user: \${OPENSHIFT_USER_ID}"
+        echo "\${USER_ID} \${OPENSHIFT_USER_ID}" >> \${ALL_USERS}
       fi
   done
 }
 
-init
 run
 echo "[INFO] Done."
 EOF
+
+bash get-all-{prod-id}-users.sh
 ----
 
+include::partial$snip_scaling-down-keycloak.adoc[]
+
 include::partial$snip_finding-che-database-name.adoc[]
 
+include::partial$snip_finding-postgresql-pod.adoc[]
+
 include::partial$snip_dumping-che-database.adoc[]
 
 include::partial$snip_droping-che-database.adoc[]
 
 include::partial$snip_creating-che-database.adoc[]
 
-. Migrate Users ID:
+. Migrate {prod-short} users:
 +
 [subs="+quotes,+attributes"]
 ----
-bash migration.sh --migrate-users --dump che.sql
+DUMP="che.sql"
+ALL_USERS={prod-id}-users.txt
+while IFS= read -r line
+do
+  IDS=($line)
+  USER_ID=${IDS[0]}
+  OPENSHIFT_USER_ID=${IDS[1]}
+
+  sed -i -e "s|${USER_ID}|${OPENSHIFT_USER_ID}|g" "${DUMP}"
+
+  echo "[INFO] Migrated User ID from \"${USER_ID}\" to \"${OPENSHIFT_USER_ID}\""
+done < "${ALL_USERS}"
 ----
 
 include::partial$snip_restoring-che-database.adoc[]
 
-. Add Users Profiles:
+. Add empty users profiles:
 +
 [subs="+quotes,+attributes"]
 ----
-bash migration.sh --add-profiles
+ALL_USERS={prod-id}-users.txt
+while IFS= read -r line
+do
+  IDS=($line)
+  OPENSHIFT_USER_ID=${IDS[1]}
+
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"insert into profile(userid) values ('${OPENSHIFT_USER_ID}');\""
+
+  echo "[INFO] Added profile for \"${OPENSHIFT_USER_ID}\""
+done < "${ALL_USERS}"
 ----
 
 . Find Cluster Service Version name:
@@ -121,18 +125,18 @@ bash migration.sh --add-profiles
 CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
 ----
 
-. Delete Subscription from `{prod-channel}` channel:
+. Delete Cluster Service Version:
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} delete subscription {prod-id} -n {prod-namespace}
+{orch-cli} delete csv ${CSV} -n {prod-namespace}
 ----
 
-. Delete Cluster Service Version:
+. Delete Subscription:
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} delete csv ${CSV} -n {prod-namespace}
+{orch-cli} delete subscription {prod-id} -n {prod-namespace}
 ----
 
 . Enable {devworkspace} engine:
@@ -143,7 +147,7 @@ CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.s
 '[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}]'
 ----
 
-. Set single-host exposure strategy:
+. Enable single-host exposure strategy:
 +
 [subs="+quotes,+attributes"]
 ----
@@ -151,7 +155,22 @@ CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.s
 '[{"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "single-host"}]'
 ----
 
-. Create a OLM new subscription to `{prod-tech-preview-channel}` channel:
+. Delete {identity-provider} route:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} delete route keycloak -n {prod-namespace}
+----
+
+. Delete {identity-provider} service:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} delete service keycloak -n {prod-namespace}
+----
+
+
+. Create a new subscription to `{prod-tech-preview-channel}` channel:
 +
 [subs="+quotes,+attributes"]
 ----
@@ -170,4 +189,16 @@ spec:
 EOF
 ----
 
+. Wait until Operator is ready:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={prod-operator} -n openshift-operators --timeout=120s
+----
 
+. Wait until {prod-short} is ready:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={prod-deployment} -n {prod-namespace} --timeout=240s
+----
diff --git a/modules/administration-guide/partials/snip_dumping-che-database.adoc b/modules/administration-guide/partials/snip_dumping-che-database.adoc
index b4f7539ee0..294390c812 100644
--- a/modules/administration-guide/partials/snip_dumping-che-database.adoc
+++ b/modules/administration-guide/partials/snip_dumping-che-database.adoc
@@ -3,5 +3,11 @@
 [subs="+quotes,+attributes"]
 ----
 {orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "pg_dump $CHE_POSTGRES_DB > /tmp/che.sql"
+----
+
+. Copy {prod-short} database to a local file system:
++
+[subs="+quotes,+attributes"]
+----
 {orch-cli} cp {prod-namespace}/$POSTGRES_POD:/tmp/che.sql che.sql
 ----
diff --git a/modules/administration-guide/partials/snip_restoring-che-database.adoc b/modules/administration-guide/partials/snip_restoring-che-database.adoc
index 84a3dc6f32..4a6b95489c 100644
--- a/modules/administration-guide/partials/snip_restoring-che-database.adoc
+++ b/modules/administration-guide/partials/snip_restoring-che-database.adoc
@@ -1,3 +1,10 @@
+. Copy {prod-short} database from a local file system:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} cp che.sql {prod-namespace}/$POSTGRES_POD:/tmp/che.sql
+----
+
 . Restore {prod-short} database:
 +
 [subs="+quotes,+attributes"]

From 99f6d2b5a013f713b14b26fa8dcfd43390b3c9d7 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Mon, 29 Nov 2021 12:16:23 +0200
Subject: [PATCH 11/18] Fix

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 .../partials/proc_migration-to-devworkspace-engine.adoc     | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 2940aba666..a2b3535808 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -169,6 +169,12 @@ CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.s
 {orch-cli} delete service keycloak -n {prod-namespace}
 ----
 
+. Delete {identity-provider} deployment:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} delete deployment keycloak -n {prod-namespace}
+----
 
 . Create a new subscription to `{prod-tech-preview-channel}` channel:
 +

From f95698e166efa1e67c64eed33fea6961d2396117 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Tue, 30 Nov 2021 09:10:54 +0200
Subject: [PATCH 12/18] Fixes

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 .../partials/proc_migration-to-devworkspace-engine.adoc     | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index a2b3535808..69abfb6d14 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -7,14 +7,12 @@ This procedure describes how to migration to {devworkspace} engine using https:/
 .Prerequisites
 
 * The `{orch-cli}` tool is available.
-* An instance of {prod-short} running in OpenShift 4 cluster.
+* An instance of {prod-short} deployed using xref:installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc[Operator Hub] from `{prod-channel}` channel on OpenShift cluster version greater or equal to 4.8
 * OpenShift OAuth is enabled. See xref:configuring-openshift-oauth.adoc[].
 
 .Procedure
 
-. Save and push changes back to the Git repositories for all running workspaces of the {prod-short} instance.
-
-. Stop all workspaces in the {prod-short} instance.
+. All workspaces must be stopped and changes pushed back to Git repositories.
 
 . Backup {prod-short} data. See xref:managing-backups-using-chectl.adoc[].
 

From a4a823a7641aba5ce068cd7be82e15a78accc775 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Thu, 2 Dec 2021 09:24:13 +0200
Subject: [PATCH 13/18] Fixes

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 .../proc_migration-to-devworkspace-engine.adoc     | 14 ++++++--------
 .../partials/snip_verification-che-working.adoc    |  8 ++++++++
 .../partials/snip_waiting-for-component.adoc       |  9 +++++++++
 3 files changed, 23 insertions(+), 8 deletions(-)
 create mode 100644 modules/administration-guide/partials/snip_verification-che-working.adoc
 create mode 100644 modules/administration-guide/partials/snip_waiting-for-component.adoc

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 69abfb6d14..729de26ca5 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -195,14 +195,12 @@ EOF
 
 . Wait until Operator is ready:
 +
-[subs="+quotes,+attributes"]
-----
-{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={prod-operator} -n openshift-operators --timeout=120s
-----
+:k8s-component: {prod-operator}
+include::partial$snip_waiting-for-component.adoc[]
 
 . Wait until {prod-short} is ready:
 +
-[subs="+quotes,+attributes"]
-----
-{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={prod-deployment} -n {prod-namespace} --timeout=240s
-----
+:k8s-component: {prod-deployment}
+include::partial$snip_waiting-for-component.adoc[]
+
+include::partial$snip_verification-che-working.adoc[]
diff --git a/modules/administration-guide/partials/snip_verification-che-working.adoc b/modules/administration-guide/partials/snip_verification-che-working.adoc
new file mode 100644
index 0000000000..6816b44baf
--- /dev/null
+++ b/modules/administration-guide/partials/snip_verification-che-working.adoc
@@ -0,0 +1,8 @@
+. Open Dashboard:
++
+[subs="+quotes,+attributes"]
+----
+{prod-cli} dashboard:open -n {prod-namespace}
+----
+
+. Log in the {prod}.
diff --git a/modules/administration-guide/partials/snip_waiting-for-component.adoc b/modules/administration-guide/partials/snip_waiting-for-component.adoc
new file mode 100644
index 0000000000..ce0f070332
--- /dev/null
+++ b/modules/administration-guide/partials/snip_waiting-for-component.adoc
@@ -0,0 +1,9 @@
+[subs="+quotes,+attributes"]
+----
+while [[ $({orch-cli} get pod -l app.kubernetes.io/component={k8s-component} -n {prod-namespace} -o go-template='{{len .items}}') == 0 ]]
+do
+  echo "Waiting..."
+  sleep 10s
+done
+{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={k8s-component} -n openshift-operators --timeout=120s
+----

From 23f538deefa74ac049bcbe246d73f4d3fcfcf6a2 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Thu, 2 Dec 2021 10:48:26 +0200
Subject: [PATCH 14/18] Fix

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 .../partials/proc_migration-to-devworkspace-engine.adoc       | 3 +++
 .../partials/snip_waiting-for-component.adoc                  | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 729de26ca5..39fd801f97 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -9,6 +9,7 @@ This procedure describes how to migration to {devworkspace} engine using https:/
 * The `{orch-cli}` tool is available.
 * An instance of {prod-short} deployed using xref:installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc[Operator Hub] from `{prod-channel}` channel on OpenShift cluster version greater or equal to 4.8
 * OpenShift OAuth is enabled. See xref:configuring-openshift-oauth.adoc[].
+* Bundled PostgreSQL
 
 .Procedure
 
@@ -196,11 +197,13 @@ EOF
 . Wait until Operator is ready:
 +
 :k8s-component: {prod-operator}
+:k8s-namespace: openshift-operators
 include::partial$snip_waiting-for-component.adoc[]
 
 . Wait until {prod-short} is ready:
 +
 :k8s-component: {prod-deployment}
+:k8s-namespace: {prod-namespace}
 include::partial$snip_waiting-for-component.adoc[]
 
 include::partial$snip_verification-che-working.adoc[]
diff --git a/modules/administration-guide/partials/snip_waiting-for-component.adoc b/modules/administration-guide/partials/snip_waiting-for-component.adoc
index ce0f070332..78a172260a 100644
--- a/modules/administration-guide/partials/snip_waiting-for-component.adoc
+++ b/modules/administration-guide/partials/snip_waiting-for-component.adoc
@@ -1,9 +1,9 @@
 [subs="+quotes,+attributes"]
 ----
-while [[ $({orch-cli} get pod -l app.kubernetes.io/component={k8s-component} -n {prod-namespace} -o go-template='{{len .items}}') == 0 ]]
+while [[ $({orch-cli} get pod -l app.kubernetes.io/component={k8s-component} -n {k8s-namespace} -o go-template='{{len .items}}') == 0 ]]
 do
   echo "Waiting..."
   sleep 10s
 done
-{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={k8s-component} -n openshift-operators --timeout=120s
+{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={k8s-component} -n {k8s-namespace} --timeout=120s
 ----

From 9dea0683a34fbd30729b84775051dff5fab546f5 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Mon, 13 Dec 2021 14:35:49 +0200
Subject: [PATCH 15/18] Set user's email

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 ...proc_migration-to-devworkspace-engine.adoc | 33 ++++++++++++-------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 39fd801f97..551cb1693d 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -27,7 +27,7 @@ cat >get-all-{prod-id}-users.sh<<EOF
 #!/bin/bash
 set -e
 
-ALL_USERS={prod-id}-users.txt
+ALL_USERS_DUMP={prod-id}-users.txt
 IDENTITY_PROVIDER_URL=\$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath="{.status.keycloakURL}" )
 IDENTITY_PROVIDER_SECRET=\$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderSecret}")
 IDENTITY_PROVIDER_PASSWORD=\$(if [ -z "\$IDENTITY_PROVIDER_SECRET" ] || [ \$IDENTITY_PROVIDER_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster}  -n {prod-namespace} -o jsonpath="{.spec.auth.identityProviderPassword}"; else {orch-cli} get secret \$IDENTITY_PROVIDER_SECRET -n {prod-namespace} -o jsonpath="{.data.password}" | base64 -d; fi)
@@ -44,20 +44,27 @@ refreshToken() {
 }
 
 run() {
-  rm -f \${ALL_USERS}
+  rm -f \${ALL_USERS_DUMP}
   refreshToken
-  USER_IDS=(\$(curl -ks  -H "Authorization: bearer \${IDENTITY_PROVIDER_TOKEN}" "\${IDENTITY_PROVIDER_URL}/\${IDENTITY_PROVIDER_USERNAME}/realms/\${IDENTITY_PROVIDER_REALM}/users" | jq ".[] | .id" | tr "\r\n" " "))
+  ALL_USERS=\$(curl -ks  -H "Authorization: bearer \${IDENTITY_PROVIDER_TOKEN}" "\${IDENTITY_PROVIDER_URL}/\${IDENTITY_PROVIDER_USERNAME}/realms/\${IDENTITY_PROVIDER_REALM}/users")
+  ALL_USERS_IDS=(\$(echo "\${ALL_USERS}" | jq ".[] | .id" | tr "\r\n" " "))
 
-  for USER_ID in "\${USER_IDS[@]}"; do
+  for USER_ID in "\${ALL_USERS_IDS[@]}"; do
       refreshToken
 
       USER_ID=\$(echo "\${USER_ID}" | tr -d "\"")
       FEDERATED_IDENTITY=\$(curl -ks -H "Authorization: bearer \${IDENTITY_PROVIDER_TOKEN}" "\${IDENTITY_PROVIDER_URL}/\${IDENTITY_PROVIDER_USERNAME}/realms/\${IDENTITY_PROVIDER_REALM}/users/\${USER_ID}/federated-identity")
       IDENTITY_PROVIDER=\$(echo "\${FEDERATED_IDENTITY}" | jq -r ".[] | select(.identityProvider == \"openshift-v4\")")
       if [ -n "\${IDENTITY_PROVIDER}" ]; then
+        USER_PROFILE=\$(echo "\${ALL_USERS}" | jq -r ".[] | select(.id == \"\${USER_ID}\")")
+        USER_EMAIL=\$(echo "\${USER_PROFILE}" | jq -r ".email")
+        USER_NAME=\$(echo "\${USER_PROFILE}" | jq -r ".username")
+        USER_FIRST_NAME=\$(echo "\${USER_PROFILE}" | jq -r ".firstName")
+        USER_LAST_NAME=\$(echo "\${USER_PROFILE}" | jq -r ".lastName")
+
         OPENSHIFT_USER_ID=\$(echo "\${IDENTITY_PROVIDER}" | jq ".userId" | tr -d "\"")
         echo "[INFO] Find {prod-short} user: \${USER_ID} and corresponding OpenShift user: \${OPENSHIFT_USER_ID}"
-        echo "\${USER_ID} \${OPENSHIFT_USER_ID}" >> \${ALL_USERS}
+        echo "\${USER_ID} \${OPENSHIFT_USER_ID} username:\"\${USER_NAME}\" email:\"\${USER_EMAIL}\" firstName:\"\${USER_FIRST_NAME}\" lastName:\"\${USER_LAST_NAME}\"" >> \${ALL_USERS_DUMP}
       fi
   done
 }
@@ -86,7 +93,7 @@ include::partial$snip_creating-che-database.adoc[]
 [subs="+quotes,+attributes"]
 ----
 DUMP="che.sql"
-ALL_USERS={prod-id}-users.txt
+ALL_USERS_DUMP={prod-id}-users.txt
 while IFS= read -r line
 do
   IDS=($line)
@@ -96,25 +103,29 @@ do
   sed -i -e "s|${USER_ID}|${OPENSHIFT_USER_ID}|g" "${DUMP}"
 
   echo "[INFO] Migrated User ID from \"${USER_ID}\" to \"${OPENSHIFT_USER_ID}\""
-done < "${ALL_USERS}"
+done < "${ALL_USERS_DUMP}"
 ----
 
 include::partial$snip_restoring-che-database.adoc[]
 
-. Add empty users profiles:
+. Migrate users profiles:
 +
 [subs="+quotes,+attributes"]
 ----
-ALL_USERS={prod-id}-users.txt
+ALL_USERS_DUMP={prod-id}-users.txt
 while IFS= read -r line
 do
   IDS=($line)
   OPENSHIFT_USER_ID=${IDS[1]}
+  USER_EMAIL=$(echo ${IDS[3]} | cut -d ":" -f 2)
+  USER_EMAIL=${USER_EMAIL:1:-1}
 
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"insert into profile(userid) values ('${OPENSHIFT_USER_ID}');\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile(userid) VALUES ('${OPENSHIFT_USER_ID}');\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"UPDATE usr SET email = '${USER_EMAIL}' WHERE id='${OPENSHIFT_USER_ID}';\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,value, name) VALUES ('${OPENSHIFT_USER_ID}', 'email', '${USER_EMAIL}');\""
 
   echo "[INFO] Added profile for \"${OPENSHIFT_USER_ID}\""
-done < "${ALL_USERS}"
+done < "${ALL_USERS_DUMP}"
 ----
 
 . Find Cluster Service Version name:

From 6221b9bca8e2d6b5a05e1f2dd6774cb1b070c121 Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Thu, 16 Dec 2021 15:12:38 +0200
Subject: [PATCH 16/18] Drop connection, fill in user profile

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 .../proc_migration-to-devworkspace-engine.adoc   | 16 +++++++++++-----
 ...inate-connections-to-postgresql-database.adoc |  6 ++++++
 2 files changed, 17 insertions(+), 5 deletions(-)
 create mode 100644 modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 551cb1693d..72c31af39c 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -64,7 +64,7 @@ run() {
 
         OPENSHIFT_USER_ID=\$(echo "\${IDENTITY_PROVIDER}" | jq ".userId" | tr -d "\"")
         echo "[INFO] Find {prod-short} user: \${USER_ID} and corresponding OpenShift user: \${OPENSHIFT_USER_ID}"
-        echo "\${USER_ID} \${OPENSHIFT_USER_ID} username:\"\${USER_NAME}\" email:\"\${USER_EMAIL}\" firstName:\"\${USER_FIRST_NAME}\" lastName:\"\${USER_LAST_NAME}\"" >> \${ALL_USERS_DUMP}
+        echo "\${USER_ID} \${OPENSHIFT_USER_ID} username:\$(echo \${USER_NAME} | base64) email:\$(echo \${USER_EMAIL} | base64) firstName:\$(echo \${USER_FIRST_NAME} | base64) lastName:\$(echo \${USER_LAST_NAME} | base64) " >> \${ALL_USERS_DUMP}
       fi
   done
 }
@@ -84,6 +84,8 @@ include::partial$snip_finding-postgresql-pod.adoc[]
 
 include::partial$snip_dumping-che-database.adoc[]
 
+include::partial$snip_terminate-connections-to-postgresql-database.adoc[]
+
 include::partial$snip_droping-che-database.adoc[]
 
 include::partial$snip_creating-che-database.adoc[]
@@ -117,12 +119,16 @@ while IFS= read -r line
 do
   IDS=($line)
   OPENSHIFT_USER_ID=${IDS[1]}
-  USER_EMAIL=$(echo ${IDS[3]} | cut -d ":" -f 2)
-  USER_EMAIL=${USER_EMAIL:1:-1}
+  USER_NAME=$(echo ${IDS[2]} | cut -d ":" -f 2- | base64 -d)
+  USER_EMAIL=$(echo ${IDS[3]} | cut -d ":" -f 2- | base64 -d)
+  USER_FIRST_NAME=$(echo ${IDS[4]} | cut -d ":" -f 2- | base64 -d)
+  USER_LAST_NAME=$(echo ${IDS[5]} | cut -d ":" -f 2- | base64 -d)
 
   {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile(userid) VALUES ('${OPENSHIFT_USER_ID}');\""
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"UPDATE usr SET email = '${USER_EMAIL}' WHERE id='${OPENSHIFT_USER_ID}';\""
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,value, name) VALUES ('${OPENSHIFT_USER_ID}', 'email', '${USER_EMAIL}');\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'preferred_username', '${USER_NAME}');\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'email', '${USER_EMAIL}');\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'firstName', '${USER_FIRST_NAME}');\""
+  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'lastName', '${USER_LAST_NAME}');\""
 
   echo "[INFO] Added profile for \"${OPENSHIFT_USER_ID}\""
 done < "${ALL_USERS_DUMP}"
diff --git a/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc b/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc
new file mode 100644
index 0000000000..768d800b40
--- /dev/null
+++ b/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc
@@ -0,0 +1,6 @@
+. Terminate connections to PostgreSQL database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql -c \"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${CHE_POSTGRES_DB}'\""
+----

From 83cda222d7c84c91508b3685f7385c12582318cc Mon Sep 17 00:00:00 2001
From: Anatolii Bazko <abazko@redhat.com>
Date: Tue, 28 Dec 2021 11:30:52 +0200
Subject: [PATCH 17/18] Fixes

Signed-off-by: Anatolii Bazko <abazko@redhat.com>
---
 antora.yml                                    | 11 ++-
 ...proc_migration-to-devworkspace-engine.adoc | 77 ++++++++++++++-----
 .../partials/snip_creating-che-database.adoc  |  2 +-
 .../partials/snip_droping-che-database.adoc   |  2 +-
 .../partials/snip_dumping-che-database.adoc   |  4 +-
 .../snip_finding-che-database-name.adoc       |  2 +-
 .../partials/snip_restoring-che-database.adoc |  4 +-
 ...te-connections-to-postgresql-database.adoc |  2 +-
 8 files changed, 72 insertions(+), 32 deletions(-)

diff --git a/antora.yml b/antora.yml
index 278ce94a47..9c9a75d345 100644
--- a/antora.yml
+++ b/antora.yml
@@ -108,7 +108,10 @@ asciidoc:
     theia-endpoint-image: eclipse/che-theia-endpoint-runtime:next
     url-devfile-registry-repo: https://github.com/eclipse/che-devfile-registry
     url-plug-in-registry-repo: https://github.com/eclipse/che-plugin-registry
-    prod-channel: stable
-    prod-tech-preview-channel: tech-preview-stable-all-namespaces
-    prod-catalog-source: community-operators
-    prod-tech-preview-olm-package: eclipse-che
+    prod-stable-channel: stable
+    prod-stable-channel-package: eclipse-che
+    prod-stable-channel-catalog-source: community-operators
+    prod-next-channel: next
+    prod-next-channel-package: eclipse-che-preview-openshift
+    prod-next-channel-catalog-source: eclipse-che-openshift-catalog-next
+    prod-next-channel-catalog-source-image: quay.io/eclipse/eclipse-che-openshift-opm-catalog:next
diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index 72c31af39c..c9f95f1638 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -7,7 +7,7 @@ This procedure describes how to migration to {devworkspace} engine using https:/
 .Prerequisites
 
 * The `{orch-cli}` tool is available.
-* An instance of {prod-short} deployed using xref:installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc[Operator Hub] from `{prod-channel}` channel on OpenShift cluster version greater or equal to 4.8
+* An instance of {prod-short} deployed using xref:installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc[Operator Hub] from `{prod-stable-channel}` channel on OpenShift cluster version greater or equal to 4.8
 * OpenShift OAuth is enabled. See xref:configuring-openshift-oauth.adoc[].
 * Bundled PostgreSQL
 
@@ -80,8 +80,6 @@ include::partial$snip_scaling-down-keycloak.adoc[]
 
 include::partial$snip_finding-che-database-name.adoc[]
 
-include::partial$snip_finding-postgresql-pod.adoc[]
-
 include::partial$snip_dumping-che-database.adoc[]
 
 include::partial$snip_terminate-connections-to-postgresql-database.adoc[]
@@ -124,28 +122,21 @@ do
   USER_FIRST_NAME=$(echo ${IDS[4]} | cut -d ":" -f 2- | base64 -d)
   USER_LAST_NAME=$(echo ${IDS[5]} | cut -d ":" -f 2- | base64 -d)
 
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile(userid) VALUES ('${OPENSHIFT_USER_ID}');\""
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'preferred_username', '${USER_NAME}');\""
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'email', '${USER_EMAIL}');\""
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'firstName', '${USER_FIRST_NAME}');\""
-  {orch-cli} exec $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'lastName', '${USER_LAST_NAME}');\""
+  {orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile(userid) VALUES ('${OPENSHIFT_USER_ID}');\""
+  {orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'preferred_username', '${USER_NAME}');\""
+  {orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'email', '${USER_EMAIL}');\""
+  {orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'firstName', '${USER_FIRST_NAME}');\""
+  {orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'lastName', '${USER_LAST_NAME}');\""
 
   echo "[INFO] Added profile for \"${OPENSHIFT_USER_ID}\""
 done < "${ALL_USERS_DUMP}"
 ----
 
-. Find Cluster Service Version name:
-+
-[subs="+quotes,+attributes"]
-----
-CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.status.currentCSV}")
-----
-
 . Delete Cluster Service Version:
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} delete csv ${CSV} -n {prod-namespace}
+{orch-cli} delete csv $({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.status.currentCSV}") -n {prod-namespace}
 ----
 
 . Delete Subscription:
@@ -192,8 +183,33 @@ CSV=$({orch-cli} get subscription {prod-id} -n {prod-namespace} -o jsonpath="{.s
 {orch-cli} delete deployment keycloak -n {prod-namespace}
 ----
 
-. Create a new subscription to `{prod-tech-preview-channel}` channel:
+ifeval::["{project-context}" == "che"]
+. To deploy {prod} from `{prod-next-channel}` channel, create a catalog source:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} apply -f - <<EOF
+apiVersion:  operators.coreos.com/v1alpha1
+kind:         CatalogSource
+metadata:
+  name:         {prod-next-channel-catalog-source}
+  namespace:    openshift-operators
+spec:
+  image:         {prod-next-channel-catalog-source-image}
+  sourceType:  grpc
+  updateStrategy:
+    registryPoll:
+      interval: 5m
+EOF
+----
+endif::[]
+
+. Create a new subscription:
 +
+ifeval::["{project-context}" == "che"]
+To deploy from the `{prod-stable-channel}` channel:
++
+endif::[]
 [subs="+quotes,+attributes"]
 ----
 {orch-cli} apply -f - <<EOF
@@ -203,13 +219,34 @@ metadata:
   name: {prod-id}
   namespace: openshift-operators
 spec:
-  channel: {prod-tech-preview-channel}
+  channel: {prod-stable-channel}
   installPlanApproval: Automatic
-  name: {prod-tech-preview-olm-package}
-  source: {prod-catalog-source}
+  name: {prod-stable-channel-package}
+  source: {prod-stable-channel-catalog-source}
   sourceNamespace: openshift-marketplace
 EOF
 ----
++
+ifeval::["{project-context}" == "che"]
+To deploy from the `{prod-next-channel}` channel:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} apply -f - <<EOF
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: {prod-id}
+  namespace: openshift-operators
+spec:
+  channel: {prod-next-channel}
+  installPlanApproval: Automatic
+  name: {prod-next-channel-package}
+  source: {prod-next-channel-catalog-source}
+  sourceNamespace: openshift-operators
+EOF
+----
+endif::[]
 
 . Wait until Operator is ready:
 +
diff --git a/modules/administration-guide/partials/snip_creating-che-database.adoc b/modules/administration-guide/partials/snip_creating-che-database.adoc
index 907b4fe982..9f62b0eb75 100644
--- a/modules/administration-guide/partials/snip_creating-che-database.adoc
+++ b/modules/administration-guide/partials/snip_creating-che-database.adoc
@@ -2,5 +2,5 @@
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql postgres -tAc \"CREATE DATABASE $CHE_POSTGRES_DB\""
+{orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql postgres -tAc \"CREATE DATABASE $CHE_POSTGRES_DB\""
 ----
diff --git a/modules/administration-guide/partials/snip_droping-che-database.adoc b/modules/administration-guide/partials/snip_droping-che-database.adoc
index 6113072b6b..2ec4483bf7 100644
--- a/modules/administration-guide/partials/snip_droping-che-database.adoc
+++ b/modules/administration-guide/partials/snip_droping-che-database.adoc
@@ -2,5 +2,5 @@
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "dropdb $CHE_POSTGRES_DB"
+{orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "dropdb $CHE_POSTGRES_DB"
 ----
diff --git a/modules/administration-guide/partials/snip_dumping-che-database.adoc b/modules/administration-guide/partials/snip_dumping-che-database.adoc
index 294390c812..9e35a8f70b 100644
--- a/modules/administration-guide/partials/snip_dumping-che-database.adoc
+++ b/modules/administration-guide/partials/snip_dumping-che-database.adoc
@@ -2,12 +2,12 @@
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "pg_dump $CHE_POSTGRES_DB > /tmp/che.sql"
+{orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "pg_dump $CHE_POSTGRES_DB > /tmp/che.sql"
 ----
 
 . Copy {prod-short} database to a local file system:
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} cp {prod-namespace}/$POSTGRES_POD:/tmp/che.sql che.sql
+{orch-cli} cp {prod-namespace}/$({orch-cli} get pods -l app.kubernetes.io/component=postgres -n {prod-namespace} --no-headers=true  -o custom-columns=":metadata.name"):/tmp/che.sql che.sql
 ----
diff --git a/modules/administration-guide/partials/snip_finding-che-database-name.adoc b/modules/administration-guide/partials/snip_finding-che-database-name.adoc
index 34f9e54161..8c57d0cfdd 100644
--- a/modules/administration-guide/partials/snip_finding-che-database-name.adoc
+++ b/modules/administration-guide/partials/snip_finding-che-database-name.adoc
@@ -2,6 +2,6 @@
 +
 [subs="+quotes,+attributes"]
 ----
-CHE_POSTGRES_DB=$({orch-cli} get cm/che -n {prod-namespace} -o json  | jq -r '.data.CHE_JDBC_URL' | awk -F '/' '{print $NF}')
+CHE_POSTGRES_DB=$({orch-cli} get cm/che -n {prod-namespace} -o jsonpath='{.data.CHE_JDBC_URL}' | awk -F '/' '{print $NF}')
 if [ -z "$CHE_POSTGRES_DB" ] || [ $CHE_POSTGRES_DB = "null" ]; then CHE_POSTGRES_DB="dbche"; fi
 ----
diff --git a/modules/administration-guide/partials/snip_restoring-che-database.adoc b/modules/administration-guide/partials/snip_restoring-che-database.adoc
index 4a6b95489c..cce1433eb2 100644
--- a/modules/administration-guide/partials/snip_restoring-che-database.adoc
+++ b/modules/administration-guide/partials/snip_restoring-che-database.adoc
@@ -2,12 +2,12 @@
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} cp che.sql {prod-namespace}/$POSTGRES_POD:/tmp/che.sql
+{orch-cli} cp che.sql {prod-namespace}/$({orch-cli} get pods -l app.kubernetes.io/component=postgres -n {prod-namespace} --no-headers=true  -o custom-columns=":metadata.name"):/tmp/che.sql
 ----
 
 . Restore {prod-short} database:
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql $CHE_POSTGRES_DB < /tmp/che.sql"
+{orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql $CHE_POSTGRES_DB < /tmp/che.sql"
 ----
diff --git a/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc b/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc
index 768d800b40..9df6194516 100644
--- a/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc
+++ b/modules/administration-guide/partials/snip_terminate-connections-to-postgresql-database.adoc
@@ -2,5 +2,5 @@
 +
 [subs="+quotes,+attributes"]
 ----
-{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql -c \"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${CHE_POSTGRES_DB}'\""
+{orch-cli} exec deploy/postgres -n {prod-namespace}  -- bash  -c "psql -c \"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${CHE_POSTGRES_DB}'\""
 ----

From 1082018a398b152e1c847e0bb78516fe6b5cc928 Mon Sep 17 00:00:00 2001
From: Mario Loriedo <mario.loriedo@gmail.com>
Date: Tue, 29 Mar 2022 16:03:07 +0200
Subject: [PATCH 18/18] Update
 modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc

Co-authored-by: swatikarmarkar <102153540+swatikarmarkar@users.noreply.github.com>
---
 .../partials/proc_migration-to-devworkspace-engine.adoc         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
index c9f95f1638..26539fafee 100644
--- a/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
+++ b/modules/administration-guide/partials/proc_migration-to-devworkspace-engine.adoc
@@ -2,7 +2,7 @@
 [id="migration-to-devworkspace-engine_{context}"]
 = Migration to {devworkspace} engine.
 
-This procedure describes how to migration to {devworkspace} engine using https://docs.openshift.com/container-platform/latest/operators/understanding/olm/olm-understanding-olm.html[OLM] to support the Devfile 2.0.0 file format and mentions how to do so on existing instances.
+This procedure describes how to migrate to {devworkspace} engine using https://docs.openshift.com/container-platform/latest/operators/understanding/olm/olm-understanding-olm.html[OLM] to support the Devfile 2.0.0 file format and mentions how to do so on existing instances.
 
 .Prerequisites