eclipse-che · AndrienkoAleksandr · Nov 9, 2021 · Nov 9, 2021 · Nov 9, 2021 · Nov 22, 2021
diff --git a/antora.yml b/antora.yml
@@ -106,3 +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
+    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
@@ -33,7 +33,7 @@
 ** xref:external-database-setup.adoc[]
 
 * xref:migration-from-postgresql-9-to-postgresql-13.adoc[]
-
+* xref:migration-to-devworkspace-engine.adoc[]
 * xref:readiness-init-containers.adoc[]
 ** xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]
 *** xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[]

diff --git a/modules/administration-guide/pages/migration-to-devworkspace-engine.adoc 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
@@ -0,0 +1,209 @@
+
+[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} 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
+
+. All workspaces must be stopped and changes pushed back to Git repositories.
+
+. Backup {prod-short} data. See xref:managing-backups-using-chectl.adoc[].
+
+include::partial$snip_scaling-down-che.adoc[]
+
+. Create the script to get all {prod-short} users:
++
+[source,shell,subs="+attributes"]
+----
+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}")
+
+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() {
+  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" " "))
+
+  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 "\"")
+        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
+}
+
+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 {prod-short} users:
++
+[subs="+quotes,+attributes"]
+----
+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 empty users profiles:
++
+[subs="+quotes,+attributes"]
+----
+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:
++
+[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}
+----
+
+. Delete Subscription:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} delete subscription {prod-id} -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}]'
+----
+
+. Enable 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"}]'
+----
+
+. 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}
+----
+
+. 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:
++
+[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
+----
+
+. 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_creating-che-database.adoc 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
@@ -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
@@ -0,0 +1,13 @@
+. 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"
+----
+
+. 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_finding-che-database-name.adoc 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
@@ -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
@@ -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
@@ -0,0 +1,13 @@
+. 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"]
+----
+{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
@@ -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
@@ -0,0 +1,6 @@
+. Scale down the {identity-provider} deployment:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} scale deployment keycloak --replicas=0 -n {prod-namespace}
+----
diff --git a/modules/administration-guide/partials/snip_verification-che-working.adoc 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
@@ -0,0 +1,9 @@
+[subs="+quotes,+attributes"]
+----
+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 {k8s-namespace} --timeout=120s
+----