Upgrade Security Compliance Management in an air-gapped environment

When your Bolt runner does not have internet access, you must build a new offline bundle on an internet-connected machine, transfer it to the air-gapped machine, and restore your site-specific configuration before running the upgrade plan.

Before you begin:

You need a machine with internet access to build the bundle.
Ensure that the required runtime environment (Docker or Podman) is installed on the SCM host. The upgrade plan cannot install a runtime without internet access.
Ensure you are running Bolt 3.27.2 or later on the air-gapped Bolt runner.

Rename your current Bolt project directory to preserve it as a backup:
Copy
```
mv comply-bolt-project comply-bolt-project-backup
```
This directory contains your encrypted secrets, certificates, and target configuration. You will restore these from the backup in a later step.
The next series of steps require you to build the offline bundle in the comply-bolt-project directory. If this directory is no longer available, recreate it now using:
Copy
```
mkdir comply-bolt-project
cd comply-bolt-project
bolt project init comply_bolt_project
```
On a machine with internet access, switch to the comply-bolt-project directory that was initially created for generating the offline bundle:
Copy
```
cd comply-bolt-project
```

Edit the bolt-project.yaml file to specify the new version of the module and your Forge API token. Change the modules and module-install sections to:

Copy

--- 
name: comply_bolt_project
modules:
- name: puppetlabs/complyadm
  version_requirement: 3.y.z

module-install:
  forge:
     authorization_token: 'Bearer <your API token>'
     baseurl: https://forgeapi.puppet.com

Install the complyadm module using the command: bolt module install.
Create an air-gapped bundle using:
Copy
```
bolt plan run complyadm::install::create_offline_bundle
```
This creates a bundle called project.zip that contains all the images and dependencies needed to install Security Compliance Management.
Next, on the air-gapped Bolt runner, install and configure Security Compliance Management.
Copy the air-gapped bundle, project.zip, from the internet-connected machine to the air-gapped Bolt runner, then extract it into the comply-bolt-project directory:
Copy
```
cp project.zip comply-bolt-project/
unzip project.zip
```
Restore your site-specific configuration from the backup by copying across your keys, data, and inventory:
Copy
```
cp -r ../comply-bolt-project-backup/keys/ keys/
cp -r ../comply-bolt-project-backup/data/ data/
cp -r ../comply-bolt-project-backup/ssh/ ssh/
cp ../comply-bolt-project-backup/hiera.yaml hiera.yaml
cp ../comply-bolt-project-backup/inventory.yaml inventory.yaml
```
These items are unique to your installation. keys/ holds the PKCS7 keypair used to decrypt your secrets, data/ contains your encrypted configuration (hostnames, credentials, certificates), hiera.yaml wires the keys to the data directory, and inventory.yaml defines your SCM target. Without them, the upgrade plan cannot connect to or configure your installation.
Run the upgrade plan:
```
bolt plan run complyadm::upgrade
```
The plan prompts you to make a backup. Respond to this prompt with y to make a backup. Because the offline bundle pre-stages the images in downloads/comply/images/, the plan uses the local cache automatically. You see output confirming each image is served from the local bundle:
```
Archive '...comply-assessor_4.60.0.tar.gz' for role 'ui' exists in local cache, not updating.
Archive '...comply-assessor_4.60.0.tar.gz' for 'ui' role does not exist on 'scm', uploading.
[...]
Plan completed successfully with no result
```

Optional parameters

You can pass the following parameters to skip interactive prompts or modify upgrade behavior:

Parameter	Type	Default	Description
`ignore_failing_preflights`	Boolean	`false`	When `true`, the plan continues even if preflight checks (OS, memory, CPU, required packages) do not pass.
`upload_images`	Boolean	`true`	Must remain `true` for air-gapped upgrades. Setting this to `false` would cause the SCM host to attempt to pull images directly from the registry, which fails without internet access.

Examples

Skip preflight checks on an air-gapped:

Copy

bolt plan run complyadm::upgrade ignore_failing_preflights=true

What the plan does

The upgrade plan performs the following steps in order:

Verifies your Bolt version is supported.
Optionally runs complyadm::backup to back up the database and volumes.
Runs preflight checks (architecture, runtime, memory, OS, CPU, required packages).
Skips container runtime installation. In an air-gapped environment the runtime must already be present on the SCM host.
Uploads container images from the local bundle (downloads/comply/images/) to the target. Images already present on the target are skipped.
Detects whether a major PostgreSQL version bump has occurred. If so, it automatically stops services, backs up the database, removes the old volume, applies the new version, and restores the backup.
Applies updated configuration to all roles (database, backend, UI).
Waits for services to become healthy.
Runs cleanup tasks.

Results
Security Compliance Management is upgraded to the new version using the locally bundled images. No internet access is required during the upgrade itself.

You can verify the upgrade by navigating to your Security Compliance Management web console, or by running:

bolt plan run complyadm::validate