Chapter 2. Upgrade Trusted Profile Analyzer to version 3

Procedure

1. In the RHTPA dashboard, click Importers. In the list of importers, disable all importers.

2. On your workstation, open a terminal, and log in to OpenShift:

   $ oc login --token=sha256~example --server=https://example.com:6443

   Note

   You can find your login token and URL information from the OpenShift web console to use on the command line. To find your login token and URL:

   • Log in to the OpenShift web console.
   • Click your user name, and click Copy login command.
   • Enter your user name and password again, and click Display Token to view the command.

3. Switch to the project/namespace where RHTPA is installed:

   $ oc project trusted-profile-analyzer

   Replace trusted-profile-analyzer with the namespace in which you installed RHTPA.

4. Get the current RHTPA 2.2.5 image name:

   $ oc get deploy -n trusted-profile-analyzer -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.template.spec.containers[0].image}{"\n"}{end}'

   Make note of the current RHTPA 2.2.5 image name and version number for use later on.

5. Save the existing Helm deployment values:

   export helm_release=redhat-trusted-profile-analyzer
   helm get values "${helm_release}" | grep -v 'USER-SUPPLIED VALUES' > original-values.yaml

6. Create the rhtpa-read-only.yaml file with the following content:

   readOnly: true
   modules:
     migrateDatabase:
       enabled: false
     server:
       image:
         fullName: <TPA_IMAGE>
     importer:
       image:
         fullName: <TPA_IMAGE>
     createDatabase:
       enabled: false
     createImporters:
       enabled: false

   Replace <TPA_IMAGE> with the full current RHTPA 2.2.5 image name. These settings freeze the image, preventing the helm upgrade command from updating the services to the new version before the migration is complete. They also disable re-creating the database and importers during the migration.

7. Run the following command to apply the changes:

   helm upgrade "${helm_release}" openshift-helm-charts/redhat-trusted-profile-analyzer -f original-values.yaml -f rhtpa-read-only.yaml

8. Check that RHTPA is in read-only mode and rejecting requests.

   1. Verify that RHTPA is in read-only mode:

      $ oc exec -n trusted-profile-analyzer deploy/<release-name>-server -- \
        curl -s http://localhost:8080/.well-known/trustify | jq '.readOnly'

      This command must return a value of true. RHTPA is now in read-only mode.

   2. Verify that RHTPA is rejecting requests:

      $ oc exec -n trusted-profile-analyzer deploy/<release-name>-server -- \
        curl -s -o /dev/null -w '%{http_code}' -X POST http://localhost:8080/api/v2/advisory

      This command must return a 503 code, signifying that incoming requests will be rejected.

9. Create a clone of the RHTPA PostgreSQL database. This new cloned database is the target for the data migration. Depending on your infrastructure, you can use the tools for your cloud provider to create a replica or else use the pg_dump and pg_restore commands.

   Important

   The cloned database must have the same username, password, and database name as the original database. If the credentials differ, update the postgresql-credentials and postgresql-admin-credentials secrets with the new values before proceeding.

10. Create the rhtpa-migratedb.yaml file with the following content:

    modules:
      migrateDatabase:
        enabled: true
    migrateDatabase:
      host: <new-db-endpoint>

    Replace <new-db-endpoint> with the endpoint URL of your new database clone.

    With these settings, the migration proceeds on the new database clone, while the RHTPA services continue operating in read-only mode using the original database.

11. Run the following command to start the database migration process.

    helm upgrade --wait --timeout 24h0m0s "${helm_release}" openshift-helm-charts/redhat-trusted-profile-analyzer -f original-values.yaml -f rhtpa-read-only.yaml -f rhtpa-migratedb.yaml

    Warning

    The database migration process can take a significant time.

12. After the migration process completes, create the rhtpa-swapdb.yaml file with the following content:

    readOnly: true
    database:
      host: <new-db-endpoint>

    Replace <new-db-endpoint> with the endpoint URL of your new database clone, which is migrated by now.

13. Run the following command to upgrade the services and use the new database endpoint.

    helm upgrade --wait --timeout 24h0m0s "${helm_release}" openshift-helm-charts/redhat-trusted-profile-analyzer -f original-values.yaml -f rhtpa-swapdb.yaml

    This command does not include the image-freeze settings from rhtpa-read-only.yaml, so Helm upgrades the services to the new version. The readOnly: true setting in rhtpa-swapdb.yaml keeps the services in read-only mode until you verify that the upgrade is working correctly.

14. Verify that the upgraded RHTPA services are working correctly with the migrated database:

    $ oc exec -n trusted-profile-analyzer deploy/<release-name>-server -- \
      curl -s http://localhost:8080/api/v3/sbom?limit=1 | jq '. | has("items")'

    This command queries the upgraded v3 API and confirms that the server can read from the migrated database.

15. After verifying that the upgraded services are working, switch RHTPA to read/write mode:

    helm upgrade --wait --timeout 24h0m0s "${helm_release}" openshift-helm-charts/redhat-trusted-profile-analyzer -f original-values.yaml -f rhtpa-swapdb.yaml --set readOnly=false

16. Connect to the new RHTPA PostgreSQL database with the psql utility and then run the following optimizations:

    $ psql -c "VACUUM ANALYZE;"
    $ psql -c "REINDEX DATABASE CONCURRENTLY \"$PGDATABASE\";"

17. In the RHTPA dashboard, click Importers. In the list of importers, enable the importers that you use.

Procedure

1. In the RHTPA dashboard, click Importers. In the list of importers, disable all importers.

2. Open the RHTPA Operator CR and make the following change:

   readOnly: true

3. Check that RHTPA is in read-only mode and rejecting requests.

   1. Verify that RHTPA is in read-only mode:

      $ oc exec -n trusted-profile-analyzer deploy/<release-name>-server -- \
        curl -s http://localhost:8080/.well-known/trustify | jq '.readOnly'

      This command must return a value of true. RHTPA is now in read-only mode.

   2. Verify that RHTPA is rejecting requests:

      $ oc exec -n trusted-profile-analyzer deploy/<release-name>-server -- \
        curl -s -o /dev/null -w '%{http_code}' -X POST http://localhost:8080/api/v2/advisory

      This command must return a 503 code, signifying that incoming requests will be rejected.

4. Save the current Operator CR as a backup:

   $ oc get trustedprofileanalyzer <release-name> -n trusted-profile-analyzer -o yaml > original-cr.yaml

   Replace <release-name> with the name of your RHTPA deployment.

5. Create a clone of the RHTPA PostgreSQL database. This new cloned database is the target for the data migration. Depending on your infrastructure, you can use the tools for your cloud provider to create a replica or else use the pg_dump and pg_restore commands. The new clone must be outside the RHTPA Operator deployment so that it does not get removed when you remove the Operator deployment.

   Important

   The cloned database must have the same username, password, and database name as the original database. If the credentials differ, update the postgresql-credentials and postgresql-admin-credentials secrets with the new values before proceeding.

6. Remove the RHTPA 2.2.5 Operator deployment.

7. Start deploying the RHTPA 3.0 Operator and select the stable-v3 channel, which provides RHTPA 3.0. Before deploying the Operator, make the following changes to the CR:

   modules:
     migrateDatabase:
       enabled: true
   migrateDatabase:
     host: <new-db-endpoint>
   readOnly: true
   database:
     host: <new-db-endpoint>

   Replace <new-db-endpoint> with the endpoint URL of your new database clone. These settings run the services in read-only mode while the migration completes.

8. After the migration process completes, edit the RHTPA Operator CR and make the following change:

   readOnly: false

9. Connect to the new RHTPA PostgreSQL database with the psql utility and then run the following optimizations:

   $ psql -c "VACUUM ANALYZE;"
   $ psql -c "REINDEX DATABASE CONCURRENTLY \"$PGDATABASE\";"

10. In the RHTPA dashboard, click Importers. In the list of importers, enable the importers that you use.

11. Verify that the upgraded RHTPA services are working correctly with the migrated database:

    $ oc exec -n trusted-profile-analyzer deploy/<release-name>-server -- \
      curl -s http://localhost:8080/api/v3/sbom?limit=1 | jq '. | has("items")'