You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+182-2Lines changed: 182 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,6 +30,100 @@ From the base image, this image is used to provide the initial flashing of a dev
30
30
31
31
For advanced use cases, there may be a need to add additional packages not included in the [Base Images](https://github.com/kairos-io/kairos/tree/master/images). If those packages or configuration elements need to be added, they can be included in the empty `Dockerfile` located in this repo and they will be included in the build process and output artifacts.
32
32
33
+
### Custom Hardware Specs Lookup
34
+
35
+
A custom hardware specs lookup file can be provided to extend or override the default GPU specifications. This is useful for adding custom hardware entries or overriding default specifications.
This file will be copied to `/etc/spectrocloud/custom-hardware-specs-lookup.json` in the final image.
45
+
46
+
#### Configuration
47
+
48
+
The file must be a valid JSON array. These entries will be merged with the default hardware specs lookup table, with the custom entries taking precedence for matching `vendorID` and `deviceID` combinations.
49
+
50
+
#### Sample Entry
51
+
52
+
Here's an example entry structure:
53
+
54
+
```json
55
+
[
56
+
{
57
+
"marketingName": "NVIDIA Quadro RTX 6000",
58
+
"vRAM": 24,
59
+
"migCapable": false,
60
+
"vendor": "NVIDIA",
61
+
"vendorID": "10de",
62
+
"deviceID": [
63
+
"1e36",
64
+
"1e78"
65
+
],
66
+
"architecture": "Turing"
67
+
}
68
+
]
69
+
```
70
+
71
+
#### Field Descriptions
72
+
73
+
| Field | Description | Example |
74
+
|-------|-------------|---------|
75
+
|`marketingName`| Display name for the hardware |`"NVIDIA Quadro RTX 6000"`|
76
+
|`vRAM`| Video RAM in GB (decimal) |`24`|
77
+
|`migCapable`| Whether Multi-Instance GPU is supported (for NVIDIA GPUs) |`false`|
78
+
|`vendor`| Vendor name |`"NVIDIA"`, `"AMD"`, `"Intel"`|
79
+
|`vendorID`| PCI vendor ID in hexadecimal (lowercase) |`"10de"`|
80
+
|`deviceID`| Array of PCI device IDs in hexadecimal (can have multiple IDs for same model) |`["1e36", "1e78"]`|
81
+
|`architecture`| GPU architecture name |`"Turing"`, `"Ampere"`, `"Hopper"`, `"Blackwell"`|
82
+
83
+
#### Usage
84
+
85
+
There are two ways to provide the custom hardware specs lookup file:
86
+
87
+
##### Method 1: During CanvOS Build (Recommended for Pre-staged Images)
88
+
89
+
1. Create the file at `overlay/files/etc/spectrocloud/custom-hardware-specs-lookup.json`
90
+
2. Add custom entries as a JSON array
91
+
3. Build the images - the custom lookup file will be included automatically
92
+
4. Custom entries will override default entries for matching `vendorID`+`deviceID` combinations
93
+
94
+
##### Method 2: Via user-data (Runtime Configuration)
95
+
96
+
The custom hardware specs lookup file can be provided via user-data using the `boot.after` stage (recommended) or `boot` stage. Note that `/etc` is read-only at runtime, but cloud-init can write files during boot stages.
97
+
98
+
Add the following to the `user-data` file (replace the example entry with actual hardware specs):
| MAAS_IMAGE_NAME | Custom name for the final MAAS image (without .raw.gz extension). Only used when building MAAS images. | string |`kairos-ubuntu-maas`|
247
+
| IS_MAAS | Build MAAS-compatible disk images. Set to `true` when building for MAAS deployment. | boolean |`false`|
152
248
153
249
>For use cases where UEFI installers are burned into a USB and then edge hosts are booted with the USB. Use the OSBUILDER_VERSION=0.300.4 in the .arg file with canvos when building the installer.
154
250
Version 0.300.3 does not support UEFI builds loading from USB.
@@ -325,6 +421,90 @@ AUTO_ENROLL_SECUREBOOT_KEYS=false # Auto enroll SecureBoot keys when device boot
325
421
326
422
2. `./earthly.sh +build-all-images`
327
423
424
+
### Building MAAS Images
425
+
426
+
MAAS (Metal as a Service) is Canonical's bare-metal provisioning tool. CanvOS can build MAAS-compatible disk images in `dd.gz` format that can be uploaded directly to MAAS for deployment.
427
+
428
+
#### Prerequisites
429
+
430
+
- MAAS image builds only support Ubuntu (OS_DISTRIBUTION must be set to `ubuntu`)
431
+
- The build process requires privileged mode (handled automatically by `earthly.sh`)
432
+
433
+
#### Configuration
434
+
435
+
1. In your `.arg` file, ensure the following settings:
436
+
437
+
```shell
438
+
OS_DISTRIBUTION=ubuntu
439
+
OS_VERSION=22 # or 20, 24, etc.
440
+
ARCH=amd64
441
+
```
442
+
443
+
2. (Optional) Set a custom name for the MAAS image:
444
+
445
+
```shell
446
+
MAAS_IMAGE_NAME=my-custom-maas-image
447
+
```
448
+
449
+
If not specified, the default name will be `kairos-ubuntu-maas`. The final output will be in `dd.gz` format (e.g., `my-custom-maas-image.raw.gz`).
450
+
451
+
#### Building the MAAS Image
452
+
453
+
Run the following command to build the MAAS image:
454
+
455
+
```shell
456
+
./earthly.sh +maas-image
457
+
```
458
+
459
+
The build process consists of two steps:
460
+
1. **Step 1**: Generates the Kairos raw disk image from the installer image
461
+
2. **Step 2**: Creates a composite MAAS image that includes:
462
+
- Kairos OS partitions (EFI, OEM, Recovery)
463
+
- Ubuntu root filesystem for MAAS deployment
464
+
- Curtin hooks for MAAS integration
465
+
- Cloud-init scripts for post-deployment configuration
466
+
467
+
#### Output
468
+
469
+
After a successful build, you will find the compressed MAAS image in the `build/` directory:
470
+
471
+
```shell
472
+
ls build/
473
+
474
+
my-custom-maas-image.raw.gz
475
+
my-custom-maas-image.raw.gz.sha256
476
+
```
477
+
478
+
The output includes:
479
+
- **Compressed disk image** (`.raw.gz`): The MAAS-compatible disk image in `dd.gz` format
480
+
- **SHA256 checksum** (`.sha256`): Checksum file for verification
481
+
482
+
#### Uploading to MAAS
483
+
484
+
1. Upload the `.raw.gz` file to MAAS as a custom image:
485
+
- Go to MAAS UI → Images → Custom Images
486
+
- Click "Upload custom image"
487
+
- Select the `.raw.gz` file
488
+
- Specify format as `dd.gz`
489
+
- MAAS will automatically decompress the image during upload
490
+
491
+
2. The image is now ready to be deployed to bare-metal servers via MAAS.
492
+
493
+
#### Image Contents
494
+
495
+
The MAAS image includes:
496
+
- **Content bundles**: Pre-staged container images and artifacts (if provided during build)
497
+
- **Cluster config (SPC)**: Cluster definition files (if `CLUSTERCONFIG` is set in `.arg`)
498
+
- **Local UI**: Local management interface (if `local-ui.tar` is provided)
499
+
- **Curtin hooks**: Custom installation hooks for MAAS deployment
500
+
- **Cloud-init integration**: Automatic userdata processing and recovery mode boot
501
+
502
+
#### Troubleshooting
503
+
504
+
- **Build fails with "OS_DISTRIBUTION is not set"**: Ensure `OS_DISTRIBUTION=ubuntu` is set in your `.arg` file
505
+
- **Build fails with "OS_DISTRIBUTION is not ubuntu"**: MAAS images only support Ubuntu. Change `OS_DISTRIBUTION` to `ubuntu` in your `.arg` file
506
+
- **Image not found after build**: Check that the build completed successfully and look for the `.raw.gz` file in the `build/` directory
507
+
328
508
### Building with private registry
329
509
330
510
1. Make sure you have logged into your registry using docker login
0 commit comments