diff options
Diffstat (limited to 'doc/rtd/reference/datasources/vmware.rst')
| -rw-r--r-- | doc/rtd/reference/datasources/vmware.rst | 451 |
1 files changed, 451 insertions, 0 deletions
diff --git a/doc/rtd/reference/datasources/vmware.rst b/doc/rtd/reference/datasources/vmware.rst new file mode 100644 index 00000000..5e060769 --- /dev/null +++ b/doc/rtd/reference/datasources/vmware.rst @@ -0,0 +1,451 @@ +.. _datasource_vmware: + +VMware +****** + +This datasource is for use with systems running on a VMware platform such as +vSphere and currently supports the following data transports: + +* `Guest OS Customization`_ +* `GuestInfo keys`_ + +The configuration method is dependent upon the transport. + +Guest OS customisation +====================== + +The following configuration can be set for this datasource in ``cloud-init`` +configuration (in :file:`/etc/cloud/cloud.cfg` or +:file:`/etc/cloud/cloud.cfg.d/`). + +System configuration +-------------------- + +* ``disable_vmware_customization``: true (disable) or false (enable) the VMware + traditional Linux guest customisation. Traditional Linux guest customisation + is customising a Linux virtual machine with a + `traditional Linux customisation specification`_. Setting this configuration + to false is required to make sure this datasource is found in ``ds-identify`` + when using Guest OS customisation transport. + + Default: true + +Datasource configuration +------------------------ + +* ``allow_raw_data``: true (enable) or false (disable) the VMware customisation + using ``cloud-init`` metadata and user data directly. Since vSphere 7.0 + Update 3 version, users can create a Linux customisation specification with + minimal ``cloud-init`` metadata and user data, and apply this specification + to a virtual machine. This datasource will parse the metadata and user data + and configure the virtual machine with them. See + `Guest customisation using cloud-init`_ for more information. + + Default: true + +* ``vmware_cust_file_max_wait``: The maximum amount of clock time (in seconds) + that should be spent waiting for VMware customisation files. + + Default: 15 + +Configuration examples +---------------------- + +1. Create the :file:`/etc/cloud/cloud.cfg.d/99-vmware-guest-customization.cfg` + file with the following content, which will enable VMware customisation and + set the maximum waiting time for the VMware customisation file to 10 + seconds: + + .. code-block:: yaml + + disable_vmware_customization: false + datasource: + VMware: + vmware_cust_file_max_wait: 10 + +2. Create the :file:`/etc/cloud/cloud.cfg.d/99-vmware-guest-customization.cfg` + file with the following content, which will enable VMware customisation but + will only try to apply a traditional Linux Guest Customisation + configuration, and set the maximum waiting time for the VMware + customisation file to 10 seconds: + + .. code-block:: yaml + + disable_vmware_customization: false + datasource: + VMware: + allow_raw_data: false + vmware_cust_file_max_wait: 10 + +VMware Tools configuration +-------------------------- + +`VMware Tools`_ is required for this datasource's configuration settings, as +well as vCloud and vSphere admin configuration. Users can change the VMware +Tools configuration options with the following command: + +.. code-block:: shell + + vmware-toolbox-cmd config set <section> <key> <value> + +The following VMware Tools configuration option affects this datasource's +behaviour when applying customisation configuration with custom scripts: + +* ``[deploypkg] enable-custom-scripts``: If this option is absent in VMware + Tools configuration, the custom script is disabled by default for security + reasons. Some VMware products could change this default behaviour (for + example: enabled by default) via customisation of the specification settings. + + VMware admins can refer to `customization configuration`_ and set the + customisation specification settings. + +For more information, see `VMware vSphere Product Documentation`_ and specific +VMware Tools configuration options. + +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`_: + +.. list-table:: + :header-rows: 1 + + * - Property + - Description + * - ``guestinfo.metadata`` + - A YAML or JSON document containing the ``cloud-init`` metadata. + * - ``guestinfo.metadata.encoding`` + - The encoding type for ``guestinfo.metadata``. + * - ``guestinfo.userdata`` + - A YAML document containing the ``cloud-init`` user data. + * - ``guestinfo.userdata.encoding`` + - The encoding type for ``guestinfo.userdata``. + * - ``guestinfo.vendordata`` + - A YAML document containing the ``cloud-init`` vendor data. + * - ``guestinfo.vendordata.encoding`` + - The encoding type for ``guestinfo.vendordata``. + + +All ``guestinfo.*.encoding`` values may be set to ``base64`` or +``gzip+base64``. + +Features +======== + +This section reviews several features available in this datasource. + +Instance data and lazy networks +------------------------------- + +One of the hallmarks of ``cloud-init`` is +:ref:`its use of instance-data and JINJA queries <instancedata-Using>` -- the +ability to write queries in user and vendor data that reference runtime +information present in :file:`/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 +:file:`/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: + +.. code-block:: bash + + PYTHONPATH="$(pwd)" python3 cloudinit/sources/DataSourceVMware.py + +The above command will result in output similar to the below JSON: + +.. code-block:: 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 (GuestInfo keys transport only) +--------------------------------------------------------------- + +Sometimes the ``cloud-init`` user data 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: + +.. code-block:: yaml + + 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: + +.. code-block:: shell + + 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-ipv4`` +* ``guestinfo.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 a :file:`/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: + +.. code-block:: yaml + + 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 of GuestInfo keys transport +======================================= + +The following series of steps is a demonstration of how to configure a VM with +this datasource using the GuestInfo keys transport: + +#. Create the metadata file for the VM. Save the following YAML to a file named + :file:`metadata.yaml`\: + + .. code-block:: yaml + + instance-id: cloud-vm + local-hostname: cloud-vm + network: + version: 2 + ethernets: + nics: + match: + name: ens* + dhcp4: yes + +#. Create the userdata file :file:`userdata.yaml`\: + + .. code-block:: 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== sakutz@gmail.com + +#. 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``\: + + .. code-block:: shell + + export VM="/inventory/path/to/the/vm" + +#. Power off the VM: + + .. raw:: html + + <hr /> + + ⚠️ <strong>First Boot Mode</strong> + + To 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: + + .. code-block:: bash + + cloud-init clean --logs --machine-id + + Otherwise ``cloud-init`` may not run in first-boot mode. For more + information on how the boot mode is determined, please see the + :ref:`First Boot Documentation <boot-First_boot_determination>`. + + .. raw:: html + + <hr /> + + .. code-block:: shell + + govc vm.power -off "${VM}" + +#. Export the environment variables that contain the ``cloud-init`` metadata + and user data: + + .. code-block:: shell + + 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 user data to the VM: + + .. code-block:: shell + + 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" + + .. note:: + 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.encoding`` and + ``userdata.encoding`` include: + + * ``base64`` + * ``gzip+base64`` + +#. Power on the VM: + + .. code-block:: shell + + govc vm.power -on "${VM}" + +If all went according to plan, the CentOS box is: + +* Locked down, allowing SSH access only for the user in the user data. +* Configured for a dynamic IP address via DHCP. +* Has a hostname of ``cloud-vm``. + +Examples of 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 +: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 +:file:`~/.ssh/authorized_keys`. If the value is empty or absent, then nothing +will be written to :file:`~/.ssh/authorized_keys`. + +Configuring the network +----------------------- + +The network is configured by setting the metadata key ``network`` with a value +consistent with Network Config :ref:`Version 1 <network_config_v1>` or +:ref:`Version 2 <network_config_v2>`, 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``. + + +.. LINKS +.. _Guest OS Customization: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html +.. _GuestInfo keys: https://github.com/vmware/govmomi/blob/master/govc/USAGE.md +.. _traditional Linux customisation specification: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-EB5F090E-723C-4470-B640-50B35D1EC016.html#GUID-9A5093A5-C54F-4502-941B-3F9C0F573A39__GUID-40C60643-A2EB-4B05-8927-B51AF7A6CC5E +.. _Guest customisation using cloud-init: https://developer.vmware.com/docs/17020/vsphere-web-services-sdk-programming-guide--8-0-/GUID-75E27FA9-2E40-4CBF-BF3D-22DCFC8F11F7.html +.. _VMware Tools: https://docs.vmware.com/en/VMware-Tools/index.html +.. _customization configuration: https://github.com/canonical/cloud-init/blob/main/cloudinit/sources/helpers/vmware/imc/config.py +.. _VMware vSphere Product Documentation: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-EB5F090E-723C-4470-B640-50B35D1EC016.html#GUID-9A5093A5-C54F-4502-941B-3F9C0F573A39__GUID-40C60643-A2EB-4B05-8927-B51AF7A6CC5E +.. _property: https://vdc-repo.vmware.com/vmwb-repository/dcr-public/723e7f8b-4f21-448b-a830-5f22fd931b01/5a8257bd-7f41-4423-9a73-03307535bd42/doc/vim.vm.ConfigInfo.html +.. _govc: https://github.com/vmware/govmomi/blob/master/govc + |