Customizing a VM using cloud-init in VMware Cloud Director

By using cloud-init, you can customize a new VM using code, during the creation of the VM.

Here, you will learn how to customize a VM using cloud-init in a VMware Cloud Director environment.

If you are deploying a VM from a Glesys template in VMware Cloud Director, then follow the instructions outlined in this document.

However, if you are deploying a VM from a custom-built template, then the steps outlined here do not apply, and you can continue using existing workflows for customization.

Brief overview of guest OS customization in VMware Cloud Director

Historically, VMs deployed from a Glesys template in VMware Cloud Director have been customized using the vmware-imc method, the default method supported in the platform.

The vmware-imc method leverages customization scripts bundled with VMware Cloud Director, which are copied onto the guest operating system and then executed by the vmtools service running in the guest.

From now on, VMs deployed from a Glesys template in VMware Cloud Director will be customized using cloud-init.

The cloud-init method has become the de facto industry standard for customizing VMs in the cloud. In a VMware environment, the cloud-init configuration data supplied to a VM is read using vmtools. The cloud-init service running in the guest then customizes the guest operating system according to that configuration.

There are many benefits to using the cloud-init method over the vmware-imc method:

cloud-init offers more capabilities with the potential to automate the entire initial setup of a VM.
cloud-init offers better security as it does not rely on default root/admin accounts like vmware-imc.
cloud-init offers broader guest operating system support. vmware-imc can be limited, and it can take a long time after a new OS is released before it is officially supported.

How to customize a VM using cloud-init

The following steps apply to all GleSYS templates in VMware Cloud Director.

Step 1 – Generating a VMware Cloud Director API token

In the top right corner of the navigation bar, click your user name, select User preferences → API Tokens, and click New.
Enter a Name for the token, and click Create. The generated API token appears. You must copy the token because it appears only once.

Step 2 – Creating a cloud-init metadata file

The metadata file is a plain-text file formatted as YAML, where you can define the hostname, instance ID, and network configuration of your VM.

Create a metadata.yaml file on your local machine and paste the following configuration:

metadata.yaml

instance-id: demo.example.com # a unique identifier or UUID for the instance
local-hostname: demo.example.com # replace with your own FQDN
network:
  version: 2
  ethernets:
    ens192:
      dhcp4: yes

Step 3 – Creating a cloud-init userdata file

The userdata file is a plain-text file formatted as YAML, where you can define many options to customize your VM, including options to create user accounts, install software packages, execute commands, and create files.

Create a userdata.yaml file on your local machine and paste the following configuration:

userdata.yaml

#cloud-config
users:
- name: demo
  shell: /bin/bash
  sudo: ALL=(ALL) NOPASSWD:ALL
  lock_passwd: true
  ssh_authorized_keys: 
    - # Paste your public SSH key here
manage_etc_hosts: true

Step 4 – Creating a VM from a template

Navigate to Compute → Virtual Machines and click New VM.
Enter a Name and a Computer Name.
Select From Template.
Uncheck the Power on check box.
Select a VM template from the list of available templates. For this article, choose ubuntu-2204.
Select a Storage Policy.
Specify the settings for the network adapter, such as Connected, Network, and IP Mode.
Click OK to create the VM.

Unfortunately, supplying the cloud-init configuration in the New VM wizard is not currently possible. Therefore, an additional step is required to provide the cloud-init configuration using the VMware Cloud Director API.

Step 5 – Supplying a cloud-init configuration to a VM

Supply the cloud-init configuration to the VM using the set_vcd_vm_extraconfig binary, which you can download from GitHub. Then, run the commands below on your local machine:

Multiple commands in Linux/macOS

export METADATA=$(gzip -c9 <metadata.yaml | { base64 -w0 2>/dev/null || base64; })
export USERDATA=$(gzip -c9 <userdata.yaml | { base64 -w0 2>/dev/null || base64; })

./set_vcd_vm_extraconfig \
 -url vcd.dc-####.glesys.net \
 -token ABC12345678 \
 -org vdo-##### \
 -vdc vdc-##### \
 -vm demo \
 -e guestinfo.metadata="${METADATA}" \
 -e guestinfo.metadata.encoding="gzip+base64" \
 -e guestinfo.userdata="${USERDATA}" \
 -e guestinfo.userdata.encoding="gzip+base64"

The above commands assume your local machine is running Linux/macOS. If your local machine is running Windows, you can run the following command in PowerShell:

Multiple commands in Windows PowerShell

$metadata = [convert]::ToBase64String((Get-Content -path "metadata.yaml" -Encoding byte))
$userdata = [convert]::ToBase64String((Get-Content -path "userdata.yaml" -Encoding byte))

.\set_vcd_vm_extraconfig.exe `
 -url vcd.dc-####.glesys.net `
 -token ABC12345678 `
 -org vdo-##### `
 -vdc vdc-##### `
 -vm demo `
 -e guestinfo.metadata="$metadata" `
 -e guestinfo.metadata.encoding="base64" `
 -e guestinfo.userdata="$userdata" `
 -e guestinfo.userdata.encoding="base64"

Step 6 – Powering on the VM

Navigate to Compute → Virtual Machines. Choose the specific VM and click Actions → Power → Power On.

You should now be able to SSH to your VM and verify that cloud-init has customized the instance according to the configuration specified in metadata and userdata.

Additional information regarding Windows virtual machines

As mentioned, all the steps outlined in this article apply to both Linux and Windows-based Glesys templates.

However, there is a difference regarding the contents of the userdata file when comparing Windows and Linux deployments that is worth highlighting.

Windows userdata file

Here is a sample userdata.yaml file for Windows-based VMs: