Running Playbooks — Upgrades

This guide covers how to upgrade an existing Diskover deployment to a new version using Ansible — the upgrade procedure, targeting specific hosts, adding SSL to an existing deployment, renewing certificates, rolling back, and understanding what gets backed up.

Deploying Diskover for the first time? See the Running Playbooks — Fresh Install guide instead.

Before You Upgrade

Pre-Upgrade Checklist

Before upgrading, make sure the following are in order:

• Confirm your current Diskover version (check Diskover Admin or run diskoverd --version on a worker host)
• Review the release notes for the new version — check for breaking changes, new dependencies, or migration steps
• Ensure all running scans have completed or are paused
• Verify you have the correct JFrog credentials (or updated offline tarballs) for the new version
• Confirm SSH access from your control machine to all target hosts still works
• Schedule a maintenance window if your environment requires it

What Gets Backed Up

Individual Ansible roles back up their own configuration files before making changes. Backups are stored on each target host at:

/root/diskover-backups-YYYYMMDD/

This includes configuration files for Diskover components (Nginx configs, service files, etc.). The Diskover Admin SQLite database (which stores your Elasticsearch connections, RabbitMQ settings, license, and other Admin configuration) is not overwritten by the upgrade as long as config_diskover_admin_api is set to false.

Upgrade Procedure

Upgrading Diskover is a three-step process: update the version variable, set the Admin API flag, and re-run the playbook.

Step 1: Update diskover_version in all.yml

Change the version to the new release:

diskover_version: 2.5.1  # Change to the new version

This must match a version available in JFrog Artifactory (or in your offline tarballs if using air-gapped installation).

Step 2: Set config_diskover_admin_api to false

This is the most critical step. Setting this to false prevents the playbook from overwriting your existing Diskover Admin configuration.

config_diskover_admin_api: false

If you forget this step and leave it as true, the playbook will reset the following settings in the Diskover Admin database to match the current Ansible variables — discarding any manual changes you've made through the Admin UI:

• Web.Elasticsearch — host IP(s), port, HTTPS, username, password, certificate settings

• Diskover.Elasticsearch — scanner/ingest Elasticsearch connection settings

• System.Message Queue — RabbitMQ host, username, password

• System.API — Admin API host, port, HTTPS

Step 3: Run the Playbook

time ansible-playbook -i inventory/hosts.yml install_diskover.yml

For AWS/cloud deployments with PEM key:

time ansible-playbook -i inventory/hosts.yml install_diskover.yml --private-key /path/to/your-key.pem

Step 4: Verify the Upgrade

1. Check the PLAY RECAP for failed=0 on all hosts:

PLAY RECAP *********************************************************************
10.0.1.10   : ok=71   changed=31   unreachable=0    failed=0    skipped=5    rescued=0    ignored=0
10.0.1.20   : ok=35   changed=18   unreachable=0    failed=0    skipped=5    rescued=0    ignored=0

2. Verify the version — the new version is displayed on the Diskover UI login page. Navigate there and confirm it shows the expected version number.

3. Restart Diskoverd and Celery on each worker host:

systemctl restart diskoverd
systemctl restart celery

Verify both services are running:

systemctl status diskoverd
systemctl status celery

4. Confirm workers are online in the Diskover Web UI under Task Panel > Workers.

What the Playbook Does During an Upgrade

The playbook runs the same roles as a fresh install, but the behavior is different because packages already exist on the target hosts. Infrastructure packages that are already installed are detected and skipped — the playbook only upgrades Diskover-specific components.

What gets upgraded:

1. Backs up configuration — Individual roles save their configuration files to /root/diskover-backups-YYYYMMDD/ before making changes

2. Updates Diskover packages — Installs the new version of each Diskover component (diskover-web, diskover-admin, diskoverd, scanners, plugins, file actions, etc.)

3. Preserves Admin configuration — Because config_diskover_admin_api: false, the Diskover Admin database is not touched

4. Updates dependencies — Python pip packages and other dependencies are updated to match the new version's requirements

5. Restarts services — Services that were changed are restarted with the new version

What gets skipped:

The following infrastructure packages are already installed from your initial deployment and will not be reinstalled or modified during an upgrade:

• Elasticsearch — The existing Elasticsearch cluster is left as-is. Data and configuration are not touched. If you are using AWS OpenSearch, the Elasticsearch role is skipped entirely since your search backend is managed by AWS.

• Kibana — Already installed and configured on the web host. If you are using AWS OpenSearch, Kibana is also skipped since OpenSearch Dashboards is managed by AWS.

• RabbitMQ — The message broker is left running with its existing configuration and queues.

• Nginx — The web server configuration is preserved (including any SSL settings).

• PHP 8.4 — The PHP runtime is already in place from the initial install.

This means the upgrade is focused entirely on Diskover application components — your underlying infrastructure remains stable and unchanged.

Targeting Specific Hosts with --limit

Just like with fresh installs, you can use --limit to upgrade specific components independently. This is useful for staged rollouts, when you only need to upgrade part of the stack, or when expanding your deployment.

Common --limit Scenarios for Upgrades

# Example: upgrade web and worker hosts only
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit web,worker

Important: When using --limit, only the plays targeting the specified host groups run. Make sure the components you're skipping are already at a compatible version — check the release notes for any cross-component version requirements.

Proxy Support for Upgrades

If your environment uses an HTTP proxy, the upgrade process is the same — just make sure your install_diskover.yml is still the proxy-aware version. If you set up proxy support during your initial install (by copying docs/example_docs/install_diskover.proxy.yml over install_diskover.yml), this is already in place and you can run the playbook normally:

time ansible-playbook -i inventory/hosts.yml install_diskover.yml

If you're unsure whether your install_diskover.yml is the proxy-aware version, you can re-copy it:

cp docs/example_docs/install_diskover.proxy.yml install_diskover.yml

Make sure your proxy_env settings in inventory/hosts.yml are still correct. See the Running Playbooks — Fresh Install guide for full proxy configuration details.

SSL/TLS Changes on an Existing Deployment

Adding SSL to a Deployment That Doesn't Have It

If Diskover was originally deployed without SSL and you now want to enable HTTPS:

1. Set the SSL variables in all.yml:

   ssl_enabled: true
   ssl_domain: "diskover.example.com"
   ssl_cert_source: "/root/certs/diskover.crt"
   ssl_key_source: "/root/certs/diskover.key"
   ssl_force_reconfigure: true

2. Make sure config_diskover_admin_api is set to false to preserve your existing Admin configuration:

   config_diskover_admin_api: false

3. Run the playbook (you can limit to the web host since that's where Nginx and SSL are configured):

   time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit web

4. After verifying SSL is working, set ssl_force_reconfigure back to false in all.yml for future runs.

Renewing or Replacing SSL Certificates

When your SSL certificate expires or you need to replace it:

1. Place the new certificate and key files on the control machine

2. Update ssl_cert_source and ssl_key_source in all.yml if the file paths changed

3. Set ssl_force_reconfigure: true to force the SSL role to redeploy:

   ssl_force_reconfigure: true

4. Run the playbook against the web host:

   time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit web

5. Set ssl_force_reconfigure back to false after verifying the new certificate is active

Verifying SSL After Changes

1. Navigate to https://<ssl_domain> in your browser

2. Verify the padlock icon appears and the certificate details show the new expiration date

3. Confirm that http://<web-host-ip> redirects to HTTPS

Rolling Back an Upgrade

If something goes wrong after an upgrade, you can roll back to the previous version.

Rollback Procedure

1. Change diskover_version back to the previous version in all.yml:

   diskover_version: 2.5.0  # Previous version

2. Keep config_diskover_admin_api: false — you don't want to touch Admin configuration during a rollback either:

   config_diskover_admin_api: false

3. Re-run the playbook:

   time ansible-playbook -i inventory/hosts.yml install_diskover.yml

The playbook will install the previous version's packages. Your Admin configuration (stored in the SQLite database) is preserved across version changes — it is not affected by the package version.

Restoring Configuration Files

If you need to restore specific configuration files that were changed during the upgrade, the backups are available on each target host at:

/root/diskover-backups-YYYYMMDD/

Check the contents of the backup directory to find the files you need:

ls -la /root/diskover-backups-YYYYMMDD/

Upgrading Offline / Air-Gapped Deployments

For environments without internet access, the upgrade process has an additional step — staging the new version's offline tarballs.

1. Obtain new artifacts from Diskover Data for the target version and OS

2. Stage the new tarballs on the control machine at offline_rpms_location (replacing the previous version's tarballs)

3. Update all.yml:

   diskover_version: 2.5.1
   config_diskover_admin_api: false
   offline_install: true

4. Run the playbook:

   time ansible-playbook -i inventory/hosts.yml install_diskover.yml

For the complete offline deployment process, see the Offline / Air-Gapped Installation guide.

Next Steps

• When things go wrong during an upgrade, consult the Troubleshooting guide. If the issue persists, reach out to the Diskover support team at https://support.diskoverdata.com

• For a fresh deployment on new hosts, see the Running Playbooks — Fresh Install guide