Fixes final few release notes issues (#1136) (#1138)

Co-authored-by: Steven Smith <[email protected]>
quay · Oct 28, 2024 · bbbd178 · bbbd178
1 parent 83fb535
commit bbbd178
Show file tree

Hide file tree

Showing 9 changed files with 227 additions and 7 deletions.
diff --git a/clair/master.adoc b/clair/master.adoc
@@ -31,6 +31,7 @@ include::modules/fips-overview.adoc[leveloffset=+2]
 This guide contains procedures for running Clair on {productname} in both standalone and {ocp} Operator deployments.
 
 include::modules/clair-standalone-configure.adoc[leveloffset=+1]
+include::modules/clair-postgresql-database-update.adoc[leveloffset=+2]
 include::modules/clair-standalone-upgrade.adoc[leveloffset=+2]
 
 include::modules/clair-openshift.adoc[leveloffset=+1]

diff --git a/modules/about-clair.adoc b/modules/about-clair.adoc
@@ -30,6 +30,16 @@ New versions of Clair are regularly released. The source code needed to build Cl
 
 Release artifacts also include the `clairctl` command line interface tool, which obtains updater data from the internet by using an open host.
 
+[discrete]
+[id="clair-releases-474"]
+=== Clair 4.8
+
+Clair 4.8 was released on 24-10-28. The following changes have been made:
+
+* Clair on {productname} now requires that you update the Clair PostgreSQL database from version 13 to version 15. For more information about this procedure, see link:https://docs.redhat.com/en/documentation/red_hat_quay/3.12/html-single/vulnerability_reporting_with_clair_on_red_hat_quay/index#upgrading-clair-postgresql-database[Upgrading the Clair PostgreSQL database].
+
+* This release deprecates the updaters that rely on the Red Hat OVAL v2 security data in favor of the Red Hat VEX data. This change includes a database migration to delete all the vulnerabilities that originated from the OVAL v2 feeds. Because of this, there could be intermittent downtime in production environments before the VEX updater complete for the first time when no vulnerabilities exist.
+
 [discrete]
 [id="clair-releases-474"]
 === Clair 4.7.4

diff --git a/modules/attributes.adoc b/modules/attributes.adoc
@@ -41,6 +41,6 @@ ifeval::["{productname}" == "Red Hat Quay"]
 :clairproductminv: 4.8
 :builderimage: quay-builder-rhel8
 :builderqemuimage: quay-builder-qemu-rhcos
-:postgresimage: registry.redhat.io/rhel8/postgresql-13:1-109
+:postgresimage: registry.redhat.io/rhel8/postgresql-13
 :redisimage: registry.redhat.io/rhel8/redis-6:1-110
 endif::[]
diff --git a/modules/clair-postgresql-database-update.adoc b/modules/clair-postgresql-database-update.adoc
@@ -0,0 +1,99 @@
+[id="upgrading-clair-postgresql-database"]
+= Upgrading the Clair PostgreSQL database
+
+If you are upgrading {productname} to version 13, you must migrate your Clair PostgreSQL database version from PostgreSQL version 13 -> version 15. This requires bringing down your Clair PostgreSQL 13 database and running a migration script to initiate the process.
+
+Use the following procedure to upgrade your Clair PostgreSQL database from version 13 -> to version 15.
+
+[IMPORTANT]
+====
+Clair security scans might become temporarily disrupted after the migration procedure has succeeded.
+====
+
+.Procedure 
+
+. Stop the {productname} container by entering the following command:
++
+[source,terminal]
+----
+$ sudo podman stop <quay_container_name>
+----
+
+. Stop the Clair container by running the following command:
++
+[source,terminal]
+----
+$ sudo podman stop <clair_container_id>
+----
+
+. Run the following Podman process from SCLOrg's link:https://github.com/sclorg/postgresql-container/tree/master/13#data-migration[Data Migration] procedure, which allows for data migration from a remote PostgreSQL server:
++
+[source,terminal]
+----
+$ sudo podman run -d --name <clair_migration_postgresql_database> <1>
+  -e POSTGRESQL_MIGRATION_REMOTE_HOST=<container_ip_address> \ <2>
+  -e POSTGRESQL_MIGRATION_ADMIN_PASSWORD=remoteAdminP@ssword \
+  -v </host/data/directory:/var/lib/pgsql/data:Z> \ <3>
+  [ OPTIONAL_CONFIGURATION_VARIABLES ]
+  registry.redhat.io/rhel8/postgresql-15
+----
++
+<1> Insert a name for your Clair PostgreSQL 15 migration database.
+<2> Your new Clair PostgreSQL 15 database container IP address. Can obtained by running the following command: `sudo podman inspect -f "{{.NetworkSettings.IPAddress}}" postgresql-quay`. 
+<3> You must specify a different volume mount point than the one from your initial Clair PostgreSQL 13 deployment, and modify the access control lists for said directory. For example:
++
+[source,terminal]
+----
+$ mkdir -p /host/data/clair-postgresql15-directory
+----
++
+[source,terminal]
+----
+$ setfacl -m u:26:-wx /host/data/clair-postgresql15-directory
+----
++
+This prevents data from being overwritten by the new container.
+
+. Stop the Clair PostgreSQL 13 container:
++
+[source,terminal]
+----
+$ sudo podman stop <clair_postgresql13_container_name>
+----
+
+. After completing the PostgreSQL migration, run the Clair PostgreSQL 15 container, using the new data volume mount from Step 3, for example, `</host/data/clair-postgresql15-directory:/var/lib/postgresql/data>`:
++
+[source,terminal]
+----
+$ sudo podman run -d --rm --name <postgresql15-clairv4> \
+  -e POSTGRESQL_USER=<clair_username> \
+  -e POSTGRESQL_PASSWORD=<clair_password> \
+  -e POSTGRESQL_DATABASE=<clair_database_name> \
+  -e POSTGRESQL_ADMIN_PASSWORD=<admin_password> \
+  -p 5433:5432 \
+  -v </host/data/clair-postgresql15-directory:/var/lib/postgresql/data:Z> \
+    registry.redhat.io/rhel8/postgresql-15
+----
+
+. Start the {productname} container by entering the following command:
++
+[source,terminal]
+----
+$ sudo podman run -d --rm -p 80:8080 -p 443:8443 --name=quay \
+-v /home/<quay_user>/quay-poc/config:/conf/stack:Z \
+-v /home/<quay_user>/quay-poc/storage:/datastorage:Z \
+{productrepo}/{quayimage}:{productminv}
+----
+
+. Start the Clair container by entering the following command:
++
+[source,terminal]
+----
+$ sudo podman run -d --name clairv4 \
+-p 8081:8081 -p 8088:8088 \
+-e CLAIR_CONF=/clair/config.yaml \
+-e CLAIR_MODE=combo \
+registry.redhat.io/quay/clair-rhel8:{productminv}
+----
+
+For more information, see link:https://github.com/sclorg/postgresql-container/tree/master/13#data-migration[Data Migration].
diff --git a/modules/clair-standalone-configure.adoc b/modules/clair-standalone-configure.adoc
@@ -35,7 +35,7 @@ $ sudo podman run -d --name postgresql-clairv4 \
   -e POSTGRESQL_ADMIN_PASSWORD=adminpass \
   -p 5433:5432 \
   -v /home/<user-name>/quay-poc/postgres-clairv4:/var/lib/pgsql/data:Z \
-  registry.redhat.io/rhel8/postgresql-13:1-109
+  registry.redhat.io/rhel8/postgresql-15
 ----
 
 . Install the PostgreSQL `uuid-ossp` module for your Clair deployment:

diff --git a/modules/operator-upgrade.adoc b/modules/operator-upgrade.adoc
@@ -60,7 +60,7 @@ To update {productname} from one minor version to the next, for example, 3.12.z
 
 . After the `clair-postgres-upgrade`, `quay-postgres-upgrade`, and `quay-app-upgrade` pods are marked as *Completed*, the remaining pods for your {productname} deployment spin up. This takes approximately ten minutes. 
 
-. Verify that the `quay-database` and `clair-postgres` pods now use the `postgresql-13` image. 
+. Verify that the `quay-database` uses the `postgresql-13` image, and `clair-postgres` pods now uses the `postgresql-15` image. 
 
 . After the `quay-app` pod is marked as *Running*, you can reach your {productname} registry. 
 

diff --git a/modules/proc_upgrade_standalone.adoc b/modules/proc_upgrade_standalone.adoc
@@ -2,13 +2,13 @@
 [id="standalone-upgrade"]
 = Standalone upgrade
 
-In general, {productname} supports upgrades from a prior (N-1) minor version only.  For example, upgrading directly from {productname} 3.8 to the latest version of {producty} is not supported. Instead, users would have to upgrade as follows:
+In general, {productname} supports upgrades from a prior (N-1) minor version only. For example, upgrading directly from {productname} 3.8 to the latest version of {producty} is not supported. Instead, users would have to upgrade as follows:
 
 . 3.8.z -> 3.9.z
 . 3.9.z -> 3.10.z
 . 3.10.z -> 3.11.z
 . 3.11.z -> 3.12.z
-. 3.12.z -> 3.13
+. 3.12.z -> 3.13.z
 
 This is required to ensure that any necessary database migrations are done correctly and in the right order during the upgrade.
 
@@ -28,7 +28,6 @@ This document describes the steps needed to perform each individual upgrade. Det
 * link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/upgrade_red_hat_quay/index#upgrade_to_3_13_z_from_3_10_z[Upgrade to 3.13.z from 3.10.z]
 
 ////
-
 //3.12
 * link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/upgrade_red_hat_quay/index#upgrade_to_3_12_z_from_3_11_z[Upgrade to 3.12.z from 3.11.z]
 * link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/upgrade_red_hat_quay/index#upgrade_to_3_12_z_from_3_10_z[Upgrade to 3.12.z from 3.10.z]
@@ -74,11 +73,112 @@ The general procedure for a manual upgrade consists of the following steps:
 . Start Clair using the new version of the image.
 . Wait until Clair is ready to accept connections before starting the new version of Quay.
 
+[id="accessing-images"]
 == Accessing images
 
 {productname} image from version 3.4.0 and later are available from link:https://registry.redhat.io[registry.redhat.io] and
 link:https://registry.access.redhat.com[registry.access.redhat.com], with authentication set up as described in link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication].
 
+[id="upgrading-clair-postgresql-database"]
+== Upgrading the Clair PostgreSQL database
+
+If you are upgrading {productname} to version 13, you must migrate your Clair PostgreSQL database version from PostgreSQL version 13 -> version 15. This requires bringing down your Clair PostgreSQL 13 database and running a migration script to initiate the process.
+
+Use the following procedure to upgrade your Clair PostgreSQL database from version 13 -> to version 15. 
+
+[IMPORTANT]
+====
+Clair security scans might become temporarily disrupted after the migration procedure has succeeded.
+====
+
+.Procedure 
+
+. Stop the {productname} container by entering the following command:
++
+[source,terminal]
+----
+$ sudo podman stop <quay_container_name>
+----
+
+. Stop the Clair container by running the following command:
++
+[source,terminal]
+----
+$ sudo podman stop <clair_container_id>
+----
+
+. Run the following Podman process from SCLOrg's link:https://github.com/sclorg/postgresql-container/tree/master/13#data-migration[Data Migration] procedure, which allows for data migration from a remote PostgreSQL server:
++
+[source,terminal]
+----
+$ sudo podman run -d --name <clair_migration_postgresql_database> <1>
+  -e POSTGRESQL_MIGRATION_REMOTE_HOST=<container_ip_address> \ <2>
+  -e POSTGRESQL_MIGRATION_ADMIN_PASSWORD=remoteAdminP@ssword \
+  -v </host/data/directory:/var/lib/pgsql/data:Z> \ <3>
+  [ OPTIONAL_CONFIGURATION_VARIABLES ]
+  registry.redhat.io/rhel8/postgresql-15
+----
++
+<1> Insert a name for your Clair PostgreSQL 15 migration database.
+<2> Your new Clair PostgreSQL 15 database container IP address. Can obtained by running the following command: `sudo podman inspect -f "{{.NetworkSettings.IPAddress}}" postgresql-quay`. 
+<3> You must specify a different volume mount point than the one from your initial Clair PostgreSQL 13 deployment, and modify the access control lists for said directory. For example:
++
+[source,terminal]
+----
+$ mkdir -p /host/data/clair-postgresql15-directory
+----
++
+[source,terminal]
+----
+$ setfacl -m u:26:-wx /host/data/clair-postgresql15-directory
+----
++
+This prevents data from being overwritten by the new container.
+
+. Stop the Clair PostgreSQL 13 container:
++
+[source,terminal]
+----
+$ sudo podman stop <clair_postgresql13_container_name>
+----
+
+. After completing the PostgreSQL migration, run the Clair PostgreSQL 15 container, using the new data volume mount from Step 3, for example, `</host/data/clair-postgresql15-directory:/var/lib/postgresql/data>`:
++
+[source,terminal]
+----
+$ sudo podman run -d --rm --name <postgresql15-clairv4> \
+  -e POSTGRESQL_USER=<clair_username> \
+  -e POSTGRESQL_PASSWORD=<clair_password> \
+ 	-e POSTGRESQL_DATABASE=<clair_database_name> \
+  -e POSTGRESQL_ADMIN_PASSWORD=<admin_password> \
+  -p 5433:5432 \
+  -v </host/data/clair-postgresql15-directory:/var/lib/postgresql/data:Z> \
+    registry.redhat.io/rhel8/postgresql-15
+----
+
+. Start the {productname} container by entering the following command:
++
+[source,terminal]
+----
+$ sudo podman run -d --rm -p 80:8080 -p 443:8443 --name=quay \
+-v /home/<quay_user>/quay-poc/config:/conf/stack:Z \
+-v /home/<quay_user>/quay-poc/storage:/datastorage:Z \
+{productrepo}/{quayimage}:{productminv}
+----
+
+. Start the Clair container by entering the following command:
++
+[source,terminal]
+----
+$ sudo podman run -d --name clairv4 \
+-p 8081:8081 -p 8088:8088 \
+-e CLAIR_CONF=/clair/config.yaml \
+-e CLAIR_MODE=combo \
+registry.redhat.io/quay/clair-rhel8:{productminv}
+----
+
+For more information, see link:https://github.com/sclorg/postgresql-container/tree/master/13#data-migration[Data Migration].
+
 == Upgrade to 3.13.z from 3.12.z
 
 === Target images
@@ -91,6 +191,7 @@ ifdef::upstream[]
 endif::upstream[]
 * **PostgreSQL:** {postgresimage}
 * **Redis:** {redisimage}
+* **Clair-PosgreSQL:** registry.redhat.io/rhel8/postgresql-15
 
 == Upgrade to 3.13.z from 3.11.z
 
@@ -104,6 +205,7 @@ ifdef::upstream[]
 endif::upstream[]
 * **PostgreSQL:** {postgresimage}
 * **Redis:** {redisimage}
+* **Clair-PosgreSQL:** registry.redhat.io/rhel8/postgresql-15
 
 == Upgrade to 3.13.z from 3.10.z
 
@@ -117,6 +219,7 @@ ifdef::upstream[]
 endif::upstream[]
 * **PostgreSQL:** {postgresimage}
 * **Redis:** {redisimage}
+* **Clair-PosgreSQL:** registry.redhat.io/rhel8/postgresql-15
 
 ////
 == Upgrade to 3.12.z from 3.11.z

diff --git a/modules/rn_3_13_0.adoc b/modules/rn_3_13_0.adoc
@@ -146,6 +146,13 @@ _optional_|Determine whether pruned tags should or should not match the tagPatte
 
 For example API commands, see link:https://docs.redhat.com/en/documentation/red_hat_quay/3.12/html-single/manage_red_hat_quay/index#red-hat-quay-namespace-auto-pruning-overview[{productname} auto-pruning overview].
 
+[id="notable-technical-changes-313]
+== {productname} 3.13 notable technical changes
+
+Clair now requires its PostgreSQL database to be version 15. For standalone {productname} deployments, administrators must manually migrate their database over from PostgreSQL version 13 to version 15. For more information about this procedure, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/upgrade_red_hat_quay/index#upgrading-clair-postgresql-database[Upgrading the Clair PostgreSQL database].
+
+For {productname-ocp} deployments, this update is automatically handled by the Operator so long as your Clair PostgreSQL database is currently using version 13.
+
 [id="known-issues-and-limitations-313"]
 == {productname} 3.13 known issues and limitations
 

diff --git a/modules/upgrading-postgresql.adoc b/modules/upgrading-postgresql.adoc
@@ -77,7 +77,7 @@ spec:
 
 . After the `clair-postgres-upgrade`, `quay-postgres-upgrade`, and `quay-app-upgrade` pods are marked as *Completed*, the remaining pods for your {productname} deployment spin up. This takes approximately ten minutes. 
 
-. Verify that the `quay-database` and `clair-postgres` pods now use the `postgresql-13` image. 
+. Verify that the `quay-database` uses the `postgresql-13` image and `clair-postgres` pods now use the `postgresql-15` image. 
 
 . After the `quay-app` pod is marked as *Running*, you can reach your {productname} registry.