Blog from February, 2023

VSS-CLI v2023.2.1 is available for download via https://pypi.org/project/vss-cli/  or GitLab (internal). Latest version includes the following improvements and bug fixes:

Improvements

compute vm mk from-file: support clone and template build process. (#602)

Description

The easiest and quickest method to deploy any virtual machine on the ITS Private Cloud is using the vss-cli deployment specification. Thanks to this Infrastructure as Code (IaC) implementation, we create declarative infrastructure that can be executed repeatedly and it will have the same result.

Usage: vss-cli compute vm mk from-file [OPTIONS] [FILE_SPEC]

  Create virtual machine from VSS CLI file specification.

  Run the following command to deploy a vm based on a VSS CLI specification
  template:

  vss-cli compute vm mk from-file -s -t shell -e vm.yaml

  Or from an existing vm:

  vss-cli compute vm get <name-or-vm_id> spec --edit vm.yaml

  Edit vm.yaml file and deploy as follows:

  vss-cli compute vm mk from-file <cli-spec>.json|yaml

Options:
  -t, --spec-template [shell|clib|template|clone]
                                  Specification template to load and edit.
  -e, --edit                      Edit before submitting request
  -s, --save                      Save file after editing.
  --help                          Show this message and exit.

To create an empty file specification to deploy a VM from template, just execute the following command:

vss-cli compute vm mk from-file --edit --save 

Once you filled out the required settings, the vss-cli will take the specification and submit a request to the API.

If another VM was going to be deployed as the previous one, just execute a similar command as follows:

vss-cli --wait compute vm mk from-file from-file-1677513149.yaml

compute vm set secure-boot: enable --on or disable --off secure boot (#605)

Description

UEFI secure boot is, as of March 2023, the default firmware in new virtual machines ( Read more Moving towards secure by default Virtual Machines ). This means when you create a virtual machine without specifying a firmware option value, we will use efi and secure-boot. If secure boot is not needed, the following commands are available for managing secure-boot settings.

Usage: vss-cli compute vm set VM_ID_OR_NAME secure-boot [OPTIONS]

  Update virtual machine boot configuration to enable secure boot.

  vss-cli compute vm set <name-or-vm_id> secure-boot --on 
  vss-cli compute vm set <name-or-vm_id> secure-boot --off

Options:
  --on / --off  Enable/Disable secure boot  [required]
  --help        Show this message and exit.

compute vm mk from-file: clib and shell standardization. (#603)

compute vm mk from-file: default firmware set to efi. (#604)

core: upgrade pyvss from 2023.2.0 to 2023.2.1 (#606)

Bug Fixes

compute vm mk set storage-type: missing pyaload_options for scheduling (#607)

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#v2023-2-1-2023-02-24. 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 

# Homebrew users
brew upgrade vss-cli

For more information, please refer to the official documentation https://eis.utoronto.ca/~vss/vss-cli/ .

As of March 2023, the ITS Private Cloud will set the default virtual machine firmware to UEFI (Unified Extensible Firmware Interface) with Secure Boot instead of BIOS (Basic Input/Output System) when deploying a new virtual machine. This move is aimed at strengthening the security of virtual machines “by default”, which is becoming increasingly important as cyber threats continue to evolve. UEFI is a modern firmware interface that provides more security features than BIOS, such as secure boot, which helps protect the system against malware and other malicious attacks.

As a result of this change, users of the ITS Private Cloud will see the default firmware pre-set to UEFI in the both the Cloud Portal and Command-Line Interface (vss-cli). However, we understand this change may be harder to adapt for older operating systems, that is why there will still show BIOS as an option, but please consider the benefits of this change are significant and will help ensure that virtual machines are more secure and compatible with modern hardware and software.

If there is a need to disable secure boot in the Virtual Machine, the Command-Line interface vss-cli provides the following command to do that and won’t be disruptive to the installed Operating System if installed with UEFI secure boot:

vss-cli compute vm set <id> secure-boot --off

In conclusion, the move to set the default virtual machine firmware to UEFI Secure Boot instead of BIOS is a step towards improving the security of the ITS Private Cloud Virtual Machines.

The ITS Private Cloud has offered dynamic Guest OS customization for Linux for a while. This action creates per-instance tasks (update hostname, domain, networking configuration) to make a guest operating system unique after deployment from a source virtual machine or template and avoid network collisions without a lot of effort.

The structure has been simplified in the following JSON/ YAML structure, which is provided in the vss-cli or ITS Private Cloud Portal or the API directly upon deployment:

{
  "hostname": "string",
  "domain": "string",
  "dns": [
    "string"
  ],
  "dns_suffix": [
    "string"
  ],
  "interfaces": [{"dhcp": "bool",
                  "ip": "string",
                  "mask": "string",
                  "gateway": ["string"]
                 }],
  "time_zone": "string|int"
}

For example, cloning a Linux VM with multiple network interfaces and reconfiguring it right after deployment:

{
  "hostname": "db-1",
  "domain": "dept.utoronto.ca",
  "dns": [
    "128.100.100.128"
  ],
  "interfaces": [
    {
      "dhcp": false,
      "ip": "10.6.6.115",
      "mask": "255.255.255.0",
      "gateway": [
        "10.6.6.1"
      ]
    },
    {
      "dhcp": false,
      "ip": "10.6.7.115",
      "mask": "255.255.255.0",
      "gateway": [
        "10.6.7.1"
      ]
    }
  ],
  "time_zone": "America/Toronto"
}

The same example, but for a Windows guest is as follows:

{
  "hostname": "db-1",
  "domain": "dept.utoronto.ca",
  "dns": [
    "128.100.100.128"
  ],
  "interfaces": [
    {
      "dhcp": false,
      "ip": "10.6.6.115",
      "mask": "255.255.255.0",
      "gateway": [
        "10.6.6.1"
      ]
    },
    {
      "dhcp": false,
      "ip": "10.6.7.115",
      "mask": "255.255.255.0",
      "gateway": [
        "10.6.7.1"
      ]
    }
  ],
  "time_zone": 35
}

In both cases, Linux and Windows, are now supported on the ITS Private Cloud API 🎉 either via the Portal, or vss-cli.

Portal

The Web UI supports only JSON format that could be added on the “Other” tab during the Virtual Machine Form:

Command Line

--custom-spec in the vss-cli supports both YAML and JSON either from option value or file reference as follows:

vss-cli compute vm mk --wait from-clone --power-on --source Frontend \
--client EIS --folder APIDemo \
--custom-spec frontend2-custom-spec.json \ 
--description "Frontend 2" Frontend2

vss-cli compute vm mk --wait from-clone --power-on --source Frontend \
--client EIS --folder APIDemo \
--custom-spec frontend2-custom-spec.yaml \
--description "Frontend 2" Frontend2

More examples are found in the vss-cli doc site:

• https://eis.utoronto.ca/~vss/vss-cli/examples/deploy-clone.html

• https://eis.utoronto.ca/~vss/vss-cli/examples/deploy-template.html

What’s next?

Now that we have ventured into the Windows customization, we are considering also support for:

• Sysprep answer file within spec.

• Domain configuration.

Adding features to the ITS Private Cloud is based on demand, so please let us know if any of the above may be helpful to your team.

Finally

If you have any questions, willing to help us testing or feedback about the Guest OS Customization implementation, please do not hesitate contacting us via vss (at) eis.utoronto.ca.

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 and how-to to help deploying a new virtual machine running Microsoft Windows 11 with the ITS Private Cloud Command Line Interface aka vss-cli:

Checklist

• CPU: at least 2 CPUs: --cpu 2
• Memory: at least 8GB: --memory 8
• Disk: at least 64GB: --disk 64
• UEFI and Secure Boot: --firmware efi
• Guest Operating System: --os windows9_64Guest
• vTPM. vTrusted Platform Module (TPM) should be added to virtual instance. --tpm
• VBS. Virtualization-Based Security enabled. --vbs

Command Line Commands

Raw cli

With the following command you will be deploying a Windows 11 virtual machine with the parameters listed above.

vss-cli --wait compute vm mk shell \
--description 'Windows 11 VM' --os windows9_64Guest \
--memory 8 --cpu 2 --folder MyFolder --disk 64 \
--net CGN --iso Microsoft_Windows_11_Enterprise_version_21H2_64-bit_English \
--tpm --vbs --firmware efi --client Client \
--power-on Windows11VM

Another approach would be to use the vss-cli deployment specification.

vss-cli deployment specification

1. Create the following file:

   built: os_install         # Required: Do not remove.
   machine:
       name: Windows11VM         # Required: Target virtual machine name.
       os: windows9_64Guest           # Required: Guest Operating System name or Id.
       cpu: 2                # Optional: CPU count (Default: 1).
       memory: 8             # Optional: Memory in GB (Default: 1GB).
       folder: MyFolder      # Required: Folder name, path or ID.
       storage-type: hdd     # Optional: Storage Type to use for this VM. ssd or hdd
       disks:
          -  capacity_gb: 64          # Disk capacity in GB (Default: 40GB).
       iso: dae52f28-4ae9-4492-8ca2-691809006867           # Optional: ISO name or path to mount upon creation.
       firmware: efi         # Optional: Firmware to use: Either bios or efi (Default: bios).
   # Additional (Uncomment to enable)
       power_on: true         # Optional: Power on after successful deployment.
       tpm: true              # Optional: Enable vTrusted Platform Module Device.
       vbs: true              # Optional: Enable Virtualization Based Security.
   #   template: false        # Optional: Mark resulting vm as template.
   #   domain:                # Optional: Domain name or ID to deploy (Default: provided by API).
   # VM extra configuration (Uncomment to enable)
   # extra-config:
   #  - disk.EnableUUID="TRUE"
   networking:
       interfaces:
          -  network: CGN    # Required: Network name or network ID.
             type: vmxnet3   # Optional: Defaults to vmxnet3
   # metadata required
   metadata:
       client: Client       # Required: Client department
     # Required: Description of virtual machine
       description: Testing windows 11 deployment
       usage: Test           # Optional: Usage between Prod | Dev | QA | Test (default: Test)
       inform:               # Optional: list of additional contact email addresses (default: user account)
          -  user@utoronto.ca
   #  admin:                  # Optional: VM Administrator (Default: user submitting request)
   #    name:                 # (Admin) Required: VM Administrator full name
   #    email:                # (Admin) Required: VM Administrator email i.e. user@utoronto.ca
   #    phone:                # (Admin) Required: VM Administrator phone i.e. 416-123-2341
   # Recommended Metadata (Uncomment to enable)
   # notes:                  # Optional: list of key-value items to be set in Key: value form.
   #   - BillingCode: 12345
   #   - Documentation: https://uoft.me/service-docs
   #    vss_service: N/A        # Optional: VSS Service name or service id
   # vss_options:            # Optional: VSS options reset_on_restore, reboot_on_restore
   #   - reset_on_restore
   #   - reboot_on_restore

2. Save the file as win11.yaml and deploy it as follows:

   vss-cli --wait compute vm mk from-file win11.yaml

3. By using this method, you could replicate this deployment in the future.

Cloud Portal UI

Starting from version 1.10.2, Cloud Portal introduces the capability to create virtual machines equipped with Windows 11. It's crucial to ensure you carefully select the appropriate operating system, ISO image, and activate both Trusted Platform Module and Virtualization-based Security for optimal performance and security.

Troubleshooting

If a step was missed, the Windows 11 installation process may display an error:

Please review all the steps outlined in the Checklist. Below are suggested steps to verify your virtual machine configuration using the vss-cli commands:

1. Verify the CPU cores (cpu) are 2 or more:

   vss-cli compute vm get <VM_ID> cpu

2. Verify the memory (memory_gb) is 8GB or more:

   vss-cli compute vm get <VM_ID> memory

3. Verify the disk space (capacity_gib) is 64GB or more:

   vss-cli compute vm get <VM_ID> disk

4. Verify the firmware selected is efi

   vss-cli compute vm get <VM_ID> firmware

5. Verify the Guest Operating System (guest.guest_id) is windows9_64Guest

   vss-cli compute vm get <VM_ID> os

6. Verify there is a Trusted Platform Module (vTPM) configured with label, summary and key.

   vss-cli compute vm get <VM_ID> tpm

7. Verify the Virtualization-Based Security (vbs_enabled) is enabled (True).

   vss-cli compute vm get <VM_ID> vbs

Frequently, users overlook creating a Trusted Platform Module or enabling the Virtualization-Based Security setting. Here are steps to create them using vss-cli commands:

1. Create a Trusted Platform Module (vTPM)

   vss-cli compute vm set <VM_ID> tpm mk

2. Enable Virtualization-Based Security setting

   vss-cli compute vm set <VM_ID> vbs on

After completing the virtual machine update, please proceed to reboot the system..

References:

https://www.microsoft.com/en-in/windows/windows-11-specifications#table3

https://kb.vmware.com/s/article/86207

VSS-CLI v2023.2.0 is available for download via https://pypi.org/project/vss-cli/  or GitLab (internal). Latest version includes the following improvements and bug fixes:

Improvements

compute vm get/set vss-preference: manage VSS preferences in virtual machine metadata (#597)

Commands:

• compute vm get <id> vss-preference

• compute vm set <id> vss-preference --action=add|del <preference>

Description

There are times we need to balance workload in our environment or perform preventive maintenance and these examples, require moving virtual machines from datastore cluster to another. Some workloads are more susceptible to IO than others and may be impacted when moved from SSD to HDD backed datastore clusters. On that note, we have come up with a method set “preferences” in the virtual machine metadata that will help us identifying certain requirements and most importantly, do our best to honour them.

For this first iteration, we are introducing the ssd preference, which specifies that a given VM preferred storage is ssd. To set this value, use the following command:

vss-cli compute vm set <id> vss-preference ssd --action add

Once set, you could verify with the following commands:

vss-cli compute vm get <id> vss-preference
preferences         : ssd

or

vss-cli --columns moref,folder.path,name,preferences,storage_type compute vm ls 
moref     folder.path                                   name                       preferences    storage_type
--------  --------------------------------------------  -------------------------  -------------  --------------
vm-18151  VSS > Sandbox > jm                            2208T-mystifying_meninsky  ssd            ssd
vm-20159  VSS > Sandbox > jm                            2209T-test-ubuntu-clone                   hdd

core: upgrade minio to 7.1.13. (#583)

core: upgrade pyvss to 2023.2.0. (#584)

Bug Fixes

compute vm mk from-file: additional_params incorrectly parsed name and file. (#595)

compute vm mk from-file: shell/ clib issue in template disks spec. (#598)

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#v2023-2-0-2023-02-16 . 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 

# Homebrew users
brew upgrade vss-cli

For more information, please refer to the official documentation https://eis.utoronto.ca/~vss/vss-cli/ .