Blog from October, 2022

VSS Command Line Interface (vss-cli) v2022.10.1
JM Lopez posted on Oct 22, 2022

VSS-CLI v2022.10.1 is available for download via PyPI or GitLab. Latest version includes the following improvements and bug fixes:

New Features

ovf get: to inspect and generate additional-params spec file from OVA or OVF. (#571)

Commands

  • ovf get <ova_or_ovf_path

  • ovf get <ova_or_ovf_path> property-params

  • ovf get <ova_or_ovf_path> deployment-params

  • ovf get <ova_or_ovf_path> params-spec

Description

Back on v2022.5.0, we introduced the option --additional-params to support OVF PropertyParams and DeploymentOptionParams to use the pre-defined vApp options and pre-configure the appliance. Many “cloud images” like Ubuntu OS and Cisco OVA have these defined in the OVF.

However, getting this configuration from the OVF is not as simple as it seems. The ovf command goal is to simplify the process of obtaining and generating yaml specification file without much intervention and even without unpacking an ova . The only limitation (for now) is that the OVA must be locally available.

For instance, If we plan to deploy the following Ubuntu VM using a cloud image available in our Content Library:

vss-cli compute contentlib ovf ls  -f name=jammy
id                                name                              library.name         size
--------------------------------  --------------------------------  --------------  ---------
8261093e-281a-42db-8d1c-1c2f68e…  Ubuntu-22.04.jammy-server-cloud…  VSS-Nix         841781847

which can be downloaded from jammy-server-cloudimg-amd64.ova and to your workstation, you could run vss-cli ovf get jammy-server-cloudimg-amd64.ova to obtain a summary of the OVF:

Name                : ubuntu-jammy-22.04-cloudimg-20221019
ProductVersion      : None
Networks            : VM Network
Files               : ubuntu-jammy-22.04-cloudimg.vmdk
DeploymentOptionParams:
PropertyParams      : instance-id, hostname, seedfrom, public-keys, user-data, password

Tada! 🎉 we have retrieved the minimum info from the OVA. Now, if you would like to know more, try running the command with the --output yaml option at the top level.

From the previous output, we know that the OVF only has PropertyParams, but how do we use them? We have two options:

  1. Run vss-cli --columns-width=0 ovf get jammy-server-cloudimg-amd64.ova property-params to get text output of the key, type, description and default value: 

    vss-cli --columns-width=0 ovf get jammy-server-cloudimg-amd64.ova property-params
key          type    description                       default
-----------  ------  --------------------------------  -----------
instance-id  string  Specifies the instance id.  Thi…  id-ovf
hostname     string  Specifies the hostname for the …  ubuntuguest
seedfrom     string  This field is optional, but ind…  None
public-keys  string  This field is optional, but ind…
user-data    string  In order to fit into a xml attr…
password     string  If set, the default user's pass…

  2. Run vss-cli ovf get jammy-server-cloudimg-amd64.ova params-spec --edit to create an additional-params.yaml specification for you to edit in your default text editor. The best part is that it will pre-set any default value and will add comments at the bottom of the screen for guidance. After saving the changes, the vss-cli saves the yaml specification for you to use: 

    PropertyParams:
    instance-id: id-ovf
    hostname: ubuntuguest
    seedfrom:
    public-keys: ''
    user-data: ''
    password: ''


# PropertyParams:
# instance-id (string): Specifies the instance id.  This is required and used to determine if the machine should take "first boot"
 actions
# ....
Written to jammy-server-cloudimg-amd64-additional-params.yaml

Improvements

compute vm mk: option --custom-spec load from yaml/json file or input (#568)

Commands:

  • compute vm mk shell

  • compute vm mk from-clone

  • compute vm mk from-spec

  • compute vm mk from-template

Description

Applying Guest Customization Specification to a cloned instance is a popular feature and has been around for a while supporting only a json string from input via --custom-spec. However, it has been always challenging to type a long string along with the other options in a deployment command and even more difficult in JSON format. As you may know,YAML goal is to be human-readable, whereas JSON is to be a universally used and machines oriented.

Taking this into account, we have finally rolled out support for both .json and .yaml files or string values in the option. This means that your existing commands could be simplified as follows:

vss-cli compute vm mk from-clone --source vm-xxx -d 'testing vm deployment' \
--custom-spec custom-spec-vm-1.json ...

or 

vss-cli compute vm mk from-clone --source vm-xxx -d 'testing vm deployment' \
--custom-spec custom-spec-vm-1.yaml ...

On this note, either of the following specs will work as the --custom-spec value:

hostname: hostname
domain: eis.utoronto.ca
dns:
  - 128.100.100.120
# dns_suffix:
#   - string
interfaces:
  - dhcp: false
    ip: 10.6.0.12
    mask: 255.255.255.0
    gateway:
      - 10.6.0.254
{
  "hostname": "hostname",
  "domain": "eis.utoronto.ca",
  "dns": [
    "128.100.100.120"
  ],
#  "dns_suffix": [
#    "string"
#  ],
  "interfaces": [{"dhcp": false,
                  "ip": "10.6.0.12",
                  "mask": "255.255.255.0",
                  "gateway": ["10.6.0.254"]
                 }]
}

If you have an existing custom-spec.json file, you could easily convert it to yaml with the yq utility: https://github.com/mikefarah/yq i.e. yq eval -P custom-spec.json> custom-spec.yaml.

compute vm mk: option --vbs to enable Virtualization Based Security (#572)

Commands:

  • compute vm mk shell

  • compute vm mk from-clone

  • compute vm mk from-spec

  • compute vm mk from-template

Description

Version v2022.8.0 introduced VBS management in the vss-cli, and now we have made available the option --vbs to do the following tasks in a single op:

  • Use efi firmware.

  • Enable secure boot on virtual machine.

  • Enable vvtd on virtual machine.

  • Enable vbs on the virtual machine.

  • Add a virtual tpm device.

If you were to deploy a Windows 11 virtual machine, your command would look like:

vss-cli --wait compute vm mk shell \
--description "Windows 11 workstation for User" \
--client Client --os windows9_64Guest --memory 6 --cpu 2 \
--folder 'Public > Client' --disk 500 \
--net dvportgroup-XXXX \
--iso "Microsoft_Windows_11_Enterprise_version_21H2_(updated_Nov_2021)_64-bit_English" \
--tpm --vbs --power-on client-win11

compute vm mk from-file: option vbs to enable Virtualization Based Security (#573)

Description

A new attribute has been added to the machine section in the file.yaml specification file:

built: clib         # Required: Do not remove.
machine:
  item: ubuntu-22.04   # Required: Source content library id OVF.
  name: Vm-Name           # Required: Target virtual machine name.
  os: ubuntu64Guest       # Required: Guest Operating System name or Id.
  folder: Name-or-Id      # Required: Folder name, path or ID.
  storage-type: hdd       # Optional: Storage Type to use for this VM. ssd or hdd
#  domain:                # Optional: Domain name or ID to deploy (Default: provided by API).
#  power_on: true         # Optional: Power on after successful deployment.
#  template: false        # Optional: Mark resulting vm as template.
#  tpm: true              # Optional: Enable vTrusted Platform Module Device.
#  vbs: true              # Optional: Enable Virtualization Based Security.

misc: process value from input or file (#574)

Commands:

  • misc b64d-gz

  • misc gz-b64e

  • misc hash-string

Description

The misc helper commands are useful when dealing with additional tasks like compressing and encoding data such as userdata.yaml and generating hashed strings from passwords. For example, compressing and encoding a given userdata.yaml can now be done:

# as string
vss-cli misc gz-b64e "$(cat userdata.yaml)"

# file
vss-cli misc gz-b64e userdata.yaml

docs: example to deploy Photon OS from clib. (#575)

docs: example update clib deployment user data. (#576)

compute vm set <id> storage-type: set to either ssd or hdd (approval required). (#563)

compute vm get <id> storage-type: get current virtual machine storage type. (#564)

core: upgrade pyvss to v2022.10.0. (#565)

Upgrade

Remember, VSS-CLI documentation is now available in VSS-CLI and the full Change Log is available http://eis.utoronto.ca/~vss/vss-cli/changelog.html . Upgrade or install VSS-CLI as follows:

# using vss-cli
vss-cli upgrade 

# upgrade with pip
pip install vss-cli --upgrade

# install
pip install vss-cli

For more information, please refer to the official documentation site.

Upgrade your Microsoft Windows 10 VM to 11 on the ITS Private Cloud
JM Lopez posted on Oct 14, 2022

Based on the https://www.microsoft.com/en-ca/windows/windows-11-specifications?r=1#:~:text=System%20firmware-,UEFI,-%2C%20Secure%20Boot%20capable , we have gathered the following checklist to help bringing your Windows 10 to the latest Windows 11.

Pre-Upgrade checklist

  • UEFI and Secure Boot. Existing Windows 10 virtual instance should be using UEFI and Secure Boot. Check status with If you would like to migrate from bios to efi, please read the following Microsoft document https://learn.microsoft.com/en-us/windows/deployment/mbr-to-gpt
  • Guest Operating System. Virtual machine configured operating system should match the running operating system. Check with vss-cli --columns moref,name,guest_full_name,guest_full_name_run compute vm ls -f name={vm-name} both must be the same.
  • Virtual Machine Version. Recommended Virtual Machine version is vmx-19. If your instance version is lower, perform an upgrade: vss-cli compute vm set <id> version vmx vmx-19.
  • vTPM. vTrusted Platform Module (TPM) should be added to virtual instance: vss-cli compute vm set <id> tpm mk.
  • VBS. Virtualization-Based Security enabled. If disabled, please enable with: vss-cli compute vm set <id> vbs on

Upgrade process

The following steps were contributed and tested by joint efforts between the Client Success & Service Delivery team (Andrew Tomkins, thank you!) and the ITS Private Cloud team at EIS.

  1. Shut down the system (full shut down) 

    vss-cli --wait compute vm set <id> state shutdown --confirm

  2. Power on the virtual machine (system then picks up new chipset identifiers) 

    vss-cli --wait compute vm set <id> state on

  3. Proceed with upgrade as you like (e.g. by mounting an ISO or using Windows Update). To mount the ISO execute:

    vss-cli --wait compute vm set <id> cd up --backing Windows_11

Questions

As always please reach out to vss (at) eis.utoronto.ca if you have any questions or experience any issues.

Announcing VSS-CGN network available at the ITS Private Cloud
JM Lopez posted on Oct 07, 2022

We are excited to announce the general availability of a new Network using RFC 6598 address space, and the UofT institutional Carrier-Grade NAT appliance (CGNAT). With the EIS-VSS-CGN network we are able to avoid NAT between departmental networks and the campus backbone; instead using NAT only when the traffic needs to leave the campus to traverse the internet.

The EIS-VSS-CGN network works just like the VSS-PUBLIC network: IP addresses are assigned based on the NIC MAC Address and managed by DHCP. When you deploy a virtual machine or updating an existing virtual machine, you will get confirmation email indicating which IP address has been allocated to the network interface.

When a virtual machine is decommissioned and has an IP address from EIS-VSS-CGN, it will be released and put back into the pool.

Virtual machines using the EIS-VSS-CGN network will only be accessible via UofT IP addresses on-campus or via the institutional VPN service https://isea.utoronto.ca/services/vpn/utorvpn/.