CLI User Guide¶

The try-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 try-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://try.whitesky.cloud/api/1/utilities/cli?platform=linux" -H  "accept: application/zip" -H "Authorization: Bearer $jwt" --output try-whitesky-cloud.zip

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

Tip

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

Adding tab completion¶

To load completions use this command:

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

BashZshFishPowerShell

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

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

# 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:
$ try-whitesky-cloud completion zsh > "${fpath[1]}/_try-whitesky-cloud"

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

$ try-whitesky-cloud completion fish | source

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

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

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

Usage

./try-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:

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

{
"app_name": "try-whitesky-cloud",
"branch": "HEAD",
"build_date": "2021-04-15T09:53:58Z",
"build_host": "try-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://try.whitesky.cloud/api/1/utilities/cli?platform=windows",
"api_url": "try.whitesky.cloud/api/1"
}

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

$ ./try-whitesky-cloud update show

This command here will perform an update:

$ ./try-whitesky-cloud update install

Documentation¶

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

Automation¶

To support automation (scripting), try-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 try-whitesky-cloud API on each command line, the CLI stores this information in a configuration file (default directory on Linux: $HOME/.config/try-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 NV portal.
Click APIs in the navigation drawer on the left side of the page (between Docs and IAM).
Click CREATE JWT on the APIs page, choose the customer the JWT gives access to (Select customer; CREATE JWT stays disabled until you do), optionally switch on Refreshable (off by default) and enter a Refresh token name, then click CREATE JWT. Refresh tokens already issued are listed in the Existing refresh tokens table, where Revoke invalidates one.

To configure the JWT token in try-whitesky-cloud

LinuxWindows

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

$ .\try-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

LinuxWindows

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

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

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

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

Tip

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

Listing customers¶

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

LinuxWindows

$ ./try-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
        }
    ]
    }

$ .\try-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
        }
    ]
    }

Tip

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

Creating cloudspaces¶

To create a cloudspace

LinuxWindows

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

Payload:
    {
    "cloudspaceid": YmUtZzgtMzozODA1Ng
    }

$ .\try-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

LinuxWindows

$ ./try-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"

$ .\try-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

LinuxWindows

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

$ .\try-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

LinuxWindows

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

$ .\try-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.