VMware
This datasource is for use with systems running on a VMware platform such as vSphere and currently supports the following data transports:
GuestInfo keys
Configuration
The configuration method is dependent upon the transport:
GuestInfo Keys
One method of providing meta, user, and vendor data is by setting the following
key/value pairs on a VM’s extraConfig property:
Property |
Description |
|---|---|
|
A YAML or JSON document containing the cloud-init metadata. |
|
The encoding type for |
|
A YAML document containing the cloud-init user data. |
|
The encoding type for |
|
A YAML document containing the cloud-init vendor data. |
|
The encoding type for |
All guestinfo.*.encoding values may be set to base64 or
gzip+base64.
Features
This section reviews several features available in this datasource, regardless of how the meta, user, and vendor data was discovered.
Instance data and lazy networks
One of the hallmarks of cloud-init is its use of instance-data and JINJA
queries
– the ability to write queries in user and vendor data that reference runtime
information present in /run/cloud-init/instance-data.json. This works well
when the metadata provides all of the information up front, such as the network
configuration. For systems that rely on DHCP, however, this information may not
be available when the metadata is persisted to disk.
This datasource ensures that even if the instance is using DHCP to configure
networking, the same details about the configured network are available in
/run/cloud-init/instance-data.json as if static networking was used. This
information collected at runtime is easy to demonstrate by executing the
datasource on the command line. From the root of this repository, run the
following command:
PYTHONPATH="$(pwd)" python3 cloudinit/sources/DataSourceVMware.py
The above command will result in output similar to the below JSON:
{
"hostname": "akutz.localhost",
"local-hostname": "akutz.localhost",
"local-ipv4": "192.168.0.188",
"local_hostname": "akutz.localhost",
"network": {
"config": {
"dhcp": true
},
"interfaces": {
"by-ipv4": {
"172.0.0.2": {
"netmask": "255.255.255.255",
"peer": "172.0.0.2"
},
"192.168.0.188": {
"broadcast": "192.168.0.255",
"mac": "64:4b:f0:18:9a:21",
"netmask": "255.255.255.0"
}
},
"by-ipv6": {
"fd8e:d25e:c5b6:1:1f5:b2fd:8973:22f2": {
"flags": 208,
"mac": "64:4b:f0:18:9a:21",
"netmask": "ffff:ffff:ffff:ffff::/64"
}
},
"by-mac": {
"64:4b:f0:18:9a:21": {
"ipv4": [
{
"addr": "192.168.0.188",
"broadcast": "192.168.0.255",
"netmask": "255.255.255.0"
}
],
"ipv6": [
{
"addr": "fd8e:d25e:c5b6:1:1f5:b2fd:8973:22f2",
"flags": 208,
"netmask": "ffff:ffff:ffff:ffff::/64"
}
]
},
"ac:de:48:00:11:22": {
"ipv6": []
}
}
}
},
"wait-on-network": {
"ipv4": true,
"ipv6": "false"
}
}
Redacting sensitive information
Sometimes the cloud-init userdata might contain sensitive information, and it
may be desirable to have the guestinfo.userdata key (or other guestinfo
keys) redacted as soon as its data is read by the datasource. This is possible
by adding the following to the metadata:
redact: # formerly named cleanup-guestinfo, which will also work
- userdata
- vendordata
When the above snippet is added to the metadata, the datasource will iterate
over the elements in the redact array and clear each of the keys. For
example, when the guestinfo transport is used, the above snippet will cause
the following commands to be executed:
vmware-rpctool "info-set guestinfo.userdata ---"
vmware-rpctool "info-set guestinfo.userdata.encoding "
vmware-rpctool "info-set guestinfo.vendordata ---"
vmware-rpctool "info-set guestinfo.vendordata.encoding "
Please note that keys are set to the valid YAML string --- as it is not
possible remove an existing key from the guestinfo key-space. A key’s analogous
encoding property will be set to a single white-space character, causing the
datasource to treat the actual key value as plain-text, thereby loading it as
an empty YAML doc (hence the aforementioned ---).
Reading the local IP addresses
This datasource automatically discovers the local IPv4 and IPv6 addresses for a guest operating system based on the default routes. However, when inspecting a VM externally, it’s not possible to know what the default IP address is for the guest OS. That’s why this datasource sets the discovered, local IPv4 and IPv6 addresses back in the guestinfo namespace as the following keys:
guestinfo.local-ipv4guestinfo.local-ipv6
It is possible that a host may not have any default, local IP addresses. It’s also possible the reported, local addresses are link-local addresses. But these two keys may be used to discover what this datasource determined were the local IPv4 and IPv6 addresses for a host.
Waiting on the network
Sometimes cloud-init may bring up the network, but it will not finish coming
online before the datasource’s setup function is called, resulting in an
/var/run/cloud-init/instance-data.json file that does not have the correct
network information. It is possible to instruct the datasource to wait until an
IPv4 or IPv6 address is available before writing the instance data with the
following metadata properties:
wait-on-network:
ipv4: true
ipv6: true
If either of the above values are true, then the datasource will sleep for a second, check the network status, and repeat until one or both addresses from the specified families are available.
Walkthrough
The following series of steps is a demonstration on how to configure a VM with this datasource:
Create the metadata file for the VM. Save the following YAML to a file named
metadata.yaml:instance-id: cloud-vm local-hostname: cloud-vm network: version: 2 ethernets: nics: match: name: ens* dhcp4: yes
Create the userdata file
userdata.yaml:#cloud-config users: - default - name: akutz primary_group: akutz sudo: ALL=(ALL) NOPASSWD:ALL groups: sudo, wheel lock_passwd: true ssh_authorized_keys: - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDE0c5FczvcGSh/tG4iw+Fhfi/O5/EvUM/96js65tly4++YTXK1d9jcznPS5ruDlbIZ30oveCBd3kT8LLVFwzh6hepYTf0YmCTpF4eDunyqmpCXDvVscQYRXyasEm5olGmVe05RrCJSeSShAeptv4ueIn40kZKOghinGWLDSZG4+FFfgrmcMCpx5YSCtX2gvnEYZJr0czt4rxOZuuP7PkJKgC/mt2PcPjooeX00vAj81jjU2f3XKrjjz2u2+KIt9eba+vOQ6HiC8c2IzRkUAJ5i1atLy8RIbejo23+0P4N2jjk17QySFOVHwPBDTYb0/0M/4ideeU74EN/CgVsvO6JrLsPBR4dojkV5qNbMNxIVv5cUwIy2ThlLgqpNCeFIDLCWNZEFKlEuNeSQ2mPtIO7ETxEL2Cz5y/7AIuildzYMc6wi2bofRC8HmQ7rMXRWdwLKWsR0L7SKjHblIwarxOGqLnUI+k2E71YoP7SZSlxaKi17pqkr0OMCF+kKqvcvHAQuwGqyumTEWOlH6TCx1dSPrW+pVCZSHSJtSTfDW2uzL6y8k10MT06+pVunSrWo5LHAXcS91htHV1M1UrH/tZKSpjYtjMb5+RonfhaFRNzvj7cCE1f3Kp8UVqAdcGBTtReoE8eRUT63qIxjw03a7VwAyB2w+9cu1R9/vAo8SBeRqw== [email protected]
Please note this step requires that the VM be powered off. All of the commands below use the VMware CLI tool, govc.
Go ahead and assign the path to the VM to the environment variable
VM:export VM="/inventory/path/to/the/vm"
Power off the VM:
⚠️ First Boot ModeTo ensure the next power-on operation results in a first-boot scenario for cloud-init, it may be necessary to run the following command just before powering off the VM:
cloud-init cleanOtherwise cloud-init may not run in first-boot mode. For more information on how the boot mode is determined, please see the First Boot Documentation.
govc vm.power -off "${VM}"
Export the environment variables that contain the cloud-init metadata and userdata:
export METADATA=$(gzip -c9 <metadata.yaml | { base64 -w0 2>/dev/null || base64; }) \ USERDATA=$(gzip -c9 <userdata.yaml | { base64 -w0 2>/dev/null || base64; })
Assign the metadata and userdata to the VM:
govc vm.change -vm "${VM}" \ -e guestinfo.metadata="${METADATA}" \ -e guestinfo.metadata.encoding="gzip+base64" \ -e guestinfo.userdata="${USERDATA}" \ -e guestinfo.userdata.encoding="gzip+base64"
Please note the above commands include specifying the encoding for the properties. This is important as it informs the datasource how to decode the data for cloud-init. Valid values for
metadata.encodinganduserdata.encodinginclude:base64gzip+base64
Power on the VM:
govc vm.power -vm "${VM}" -on
If all went according to plan, the CentOS box is:
Locked down, allowing SSH access only for the user in the userdata
Configured for a dynamic IP address via DHCP
Has a hostname of
cloud-vm
Examples
This section reviews common configurations:
Setting the hostname
The hostname is set by way of the metadata key local-hostname.
Setting the instance ID
The instance ID may be set by way of the metadata key instance-id. However,
if this value is absent then the instance ID is read from the file
/sys/class/dmi/id/product_uuid.
Providing public SSH keys
The public SSH keys may be set by way of the metadata key public-keys-data.
Each newline-terminated string will be interpreted as a separate SSH public
key, which will be placed in distro’s default user’s
~/.ssh/authorized_keys. If the value is empty or absent, then nothing will
be written to ~/.ssh/authorized_keys.
Configuring the network
The network is configured by setting the metadata key network with a value
consistent with Network Config Versions
1 or
2, depending on the Linux
distro’s version of cloud-init.
The metadata key network.encoding may be used to indicate the format of
the metadata key “network”. Valid encodings are base64 and gzip+base64.