ITS Private Cloud Command Line Interface
Project description
ITS Private Cloud Command Line Interface vss-cli
The ITS Private Cloud Command-Line Interface vss-cli
simplifies the interaction with the
[ITS Private Cloud API][ITS Private Cloud API] to manage your virtual machines and other services.
Documentation
Package documentation is now available at docs.
Installation
Windows users, follow the installation instructions [Installing Python on Windows][Installing Python on Windows] and add
%USERPROFILE%\AppData\Roaming\Python\Python37\Scripts
toPATH
environment variable prior running pip.
PIP
The fastest way to install VSS CLI is to use pip:
pip install vss-cli
If you are planning to interact with vskey-stor
execute the following command
pip install 'vss-cli[stor]'
The command will install minio
package from PyPI.
Windows users, please install
windows-curses
andvss-cli
as follows:pip install --user vss-cli windows-curses
.
If you have the VSS CLI installed and want to upgrade to the latest version you can run:
pip install --upgrade vss-cli
Homebrew
Use Homebrew to install the vss-cli
on macOS:
brew tap vss/vss-cli https://github.com/EIS-ITS/vss-cli
brew install vss-cli
Using Homebrew will automatically setup autocompletion based on your current shell.
From Source
You can also just download the tarball.
Once you have the vss-cli
directory structure on your workstation, you can just run:
cd path_to_vss-cli
python setup.py install
Docker
If you do not have a Python setup you can try using vss-cli
via a container using Docker.
docker run uofteis/vss-cli
docker-vss-cli is a helpful script to run the vss-cli
within a
docker container. Just download or move the file and update the environment variables if required,
give execution permission and move it to your $PATH
:
# U of T
curl https://gitlab-ee.eis.utoronto.ca/vss/vss-cli/raw/main/docker/docker-vss-cli > vss-cli
chmod +x vss-cli
# Public
curl https://raw.githubusercontent.com/EIS-ITS/vss-cli/main/docker/docker-vss-cli > vss-cli
chmod +x vss-cli
CLI Releases
The release notes for the VSS CLI can be found CHANGELOG in the gitlab repo.
Getting Started
Before using VSS CLI, you need setup your VSS credentials. You can do this in a couple of ways:
- Configuration file
- Environment variables
- Command Line Input
The quickest way to get started is to run the vss-cli configure mk
command:
vss-cli configure mk
Endpoint [https://cloud-api.eis.utoronto.ca]:
Username: jm
Password:
Repeat for confirmation:
To use environment variables, set VSS_USER
and VSS_USER_PASS
or VSS_TOKEN
:
export VSS_USER=USER
export VSS_USER_PASS=superstrongpassword
# or
export VSS_TOKEN=JWT_TOKEN
For detailed information about the vss-cli
configuration, please refer to the
official documentation site.
JSON/YAML Parameter Input
VSS CLI options vary from simple string, boolean, numeric values, JSON data structures and file in both JSON and YAML as input parameters on the command line.
For example, consider the following command to deploy a new virtual machine from a given template and provide a guest operating system specification to reconfigure hostname, domain, dns, ip, subnet and gateway:
vss compute vm mk from-template --source VM-Template \
--description 'New virtual machine' \
--custom-spec '{"hostname": "fe1", "domain": "eis.utoronto.ca", "interfaces": [{"dhcp": true}]}'
However, if a file is provided instead with a JSON or YAML structure,
the CLI will take it as valid such as new-vm-custom-spec.json
or
new-vm-custom-spec.yaml
shown below:
{
"hostname": "fe1",
"domain": "eis.utoronto.ca",
"interfaces": [
{
"dhcp": true
}
]
}
or
hostname: fe1
domain: eis.utoronto.ca
interfaces:
- dhcp: true
vss compute vm mk from-template --source VM-Template \
--description 'New virtual machine' \
--custom-spec new-vm-custom-spec.json
Auto-completion
Bash completion support is provided by Click and will complete sub commands and parameters. Sub commands are always listed whereas parameters only if at least a dash has been provided. Example:
vss-cli compute <TAB><TAB>
account compute configure request stor token
vss-cli -<TAB><TAB>
--config --no-verbose --output --verbose --version -c -o
Activating bash
or zsh
completion can be done by executing the following commands:
For bash
:
source <(vss-cli completion bash)
For zsh
:
source <(vss-cli completion zsh)
For fish
_VSS_CLI_COMPLETE=fish_source vss-cli > ~/.config/fish/completions/vss-cli-complete.fish
If you do it from your .bashrc
or .zshrc
it is recommended to use the following method
since avoids triggering a run of vss-cli itself.
For bash
:
eval "$(_VSS_CLI_COMPLETE=bash_source vss-cli)"
For zsh
:
eval "$(_VSS_CLI_COMPLETE=zsh_source vss-cli)"
For fish
:
eval (env _VSS_CLI_COMPLETE=fish_source vss-cli)
VSS Shell
The VSS CLI provides a REPL interactive shell with tab-completion, suggestions and command history.
Usage: vss shell [OPTIONS]
REPL interactive shell.
Options:
-i, --history TEXT File path to save history
--help Show this message and exit.
To enter the shell just execute vss shell and you will get the following welcome message:
__ _____ ___
\ \ / / __/ __| API Endpoint: https://cloud-api.eis.utoronto.ca/v2
\ V /\__ \__ \ Tab-completion & suggestions
\_/ |___/___/ Prefix external commands with "!"
CLI v20xx.0.0 History is saved: /Users/user/.vss-cli/history
Exit shell with :exit, :q, :quit, ctrl+d
vss (cloud-api) >
Getting Help
We use GitLab issues for tracking bugs, enhancements and feature requests. If it turns out that you may have found a bug, please open a new issue.
vss-cli --help
Usage: vss-cli [OPTIONS] COMMAND [ARGS]...
Command line interface for the ITS Private Cloud.
Options:
-e, --endpoint TEXT The Cloud API endpoint URL
-c, --config TEXT Configuration file
-t, --token TEXT The Bearer token for the VSS API.
-u, --username TEXT The API username for VSS API.
-p, --password TEXT The API password for VSS API.
--totp TEXT Timed One Time Password.
--timeout INTEGER Timeout for network operations.
-l, --loglevel LVL Either CRITICAL, ERROR, WARNING, INFO or
DEBUG
-v, --verbose Enables verbose mode.
--debug Enables debug mode.
-x Print back traces when exception occurs.
-o, --output [json|yaml|table|auto|ndjson]
Output format (default: auto).
--table-format TEXT Which table format to use (default: simple)
--columns TEXT Custom columns key=value list. Example:
VM=moref,PROVISIONED=storage.provisionedGB
--columns-width INTEGER Truncates column values (0: auto, -1:
disable).
--wait / --no-wait wait for request(s) to complete
-n, --no-headers When printing tables don't use headers
(default: print headers)
-s, --sort-by TEXT Sort table by the jsonpath expression.
Example: updated_on
-w, --s3-server TEXT The Webdav server.
--version Show the version and exit.
--help Show this message and exit.
Commands:
account Manage your VSS account
completion Output shell completion code for the specified shell (bash or
zsh or fish).
compute Manage VMs, networks, folders, etc.
configure Configure VSS-CLI options.
key Manage your SSH Public Keys.
message Manage VSS Messages.
misc Miscellaneous utilities.
ovf OVF Tool
plugins External plugins.
raw Make a raw call to the API
request Manage various requests
service ITS Service catalog.
shell REPL interactive shell.
status Check ITS Private Cloud Status.
stor Manage your VSS storage account.
token Manage access tokens
upgrade Upgrade VSS CLI and dependencies.
Versioning
The vss-cli
versions are tagged based on Calendar Versioning. Versions available in the
tags section or PyPI package section.
Contributing
Refer to the Contributing Guide and Contributors for details on our code of conduct and the process of submitting code to the repository.
Changelog 📝
Refer to the Changelog for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for vss_cli-2024.9.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f3634db61c0db201751d74e46172ec79b657556a0451553bf26227d1e48509b2 |
|
MD5 | da6d8836b2c297fcf01e9302ddd8b09e |
|
BLAKE2b-256 | b8ab326f6ddb9c198cf92a4887fc81803a3943e5586cec8c505a654c3c52f249 |