Migrating from nodeletd to k3s-Based Clusters

Overview

This guide describes the recommended procedure for migrating an existing 2026.1 nodeletd-based Self-hosted Private Cloud Director deployment to a k3s-based cluster ( release 2026.4). The migration uses a backup-and-restore approach and is the supported upgrade path for on-premises customers in this release.

The high-level flow is:

Install the new release artifacts
Back up the existing (2026.1) deployment
Unconfigure and delete the existing cluster
Reconfigure and create a new k3s cluster
Restore the backup

Note: This process involves deliberate cluster destruction and recreation. Plan for a maintenance window before proceeding.

Prerequisites

Before starting the migration, confirm the following:

You have access to the airctl management host.
You have reviewed and noted all values from your current /opt/pf9/airctl/conf/airctl-config.yaml file and your existing nodelet bootstrap configuration ( /opt/pf9/airctl/conf/nodelet-bootstrap-config.yaml ) . You will need these values when reconfiguring the deployment.
You have confirmed that a valid restore target exists (an accessible backup location or S3-compatible store).
The new release artifacts and packages have been installed on the management host exactly as you would during a standard upgrade. Refer to the Upgrade Guide for package installation steps.
You have read and understood the Important Considerations section below.

Important Considerations

⚠️ This migration involves irreversible steps. Specifically, airctl unconfigure-du and airctl delete-cluster are destructive and cannot be undone. Ensure your backup is complete and verified before proceeding past Step 3.

Management Plane Downtime is expected. This migration requires the cluster to be fully destroyed before the new k3s cluster is created. Plan for a maintenance window sized to your environment's restore time. In most environments, expect several hours of downtime.
There is no in-place rollback. Once the cluster is deleted, rollback requires restoring from the backup taken in this procedure. Ensure the backup completes successfully and is accessible from the restore target before continuing.
Configuration values must be preserved. During reconfiguration, you will re-run airctl configure using the same or equivalent inputs as the original installation. Derive these values from:
- Your current airctl-config file
- Your existing nodelet bootstrap configuration
Preserve your options.json file. The options.json file, located at /opt/pf9/airctl/conf/options.json, controls deployment-specific settings such as storage class configuration, audit settings, and other platform options. This file is generally carried over by a new installation, but it is good practice to verify its contents before triggering the restore. If it is missing or outdated, recreate or update it to reflect your intended configuration before running the restore command.
Verify the backup before proceeding. A corrupted or incomplete backup will prevent successful restore. Confirm the backup artifact is intact and readable before deleting the existing cluster.

Migration Procedure

Step 1 — Install New Release Artifacts

Install the new packages as you would for a standard upgrade. Do not restart or reconfigure the deployment at this stage.

Refer to the Upgrade Guide for the full package installation procedure.

Step 2 — Back Up the Existing Deployment

Take a full backup of the existing deployment before making any configuration changes.

/opt/pf9/airctl/airctl backup --outdir /tmp/backup-mgmt/ --verbose

⚠️ Do not proceed until the backup completes successfully. Verify that the backup artifact exists at the expected destination and that it is not empty or corrupt. Keep note of the backup path or identifier — you will need it in Step 7.

Step 3 — Unconfigure the Existing Deployment

Uninstall the current deployment. This step stops services and clears the active configuration state.

/opt/pf9/airctl/airctl unconfigure-du

Step 4 — Delete the Existing Cluster

Delete the existing nodeletd cluster. This step is irreversible.

/opt/pf9/airctl/airctl delete-cluster

Step 5 — Reconfigure the Deployment

Re-run airctl configure using the same inputs that were used during the original installation.

For a full description of the airctl configure parameters and prompts, refer to the Installation Guide. Use the values from your saved airctl-config and nodelet bootstrap configuration as reference. Have both files open in a separate terminal session before proceeding.

Note: The configuration inputs required here are identical to those used during initial installation. Do not use default or example values — use the values specific to your environment.

Proxy configuration: If your environment requires a proxy, configure it after airctl configure completes. Refer to the Proxy Configuration section of the Installation Guide for instructions.

Custom certificates: If your original deployment used custom SSL/TLS certificates, you must supply them again during reconfiguration. Pass the certificate and key paths as arguments to airctl configure:

/opt/pf9/airctl/airctl configure \
  --user-cert-path /path/to/service.crt \
  --user-key-path /path/to/service.key

Alternatively, export them as environment variables before running the command:

export USER_CERT_PATH="/path/to/service.crt"
export USER_KEY_PATH="/path/to/service.key"

After airctl configure completes, verify that user_cert_path and user_key_path are present in /opt/pf9/airctl/conf/airctl-config.yaml. For full details, see Using Custom Certificates.

Step 6 — Validate Post-Configure State

After airctl configure completes, verify that the environment is correctly initialized before creating the cluster.

Verify the updated /opt/pf9/airctl/conf/airctl-config.yaml file.

Confirm that the configuration reflects the values you provided and that there are no unexpected changes.

Verify the k3s bootstrap configuration:

Confirm that the k3s bootstrap configuration has been created at the expected path: /opt/pf9/airctl/conf/k3s-bootstrap-config.yaml

Step 7 — Create the New k3s Cluster

Create the new k3s-based cluster.

/opt/pf9/airctl/airctl create-cluster --verbose

Wait for the cluster creation to complete. Monitor the output for errors. Do not interrupt this process.

Step 8 — Restore the Backup

Once the new cluster is running, restore your data from the backup taken in Step 2.

RabbitMQ clustering: The restore process enables RabbitMQ clustering by default. If you wish to disable it, update /opt/pf9/airctl/conf/options.json before proceeding with the restore by setting:

"rabbitmq_clustering_enabled": "false"

Refer to the Backup and Restore Guide for detailed restore instructions.

Quick reference — restore command:

/opt/pf9/airctl/airctl restore --backupdir <backup-path> --verbose

Replace <backup-path> with the path or identifier recorded in Step 2.

Note: The restore process may take significant time depending on the size of your deployment. Do not interrupt it once started.

Validation Steps

After the restore completes, verify that the migration was successful:

Confirm cluster health — Check that all cluster nodes report as healthy:

kubectl get nodes

Confirm management plane availability — Log in to the Private Cloud Director UI and confirm that the dashboard loads and all services are visible.
Verify workloads and data — Confirm that previously managed hosts, clusters, and configurations are present and accurate.

Upgrade hosts

Once the restore is complete, the management plane upgrade is considered done. You must then upgrade the hosts in each region to ensure compatibility and complete the overall upgrade process. Refer to the Upgrade Management Plane and Hosts guide for host upgrade instructions.

Post-Migration Notes

The migration replaces the underlying cluster runtime from nodeletd to k3s. Application-level behavior and the management plane interface remain unchanged for end users.
If you encounter issues during or after restore, contact Platform9 Support and provide the airctl-config in use, and any relevant log output.
Review the Release Notes for known issues or post-migration configuration recommendations specific to this release.

Rollback Considerations

There is no automated rollback for this migration. If the migration fails after the cluster has been deleted (Step 4 or later), recovery requires:

Re-running airctl unconfigure-du -- with --force flag
Restoring from the backup created in Step 2.

If the backup cannot be restored, contact Platform9 Support immediately. Do not delete or overwrite the backup artifact under any circumstances.

PreviousUpgrade Management Plane and Hosts NextCluster Scaling & Other Operations

Last updated 12 days ago

Was this helpful?