Offline docs (switch to live docs)                          UI-only  CLI-only

Customising machine specifications

MAAS provides the capability to customise machines. This article will help you learn:

How to customise machine storage

This section will show you:

Note that layouts can be set globally and on a per-machine basis. For additional information on storage layouts, see the Storage layouts reference article.

How to set global storage layouts

All machines will have a default layout applied when commissioned. An administrator can configure the default layout on the 'Settings' page, under the 'Storage' tab.

[note] The new default will only apply to newly-commissioned machines. [/note]

How to set per-machine storage layouts

An administrator can change the layout for a single machine as well as customise that layout providing this is done while the machine has a status of 'Ready'. This is only possible via the CLI: to see how, click the "CLI" option for your version and delivery method above.

[note] Only an administrator can modify storage at the block device level (providing the machine has a status of 'Ready'). [/note]

How to set the default erasure configuration

  1. Click on Settings" --> Storage.

  2. Set or clear Erase machines' disks prior to releasing. If you set this option, users will be compelled to use disk erasure: that option will be pre-filled in the machine's view and the user will be unable to remove the option.

How to pre-seed with curtin

You can customise the Curtin installation by either editing the existing curtin_userdata template or by adding a custom file as described above. For a flowchart, showing where Curtin and pre-seeding fits into the deployment picture, see How images get deployed.

Curtin provides hooks to execute custom code before and after installation takes place. These hooks are named early and late respectively, and they can both be overridden to execute the Curtin configuration in the ephemeral environment. Additionally, the late hook can be used to execute a configuration for a machine being installed, a state known as in-target.

Curtin commands look like this:

foo: ["command", "--command-arg", "command-arg-value"]

Each component of the given command makes up an item in an array. Note, however, that the following won't work:

foo: ["sh", "-c", "/bin/echo", "foobar"]

This syntax won't work because the value of sh's -c argument is itself an entire command. The correct way to express this is:

foo: ["sh", "-c", "/bin/echo foobar"]

The following is an example of an early command that will run before the installation takes place in the ephemeral environment. The command pings an external machine to signal that the installation is about to start:

  signal: ["wget", "--no-proxy", "", "--post-data", "system_id=&signal=starting_install", "-O", "/dev/null"]

The following is an example of two late commands that run after installation is complete. Both run in-target, on the machine being installed.

The first command adds a PPA to the machine. The second command creates a file containing the machine’s system ID:

  add_repo: ["curtin", "in-target", "--", "add-apt-repository", "-y", "ppa:my/ppa"]
  custom: ["curtin", "in-target", "--", "sh", "-c", "/bin/echo -en 'Installed ' > /tmp/maas_system_id"]

How to pre-seed with cloud-init

For a flowchart, showing where cloud-init fits into the deployment picture, see How images get deployed.

To customise cloud-init via the web UI:

  1. Select Machines.

  2. Select a machine.

  3. Select Actions > Deploy.

  4. Checkbox Cloud-init user-data....

  5. Paste, upload, or drag-and-drop the script into the box.

  6. Select Start deployment for machine.

How to choose Ubuntu kernels

This section will show you:

How to set a default minimum kernel for enlistment and commissioning

To set the default minimum enlistment and commissioning kernel for all machines:

  1. Select Settings.

  2. Select Configuration.

  3. Select Commissioning.

  4. Select a kernel from the Default minimum kernel version drop-down.

  5. Select Save to register your changes.

How to set global kernel boot options

To set global kernel boot options:

  1. Select Settings.

  2. Select Configuration > Kernel parameters.

  3. Enter the Global boot parameters always passed to the kernel in the text box.

  4. Select Save to register your changes.

How to create tags with built-in kernel options

You can create tags with embedded kernel boot options. When you apply such tags to a machine, those kernel boot options will be applied to that machine on the next deployment.

To create a tag with embedded kernel boot options, use the following command:

maas $PROFILE tags create name='$TAG_NAME' \
    comment='$TAG_COMMENT' kernel_opts='$KERNEL_OPTIONS'

For example:

maas admin tags create name='nomodeset_tag' \
    comment='nomodeset_kernel_option' kernel_opts='nomodeset vga'

This command yields the following results:

Machine-readable output follows:
    "name": "nomodeset_tag",
    "definition": ",
    "comment": "nomodeset_kernel_option",
    "kernel_opts": "nomodeset vga",
    "resource_uri": "/MAAS/api/2.0/tags/nomodeset_tag/"

You can check your work with a modified form of the listing command:

maas admin tags read | jq -r \
| @tsv' | column -t

This should give you results something like this:

tag_name             tag_comment                  kernel_options                     
--------             -----------                  --------------                     
new_tag              a-new-tag-for-test-purposes                                     
pod-console-logging  console=tty1                 console=ttyS0                      
nomodeset_tag        nomodeset_kernel_option      nomodeset       vga

How to use resource pools

This section will explain:

How to enable hardware sync on a machine

[note] MAAS hardware sync may leak the MAAS admin API token. You may need to rotate all admin tokens and re-deploy all machines that have hardware sync enabled. To find out whether this is an issue, and how to fix it, see the troubleshooting instructions for this problem. [/note]

To enable Hardware sync on a machine:

  1. Select Machines.

  2. Select a machine(s).

  3. Select Actions > Deploy*.

  4. Check Periodically synch hardware.

  5. Select Start deployment....

Once you've enabled hardware sync, any changes you make to the physical device, or to the VM through the VM host, will show up in the appropriate page for the deployed machine as soon as the sync interval has passed.

How to view updates from hardware sync

To view updates from hardware sync:

  1. Select Machines.

  2. Select the machine in question.

Any changes to the machine's hardware configuration will be updated on the next sync. The status bar at the bottom will show times for Last synced and Next sync. Updated BMC configuration and tags can also be viewed on the machine itself.

How to configure hardware sync interval

The hardware sync interval is configured globally in MAAS deployment settings.