Skip to content

Upgrade

Appliance

You receive an upgrade package pkifactor-upgrade-vX.Y.Z.tar.gz, its checksum pkifactor-upgrade-vX.Y.Z.tar.gz.sha256 and its signature pkifactor-upgrade-vX.Y.Z.tar.gz.sig. Keep the three files in the same directory. The signature is checked against the ZetaCert public key installed on the appliance (/opt/pkifactor/cosign.pub, put in place by the provisioner), never against a key shipped with the package.

The verification uses the cosign command, which must be installed on the appliance. On an appliance that has no /opt/pkifactor/cosign.pub (installed by an older provisioner), obtain the ZetaCert public key through a trusted channel and install it with sudo install -m 0644 cosign.pub /opt/pkifactor/cosign.pub.

Before you start

Check Command
Current version pkifactor-ctl status
Free disk space (at least 5 GB) df -h /opt/pkifactor /var/lib/docker
A recent backup, copied off the host, with its passphrase (/etc/pkifactor/backup.pass) sudo pkifactor-ctl backup
cosign installed cosign version
Expected interruption a few minutes, while the containers are recreated

Verify, then upgrade

sudo pkifactor-ctl verify /tmp/pkifactor-upgrade-v1.8.49.tar.gz
sudo pkifactor-ctl upgrade /tmp/pkifactor-upgrade-v1.8.49.tar.gz

verify checks the SHA-256 checksum (when the .sha256 file is present) and the cosign signature without touching the installation. upgrade runs the same verification first and refuses a package that is unsigned, or whose checksum or signature is invalid. It also refuses a package older than the installed version, or whose version cannot be read. It then:

  1. hands over to the pkifactor-ctl contained in the package, so that the upgrade logic is always the new version's;
  2. takes a backup of the database and files into /opt/pkifactor/data/backups/. If this backup fails, the command prints a warning and continues: that is why a backup of your own, taken just before, is listed in the checks above;
  3. when the new version uses a newer major version of PostgreSQL, dumps the database while the old server still runs (the original volume is kept for a rollback);
  4. stops the services and loads the new images;
  5. installs the new service definitions (the previous Compose file is kept as docker-compose.yml.bak.<previous version>): the single-node Compose file, or the high-availability Compose file on a node that runs in a cluster, plus the database initialization scripts, the witness scripts and the nginx templates;
  6. adds the configuration variables introduced by the new version to .env, without changing existing values, sets the image version, and generates the secrets that appeared with it (for example EST_PROXY_SECRET, MTLS_PROXY_SECRET); on a high-availability node without its own database superuser password, it sets one first, before any other step (see below);
  7. makes sure every secret file expected by the new version exists in /opt/pkifactor/secrets/ (values carried over from .env on older installations), and installs the new pkifactor-ctl;
  8. restores the database dump of step 3 into the new PostgreSQL server, when there was one;
  9. starts the services (the backend applies the database migrations at start-up), waits for the backend to be healthy, recreates nginx so that it reaches the new containers, checks the database schema, and ends with pkifactor-ctl status.

If the database schema cannot be migrated, the command says so explicitly and stops: the previous data is kept, /health/ready answers 503 until the cause is fixed, and the command prints the restore command for the backup of step 2.

Roll back

sudo pkifactor-ctl restore /opt/pkifactor/data/backups/pkifactor_backup_<date>.tar.gz.gpg

then reinstall the previous package with sudo env PKIFACTOR_ALLOW_DOWNGRADE=1 pkifactor-ctl upgrade <previous package> (an older version is refused otherwise), or ask ZetaCert support. The backup contains the database, the data keys, the secrets, the TLS certificate, the license and the configuration.

High availability

Upgrade one node at a time, replicas first and the database leader last (pkifactor-ctl ha-status shows the leader). The load balancer keeps serving through the other nodes; the leader switches when its node restarts. See High availability.

On a cluster created before 1.8.30 that never ran pkifactor-ctl ha-db-passwords, run it before upgrading to 1.8.47 or later (Database administration passwords on older clusters). If you did not, upgrade the leader first: the upgrade sets the superuser password there and writes /opt/pkifactor/ha-db-passwords.json; copy that file to the same path on each other node before upgrading it. An upgrade started on a replica without that file stops before changing anything.

Several versions at once

Upgrade directly to the latest version: migrations are cumulative. Read the Release notes of the intermediate versions for behaviour changes.

Kubernetes and OpenShift

Load the new images, then upgrade the release:

helm upgrade pkifactor ./chart -n pkifactor --reuse-values --set image.tag=v1.8.49

See Kubernetes and OpenShift.

After any upgrade

  • pkifactor-ctl status (or oc get pods): every service healthy;
  • sign in and open System > License in the Administration workspace to check the license status and the database schema state;
  • in the Oversight workspace, Fleet monitoring > Monitoring shows the background jobs running.