procedures: Add PostgreSQL migration guides

modules/administration-guide/nav.adoc

@@ -45,8 +45,10 @@
 *** xref:define-backup-server-for-operator.adoc[]
 ** xref:persistent-volumes-backups.adoc[]
 ** xref:external-database-setup.adoc[]
+** xref:migration-to-external-database-setup.adoc[]
 
 * xref:migration-from-postgresql-9-to-postgresql-13.adoc[]
+* xref:migration-from-helm-charts-to-operator.adoc[]
 
 * xref:readiness-init-containers.adoc[]
 ** xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/migration-from-helm-charts-to-operator.adoc

@@ -0,0 +1,6 @@
+[id="migration-from-helm-charts-to-operator"]
+:navtitle: Migration from Helm Charts to Operator
+:keywords: administration-guide, migration, helm-charts, operator, database
+:page-aliases: .:migration-from-helm-charts-to-operator
+
+include::partial$assembly_migration-from-helm-charts-to-operator.adoc[]

modules/administration-guide/pages/migration-from-postgresql-9-to-postgresql-13.adoc

@@ -1,6 +1,6 @@
 [id="migration-from-postgresql-9-to-postgresql-13"]
 :navtitle: Migration from PostgreSQL 9 to PostgreSQL 13
-:keywords: administration-guide, migration
-:page-aliases: .:migration, .:database
+:keywords: administration-guide, migration, database
+:page-aliases: .:migration-database
 
-include::partial$proc_migration_from_postgresql_9_to_postgresql_13.adoc[]
+include::partial$assembly_migration-from-postgresql-9-to-postgresql-13.adoc[]

modules/administration-guide/pages/migration-to-external-database-setup.adoc

@@ -0,0 +1,6 @@
+[id="migration-to-external-database-setup"]
+:navtitle: Migration to external database setup
+:keywords: administration-guide, external-database, migration
+:page-aliases: .:migration-to-external-database-setup
+
+include::partial$assembly_migration-to-external-database-setup.adoc[]

modules/administration-guide/partials/assembly_migration-from-helm-charts-to-operator.adoc

@@ -0,0 +1,29 @@
+
+
+:parent-context-of-migration-from-helm-charts-to-operator: {context}
+
+[id="migration-from-helm-charts-to-operator_{context}"]
+= Migration from Helm Charts to Operator
+
+:context: migration-from-helm-charts-to-operator
+
+Follow the procedures below to migrate from Helm Charts to Operator successfully without any data loss.
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* The `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[].
+* An instance of {prod-short} running in {orch-name}.
+
+include::partial$proc_backuping-postgresql.adoc[leveloffset=+1]
+
+include::partial$proc_reinstalling-che.adoc[leveloffset=+1]
+
+include::partial$proc_cleaning-up-postgresql.adoc[leveloffset=+1]
+
+include::partial$proc_restoring-internal-postgresql.adoc[leveloffset=+1]
+
+include::partial$snip_verification-che-working.adoc[]
+
+:context: {parent-context-of-migration-from-helm-charts-to-operator}
+

modules/administration-guide/partials/assembly_migration-from-postgresql-9-to-postgresql-13.adoc

@@ -0,0 +1,30 @@
+
+
+:parent-context-of-migration-from-postgresql-9-to-postgresql-13: {context}
+
+[id="migration-from-postgresql-9-to-postgresql-13_{context}"]
+= Migration from PostgreSQL 9 to PostgreSQL 13
+
+:context: migration-from-postgresql-9-to-postgresql-13
+
+By the 11th of November, 2021, the PostgreSQL version 9.6 came out of support, and {prod-short} team recommends that all users undergo migrating to version 13.
+
+Follow the procedures below to migrate to a newer version of PostgreSQL successfully without any data loss.
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* An instance of {prod-short} running in {orch-name}.
+
+include::partial$proc_backuping-postgresql.adoc[leveloffset=+1]
+
+include::partial$proc_updating-postgresql-version.adoc[leveloffset=+1]
+
+include::partial$proc_provisioning-postgresql.adoc[leveloffset=+1]
+
+include::partial$proc_restoring-internal-postgresql.adoc[leveloffset=+1]
+
+include::partial$snip_verification-che-working.adoc[]
+
+:context: {parent-context-of-migration-from-postgresql-9-to-postgresql-13}
+

modules/administration-guide/partials/assembly_migration-to-external-database-setup.adoc

@@ -0,0 +1,29 @@
+
+
+:parent-context-of-migration-to-external-database-setup: {context}
+
+[id="migration-to-external-database-setup_{context}"]
+= Migration to external database setup
+
+:context: migration-to-external-database-setup
+
+Follow the procedures below to migrate from internal to external database setup successfully without any data loss.
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* An instance of {prod-short} running in {orch-name}.
+
+include::partial$proc_backuping-postgresql.adoc[leveloffset=+1]
+
+:reuse-database-user: true
+include::partial$proc_configuring-external-PostgreSQL.adoc[leveloffset=+1]
+
+include::partial$proc_switching-che-to-work-with-external-postgresql.adoc[leveloffset=+1]
+
+include::partial$proc_restoring-external-postgresql.adoc[leveloffset=+1]
+
+include::partial$snip_verification-che-working.adoc[]
+
+:context: {parent-context-of-migration-to-external-database-setup}
+

modules/administration-guide/partials/con_external-database-setup.adoc

@@ -34,6 +34,7 @@ The recommended configuration of the example database is:
 |Automated backups | enabled (30 days)
 |===
 
+:reuse-database-user: false
 include::partial$proc_configuring-external-PostgreSQL.adoc[leveloffset=+1]
 
 include::partial$proc_configuring-che-to-work-with-external-PostgreSQL.adoc[leveloffset=+1]

modules/administration-guide/partials/proc_backuping-postgresql.adoc

@@ -0,0 +1,32 @@
+[id="backuping-postgresql{context}"]
+= Backuping PostgreSQL
+
+.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.
++
+include::partial$snip_scaling-down-che.adoc[]
+
+include::partial$snip_scaling-down-keycloak.adoc[]
+
+include::partial$snip_finding-postgresql-pod.adoc[]
+
+include::partial$snip_finding-che-database-name.adoc[]
+
+. Backup {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
+----
+
+. Backup {identity-provider} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "pg_dump keycloak > /tmp/keycloak.sql"
+{orch-cli} cp {prod-namespace}/$POSTGRES_POD:/tmp/keycloak.sql keycloak.sql
+----

modules/administration-guide/partials/proc_cleaning-up-postgresql.adoc

@@ -0,0 +1,41 @@
+[id="cleaning-up-postgresql{context}"]
+= Cleaning up PostgreSQL
+
+.Procedure
+
+include::partial$snip_scaling-down-che.adoc[]
+
+include::partial$snip_scaling-down-keycloak.adoc[]
+
+include::partial$snip_finding-postgresql-pod.adoc[]
+
+include::partial$snip_finding-che-database-name.adoc[]
+
+. Drop {identity-provider} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "dropdb keycloak"
+----
+
+. Create {identity-provider} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "psql postgres -tAc \"CREATE DATABASE keycloak\""
+----
+
+. Drop {prod-short} database:
++
+[subs="+quotes,+attributes"]
+----
+{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace}  -- bash  -c "dropdb $CHE_POSTGRES_DB"
+----
+
+. 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\""
+----
+

modules/administration-guide/partials/proc_configuring-external-PostgreSQL.adoc

@@ -3,7 +3,7 @@
 [id="configuring-external-PostgreSQL_{context}"]
 = Configuring external PostgreSQL
 
-By configuring the external PostgreSQL, you can make the workspace metadata and the user information persistent. 
+By configuring the external PostgreSQL, you can make the workspace metadata and the user information persistent.
 
 .Procedure
 
@@ -12,15 +12,24 @@ By configuring the external PostgreSQL, you can make the workspace metadata and
 --
 * `<database-user>` is the {prod-short} server database user name
 * `<database-password>` is the {prod-short} server database password
-* `<database>` is the {prod-short} server database name 
+* `<database>` is the {prod-short} server database name
 --
+ifeval::["{reuse-database-user}" == "true"]
+WARNING: Database user name should be reused from the existed {prod} deployment. Run the following command on machine with access to the {kubernetes} or OpenShift cluster and use obtained value as placeholder above:
++
+[subs="+quotes,+attributes"]
+----
+include::partial$snip_finding-che-user-name.adoc[]
+echo $CHE_USER_NAME
+----
+endif::[]
 
 . Use the following SQL script to create a user and a database for the {prod-short} server to make workspace metadata persistent:
 +
 [subs="+quotes,+attributes"]
 ----
-CREATE USER <database-user> WITH PASSWORD '<database-password>' 
-CREATE DATABASE <database>                                     
+CREATE USER <database-user> WITH PASSWORD '<database-password>'
+CREATE DATABASE <database>
 GRANT ALL PRIVILEGES ON DATABASE <database> TO <database-user>
 ALTER USER <database-user> WITH SUPERUSER
 ----
@@ -35,7 +44,7 @@ ALTER USER <database-user> WITH SUPERUSER
 +
 [subs="+quotes,+attributes"]
 ----
-CREATE USER keycloak WITH PASSWORD '<identity-database-password>' 
+CREATE USER keycloak WITH PASSWORD '<identity-database-password>'
 CREATE DATABASE keycloak
 GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak
-----
+----