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

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:

 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

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.