How-to deploy a VMware Photon OS VM pre-configured with the vss-cli in minutes

VMware Photon OS

Photon OS, is an open-source minimalist Linux operating system from VMware that is optimized for cloud computing platforms, VMware vSphere deployments, and applications native to the cloud. Photon OS is a Linux container host optimized for vSphere and cloud-computing platforms such as Amazon Elastic Compute and Google Compute Engine. More info is available

The ITS Private Cloud supports VMware Photon OS and offers two deployment methods: as OVF in our Public Content Library and as ISO file to proceed with manual installation. Deploying a VM via the content library is the quickest method to get a VM up and running in matter of minutes. However, customizing the operating system may get complex sometimes. To speed up the deployment and configuration, the minimal and full versions of Photon OS include the cloud-init service as a built-in component.

cloud-init is a set of Python scripts that initialize cloud instances of Linux machines to customize the instance without user interaction. The commands can set the root password, set a hostname, configure networking, write files to disk, upgrade packages, run custom scripts, and restart the system.

In the ITS Private Cloud, cloud-init has been used by the community for many years now, however it focused mostly on Ubuntu OS by implementing the Cloud-Init seed ISO data source, which creates a ISO image with both user-data and metadata files then read by cloud-init). In this tutorial we demonstrate the power of cloud-init's VMware datasource using VM’s guestinfo interface with the vss-cli.

VMware guestinfo Interface

The data source is configured by setting guestinfo properties on a VM's extra-config data listed in the following table:






A YAML or JSON document containing the cloud-init metadata.


The encoding type for guestinfo.metadata.


A YAML document containing the cloud-init user data.


The encoding type for guestinfo.userdata.


A YAML document containing the cloud-init vendor data.


The encoding type for guestinfo.vendordata.

All guestinfo.*.encoding property values may be set to base64 or gzip+base64.

ITS Private Cloud Command Line Interface vss-cli

The vss-cli allows you to set custom extra configuration settings in most of the compute vm mk * subcommands via the --extra-config option. Providing multiple key=value items, allows you to set any guestinfo.* property directly from the deployment process, i.e.:

vss-cli compute vm mk from-clib --extra-config guestinfo.metadata.encoding=gzip+base64 ....


The following steps guides you through the configuration of a VM deployed from the Content Library with cloud-init and the VMware datasource.

  1. Login to the or or with your local vss-cli installation.

    1. If running a local install, make sure you are running the latest vss-cli version via vss-cli upgrade.

  2. Create a userdata.yaml with all the users, packages and custom settings that you plan to use (examples are available ):

    #cloud-config hostname: its-cloud-vm1 timezone: America/Toronto fqdn: chpasswd: list: | root:your_secure_password_here expire: False users: - name: root lock_passwd: true - name: vss-user sudo: ALL=(ALL) NOPASSWD:ALL passwd: $6.... groups: sudo, wheel lock_passwd: true ssh_authorized_keys: - ssh-rsa AAAA.... packages: - git - sudo - bindutils write_files: - path: /etc/motdgen.d/ permissions: '0755' content: | #!/bin/bash INSTANCE_ID=`vmware-rpctool "info-get"` INSTANCE_NAME=`vmware-rpctool "info-get"` printf "\n" printf " University of Toronto ITS Private Cloud Instance\n" printf "\n" printf " Name: $INSTANCE_NAME\n" printf " ID: $INSTANCE_ID\n" printf "\n" package_update: true package_upgrade: true package_reboot_if_required: true power_state: delay: now mode: reboot message: Rebooting the OS condition: if [ -e /var/run/reboot-required ]; then exit 0; else exit 1; fi # Optional: Cleanup guestinfo.userdata* and guestinfo.vendordata* # uncomment the following lines to enable. # cleanup-guestinfo: # - userdata # - vendordata final_message: "The system is finally up, after $UPTIME seconds"
    1. Note that passwd hash is required to update the root password or any other user password. The vss-cli has the utility to hash strings: vss-cli misc hash-string NewPassword123

  3. Create metadata.yaml with the instance and networking configuration :

    instance-id: its-cloud-vm1 local-hostname: its-cloud-vm1 network: version: 2 ethernets: nics: match: name: ens* dhcp4: yes
    1. More examples can be found

  4. Run the following command to deploy instance assigning the userdata.yaml and metadata.yaml encoded as specified in the guestinfo.*.encoding option.

    1. Note that you should replace the --folder option value with a folder you have access to.

  5. When the previous command completes, you should get the allocated IP address in the “warnings” section:

  6. If all went well, you should be able to login via the allocated IP address included in the email and ssh access should available:


  7. There you go! We have a fully functional pre-configured virtual machine with UEFI and secure boot ready for action.

Cleaning up

If you did not include the cleanup-guestinfo directive in the userdata.yaml descriptor for debugging purposes, now that the OS is running and configured, it is recommended to manually cleanup the guestinfo.userdata* and guestinfo.vendordata* with the following commands:

Verify with the following commands:


University of Toronto - Since 1827