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
After downloading, unpack the archive. Unpacking the archive will yield the portal-afriqloud-com binary (NB: portal-afriqloud-com.exe on Windows).
Tip
On linux-based systems, add the necessary permissions to the binary chmod +x portal-afriqloud-com.
Adding tab completion¶
To load completions use this command:
$ 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
# 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.
Usage
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:
This command here will perform an update:
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 (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 portal-afriqloud-com
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
Tip
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
Tip
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
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
The API call will return the ID of the created VM
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
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
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.