.. _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 />

      &#x26a0;&#xfe0f; <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