Create and Manage MAAS Clusters Using LXD VMs
Palette supports creating and managing Kubernetes clusters deployed to a MAAS account with LXD Virtual Machines (VMs) enabled. This feature allows you to spawn multiple control plane nodes as LXD VMs and consolidate them on MAAS-managed servers, while your worker nodes run on bare metal. This improves resource utilization by reducing the number of bare metal machines needed to run control planes and keeps virtualization overhead low.
Limitations
The deployment of MAAS clusters to LXD VMs is limited to the Kubernetes distribution Palette eXtended Kubernetes (PXK).
Prerequisites
-
A MAAS account registered in Palette. All MAAS-registered Palette accounts must use either a System Private Gateway or Private Cloud Gateway (PCG) to connect to the MAAS environment. For more information on which PCG to use, refer to our MAAS Architecture guide.
-
If you want to use a static network range for the workload cluster's control plane, ensure you have configured an IP pool on the IP Address Management (IPAM) tab of the PCG. The IP pool must have Restrict to a single cluster enabled.
-
If your Palette instance does not have a direct connection to the MAAS environment, you must manually deploy a PCG cluster to your MAAS environment.
-
If you are using a self-hosted Palette or Palette VerteX instance that has a direct connection to your MAAS environment, you can use Palette's System Private Gateway.
-
-
A cluster profile for the MAAS environment. The Operating System (OS) image used in your cluster profile must be downloaded and available in your MAAS environment. Review How to use standard images for guidance on downloading OS images for MAAS.
-
MAAS hosts that support KVM or LXD VMs.
-
The LxdMaas feature flag enabled in the system console.
By default, Palette registers a Domain Name System (DNS) record in MAAS for the deployed cluster and links it to the IP addresses of the control plane nodes. However, you can use the Palette eXtended Kubernetes (PXK) pack to configure a custom API server endpoint for your cluster instead.
- If configuring the Cert Manager pack , ensure that you use version 1.19.1 or later. It is also important to
ensure:
crds.enabledis set tofalse.cainjector.enabledis set tofalseorcainjector.replicasis set to0.nodeSelectorornodeAffinityis set to prevent scheduling of Cert Manager on control pane nodes.
Deploy a MAAS Cluster with LXD-Enabled
Deploying a MAAS cluster with LXD enabled is a two-step process. First, you deploy your host cluster nodes on bare-metal MAAS servers that have LXD enabled. Then, you deploy your workload cluster with its control plane nodes as LXD VMs that are managed by the host cluster. The worker nodes are still deployed on bare-metal MAAS servers.
Deploy a Host Cluster with LXD-Enabled MAAS Hosts
-
Log in to Palette.
-
Ensure you are in the correct project scope.
-
From the left main menu, select Clusters, and choose either Create Cluster or Add New Cluster.
-
In the Data Center section, select MAAS.
-
In the bottom-right corner, click Start MAAS Configuration.
-
Complete the following information. Select Next when finished.
Field Description Cluster Name Enter a custom name for the cluster. Description (Optional) Provide context about the cluster. Tags (Optional) Assign any desired cluster tags. You can use tags to filter and organize clusters in Palette. Example: env:test.Cloud Account Select the appropriate MAAS account under which to deploy the cluster. If the account is not listed, select Add New Account, and follow the prompts to add your MAAS account to Palette. -
Choose between deploying your cluster using individual cluster profiles or a single cluster template.
- Cluster Profiles
- Cluster Templates
-
In the Cluster setup type window, choose Cluster Profiles > Add Cluster Profile.
-
Select the appropriate full or infrastructure cluster profile and Confirm your selection.
-
Review the layers of your cluster profile. Use the drop-down menus to select the appropriate cluster profile version, add necessary add-on profiles, and make changes to YAML configuration files as needed. When finished, select Next.
info- Cluster profile versions linked to cluster templates cannot be used in the cluster profile workflow.
- For ease of reuse and to persist changes across clusters using the same cluster profile, we recommend creating a new version of your cluster profile rather than making inline changes.
-
In the Cluster setup type window, choose Cluster Template > Select Cluster Template.
-
Select the appropriate cluster template and Confirm your selection.
-
Expand the Maintenance policy and Linked profiles panels to review the configuration of your cluster template.
If you need to make any changes, such as swapping your maintenance policy or updating your cluster profile version, you must exit the cluster deployment workflow and modify your cluster template before proceeding. If no changes are needed, select Next.
-
Review the layers of your cluster profile. If no changes are needed, select Next.
warningCluster profile changes, such as modifying your cluster profile version, adding additional add-on profiles, and editing YAML configuration files, are not allowed when deploying a cluster. Once a cluster profile is linked to a cluster template, that version of the cluster profile is locked to prevent configuration drift across clusters. If you need to make changes, you must create a new version of your cluster profile and modify your cluster template to use the new version.

-
The Profile variables configuration window opens if your cluster profile is configured to use cluster profile variables. Fill in the appropriate values, and select Next.
-
Fill out the following fields on the Cluster Config step.
Field Description Domains Register a DNS record in the selected domain for the deployed cluster. The DNS record links to the IP addresses of the control plane nodes. SSH Keys (Optional) Inject public Secure Shell (SSH) keys into ~/.ssh/authorized_keyson each control plane and worker node, including LXD VMs, without removing existing MAAS users. The list is populated using the keys in Tenant Settings or Project Settings > Security > SSH Keys. Select Add Item to add additional keys. Refer to SSH Keys on MAAS Cluster Nodes for details on supported distributions.NTP Servers (Optional) Specify Network Time Protocol (NTP) servers for the cluster nodes. The servers you provide override the machine image defaults. We recommend specifying at least one NTP server to prevent time drift issues. Refer to NTP Servers on MAAS Cluster Nodes for details on supported distributions. Override Cluster API cluster configuration Enable if you want to provide custom Cluster API manifests in YAML format. This is an advanced option that allows you to customize the underlying CAPI objects used to provision and manage your cluster. When enabled, the Update Cluster API cluster configuration option becomes available. Click this button to view the YAML code editor drawer, where you can provide your override configuration. Review the Override CAPI Properties documentation to learn more about this feature. -
Click the Host LXD-Based Control Planes toggle to use this cluster as an LXD-based control plane (hypervisor) for running control plane components as LXD VMs. Select Next.

-
Configure the control plane and, optionally, worker node pools.
The following input fields apply to MAAS control plane and worker node pools. For a detailed list of input fields that are common across environments and their usage, refer to our Node Pools guide. Select Next when finished.
Parameter Description Resource pool The MAAS resource pool from which to deploy nodes. Minimum CPU Only select machines from the Resource pool that have at least the specified amount of CPU. Minimum Memory Only select machines from the Resource pool that have at least the specified amount of memory. Availability zones The MAAS zones in which to deploy nodes. Palette distributes nodes across the selected zones for high availability. Override Cluster API node pool configuration (Optional) Enable if you want to provide custom Cluster API manifests in YAML format. This is an advanced option that allows you to customize the underlying CAPI objects used to provision and manage your node pool. When enabled, the Update Cluster API node pool configuration option becomes available. Click this button to view the YAML code editor drawer, where you can provide your override configuration. Review the Override CAPI Properties documentation to learn more about this feature. Tags Controls which MAAS machines to use for the node pool based on MAAS tags. If you specify multiple tags, Palette only selects machines that have all of the specified tags.
WARNING: Modifying tags on an existing node pool triggers a node repave. -
On the Cluster Settings page, configure additional options as needed. If you are deploying your cluster using cluster templates, a Cluster Timezone is required.
Left Menu Item Additional Information Cluster Timezone Specify the time zone where your cluster is being deployed. The time zone is used in maintenance policies to determine when updates are rolled out to clusters deployed with cluster templates. Lock Profile Updates (Edge Native clusters only) Hold cluster profile updates on the Edge hosts until an operator at the device releases them in Local UI. Refer to Lock Profile Updates for more information. Manage machines Set an OS patching schedule and specify nodes behavior when creating your cluster, including upgrading your nodes to use the latest OS patch version and allowing reboots. Schedule scans Enable any scan options you want Palette to perform and select a scan schedule. Palette supports Kubernetes configuration security, penetration testing, and conformance testing. Refer to Compliance Scan for details on each scan type. Schedule backups Schedule backups for your entire cluster or etcd. Refer to Backup and Restore for more information. RBAC Map a set of users or groups to a Kubernetes Role-Based Access Control (RBAC) role. This is required when custom OpenID Connect (OIDC) is configured. Refer to the following guides for more information:
- Create Role Bindings
- Palette eXtended Kubernetes (PXK)Location Specify the location of your cluster by entering the address in the search bar and selecting one of the options in the drop-down. For example, London, Greater London, England, United Kingdom. This is used for display purposes and does not impact cluster functionality. -
Select Validate to review your cluster configurations and settings.
-
If no changes are needed, select Finish Configuration to deploy your cluster.
To monitor the status of your cluster deployment, from the left main menu, select Clusters and choose your cluster. The cluster Overview tab displays the status and health of your cluster, as well as deployment details. Use the Events tab to monitor the deployment in real time. Provisioning may take several minutes.
Deploy a Workload Cluster with LXD VMs as Control Plane Nodes
-
Log in to Palette.
-
Ensure you are in the correct project scope.
-
From the left main menu, select Clusters, and choose either Create Cluster or Add New Cluster.
-
In the Data Center section, select MAAS.
-
In the bottom-right corner, click Start MAAS Configuration.
-
Enter the basic information for your cluster, including the Cluster name, Description, and Tags.
-
From the Cloud Account drop-down menu, select your MAAS cloud account, and click Next.
-
Choose between deploying your cluster using individual cluster profiles or a single cluster template.
- Cluster Profiles
- Cluster Templates
-
In the Cluster setup type window, choose Cluster Profiles > Add Cluster Profile.
-
Select the appropriate full or infrastructure cluster profile and Confirm your selection.
-
Review the layers of your cluster profile. Use the drop-down menus to select the appropriate cluster profile version, add necessary add-on profiles, and make changes to YAML configuration files as needed. When finished, select Next.
info- Cluster profile versions linked to cluster templates cannot be used in the cluster profile workflow.
- For ease of reuse and to persist changes across clusters using the same cluster profile, we recommend creating a new version of your cluster profile rather than making inline changes.
-
In the Cluster setup type window, choose Cluster Template > Select Cluster Template.
-
Select the appropriate cluster template and Confirm your selection.
-
Expand the Maintenance policy and Linked profiles panels to review the configuration of your cluster template.
If you need to make any changes, such as swapping your maintenance policy or updating your cluster profile version, you must exit the cluster deployment workflow and modify your cluster template before proceeding. If no changes are needed, select Next.
-
Review the layers of your cluster profile. If no changes are needed, select Next.
warningCluster profile changes, such as modifying your cluster profile version, adding additional add-on profiles, and editing YAML configuration files, are not allowed when deploying a cluster. Once a cluster profile is linked to a cluster template, that version of the cluster profile is locked to prevent configuration drift across clusters. If you need to make changes, you must create a new version of your cluster profile and modify your cluster template to use the new version.

Additional Configurations
-
To use two subnets, add the
cloud.maas.lxdVMSubnetsconfiguration to the Kubernetes layer of your cluster profile. The first subnet must specify the preboot execution environment (PXE), used for the initial booting and provisioning of LXD virtual machines, and the second must specify the subnet used to configure static IPs for workload traffic.Example LXD subnet configurationcloud:
maas:
lxdVMSubnets: 10.11.160.0/24,10.10.128.0/18
-
The Profile variables configuration window opens if your cluster profile is configured to use cluster profile variables. Fill in the appropriate values, and select Next.
-
Fill out the following fields on the Cluster Config step.
Field Description Domains Register a DNS record in the selected domain for the deployed cluster. The DNS record links to the IP addresses of the control plane nodes. SSH Keys (Optional) Inject public Secure Shell (SSH) keys into ~/.ssh/authorized_keyson each control plane and worker node, including LXD VMs, without removing existing MAAS users. The list is populated using the keys in Tenant Settings or Project Settings > Security > SSH Keys. Select Add Item to add additional keys. Refer to SSH Keys on MAAS Cluster Nodes for details on supported distributions.NTP Servers (Optional) Specify Network Time Protocol (NTP) servers for the cluster nodes. The servers you provide override the machine image defaults. We recommend specifying at least one NTP server to prevent time drift issues. Refer to NTP Servers on MAAS Cluster Nodes for details on supported distributions. Override Cluster API cluster configuration Enable if you want to provide custom Cluster API manifests in YAML format. This is an advanced option that allows you to customize the underlying CAPI objects used to provision and manage your cluster. When enabled, the Update Cluster API cluster configuration option becomes available. Click this button to view the YAML code editor drawer, where you can provide your override configuration. Review the Override CAPI Properties documentation to learn more about this feature. -
When creating a workload cluster that will leverage MAAS LXD or will use an existing host LXD-based control plane, leave the Host LXD-Based Control Planes option disabled. Select Next.

-
Configure the control plane and worker node pools. The following input fields apply to MAAS node pools. For a detailed list of input fields that are common across environments and their usage, refer to our Node Pools guide. Select Next when finished.
Cloud Configuration
Parameter Description Use LXD VMs Select this option to deploy the workload cluster's control plane nodes as LXD VMs instead of on bare metal MAAS servers. This option is only displayed if you have KVM or LXD enabled on MAAS and you did not select Host LXD-Based Control Planes in step 11. Resource pool The MAAS resource pool from which to deploy nodes. Minimum CPU Only select machines from the Resource pool that have at least the specified amount of CPU. Minimum Memory Only select machines from the Resource pool that have at least the specified amount of memory. Availability zones The MAAS zones in which to deploy nodes. Palette distributes nodes across the selected zones for high availability. These must match the same zones used by the hosted LXD-based control plane. Override Cluster API node pool configuration (Optional) Enable if you want to provide custom Cluster API manifests in YAML format. This is an advanced option that allows you to customize the underlying CAPI objects used to provision and manage your node pool. When enabled, the Update Cluster API node pool configuration option becomes available. Click this button to view the YAML code editor drawer, where you can provide your override configuration. Review the Override CAPI Properties documentation to learn more about this feature. Tags Control which MAAS machines to use for the node pool based on MAAS tags. If you specify multiple tags, Palette only selects machines that have all of the specified tags. If you are using a hosted LXD-based control plane, the resource pool, availability zones, and tags must also match.
WARNING: Modifying tags on an existing node pool triggers a node repave.Network Type (Control plane pools only) Select MAAS Automatic or Palette Static IP Pool. For Palette Static IP Pool, select the IP Address Management drop-down and choose the desired IPAM node pool. The IP pool must have Restrict to a single cluster enabled. This option is only available when Use LXD VMs is enabled for the control plane pool. dangerEnsure that your Resource pool, Availability zones, and Tags selections match the same values used for the host cluster nodes. Failure to do so may result in LXD VMs created on MAAS hosts that do not have LXD initialized, which can lead to cluster provisioning failures.

-
On the Cluster Settings page, configure additional options as needed. If you are deploying your cluster using cluster templates, a Cluster Timezone is required.
Left Menu Item Additional Information Cluster Timezone Specify the time zone where your cluster is being deployed. The time zone is used in maintenance policies to determine when updates are rolled out to clusters deployed with cluster templates. Lock Profile Updates (Edge Native clusters only) Hold cluster profile updates on the Edge hosts until an operator at the device releases them in Local UI. Refer to Lock Profile Updates for more information. Manage machines Set an OS patching schedule and specify nodes behavior when creating your cluster, including upgrading your nodes to use the latest OS patch version and allowing reboots. Schedule scans Enable any scan options you want Palette to perform and select a scan schedule. Palette supports Kubernetes configuration security, penetration testing, and conformance testing. Refer to Compliance Scan for details on each scan type. Schedule backups Schedule backups for your entire cluster or etcd. Refer to Backup and Restore for more information. RBAC Map a set of users or groups to a Kubernetes Role-Based Access Control (RBAC) role. This is required when custom OpenID Connect (OIDC) is configured. Refer to the following guides for more information:
- Create Role Bindings
- Palette eXtended Kubernetes (PXK)Location Specify the location of your cluster by entering the address in the search bar and selecting one of the options in the drop-down. For example, London, Greater London, England, United Kingdom. This is used for display purposes and does not impact cluster functionality. -
Select Validate to review your cluster configurations and settings.
-
If no changes are needed, select Finish Configuration to deploy your cluster.
To monitor the status of your cluster deployment, from the left main menu, select Clusters and choose your cluster. The cluster Overview tab displays the status and health of your cluster, as well as deployment details. Use the Events tab to monitor the deployment in real time. Provisioning may take several minutes.
Validate
Use the following steps to You can validate your cluster is up and in Running state.
-
Log in to Palette.
-
Ensure you are in the correct project scope.
-
From the left main menu, select Clusters. The Clusters page displays a list of all available clusters that Palette manages.
-
Select the cluster you deployed. On the Overview tab, ensure the Cluster Status is Running and that the cluster has a Health status of Healthy.
Update a MAAS Cluster
Ensure that the OS image used in your cluster profile is downloaded and available in your MAAS environment before attempting to update your cluster. Review How to use standard images for guidance on downloading compatible OS images for MAAS.
Updates can include changes to the cluster configuration, such as a Kubernetes upgrade, or a node configuration, such as changing the CPU or memory requirements, or picking a different availability zone. These updates are orchestrated using a rolling repave of the cluster nodes. To learn more about managing a MAAS cluster, refer to Manage Clusters.
Updating the host cluster causes a rolling repave across nodes. During the repave, nodes running older versions are removed, and the associated LXD VMs are deleted. If the leader node is deleted, the control plane components of the workload cluster undergo a new leader election process and choose a new leader on an LXD VM running on a different node. For this reason, it is critical that the host and workload clusters are configured for high availability, consisting of at least three nodes per cluster, with the nodes spread across different availability zones.
Workload cluster updates function the same as regular MAAS clusters. Instead of provisioning new bare-metal hosts, new LXD VMs are created for the control plane nodes.
To protect your data, we recommend creating a backup of your MAAS cluster before proceeding with any updates or infrastructure changes. Review our Backup and Restore guide for additional information.
Delete a MAAS Cluster
Before deleting a MAAS LXD cluster, consider the following:
-
If the host cluster currently runs LXD control planes for any workload clusters, you must first move the workload clusters to a different host cluster. Deleting a host cluster that hosts control planes will bring the workload clusters down. Once the host cluster is removed, or if the host cluster is not running on any LXD VMs, you can delete it the same way as regular MAAS clusters.
-
Workload clusters can be deleted the same way as regular MAAS clusters. Deleting a workload cluster that uses LXD will also delete the LXD VMs created for that workload cluster on the host cluster.
Take the following steps to delete a MAAS cluster. Note that when you delete a MAAS cluster, all machines and associated storage disks that were created for the cluster are removed.
-
Log in to Palette as a tenant admin.
-
From the left main menu, select Clusters.
-
Select the cluster you want to delete.
-
In the top-right, select the Settings drop-down menu, and choose Delete.
The cluster status is updated to Deleting while cluster resources are being deleted. When all resources are successfully deleted, the cluster status is updated to Deleted and the cluster is removed from the list. The delete operation returns the hosts to the Ready state. All the artifacts related to the Kubernetes distribution are removed.
Next Steps
Now that you have deployed a MAAS cluster, you can start developing and deploying applications to your cluster. We recommend you review the Day-2 operations and become familiar with the cluster management tasks. Check out the Manage Clusters documentation to learn more about Day-2 responsibilities.