CLI User Guide

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

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

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

Adding tab completion

To load completions use this command:

$ ./portal-afriqloud-com completion --help

Bash

$ source <(portal-afriqloud-com completion bash)

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

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-afriqloud-com completion zsh > "${fpath[1]}/_portal-afriqloud-com"

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

Fish

$ portal-afriqloud-com completion fish | source

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

PowerShell

PS> portal-afriqloud-com completion powershell | Out-String | Invoke-Expression

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

Usage

./portal-afriqloud-com 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-afriqloud-com version --json

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

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

$ ./portal-afriqloud-com update show

This command here will perform an update:

$ ./portal-afriqloud-com update install

Documentation

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

Automation

To support automation (scripting), portal-afriqloud-com 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-afriqloud-com API on each command line, the CLI stores this information in a configuration file (default directory on Linux: $HOME/.config/portal-afriqloud-com, 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 Gigify Uganda Limited 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-afriqloud-com

Linux

$ echo $JWT | ./portal-afriqloud-com config auth-token update

Windows

$ .\portal-afriqloud-com.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-afriqloud-com customers list-customer-locations --customer-id [string]

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

Windows

$ .\portal-afriqloud-com.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 Gigify Uganda Limited admins.

Listing customers

Gigify Uganda Limited admins can get a list of all their customers

Linux

$ ./portal-afriqloud-com 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-afriqloud-com.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.afriqloud.com/api/1/customers?include_deleted=false&only_deleted=false'. To learn more about API endpoints in Gigify Uganda Limited check API documentation.

Creating cloudspaces

To create a cloudspace

Linux

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

Payload:
    {
    "cloudspaceid": YmUtZzgtMzozODA1Ng
    }

Windows

$ .\portal-afriqloud-com.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-afriqloud-com 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-afriqloud-com.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-afriqloud-com customers list-cloudspace-virtual-machines --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID>

Windows

$ .\portal-afriqloud-com.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-afriqloud-com customers delete-virtual-machine --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID> --vmid=<VM_ID>

Windows

$ .\portal-afriqloud-com.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.