Migrate existing CM installation to Podman (Quadlet)

This article is new for Certificate Manager 8.11.0-1.

This article describes how to migrate an existing Smart ID Certificate Manager (CM) installation to Podman using Quadlet.

Prerequisites

Certificate Manager (CM) is installed with version CM > 8.10.x.
- Earlier CM versions are not supported for migration and must be updated the regular way before a migration can be performed.
Podman version 4.9.4 or later is installed.
A valid CM license file

Recommendations

Configuration files and libraries/addons (such as HSM) can be added as volumes to the containers.
Removing volumes can lead to losing data and configurations. Therefor, we recommend keeping updated backup of the configuration.
It is not recommended to run the database on the same machine of cf-server container, due to network issues.

Step-by-step instructions

Deployment directory setup

When deploying using quadlets the name of the directory in which the distributable deployment files are located will be dictated by the user running the container. It will map to the following directory:
$HOME/.config/containers/systemd/.

Load Podman images

The Podman images for CM are located in the images directory within the distributable package.

Load the images using the following commands:
podman image load -i images/cf-server-image-<version>.tar
podman image load -i images/pgw-image-<version>.tar

Perquisition for CF and PGW deployments

Copy all the files and folders (*.container, volumes and network) under directory certificate-manager-<Release_version>/deployment/podman-quadlets to $HOME/.config/containers/systemd, assuming that the current user is the operator for the container deployment.
1. Copy the license file into: $HOME/.config/containers/systemd/license
If outgoing connectivity from the containers is required, edit the cmnet.network unit file and make sure the parameter Internal=no is set. Additional security hardening may be needed to restrict undesired outgoing connectivity from the container network with firewall rules or by other means.

CF in Podman container

Uninstall existing CF server

Stop the services and make a backup of the following directories in <server_home> to be utilized later as volumes content for cf-server container:
<server-home>/bin
<server-home>/certs
<server-home>/config
Back up logs files.
Uninstall the current CF server. See Uninstall Certificate Manager server components and clients for more information.

Migrate CF server configuration

Follow the commands with standard user (no sudo privilege).
systemctl --user daemon-reload
Start the following cf-server volumes:
systemctl --user start cf-server-bin-volume
systemctl --user start cf-server-certs-volume
systemctl --user start cf-server-config-volume
Start and stop the cf-service:
systemctl --user start cf-server
Verify starting the service has logged Applying runtime configuration:
systemctl --user stop cf-server
Copy the content of the backed up folders you performed in section “Uninstall existing CF server“ to the volumes respectively (this assumes that your current installation is running CF with internal cis):
cp <server-home-backup>/certs/* $HOME/.local/share/containers/storage/volumes/systemd-cf-server-certs/_data
cp -r <server-home-backup>/config/* $HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data

Make sure to override the contents of: systemd-cf-server-certs/_data and systemd-cf-server-config/_data

Verify the database connection details under config volume:
$HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data/cm.conf
Database.name = jdbc:<db>://<DB_host_name>:<port>/<cmdb-name>
If there are custom ports configured in server.xml then exposed them in PGW container.

ensure the ports are defined in pgw.container "/home/azureuser/.config/containers/systemd/pgw.container"

Connecting to services running on the Podman host

There might be situations where a connection from a container to the Podman host machine is needed. As Podman uses the slirp4netns driver by default for rootless containers, there is no directly available routing configured to reach the Podman localhost/127.0.0.1 address. To achieve this, a special IP address 10.0.2.2 can be configured in the CM configuration files to reach the Podman machine localhost. Enable this by adding the following configuration to the container-files:

Location	Configuration
In the [Container] section	`Network=slirp4netns:allow_host_loopback=true`

Enlarge the table by opening it in a full screen dialogOpen.

Change the logging to podman console, edit cm.conf:
$HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data/cm.conf
for example, under Loggers configurations change to:
cm.agent.log.1.type = stdout
Verify configuration for cis.hostport in cm.conf.
- If CIS is configured internally within the CF service, then set cis.hostport=cf-internal

Configure HSM with cf-server container

Copy the HSM driver and config files to $HOME/.local/share/containers/storage/volumes/systemd-cf-server-bin/_data
example Utimaco files (not limited to): libcs_pkcs11_R3.so cs_pkcs11_R3.cfg
Provide the required environment variables via $HOME.config/containers/systemd/cf-server.container
example of Utimaco driver configuration: Environment="CS_PKCS11_R3_CFG=/opt/cm/server/bin/cs_pkcs11_R3.cfg"

Verify the connectivity details in the HSM driver configuration file.

Start CF server container

Start the CF server container using the following command:
systemctl --user start cf-server
Make sure the cf-server is started and that it is logging:
systemctl --user start cf-server; podman logs -f cf-server

PGW in Podman container

Uninstall existing PGW

Make a backup of the following directories in <pgw_home>to be utilized later as volumes content for pgw container:
1. Tomcat configuration which contains the TLS and server.xml: <tomcat_home>/conf
2. PGW configuration which contains the conf and certdir: <pgw_home)/conf
Uninstall Tomcat instance and remove Protocol Gateway (PGW) folders and files.

Migrate PGW configuration

Start the following pgw volumes:
systemctl --user start pgw-config-tomcat-volume
systemctl --user start pgw-config-gw-volume
Start and stop the pgw container
systemctl --user start pgw
verify that PGW service started successfully
systemctl --user stop pgw
Copy the content of the backed-up folders you performed in section “Uninstall existing PGW“.

Exclude all logging.properties while copying the required files into the volumes. Copy CA, *.p12 and config files.
Override the contents of systemd-pgw-config-tomcat/_data and systemd-pgw-config-gw/_data:

cp <tomcat-installation>/conf/<file> $HOME/.local/share/containers/storage/volumes/systemd-pgw-config-tomcat/_data
cp -r <cm-gateway>/conf/<file_dir> $HOME/.local/share/containers/storage/volumes/systemd-pgw-config-gw/_data

Verify that the connectivity details towards the cf-server container is correct:
$HOME/.local/share/containers/storage/volumes/systemd-pgw-config-gw/_data/cm-gateway.properties
cmhost=<cf-server-host>, example cmhost=cf-server

Start PGW container

Start the PGW container using the following command:
systemctl --user start pgw
Make sure PGW is running:
systemctl --user status pgw; podman logs pgw

Configure HSM with PGW container

Configuring the HSM with PGW can be performed similar to the approach outlined in “Configure HSM with cf-server container” above.