/
VSS Command Line Interface (vss-cli) v2021.5.1🎉

VSS Command Line Interface (vss-cli) v2021.5.1🎉

By JM Lopez
May 06, 2021
4 min

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

New Features

compute vm set/get retire: manage retirement requests for vms. (#418. #419, #420)

Commands:

  • compute vm set <id> retire mk

  • compute vm set <id> retire confirm

  • compute vm set <id> retire cancel

  • compute vm set <id> retire send

  • compute vm get <id> retire

  • request retire ls

  • request retire cancel

  • request retire confirm

  • request retire send

  • request retire get

Introducing Virtual Machine Retirement Requests to provide retirement workflows that lets you manage the retirement and deletion of virtual machines and provide automated messages on a given time before the retirement to cancel or confirm the request. Once the retire on date is met, a Virtual Machine Change Request to decommission the instance will be created automatically.

VM Retirement requests can be of two types: 

  • timedelta: days, months and hours from now until retirement.

  • datetime: specific timestamp to retire vm.

For existing instances, you can use the compute vm set <id> retire mk command to set a retirement date or given time until retirement:

vss-cli compute vm set vm-2665 retire --help
Usage: vss-cli compute vm set retire mk [OPTIONS] Retire virtual machine on given time. vss-cli compute vm set <id> retire mk -t timedelta -w <days> -v <hours>,<days>,<months> vss-cli compute vm set <id> retire mk -t datetime -w <days> -v "YYYY-MM-DD HH:MM" Options: -t, --rtype [timedelta|datetime] Retirement request type. [required] -w, --warning-days INTEGER Days before retirement date to notify -v, --value TEXT Value for given retirement type. i.e. <hours>,<days>,<months> [required] -c, --confirm Confirm state change --help Show this message and exit.

For example, if I wanted to set a retirement date for a given virtual machine to be decommissioned on 2021-05-08 00:00 and get a confirmation notification 1 day before:

vss-cli compute vm set vm-2665 retire mk -t datetime --value '2021-05-08 00:00' --warning-days 1



If no warning is set the following message will be prompt for confirmation because the decommissioning process will automatically be executed:

vss-cli compute vm set vm-2665 retire mk -t datetime --value '2021-05-08 00:00' No warning will be sent for confirmation or cancellation. Retirement request will proceed when specified. Are you sure? [y/N]:



The previous command will create a Retirement Request for 2021-05-08 00:00 and a notification will be sent 24 hours before. To verify the retirement request, the command vss-cli compute vm get <id> retire provides information about the request:

vss-cli compute vm get vm-2665 retire --sort created_on,asc id created_on updated_on status vm_moref vm_name retire_on warning warning_on ---- --------------------------- --------------------------- --------------------- ---------- ------------------ --------------------------- ----------- --------------------------- 11 2021-05-06 Thu 13:42:59 EDT 2021-05-06 Thu 13:42:59 EDT CONFIRMATION_REQUIRED vm-2665 2104T-relaxed_kare 2021-05-08 Sat 00:00:00 EDT {'days': 1} 2021-05-07 Fri 00:00:00 EDT

If by the retire_on date, the request hasn't been confirmed, the decommissioning step will not happen until either is confirmed by the email sent, manually confirmed or cancelled:

vss-cli compute vm set vm-2665 retire confirm 11 # to confirm the request vss-cli compute vm set vm-2665 retire cancel 11 # to cancel the request

A more realistic scenario would be to retire an instance 6 months from now and have a notification 15 days before, the value option would have the following notation:

vss-cli compute vm set vm-2665 retire mk -t timedelta --value 0,0,6 --warning-days 15

Improvements

core: update pyvss from v0.18.1 to v2021.5.0 (#426)

core: move from semver to calver (#417)

We have moved to a new versioning schema from semantic versioning. From now on, the VSS Command Line interface will be using calendar versioning, consisting of the year, month and a patch number to indicate a bug-fix release. 

compute vm mk: support for retirement requests. (#424)

Commands:

  • compute vm mk from-clone

  • compute vm mk from-spec

  • compute vm mk from-clib

  • compute vm mk from-image

  • compute vm mk from-template

Virtual Machine Retirement Requests are also available for new virtual machine deployments via the following options:

--retire-type [timedelta|datetime] Retirement request type. --retire-warning INTEGER Days before retirement date to notify --retire-value TEXT Value for given retirement type. i.e. <hours>,<days>,<months>

For instance, if I wanted to deploy a new virtual machine that will be available for 6 months only due to the project requirements and get a notification starting 10 days before the retirement date, the following command would be used:

vss-cli --wait compute vm mk from-clone --source vm-2659 \ -d 'Temporary instance. Planned to be available only 6 months' \ --os ubuntu64Guest --disk 100 --net NET --folder group-v2522 \ --retire-type timedelta --retire-warning 10 --retire-value 0,0,6

compute vm set custom-spec: allow multiple --dns-suffix options for dns search settings. (#423)

Commands:

  • compute vm set custom-spec

The Customization Specification set command now supports multiple --dns-suffix options for dns search settings:

Usage: vss-cli compute vm set custom-spec [OPTIONS] Set up Guest OS customization specification. Virtual machine power state require is powered off. Options: -h, --hostname TEXT OS hostname. [required] -m, --domain TEXT OS domain. [required] -n, --dns TEXT DNS servers list. -i, --interface TEXT Interfaces to customize in json format. -s, --dns-suffix TEXT list of DNS search domains to add to the DNS configuration. --help Show this message and exit.

For instance:

vss-cli compute vm set vm-137 custom-spec --hostname centos-clib \ --dns 10.241.192.8 --dns 128.100.100.128 \ --dns-suffix dept.utoronto.ca --dns-suffix utoronto.ca \ --interface '{"dhcp": true}' --domain dept.utoronto.ca

The dns_suffix also applies for  vm deployment commands as follows:

--custom-spec '{"hostname": "fe1", "domain": "dept.utoronto.ca", "interfaces": [{"dhcp": true}]}, "dns_suffix": ["dept.utoronto.ca", "utoronto.ca"], "dns": ["128.100.100.128", "128.100.100.129"]'

Bug Fixes

request new retry: --wait is ignored (#421)

request change retry: --wait is ignored (#422)

Upgrade

Remember, VSS-CLI documentation is now available in VSS-CLI and the full Change Log is available here. 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.

Related content

University of Toronto - Since 1827