> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/migrating-from-nodeletd-to-k3s-based-clusters.md).
# 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:
1. Install the new release artifacts
2. Back up the existing (2026.1) deployment
3. Unconfigure and delete the existing cluster
4. Reconfigure and create a new k3s cluster
5. 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](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/upgrade#step-1-download-and-run-the-installer-artifacts) 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.
```bash
/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.
```bash
/opt/pf9/airctl/airctl unconfigure-du
```
***
#### Step 4 — Delete the Existing Cluster
Delete the existing nodeletd cluster. This step is **irreversible**.
```bash
/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](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/self-hosted-install#configure-airctl). 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](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/self-hosted-install#proxy-configuration-optional) 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`:
```bash
/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:
```bash
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](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/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.
{% hint style="info" %}
**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:
```json
"rabbitmq_clustering_enabled": "false"
```
{% endhint %}
Refer to the [Backup and Restore Guide](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/backup-and-restore) for detailed restore instructions.
**Quick reference — restore command:**
```bash
/opt/pf9/airctl/airctl restore --backupdir --verbose
```
Replace `` 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:
1. **Confirm cluster health** — Check that all cluster nodes report as healthy:
```bash
kubectl get nodes
```
2. **Confirm management plane availability** — Log in to the Private Cloud Director UI and confirm that the dashboard loads and all services are visible.
3. **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](https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/upgrade#upgrade-the-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](https://docs.platform9.com/release-notes/april-2026-release) 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:
1. Re-running `airctl unconfigure-du --` with `--force` flag
2. 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.**
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.platform9.com/private-cloud-director/getting-started/self-hosted/migrating-from-nodeletd-to-k3s-based-clusters.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.