Virtru Private Keystore (for Virtru Solutions): Upgrade with KAS

Purpose

Use this runbook to update an existing Virtru Private keystore (VPK) deployment to include the Key Access Service (KAS) configuration. Enable KAS when your organization is moving to Virtru Collaborate and the Data Security Platform.

Prerequisites

Before starting, confirm you have:

• An existing VPK deployment installed with the VPK setup scripts.
• Access to the VPK host.
• Docker installed and running.
• The existing VPK working directory.
• Outbound internet access from the host to validate and pull the target VPK image.
• The target VPK version to deploy.
• A decision on whether the optional KAS configuration should be enabled during this update.

Information to Collect Before Running the Script

Have the following values available before you begin:

Backup Your CKS

Before making any updates, perform a full backup of all directories and files.

Commands:

cd /var/virtru
mkdir backup
cd backup
cp -r /var/virtru/cks .

Step 1: Connect to the Existing VPK Host

SSH to the host that currently runs VPK.

ssh <user>@<cks-host>

Run the remaining commands from that host.

Step 2: Identify the Existing Working Directory

Locate the existing VPK working directory.

Example:

/var/virtru/cks

Do not proceed until the correct working directory is confirmed.

Step 3: Download the Latest Setup Scripts

If the latest setup scripts are not already present on the host, download them.

curl -s https://raw.githubusercontent.com/virtru/cks-setup-script/main/download.sh -o download.sh

Run the download script.

bash ./download.sh

The download creates or refreshes the local cks-setup-scripts directory.

Step 4: Run the Update Script

Start the update script. It will guide you through the values required for the update.

bash ./cks-setup-scripts/update.sh

Step 5: Enter the Target VPK Version

When asked for the version, enter the target VPK version you intend to deploy.

Prompt:

Enter CKS Version:

Example:

<version>

The update process verifies that the matching container image exists at:

containers.virtru.com/cks:v<version>

If the version is invalid or cannot be reached from the host, the update stops with this message:

Invalid CKS Version

Step 6: Enter the Existing VPK Working Directory

When asked for the working directory, enter the existing VPK working directory. The default working directory is /var/virtru/cks.

Prompt:

Enter the CKS Working Directory:

Example:

/var/virtru/cks

If the directory does not exist, the update will stop so the path can be corrected.

Step 7: Respond to JWT Authentication Prompt if Shown

If the existing env/cks.env file does not include JWT_AUTH_ENABLED, you will be asked whether to enable JWT authentication.

Prompt:

Do you want to enable auth via JWTs [yes/no]?

Answer according to your deployment requirements.

If answering yes, enter your Virtru Org ID when asked.

Step 8: Choose Whether to Enable KAS

If the existing deployment does not already have KAS enabled, you will be asked whether to enable KAS.

Prompt:

Do you want to enable KAS [yes/no]?

Answer yes if this existing VPK deployment should be upgraded to include KAS support for DSP.

Answer no to keep the deployment as VPK-only.

If KAS is already configured, you will see this message:

Detected existing KAS configuration.

In that case, you will not be asked to enable KAS again.

Step 9: What Happens When KAS Is Enabled

If KAS is enabled during the update, the update process first creates a timestamped backup of the existing environment file.

Backup file format:

env/cks.env.backup.<YYYYMMDD_HHMMSS>

The update process then adds KAS configuration to env/cks.env.

These standard KAS values are added automatically:

The update process also generates these values automatically:

• KAS_ROOT_KEY
• DSP_DB_PASSWORD

The update process detects the existing key type and adds the matching KAS key settings.

Important: The key file paths shown below are defaults. Existing deployments may use different key filenames, especially if keys have been rotated or if the deployment uses older key naming such as rsa001.pem, rsa002.pem, or rsa003.pem. Before restarting the container, confirm KAS_PUBLIC_KEY_FILE and KAS_PRIVATE_KEY_FILE point to the active key pair in the working directory's keys folder.

For existing ECC keys:

For existing RSA keys:

Your existing VPK keys and SSL files are preserved.

Important: KAS deployments require KEY_ID. This is the key identifier provisioned in Virtru SaaS DSP. Confirm KEY_ID is present and correct in env/cks.env before restarting VPK.

Step 10: Review the Generated Update Summary

After configuration is updated, review the generated summary. It includes:

• Deployment type: CKS with KAS or CKS Only
• Docker image that will be used
• Commands to stop, remove, and start the VPK container

The update process also regenerates the working directory's run.sh file.

Step 11: Review KAS-Sensitive Environment Values

If KAS was enabled or already exists, review the KAS-related values in env/cks.env before restarting the container.

If you use a different working directory, replace /var/virtru/cks with that path.

Confirm:

• ORG_ID is populated with your Virtru Org ID.
• KAS_URI is your public VPK URL, for example https://cks.example.com.
• KAS_PUBLIC_KEY_FILE and KAS_PRIVATE_KEY_FILE point to files that exist in the keys directory.
• KEY_ALGORITHM matches the selected key type, for example rsa:2048 or ec:p256.
• KEY_ID is present and matches the key identifier provisioned in Virtru SaaS DSP.
• PORT is 9000.

Example: if the active key pair is rsa001.pub and rsa001.pem, update the env file before starting the container.

KAS_PUBLIC_KEY_FILE=/app/keys/rsa001.pub
KAS_PRIVATE_KEY_FILE=/app/keys/rsa001.pem

Do not invent a new KEY_ID. If KEY_ID is absent, confirm the correct Virtru SaaS DSP-provisioned key identifier before restarting the VPK.

Step 12: Apply the Updated Container Configuration

Stop the current VPK container.

docker stop Virtru_CKS

Remove the stopped container.

docker rm Virtru_CKS

Start the updated container using the regenerated run script.

bash /var/virtru/cks/run.sh

If you use a different working directory, replace /var/virtru/cks with that path.

The regenerated Docker command starts a container named Virtru_CKS and maps host port 443 to the container's internal Caddy listener on port 9000.

Step 13: Monitor Startup Logs

Follow the container logs.

docker logs -f Virtru_CKS

For a VPK-only deployment, confirm VPK starts successfully.

For a VPK with KAS deployment, confirm the logs show the VPK, KAS, PostgreSQL, and Caddy services starting successfully.

Step 14: Validate the Deployment

Verify the service responds over HTTPS.

curl -k https://<CKS_FQDN>/status

Replace <CKS_FQDN> with your VPK hostname.

Rollback Guidance

If the updated container does not start or you need to revert:

1. Stop and remove the updated container.

   docker stop Virtru_CKS
   docker rm Virtru_CKS

2. Restore the previous env/cks.env from the timestamped backup created during KAS enablement.

   cp /var/virtru/cks/env/cks.env.backup.<YYYYMMDD_HHMMSS> /var/virtru/cks/env/cks.env

3. Recreate run.sh using the previous known-good configuration or rerun the update script with the previous VPK version and KAS selection.

4. Start the container again.

   bash /var/virtru/cks/run.sh

Note: An automatic cks.env backup is created only when KAS is enabled during the update. If you are performing a VPK-only version update, manually back up env/cks.env before starting.

Troubleshooting

The script says Invalid CKS Version

Confirm the version number is correct and that the host can reach the Virtru container registry.

curl -sI https://containers.virtru.com/v2/cks/manifests/v<version>

The working directory is rejected

Confirm the path is the existing VPK working directory and contains env/cks.env.

KAS URI uses localhost

KAS_URI is derived from the first certificate file in the ssl directory. If no certificate is found, it uses https://localhost.

If this happens, update KAS_URI in env/cks.env to your actual VPK FQDN before starting the container.

KAS key files do not match the active key pair

If the deployment has multiple key pairs in the keys directory, confirm which key pair is active before restarting. Update KAS_PUBLIC_KEY_FILE and KAS_PRIVATE_KEY_FILE in env/cks.env if the defaults do not match the active files.

Existing deployments may use older key naming such as rsa001.pem, rsa002.pem, or rsa003.pem. Those names are valid if they are the active key pair and the env file points to them correctly.

Example:

KAS_PUBLIC_KEY_FILE=/app/keys/rsa002.pub
KAS_PRIVATE_KEY_FILE=/app/keys/rsa002.pem

ORG_ID is blank after enabling KAS

ORG_ID is derived from JWT_AUTH_AUDIENCE when KAS is added. Some older env files may not have JWT_AUTH_AUDIENCE.

If ORG_ID is blank, update it with your Virtru Org ID before starting the container.

KEY_ID is missing or incorrect

KAS deployments require KEY_ID. This value must match the key identifier provisioned in Virtru SaaS DSP.

If KEY_ID is missing or does not match the DSP-provisioned key identifier, update env/cks.env before restarting VPK.

KEY_ID=<key-id-provisioned-in-virtru-saas-dsp>

Container name conflict

The generated run.sh starts a container named Virtru_CKS. If a container with that name already exists, stop and remove the old container before running run.sh.

docker stop Virtru_CKS
docker rm Virtru_CKS

KAS does not start

Confirm KAS_ROOT_KEY exists in env/cks.env.

grep KAS_ROOT_KEY /var/virtru/cks/env/cks.env

Review startup logs.

docker logs Virtru_CKS

VPK endpoints fail after update

Confirm the generated run.sh points to the correct working directory and mounts the expected keys and ssl directories.

cat /var/virtru/cks/run.sh
docker logs Virtru_CKS