Projquay 2242

manage_quay/master.adoc

@@ -96,6 +96,23 @@ include::modules/mirroring-tag-patterns.adoc[leveloffset=+2]
 include::modules/mirroring-working-with.adoc[leveloffset=+2]
 include::modules/mirroring-recommend.adoc[leveloffset=+2]
 
+[[back-up-and-restore-red-hat-quay]]
+== Back up and recover Red Hat Quay
+Use the content within this section to back up and restore {productname} on an OpenShift Container Platform deployment.
+
+.Prerequisites
+
+* A {productname} deployment on OpenShift Container Platform.
+* An initial user set as `superuser` to prevent user creation.
+* At least two user accounts. This procedure uses `test1` and `test2` as sample user names.
+* A organization within your Quay deployment. This procedure uses `testorg` as its example organization.
+* An image in your repository. This documentation uses the `busybox` image for backing up and restoring.
+
+include::modules/back-up-quay-procedure.adoc[leveloffset=+3]
+// include::modules/restore-quay-ocp-management.adoc[leveloffset=+4]
+// include::modules/restore-quay-non-ocp-management.adoc[leveloffset=+4]
+// include::modules/restore-quay-vm-deployment.adoc[leveloffset=+4]
+
 
 :context: manage_quay
 
@@ -117,5 +134,3 @@ include::modules/con_schema.adoc[leveloffset=+1]
 
 [discrete]
 == Additional resources
-
-

modules/back-up-quay-procedure.adoc

@@ -0,0 +1,171 @@
+== Backing up Red Hat Quay
+
+This procedure is exclusively for OpenShift Container Platform and NooBaa deployments.
+
+.Procedure
+
+[NOTE]
+====
+The procedure in this documents uses the following namespace: `quay-enterprise`.
+====
+
+. Obtain a list of your deployed pods in your Quay namespace:
++
+----
+$ oc get pods -n quay-enterprise
+----
++
+Example output:
++
+----
+NAME                                                   READY   STATUS      RESTARTS   AGE
+example-registry-clair-app-7dccddc6fd-fwckp            1/1     Running     0          69m
+example-registry-clair-postgres-558d7cc9c-xgk2m        1/1     Running     0          68m
+example-registry-quay-app-5677cb59b7-fpxcg             1/1     Running     0          69m
+example-registry-quay-app-upgrade-zstr4                0/1     Completed   0          69m
+example-registry-quay-config-editor-67c769f669-dp5gf   1/1     Running     0          69m
+example-registry-quay-database-6d58c4c545-99s2g        1/1     Running     0          69m
+example-registry-quay-mirror-d4bc9c99c-rmk4f           1/1     Running     0          68m
+example-registry-quay-postgres-init-rwbsq              0/1     Completed   0          69m
+example-registry-quay-redis-577776d494-k48zv           1/1     Running     0          69m
+quay-operator.{productminv}-798d5c8b69-q6x88                  1/1     Running     0          79m
+----
+
+. Obtain the configuration secret of your Quay application deployment:
++
+----
+$ oc get deployment -n quay-enterprise example-registry-quay-app -o json | jq '.spec.template.spec.containers[].env[]'
+----
++
+Example output:
++
+[source,terminal]
+----
+{
+  "name": "QE_K8S_CONFIG_SECRET",
+  "value": "example-registry-quay-config-secret-m25mf4dg78"
+}
+{
+  "name": "QE_K8S_NAMESPACE",
+  "valueFrom": {
+    "fieldRef": {
+      "apiVersion": "v1",
+      "fieldPath": "metadata.namespace"
+    }
+  }
+}
+{
+  "name": "DEBUGLOG",
+  "value": "false"
+}
+{
+  "name": "WORKER_COUNT_WEB",
+  "value": "4"
+}
+{
+  "name": "WORKER_COUNT_SECSCAN",
+  "value": "2"
+}
+{
+  "name": "WORKER_COUNT_REGISTRY",
+  "value": "8"
+}
+----
+
+. Back up the Quay configuration secret in a specified yaml file:
++
+----
+$ oc get secret -n quay-enterprise example-registry-quay-config-secret-m25mf4dg78 -o json | jq '.data."config.yaml"' | cut -d '"' -f2 | base64 -d -w0 > quay-config-yaml-backup.yaml
+----
+
+. Reveal the name of your Quay database from the generated yaml file in Step 3:
++
+----
+$ cat quay-config-yaml-backup.yaml | grep -i DB_URI | cut -d ':' -f3 | sed 's/^..//g'
+----
++
+Example output:
++
+----
+example-registry-quay-database
+----
+
+. Back up your Quay database locally:
++
+----
+$ oc exec -it -n quay-enterprise example-registry-quay-database-5675f6c575-dn7vd -- pg_dump -h localhost -d new-quay-quay-database -O > quay-database-backup.sql
+----
+
+. Ensure that your database has been backed up by running the following command:
++
+----
+$ ls -lah
+----
++
+Example output:
++
+----
+total 248K
+drwxr-xr-x  2 root root   74 Jan 28 15:00 .
+drwx------ 12 root root  298 Jan 28 14:42 ..
+-rw-r--r--  1 root root 1.9K Jan 28 14:56 quay-config-yaml-backup.yaml
+-rw-r--r--  1 root root 243K Jan 28 15:00 quay-database-backup.sql
+----
+
+. Obtain the secret of your Quay configuration from the backup yaml file:
++
+----
+$ cat quay-config-yaml-backup.yaml
+----
++
+Example output:
++
+----
+...
+local_us:
+ - RHOCSStorage
+ - access_key: EX6TtZQ6yCgDn8PqITzO
+   bucket_name: quay-datastore-776165c1-f2a1-43bd-96c5-65c35b458201
+   hostname: s3.openshift-storage.svc.cluster.local
+   is_secure: true
+   port: 443
+   secret_key: Y+Es2psOqsYoHNHRnM541PwgEtNt23qOzQwlppaO
+   storage_path: /datastorage/registry
+...
+----
+
+. Create a directory for your bucket backup:
++
+----
+$ mkdir bucket-backup
+----
+
+. Export the AWS Access Key ID revealed in Step 7:
++
+----
+$ export AWS_ACCESS_KEY_ID=EX6TtZQ6yCgDn8Pxxxxx
+----
+
+. Export the AWS Secret Access Key revealed in Step 7:
++
+----
+$ export AWS_SECRET_ACCESS_KEY=Y+Es2psOqsYoHNHRnM541PwgEtNt23xxxxxxxxxx
+----
+
+. Obtain the s3 route of your Quay namespace:
++
+----
+$ oc get route s3 -n quay-enterprise -o yaml -o jsonpath="{.spec.host}{'\n'}"
+----
++
+Example output:
++
+----
+s3-openshift-storage.apps.ci-ln-3wbqlxt-76ef8.origin-ci-int-aws.dev.rhcloud.com
+----
+
+. Set your AWS s3 storage route as the s3 route of your Quay namespace:
++
+----
+$ aws s3 sync --no-verify-ssl --endpoint-url s3-openshift-storage.apps.ci-ln-3wbqlxt-76ef8.origin-ci-int-aws.dev.rhcloud.com s3://quay-datastore-776165c1-f2a1-43bd-96c5-65c35b458201
+----

modules/proc_deploy_quay_add.adoc

@@ -14,9 +14,9 @@ three or more nodes (for example, quay01, quay02, and quay03).
 ====
 The resulting {productname} service will listen on regular port 8080 and SSL port 8443.
 This is different from previous releases of {productname}, which listened on
-standard ports 80 and 443, respectively. 
+standard ports 80 and 443, respectively.
 In this document, we map 8080 and 8443 to standard ports 80 and 443 on the host, respectively.
-Througout the rest of this document, we assume you have mapped the ports in this way.
+Throughout the rest of this document, we assume you have mapped the ports in this way.
 ====
 
 Here is what you do:
@@ -55,15 +55,13 @@ the startup process.
 [subs="verbatim,attributes"]
 ```
 # sudo podman run --restart=always -p 443:8443 -p 80:8080 \
-   --sysctl net.core.somaxconn=4096 \
-   --privileged=true \
    -v /mnt/quay/config:/conf/stack:Z \
    -v /mnt/quay/storage:/datastorage:Z \
    -d {productrepo}/{quayimage}:{productminv}
 ```
 
 . **Open browser to UI**: Once the `Quay` container has started, go to your web browser and
-open the URL, to the node running the `Quay` container. 
+open the URL, to the node running the `Quay` container.
 
 . **Log into {productname}**: Using the superuser account you created during
 configuration, log in and make sure {productname} is working properly.
@@ -78,7 +76,7 @@ Clair images scanning and Repository Mirroring, continue on to the next section.
 == Add Clair image scanning to {productname}
 
 Setting up and deploying Clair image scanning for your
-{productname} deployment is described in link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/manage_red_hat_quay/index#clair-v4[Clair Security Scanning] 
+{productname} deployment is described in link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/manage_red_hat_quay/index#clair-v4[Clair Security Scanning]
 
 [[add-repo-mirroring]]
 == Add repository mirroring {productname}

modules/proc_manage-upgrade-quay-guide.adoc

@@ -54,8 +54,6 @@ The Quay image will be labeled `quay.io/coreos/registry`.
 
 ```
 # docker run --restart=always -p 443:443 -p 80:80 \
-   --sysctl net.core.somaxconn=4096 \
-   --privileged=true \
    -v /mnt/quay/config:/conf/stack:Z \
    -v /mnt/quay/storage:/datastorage:Z \
    -d quay.io/coreos/registry:RELEASE_VERSION

modules/proc_upgrade_v3.adoc

@@ -1,4 +1,4 @@
-[[upgrade-v3-proc]] 
+[[upgrade-v3-proc]]
 = Choosing upgrade type
 
 Choose between a synchronous upgrade (complete the upgrade in downtime)
@@ -29,7 +29,7 @@ V3_UPGRADE_MODE: complete
 
 . Pull and start up the v3 container on a single node and wait for however long it takes to do the upgrade (it will take a few minutes). Use the following container or later:
 +
-* *Quay*:  quay.io/redhat/quay:v3.0.5 
+* *Quay*:  quay.io/redhat/quay:v3.0.5
 +
 Note that the `Quay` container comes up on ports 8080 and 8443 for {productname} 3, instead
 of 80 and 443, as they did for {productname} 2. Therefore, we recommend remapping 8080
@@ -39,8 +39,6 @@ and 8443 into 80 and 443, respectively, as shown in this example:
 [subs="verbatim,attributes"]
 ```
 # docker run --restart=always -p 80:8080 -p 443:8443 \
-   --sysctl net.core.somaxconn=4096 \
-   --privileged=true \
    -v /mnt/quay/config:/conf/stack:Z \
    -v /mnt/quay/storage:/datastorage:Z \
    -d quay.io/redhat/quay:v3.0.5
@@ -88,8 +86,6 @@ and 8443 into 80 and 443, respectively, as shown in this example:
 [subs="verbatim,attributes"]
 ```
 # docker run --restart=always -p 80:8080 -p 443:8443 \
-   --sysctl net.core.somaxconn=4096 \
-   --privileged=true \
    -v /mnt/quay/config:/conf/stack:Z \
    -v /mnt/quay/storage:/datastorage:Z \
    -d quay.io/redhat/quay:v3.0.5

modules/restore-quay-non-ocp-management.adoc

@@ -0,0 +1,71 @@
+== Restore Quay when the Quay Operator does not manage the database
+
+This procedure is used to restore {productname} when the Quay Operator does not manage the database.
+
+This procedure is tested within the same {productname} minor version, regardless of the z-stream version. There should be no changes in the database schema between z-stream releases.
+
+.Prerequisites
+
+* {productname} is deployed on OpenShift Container Platform using the Quay Operator.
+* To create a PostgreSQL database, you must be a superuser or have the `CREATEDB` privilege.
+
+.Procedure
+
+. Create a new database in the database engine:
++
+----
+$ CREATE DATABASE <name>
+----
++
+For a list of available parameters, see link:https://www.postgresql.org/docs/11/sql-createdatabase.html[Creating a PostgreSQL database].
+
+. Create the `pg_trgm` extension on the newly-created database:
++
+----
+$ CREATE EXTENSION pg_trgm
+----
+
+. Restore the Quay database from backup with psql.
+.. Generate a file with the SQL commands that will recreate the database in the same state as it was at the time of the dump:
++
+----
+$ pg_dump dbname > dumpfile
+----
+
+. Restore the dump.
+.. Files created by `pg_dump` are intended to be read by the psql program. To restore a dump, use the following command:
++
+----
+$ psql dbname < dumpfile <1>
+----
++
+<1> The database `dbname` will not be created by this command. You must create it yourself from `template0` before executing psql. For example, `createdb -T template0 dbname`. Additionally, your dumpfile is the file output by the `pg_dump` command.
+
+.. By default, the `psql` script will continue executing after an SQL error is encountered. Running `psql` with the `ON_ERROR_STOP` variable set has `psql exit` with an exist status of 3 if an SQL error occurs:
++
+----
+$ psql --set ON_ERROR_STOP=on dbname < dumpfile
+----
+
+.. Using `pg_dump` and `psql` to write or read from pipes makes it possible to dump a database from one server to another. For example:
++
+----
+pg_dump -h host1 dbname | psql -h host2 dbname
+----
++
+[IMPORTANT]
+====
+The dumps produced by `pg_dump` are relative to template0. This means that any languages, procedures, etc. added via template1 will also be dumped by `pg_dump`. As a result, when restoring, if you are using a customized template1, you must create the empty database from template0, as in the example above.
+
+After restoring a backup, we suggest running link:https://www.postgresql.org/docs/11/sql-analyze.html[ANALYZE] on each database so that the query optimizer has useful statistics; see link:https://www.postgresql.org/docs/11/routine-vacuuming.html#VACUUM-FOR-STATISTICS[Section 24.1.3] and link:https://www.postgresql.org/docs/11/routine-vacuuming.html#AUTOVACUUM[Section 24.1.6] for more information. For more advice on how to load large amounts of data into PostgreSQL efficiently, see link:https://www.postgresql.org/docs/11/populate.html[section 14.4].
+====
+
+. Create a new blob storage bucket and copy all blobs to the bucket from backup with the appropriate tool, such as s3cmd, awscli, or Azure. The following example uses s3cmd:
++
+----
+$ aws s3 sync s3://DOC-EXAMPLE-BUCKET-SOURCE s3://DOC-EXAMPLE-BUCKET-TARGET
+----
+
+. Edit the custom config bundle and modify the `DB_URI` and `storage` parameters if needed. Create the custom config bundle secret with the same name as before.
+
+. Install the Quay Operator and apply the same QuayRegistry CR as before. It should reference the created custom config bundle. The Operator should reconcile everything, create the necessary secrets, and start Quay.