CLI User Guide

The portal-whitesky-cloud tool allows you to manage resources (such as VMs and vdisks) at a location on the command line. It is available for Linux, Windows and OS X operating systems (x86-64 only).

Installation

To install portal-whitesky-cloud you can download the latest CLI for your platform from the Downloads section.

Alternatively, you can download the CLI binary using curl

jwt=<YOUR JWT TOKEN>
curl -X GET "https://portal.whitesky.cloud/api/1/utilities/cli?platform=linux" -H  "accept: application/zip" -H "Authorization: Bearer $jwt" --output portal-whitesky-cloud.zip --output portal-whitesky-cloud.zip

After downloading, unpack the archive. Unpacking the archive will yield the portal-whitesky-cloud binary (NB: portal-whitesky-cloud.exe on Windows).

On linux-based systems, add the nessesary permissions to the binary chmod +x portal-whitesky-cloud.

Adding tab completion

To load completions use this command:

$ ./portal-whitesky-cloud completion --help

Bash

$ source <(portal-whitesky-cloud completion bash)

# To load completions for each session, execute once:
# Linux:
$ portal-whitesky-cloud completion bash > /etc/bash_completion.d/portal-whitesky-cloud
# macOS:
$ portal-whitesky-cloud completion bash > /usr/local/etc/bash_completion.d/portal-whitesky-cloud

Zsh

# If shell completion is not already enabled in your environment,
# you will need to enable it.  You can execute the following once:

$ echo "autoload -U compinit; compinit" >> ~/.zshrc

# To load completions for each session, execute once:
$ portal-whitesky-cloud completion zsh > "${fpath[1]}/_portal-whitesky-cloud"

# You will need to start a new shell for this setup to take effect.

Fish

$ portal-whitesky-cloud completion fish | source

# To load completions for each session, execute once:
$ portal-whitesky-cloud completion fish > ~/.config/fish/completions/portal-whitesky-cloud.fish

PowerShell

PS> portal-whitesky-cloud completion powershell | Out-String | Invoke-Expression

# To load completions for every new session, run:
PS> portal-whitesky-cloud completion powershell > portal-whitesky-cloud.ps1
# and source this file from your PowerShell profile.

Usage

./portal-whitesky-cloud completion [bash|zsh|fish|powershell]
[...]

Updating the CLI

The CLI checks for the availability of updates automatically and will notify the user if a new version is available:

$ ./portal-whitesky-cloud version --json

{
"app_name": "portal-whitesky-cloud",
"branch": "HEAD",
"build_date": "2021-04-15T09:53:58Z",
"build_host": "portal-whitesky-cloud-builder-mds9t",
"version": {
"cli_version": "0.2.0-dirty",
"api_version": "2021-04-15T09:53:58Z-unknown"
},
"api_hash": "b3086d6d4baa39f55969dda0136f766de7d49a4932f1659bbb04347f6a54dee1",
"default_update_location": "https://portal.whitesky.cloud/api/1/utilities/cli?platform=windows",
"api_url": "portal.whitesky.cloud/api/1"
}

Alternatively, there's also an explicit check for the latest version available:

$ ./portal-whitesky-cloud update show

This command here will perform an update:

$ ./portal-whitesky-cloud update install

Documentation

The CLI is self-documenting: any portal-whitesky-cloud command line accepts a --help flag providing information about its arguments and flags.

Automation

To support automation (scripting), portal-whitesky-cloud command lines accept a --json flag which provides output in JSON format to stdout to ease further processing.

Configuration

To avoid having to specify the authentication token to connect to the portal-whitesky-cloud API on each command line, the CLI stores this information in a configuration file (default directory on Linux: $HOME/.config/portal-whitesky-cloud, can be overridden with the --config flag). Modification of the configuration database also happens through the CLI.

Authentication using JWT

Authentication is achieved by using JWT tokens. To access a valid JWT token

Go to the whitesky.cloud BV portal.
Click APIS in the navigation drawer on the left side of the page.
Click Copy JWT to copy the JWT token, you can also click the downward-facing arrow icon to display the JWT token.

To configure the JWT token in portal-whitesky-cloud

Linux

$ echo $JWT | ./portal-whitesky-cloud config auth-token update

Windows

$ .\portal-whitesky-cloud.exe config auth-token update

The JWT is refreshed automatically behind the scenes when the CLI is in use. Conversely, if the CLI hasn't been used for a while the JWT can expire and a new one needs to be obtained and configured.

Examples

Listing locations

To get a list of the available locations for a customer

Linux

$ ./portal-whitesky-cloud customers list-customer-locations --customer-id [string]

Payload:
    {
    "currency": "USD",
    "locations": [
        {
        "location": "be-loc-dc01-001",
        "resources": {
            "mu": 0,
            "nu": 0,
            ...
        }
    ]
    }

Windows

$ .\portal-whitesky-cloud.exe customers list-customer-locations --customer-id [string]

Payload:
    {
    "currency": "USD",
    "locations": [
        {
        "location": "be-loc-dc01-001",
        "resources": {
            "mu": 0,
            "nu": 0,
            ...
        }
    ]
    }

Listing locations using locations list-locations command is only available for whitesky.cloud BV admins.

Listing customers

whitesky.cloud BV admins can get a list of all their customers

Linux

$ ./portal-whitesky-cloud customers list-customers

Payload:
    {
    "result": [
        {
        "customer_id": "customer_1",
        "name": "customer-cloud",
        "contact_name": "test",
        "email": "test@example.com",
        "billable": true,
        "status": "Active",
        "deleted_timestamp": 0,
        "deleted": false
        }
    ]
    }

Windows

$ .\portal-whitesky-cloud.exe customers list-customers

Payload:
    {
    "result": [
        {
        "customer_id": "customer_1",
        "name": "customer-cloud",
        "contact_name": "test",
        "email": "test@example.com",
        "billable": true,
        "status": "Active",
        "deleted_timestamp": 0,
        "deleted": false
        }
    ]
    }

For an API alternative, you can use GET 'https://portal.whitesky.cloud/api/1/customers?include_deleted=false&only_deleted=false'. To learn more about API endpoints in whitesky.cloud BV check API documentation.

Creating cloudspaces

To create a cloudspace

Linux

$ ./portal-whitesky-cloud customers create-cloudspace --customer-id=<CUSTOMER_ID> --payload.name=<CLOUDSPACE_NAME> --payload.location=<LOCATION_NAME> --payload.firewall.private=true

Payload:
    {
    "cloudspaceid": YmUtZzgtMzozODA1Ng
    }

Windows

$ .\portal-whitesky-cloud.exe customers create-cloudspace --customer-id=<CUSTOMER_ID> --payload.name=<CLOUDSPACE_NAME> --payload.location=<LOCATION_NAME> --payload.firewall.private=true

Payload:
    {
    "cloudspaceid": YmUtZzgtMzozODA1Ng
    }

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_NAME: Specify the name you want to give your new cloudspace.
LOCATION_NAME: Specify the location you want to associate your cloudspace with.

payload.firewall.private=true sets the new cloudspace as a private cloudspace.

Result

The new Cloudspace ID is returned.

Creating VMs

To create a virtual machine

Linux

$ ./portal-whitesky-cloud customers create-virtual-machine --cloudspace-id=<CLOUDSPACE_ID> --customer-id=<CUSTOMER_ID> --disk-size 8192 --memory 1024 --vcpus 1 --name f_Vm --description "linux vm" --os-type Linux --timeout=2m --os-name "Ubuntu server 16.04"

Windows

$ .\portal-whitesky-cloud.exe customers create-virtual-machine --cloudspace-id=<CLOUDSPACE_ID> --customer-id=<CUSTOMER_ID> --disk-size 8192 --memory 1024 --vcpus 1 --name f_Vm --description "linux vm" --os-type Linux --timeout=2m --os-name "Ubuntu server 16.04"

The API call will return the ID of the created VM

    Payload:
        {
        "vmid": 59106
        }

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_ID: Specify the ID of the cloudspace you want the new virtual machine to belong to.
Specify the rest of the configurations you need for the new virtual machine.

Result

The new virtual machine ID is returned.

Note: The timeout is increased to 2 minutes (where the default value is 30 sec) as this operation might take a while.

Listing VMs

To list the virtual machines in a certain cloudspace

Linux

$ ./portal-whitesky-cloud customers list-cloudspace-virtual-machines --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID>

Windows

$ .\portal-whitesky-cloud.exe customers list-cloudspace-virtual-machines --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID>

    Payload:
      result:
      - appliance: false
        creationtime: 1.619083789e+09
        disks:
        - 81165
        imageid: 8053
        memory: 1024
        name: f_Vm
        networkinterfaces:
        - devicename: ve6e2-10296
          ipaddress: [192.168.103.254]
            macaddress: 52:54:00:00:ee:ee
            networkid: 66198
          referenceid: 9ddab987-c8d7-42d6-83fe-e99d164ebc22
          stackid: 0
          status: HALTED
          storage: 8192
          updatetime: 1.61908379e+09
          vcpus: 1
          vmid: 59106

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_ID: Specify the cloudspace ID.

Result

A list of the virtual machines and their properties is returned.

Deleting VMs

To delete a virtual machine

Linux

$ ./portal-whitesky-cloud customers delete-virtual-machine --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID> --vmid=<VM_ID>

Windows

$ .\portal-whitesky-cloud.exe customers delete-virtual-machine --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID> --vmid=<VM_ID>

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_ID: Specify the cloudspace ID.
VM_ID: Replace this argument with the ID of the virtual machine you want to delete.

Result

The specified virtual machine is deleted.