Skip to content

Commit 94279fd

Browse files
svetlana-efimovagithub-actions[bot]achuribooksvault-token-factory-spectrocloud[bot]
authored
docs: PE-7889 Document how to deploy MAAS Edge hosts (#9134)
* Document how to deploy MAAS Edge hosts * Minor fix * Optimised images with calibre/image-actions * Update maas-deployment.md * Update build-maas-image.md * Update build-maas-image.md * Update build-maas-image.md * Update site-deployment.md * Update maas-deployment.md * ci: auto-formatting prettier issues * Update build-maas-image.md * Add release note * ci: auto-formatting prettier issues * Update known-issues.md * ci: auto-formatting prettier issues * Update docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-maas-image.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/site-deployment/maas-deployment.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/site-deployment/site-deployment.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/release-notes/release-notes.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/site-deployment/maas-deployment.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-maas-image.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-maas-image.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/site-deployment/maas-deployment.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/site-deployment/maas-deployment.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * Update docs/docs-content/clusters/edge/site-deployment/maas-deployment.md Co-authored-by: Amanda Churi Filanowski <[email protected]> * ci: auto-formatting prettier issues * Update maas-deployment.md * Update build-maas-image.md * ci: auto-formatting prettier issues * ci: auto-formatting prettier issues * Update maas-deployment.md * ci: auto-formatting prettier issues * Update maas-deployment.md * ci: auto-formatting prettier issues * Update build-maas-image.md * Update maas-deployment.md * Update known-issues.md * ci: auto-formatting prettier issues * Update maas-deployment.md * Update build-maas-image.md * ci: auto-formatting prettier issues * Update build-maas-image.md * Update maas-deployment.md * ci: auto-formatting prettier issues --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: svetlana-efimova <[email protected]> Co-authored-by: Amanda Churi Filanowski <[email protected]> Co-authored-by: vault-token-factory-spectrocloud[bot] <133815545+vault-token-factory-spectrocloud[bot]@users.noreply.github.com>
1 parent 5f0fee7 commit 94279fd

File tree

6 files changed

+308
-0
lines changed

6 files changed

+308
-0
lines changed

‎docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/arg.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ of both the provider images and the Edge Installer ISO. This page lists the para
3131
| `IS_UKI` | Determines whether to build a Unified Kernel Image (UKI) to enabled Trusted Boot. Refer to [Trusted Boot](../../trusted-boot/trusted-boot.md) for more information. | `true`, `false`. Default is `false`. |
3232
| `K8S_DISTRIBUTION` | Kubernetes distribution. | ` k3s`, `rke2`, `kubeadm`, `kubeadm-fips`, `nodeadm`, `canonical`. |
3333
| `K8S_VERSION` | Kubernetes version. The available versions vary depending on the specified `K8S_DISTRIBUTION`. Review the `k8s_version.json` file in the [CanvOS](https://github.com/spectrocloud/CanvOS) repository for all supported versions. | Semantic Versioning patch release format - `x.y.z`. |
34+
| `MAAS_IMAGE_NAME` | Custom MAAS image name. | Lowercase alphanumeric string without spaces. The characters `-` and `_` are allowed. |
3435
| `MY_ORG` | Name of the org to use during secure boot key generation. For more information, refer to [Generate Keys](../../trusted-boot/keys/generate-keys.md). | String. |
3536
| `NO_PROXY` | URLS that should be excluded from the proxy. | Comma-separated URL string. |
3637
| `OS_DISTRIBUTION` | Operating System (OS) distribution. | `ubuntu`, `opensuse-leap`, `rhel`. |

‎docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-maas-image.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
sidebar_label: "Build MAAS Images"
3+
title: "Build MAAS Images"
4+
description: "Learn how to build the Palette MAAS Image using the EdgeForge utilities."
5+
icon: ""
6+
hide_table_of_contents: false
7+
sidebar_position: 35
8+
tags: ["edge"]
9+
---
10+
11+
With Palette Edge, you can use MAAS-managed bare-metal machines and LXD VMs as Edge hosts. The EdgeForge workflow
12+
enables the creation of MAAS-compatible images. In this guide, you will use the CanvOS utility to build MAAS images for
13+
your Edge deployment.
14+
15+
## Limitations
16+
17+
- MAAS image creation is supported only for appliance-mode Palette eXtended Kubernetes - Edge (PXK-E) deployments. Other
18+
Kubernetes distributions and agent-mode deployments are not supported by this workflow.
19+
20+
- For MAAS-based deployments, the Kairos `install` stage in user data is not used. Any GRand Unified Bootloader (GRUB)
21+
configuration or mount customizations must be applied using other Kairos stages or overlay files. Refer to
22+
[Edge Installer Configuration Reference](../../edge-configuration/installer-reference.md) for details on the available
23+
stages.
24+
25+
## Prerequisites
26+
27+
- (Optional) A [Palette registration token](../../site-deployment/site-installation/create-registration-token.md) to
28+
embed user data in the MAAS image. If you do not embed the user data, you must provide the user data, including a
29+
registration token, when deploying your MAAS host using the MAAS UI.
30+
31+
- A physical or virtual Linux machine with an AMD64 (also known as `x86_64`) processor architecture and the following
32+
minimum hardware configuration:
33+
34+
- 4 CPUs
35+
- 8 GB memory
36+
- 150 GB storage
37+
38+
- A user account with permission to run commands using `sudo` privileges.
39+
40+
- The following software installed on the Linux machine:
41+
42+
- [Docker Engine](https://docs.docker.com/engine/install/)
43+
- (Optional) [Earthly](https://earthly.dev/)
44+
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
45+
- [`qemu-utils`](https://installati.one/install-qemu-utils-ubuntu-20-04/)
46+
47+
## Build MAAS Images
48+
49+
1. Check out the [CanvOS](https://github.com/spectrocloud/CanvOS) GitHub repository, which contains the starter code.
50+
51+
```bash
52+
git clone https://github.com/spectrocloud/CanvOS.git
53+
```
54+
55+
2. Navigate to the `CanvOS` directory.
56+
57+
```bash
58+
cd CanvOS
59+
```
60+
61+
3. View the available [git tags](https://github.com/spectrocloud/CanvOS/tags).
62+
63+
```bash
64+
git tag
65+
```
66+
67+
4. Check out the newest available tag. This guide uses the tag **v4.8.5** as an example.
68+
69+
```shell
70+
git checkout v4.8.5
71+
```
72+
73+
5. Issue the command below to create an `.arg` file. Configure the build to use the PXK-E (`kubeadm`) Kubernetes
74+
distribution (`K8S_DISTRIBUTION=kubeadm`), the Ubuntu OS (`OS_DISTRIBUTION=ubuntu`) version 22 (`OS_VERSION=22`),
75+
and the AMD64 architecture (`ARCH=amd64`). Replace `1.32.3` with the required PXK-E Kubernetes version and
76+
`custom-maas-image` with the desired MAAS image name. If you do not specify the MAAS image name, it defaults to
77+
`kairos-ubuntu-maas`.
78+
79+
```bash
80+
cat << EOF > .arg
81+
OS_DISTRIBUTION=ubuntu
82+
OS_VERSION=22
83+
K8S_DISTRIBUTION=kubeadm
84+
K8S_VERSION=1.32.3
85+
ARCH=amd64
86+
MAAS_IMAGE_NAME=custom-maas-image
87+
UPDATE_KERNEL=false
88+
EOF
89+
```
90+
91+
Refer to [Edge Artifact Build Configurations](./arg.md) for a complete list of supported configuration parameters.
92+
93+
6. (Optional) Prepare the `user-data` file. Refer to [Prepare User Data and Argument Files](../prepare-user-data.md)
94+
for instructions. If you place the `user-data` file in the `CanvOS` repository root, it is embedded into the image
95+
at build time. You can also supply user data through the MAAS UI at deployment time instead of creating the
96+
`user-data` file in the `CanvOS` directory.
97+
98+
7. Issue the following command to start the build process.
99+
100+
```bash
101+
sudo ./earthly.sh +maas-image
102+
```
103+
104+
The build process takes some time to finish.
105+
106+
8. When the process finishes, the terminal displays the following message.
107+
108+
```bash hideClipboard title="Example Output"
109+
...
110+
✅ Composite image created and compressed successfully: /home/ubuntu/CanvOS/custom-maas-image.raw.gz
111+
You can now upload this compressed raw image to MAAS (MAAS will automatically decompress it).
112+
=== Generating SHA256 checksum ===
113+
✅ SHA256 checksum created: build/custom-maas-image.raw.gz.sha256
114+
✅ MAAS composite image created and compressed successfully: build/custom-maas-image.raw.gz
115+
Final size: 2.0G
116+
SHA256: 50b1b95e18b257727f40c2f6c9a07e72214a3fbd60e7232268b07503a2f08a9a
117+
MAAS will automatically decompress this image during upload.
118+
```
119+
120+
## Validate
121+
122+
1. Issue the following command to list the files in the `build` directory.
123+
124+
```bash
125+
ls build
126+
```
127+
128+
```bash hideClipboard title="Example Output"
129+
custom-maas-image.raw.gz custom-maas-image.raw.gz.sha256
130+
```
131+
132+
The output includes:
133+
134+
- The MAAS-compatible compressed disk image (`custom-maas-image.raw.gz`).
135+
- The SHA256 checksum file (`custom-maas-image.raw.gz.sha256`).
136+
137+
2. Verify the integrity of the image by validating the checksum. Replace `custom-maas-image.raw.gz.sha256` with your
138+
checksum file name.
139+
140+
```bash
141+
sha256sum --check build/custom-maas-image.raw.gz.sha256
142+
```
143+
144+
If the checksum is valid, the command returns the following output.
145+
146+
```bash hideClipboard title="Example Output"
147+
build/custom-maas-image.raw.gz: OK
148+
```
149+
150+
## Next Steps
151+
152+
Refer to [Deploy Edge Hosts on MAAS](../../site-deployment/maas-deployment.md) for step-by-step instructions on
153+
uploading the image to MAAS and deploying an Edge host using the MAAS UI.

‎docs/docs-content/clusters/edge/site-deployment/maas-deployment.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
sidebar_label: "Deploy Edge Hosts on MAAS"
3+
title: "Deploy Edge Hosts on MAAS"
4+
description: "Learn how to deploy Edge hosts on MAAS."
5+
icon: ""
6+
hide_table_of_contents: false
7+
sidebar_position: 55
8+
tags: ["edge"]
9+
---
10+
11+
Palette Edge supports deployment on MAAS-managed bare-metal machines and LXD VMs. You can use MAAS to provision hosts,
12+
register them with Palette, and deploy clusters on them just like any other Edge host. This enables consistent and
13+
automated deployments across both physical and virtual infrastructure managed by MAAS.
14+
15+
## Limitations
16+
17+
- MAAS image creation is supported only for appliance-mode Palette eXtended Kubernetes - Edge (PXK-E) deployments. Other
18+
Kubernetes distributions and agent-mode deployments are not supported by this workflow.
19+
20+
<!-- prettier-ignore-start -->
21+
22+
- MAAS-based Edge deployments are verified only with
23+
<VersionedLink text="Calico" url="/integrations/packs/?pack=cni-calico" /> as the Container Network Interface (CNI) and
24+
<VersionedLink text="Longhorn" url="/integrations/packs/?pack=csi-longhorn" /> as the Container Storage Interface (CSI).
25+
<!-- prettier-ignore-end -->
26+
27+
- For MAAS-based deployments, the Kairos `install` stage in user data is not used. Any GRand Unified Bootloader (GRUB)
28+
configuration or mount customizations must be applied using other Kairos stages or overlay files. Refer to
29+
[Edge Installer Configuration Reference](../edge-configuration/installer-reference.md) for details on the available
30+
stages.
31+
32+
## Prerequisites
33+
34+
- A [Palette account](https://www.spectrocloud.com/get-started).
35+
36+
- A MAAS image created according to the [Build MAAS Images](../edgeforge-workflow/palette-canvos/build-maas-image.md)
37+
guide.
38+
39+
- If you did not embed user data in the MAAS image, you need a
40+
[Palette registration token](site-installation/create-registration-token.md) to pair your Edge hosts with Palette.
41+
42+
- A MAAS-managed bare-metal machine or LXD virtual machine.
43+
44+
- A user and a machine with permissions to upload and publish custom images to MAAS. The machine must have the
45+
[MAAS CLI](https://maas-cli-doc.readthedocs.io/en/latest/maas-cli-install.html) installed and be able to access the
46+
MAAS API.
47+
48+
- MAAS-based Edge deployments require additional disk space on the target machine. The space allocated to the
49+
`UBUNTU_ROOTFS` partition (~3 GB) is not reclaimed after deployment, reducing the size of `COS_PERSISTENT`. If content
50+
is bundled into the image at build time, additional disk space equal to the size of the content partition is also not
51+
reclaimed dynamically. Ensure the target machine has sufficient disk capacity to accommodate the `UBUNTU_ROOTFS` and
52+
content partitions.
53+
54+
- The target machine must either be configured for Unified Extensible Firmware Interface (UEFI) boot mode or, if the
55+
boot mode is not set to UEFI, have UEFI-based boot options prioritized. Legacy Basic Input/Output System (BIOS) boot
56+
mode is not supported for this workflow.
57+
58+
For MAAS-managed bare-metal machines, verify the UEFI-related boot settings and adjust the boot order if needed
59+
directly in the machine firmware:
60+
61+
- Access the machine console (for example, using a Windows jump host).
62+
63+
- Reboot the machine and press **F11** during boot to enter the BIOS/UEFI setup.
64+
65+
- In the **Boot** menu, check the current boot mode. If it is not set to **UEFI**, ensure that **UEFI Network** is
66+
first in the boot order, and the UEFI local disk entry (for example, **UEFI Hard Disk:UEFI OS**) is second.
67+
68+
The following screenshot shows an example of the required boot order configured.
69+
70+
![A screenshot with the required UEFI boot order configured](/clusters_site-deployment_maas-deployment_boot-order_4-8.webp)
71+
72+
For LXD VMs managed by MAAS, ensure the VM is created with UEFI boot enabled. You can verify the machine configuration
73+
in the MAAS UI by opening the machine **Summary** page and checking the **Boot mode**. It must be set to **UEFI**
74+
before deploying the Edge host.
75+
76+
## Deploy MAAS Edge Host
77+
78+
1. Copy the MAAS image from the system where it was built to the machine you will use to access MAAS. The following
79+
command is an example that copies the `custom-maas-image.raw.gz` image to the local `Downloads/` directory.
80+
81+
```bash title="Example command"
82+
scp [email protected]:/home/ubuntu/CanvOS/build/custom-maas-image.raw.gz ~/Downloads/
83+
```
84+
85+
2. Use the following command to log in to MAAS. Replace `<MAAS-URL>` and `<API-KEY>` with your MAAS endpoint and API
86+
key. Replace `admin` with the name of your MAAS CLI profile.
87+
88+
```bash
89+
maas login admin http://<MAAS-URL>:5240/MAAS <API-KEY>
90+
```
91+
92+
3. Upload the custom image to MAAS using the `maas <profile> boot-resources create` command. The following table
93+
describes the parameters used in the command.
94+
95+
| **Parameter** | **Description** |
96+
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97+
| `<profile>` | The MAAS CLI profile name created using the `maas login` command. |
98+
| `name` | The unique identifier for the custom image within MAAS. Must follow MAAS naming conventions (lowercase, no spaces, and typically using `/` as a namespace separator). |
99+
| `title` | A human-readable label displayed in the MAAS UI. |
100+
| `architecture` | The target CPU architecture for the image. Use `amd64/generic` for AMD64 (`x86_64`) MAAS deployments. |
101+
| `filetype` | The format of the uploaded image. Use `ddgz` for compressed raw disk images. |
102+
| `content@` | Path to the image location. |
103+
104+
The following command serves as an example.
105+
106+
```bash title="Example command"
107+
maas admin boot-resources create \
108+
name='custom/my-image' \
109+
title='My Custom Image' \
110+
architecture='amd64/generic' \
111+
filetype='ddgz' \
112+
content@=~/Downloads/custom-maas-image.raw.gz
113+
```
114+
115+
4. In the MAAS web UI, open the page for the machine you want to use as your Edge host. Select **Actions** > **Deploy**.
116+
117+
5. Select the **Custom** value in the **OS** field. In the **Release** field, select the custom MAAS image you uploaded
118+
in step 3.
119+
120+
6. (Optional) If you did not embed the user data in the custom image, enable **Cloud-init user-data** and paste the
121+
required user data. For instructions on preparing user data, refer to
122+
[Prepare User Data and Argument Files](../edgeforge-workflow/prepare-user-data.md).
123+
124+
7. Click **Deploy machine** to start the deployment.
125+
126+
## Validate
127+
128+
1. Once the deployment finishes, log in to [Palette](https://console.spectrocloud.com).
129+
130+
2. From the left main menu, select **Clusters**.
131+
132+
3. At the top of the **Clusters** page, click the **Edge Hosts** tab. Once the Edge host is registered with Palette, it
133+
appears in the grid.
134+
135+
## Next Steps
136+
137+
Once an Edge host is registered with Palette, you can allocate the Edge host to a cluster. For more information, refer
138+
to [Create Cluster Definition](cluster-deployment.md).

‎docs/docs-content/clusters/edge/site-deployment/site-deployment.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,14 @@ templates and provision Edge hosts using the templates. Or check out the
4444
[Deploy Edge Cluster on VMware](../../../tutorials/clusters/edge/deploy-cluster.md) for an end-to-end tutorial to learn
4545
the Palette Edge deployment lifecycle using VMs.
4646

47+
## Deployment on MAAS
48+
49+
You can deploy Edge hosts on MAAS-managed bare-metal machines and LXD VMs. MAAS-provisioned machines function similarly
50+
to other Edge hosts, enabling automated, scalable deployments using existing MAAS infrastructure. Refer to
51+
[Build MAAS Images](../edgeforge-workflow/palette-canvos/build-maas-image.md) to learn how to create custom MAAS images
52+
for Palette Edge and [Deploy Edge Hosts on MAAS](maas-deployment.md) for step-by-step instructions on uploading images
53+
to MAAS and deploying an Edge host using the MAAS UI.
54+
4755
## Resources
4856

4957
- [Model Cluster Profile](model-profile.md)
@@ -54,6 +62,8 @@ the Palette Edge deployment lifecycle using VMs.
5462

5563
- [Deploy Edge Hosts as Virtual Machines](./virtual-deployment/virtual-deployment.md)
5664

65+
- [Deploy Edge Hosts on MAAS](maas-deployment.md)
66+
5767
- [Edge Host Grid View](./edge-host-view.md)
5868

5969
- [Deployment with Custom Registries](./deploy-custom-registries/deploy-custom-registries.md)

‎docs/docs-content/release-notes/release-notes.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,12 @@ The [CanvOS](https://github.com/spectrocloud/CanvOS) version corresponding to th
7474

7575
#### Features
7676

77+
- The EdgeForge workflow now enables the creation of MAAS-compatible images. Refer to
78+
[Build MAAS Image](../clusters/edge/edgeforge-workflow/palette-canvos/build-maas-image.md) to learn how to create
79+
custom MAAS images for Palette Edge and
80+
[Deploy Edge Hosts on MAAS](../clusters/edge/site-deployment/maas-deployment.md) for step-by-step instructions on
81+
uploading images to MAAS and deploying Edge hosts using the MAAS UI.
82+
7783
#### Improvements
7884

7985
- [Trusted Boot](../clusters/edge/trusted-boot/trusted-boot.md) has exited Tech Preview and is now ready for production

‎static/assets/docs/images/clusters_site-deployment_maas-deployment_boot-order_4-8.webp‎

64.2 KB
Loading

0 commit comments

Comments
 (0)