How to customise machines

MAAS provides a robust capability to customise machines when provisioning them

Errors or typos? Topics missing? Hard to read? Let us know!

MAAS allows you to customize machines before you provision them, using curtin or cloud-init.

Pre-seed 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:

early_commands:
  signal: ["wget", "--no-proxy", "http://example.com/", "--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:

late_commands:
  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"]

Pre-seed 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.

To customise cloud-init via the web UI:

  1. Select a machine.

  2. Choose Take action >> Deploy.

  3. Select a viable release.

  4. Check the box labelled Cloud-init user-data….

  5. Paste the desired script directly into the box.

  6. Select Start deployment for machine.

For example, to import an SSH key immediately after your machine deployment, you could paste this script:

#!/bin/bash
(
echo === $date ===
ssh-import-id foobar_user
) | tee /ssh-key-import.log

No script validation of any kind is provided with this capability. You will need to test and debug your own cloud-init scripts.

Using cloud-init to customise a machine after deployment is relatively easy. After you’re logged in, use the following command to deploy a machine with a custom script you’ve written:

maas $PROFILE machine deploy $SYSTEM_ID user_data=<base-64-encoded-script>

The three replaceable parameters shown above decode to:

  1. $PROFILE: Your MAAS login. E.g. admin
  2. $SYSTEM_ID: The machine’s system ID (see example below)
  3. <base-64-encoded-script>: A base-64 encoded copy of your customisation script. See below for an example.

E.g.:

Suppose you would like to import an SSH key immediately after your machine deployment. First, you want to find the machine’s system_id, which you can do with this short, command-line jq script:

maas admin machines read | jq -r '(["HOSTNAME","SYSID"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id]) | @tsv' | column -t

You might then use this script, called import_key.sh, to retrieve the needed key:

#!/bin/bash
(
echo === $date ===
ssh-import-id foobar_user
) | tee /ssh-key-import.log

This script echoes the date in addition to the output of the ssh-import-key command. It also adds that output to a file, /ssh-key-import.log.

Base-64 encoding is required because the MAAS command-line interacts with the MAAS API, and base-64 encoding allows MAAS to send the script inside a POST HTTP command.

Use the base64 command to output a base-64 encoded version of your script:

base64 -w0 ./import_key.sh

Putting it together:

maas $PROFILE machine deploy $SYSTEM_ID user_data=$(base64 -w0 ./import_key.sh)

After MAAS deploys the machine, you’ll find /ssh-key-import.log on the machine you deployed.

Default minimum kernel

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.

To set the default minimum enlistment and commissioning kernel (based on Ubuntu release: GA kernel) for all machines:

  1. Select Settings >> General.

  2. Select a kernel in the Default Minimum Kernel Version field of the Commissioning section

Set minimum deployment kernel for one machine

To set the minimum deploy kernel on a machine basis:

  1. Select Machines.

  2. Click on a machine.

  3. Select Configuration.

  4. Select Edit in the Machine configuration section.

  5. Select a kernel in the Minimum Kernel field.

Set a specific kernel during machine deployment

To set a specific kernel during deployment:

  1. Select Machines.

  2. Click on a machine.

  3. Choose Take action >> Deploy.

  4. Choose a kernel from the third kernel field.

  5. Click Deploy machine to initiate the deployment.

MAAS verifies that the specified kernel is available for the given Ubuntu release (series) before deploying the machine.

[tab version=“3.4 Snap,3.4 Packages,3.3 Snap,3.3 Packages,3.2 Snap,3.2 Packages,3.1 Snap,3.1 Packages,3.0 Snap,3.0 Packages,2.9 Snap,2.9 Packages” view=“CLI”]
To set a default minimum kernel for all new and commissioned machines:

maas $PROFILE maas set-config name=default_min_hwe_kernel value=$KERNEL

For example, to set it to the 16.04 GA kernel:

maas $PROFILE maas set-config name=default_min_hwe_kernel value=ga-16.04

The command option default_min_hwe_kernel appears to apply to only HWE kernels but this is not the case.

Set a minimum deployment kernel for a machine

To set the minimum deploy kernel on a per-machine basis:

maas $PROFILE machine update $SYSTEM_ID min_hwe_kernel=$HWE_KERNEL

For example, to set it to the HWE 16.04 kernel:

maas $PROFILE machine update $SYSTEM_ID min_hwe_kernel=hwe-16.04

The command option default_min_hwe_kernel appears to apply to only HWE kernels but this is not the case.

Set a specific kernel during machine deployment

To set a specific kernel during the deployment of a machine:

maas $PROFILE machine deploy $SYSTEM_ID distro_series=$SERIES hwe_kernel=$KERNEL

The operation will fail if the kernel specified by hwe_kernel is older than the kernel (possibly) given by default_min_hwe_kernel. Similarly, it will not work if the kernel is not available for the given distro series (such as ‘hwe-16.10’ for ‘xenial’).

For example, to deploy a Xenial node with the HWE 16.04 edge kernel:

maas $PROFILE machine deploy $SYSTEM_ID distro_series=xenial hwe_kernel=hwe-16.04-edge

The command option hwe_kernel appears to apply to only HWE kernels but this is not the case.

[/tabs]

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.

To set kernel boot options globally:

  1. Make sure that you are logged in as an administrator.

  2. Go to Settings >> General.

  3. Scroll down to the Global Kernel Parameters section:

  4. Type in the desired (space separated) options.

  5. Be sure to click Save.

The contents of the field will be used as-is. Do not use extra characters.

You can set kernel boot options and apply them to all machines with the CLI command:

maas $PROFILE maas set-config name=kernel_opts value='$KERNEL_OPTIONS'

Kernel option tags

This feature is only available via the MAAS CLI.

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:

Success.
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 \
'(["tag_name","tag_comment","kernel_options"]
|(.,map(length*"-"))),(.[]|[.name,.comment,.kernel_opts]) 
| @tsv' | column -t

This should give you results something like this:

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

Hardware sync

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.

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.

To enable Hardware sync on a machine:

  1. Select Machines.

  2. Select a machine.

  3. Select Take action >> Deploy*.

  4. Check Periodically synch hardware.

  5. Select Start deployment for machine.

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.

To enable Hardware sync on a machine, deploy the machine from the command line, adding enable_hw_sync=true:

maas $PROFILE machine deploy $SYSTEM_ID osystem=$OSYSTEM distro_series=$VERSION enable_hw_sync=true

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

Hardware sync updates the machine’s blockdevice, interface and device sets on a periodic basis. These can be viewed with the CLI command:

maas $PROFILE machine read $SYSTEM_ID

The timestamps of the last time data was synced and the estimated next time the machine will be synced can be seen in the last_sync and next_sync fields respectively.


Last updated a day ago.