Categories

GIG CLI Quickstart Guide

You are here:
< All Topics

Introduction

The gig tool allows you to manage resources (such as VMs and vdisks) in a G8 on the command line. It is available for Linux, Windows and OS X operating systems (x86-64 only). To achieve support for multiple platforms it consists of a platform specific frontend binary that drives a backend in a Docker container, so a working Docker installation is prerequisite to using the gig CLI. Please refer to https://docs.docker.com/get-docker/ for more information on how to install Docker on your platform.

Installation

First Installation

Download the latest zip archive for your platform. Unpacking the archive will yield the gig binary (NB: gig.exe on Windows). Example for Linux:

$ wget -q https://storage-meneja.gig.tech/gig-cli/linux/amd64/gig.zip
$ unzip gig.zip  
Archive:  gig.zip
  inflating: gig

Download Locations

Updating

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

$ ./gig version --json
time=2020-05-07T12:55:17+02:00 level=info msg=checking \https://storage-meneja.gig.tech/gig-cli/linux/amd64\ for updates
time=2020-05-07T12:55:17+02:00 level=info msg=fetching https://storage-meneja.gig.tech/gig-cli/linux/amd64/gig.zip.sha256
time=2020-05-07T12:55:18+02:00 level=info msg=local version: 0.0.8, remote version: 0.0.9
a more recent version 0.0.9 is available - run gig update install [VERSION] to update
{
    "app_name": "gig",
    "branch": "HEAD",
    "date": "2020-03-10T14:37:56Z",
    "host": "9220ad80ceb7",
    "version": "0.0.8",
    "default_docker_image": "gigtech/gig-cli:0.0.8",
    "default_update_location": "https://storage-meneja.gig.tech/gig-cli/linux/amd64
}

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

$ ./gig update show
time=2020-05-07T12:56:59+02:00 level=info msg=fetching https://storage-meneja.gig.tech/gig-cli/linux/amd64/gig.zip.sha256
0.0.9

Note that your version might be different from the version above

The gig update install command will perform an update:

$ ./gig update install 0.0.9
time=2020-05-07T12:57:08+02:00 level=info msg=fetching https://storage-meneja.gig.tech/gig-cli/linux/amd64/gig.0.0.9.zip.sha256
time=2020-05-07T12:57:09+02:00 level=info msg=fetching gig.0.0.9.zip archive -> /tmp/gig.0.0.9.zip.908443948, digest 312a5a0065e90a98721ef13f31f8f9c6f5d8046e2ccc512f538988e2a2a6908a
time=2020-05-07T12:57:09+02:00 level=info msg=fetching https://storage-meneja.gig.tech/gig-cli/linux/amd64/gig.0.0.9.zip
time=2020-05-07T12:57:11+02:00 level=info msg=downloaded and verified gig.0.0.9.zip
time=2020-05-07T12:57:11+02:00 level=info msg=renaming old binary /tmp/linux/gig -> /tmp/linux/gig.bak
time=2020-05-07T12:57:11+02:00 level=info msg=renaming new binary /tmp/gig.209547419 -> /tmp/linux/gig
time=2020-05-07T12:57:11+02:00 level=info msg=removing old binary /tmp/linux/gig.bak
old version: 0.0.8, new version: 0.0.9

Documentation

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

Automation

To support automation (scripting), gig 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 address and credentials for a G8 on each command line, the CLI stores this information in a configuration file (default directory on Linux: $HOME/.config/gig, can be overridden with the --config flag). First, the credentials to be used with a G8 have to be added:

command

$ ./gig config credentials add <NAME OF CREDENTIALS>  <USER ID> <SECRET>

arguments

NAME OF CREDENTIALS: This could be any name for your credentials. Will be used as a reference to your key and secret of this specific configuration. Example: my-demo-creds
USER ID: This is your Client ID which can be retrieved from https://itsyou.online account settings. Example: SBvtarbgRzPBpsNqeVNbgRe9-_Lg
SECRET: This is your secret which can be retrieved from https://itsyou.online account settings. Example: UU3JKQxl8B3k97ZAUGha-3k97an

Shell Tip: use -- before USER ID and SECRET if either begin with "-". This will tell the shell to interpret the - as part of the string and not a flag for the cli tool

Example command
$ ./gig config credentials add my-demo-creds -- "-CvtarbgRzPBpsNqeVNbgRe9-_Lg" "UU3JKQxl8B3k97ZAUGha-3k97an"

These credentials are used to fetch JWTs from https://itsyou.online which are then used for authentication with the G8.
Once the credentials are added, the G8 environment can be configured:

command

$ ./gig config environment add <NAME OF YOUR G8> <G8 URL> <CREDENTIALS>

arguments

NAME OF YOUR G8: This can be any name of your choice to reference your G8 in your commands. Example: my-g8
G8 URL: Url of your G8. Example: https://my-g8.gig.tech
CREDENTIALS: This is one of your credentials you have added in the previous step. Example: my-demo-creds

Example command
$ ./gig config environment add my-g8 https://my-g8.gig.tech  my-demo-creds

Tasks

Certain jobs such as a VM import can take a long time and might leave resources in an incomplete state, e.g. if the client machine is powercycled during a VM import. To address these problems, the CLI uses the concept of a task: tasks that previously did not finish can either be aborted (NB: not while a task is still running!) or, if supported by the task (such as the VM import), be resumed. tasks that did not run to completion can be inspected:

command

$ ./gig task show --json
[
  {
    task_id: e23eca4e-1b44-4cd5-abfe-50ab6f53f6e4,
    date: 2020-03-24T15:27:14.590751203+01:00,
    [....]
  }
] 

command

It can then be aborted (= any resources created in the G8 will be cleaned up) or resumed using the task_id:

./gig task abort e23eca4e-1b44-4cd5-abfe-50ab6f53f6e4 

Importing VMs

The gig tool allows to import VM images that were exported to the the Open Virtualization Format (OVF) into a cloudspace in a G8:

command

./gig import vm <NAME OF YOUR G8> <ACCOUNT>  <CLOUDSPACE> <path/to/your/ova/file> --image-type <TYPE> --memory <MEMORY SIZE> --vcpus <VCPUs> --json

arguments

NAME OF YOUR G8: Name of an already added G8 via the config environment command explained earlier. Example: my-g8
ACCOUNT: name of an account that already exists on your G8 to be used in the creation of the VM. Example: my-account
CLOUDSPACE: name of an existing cloudspace on your G8. This is where gigcli will create your VM. Example: my-cloudspace
TYPE: Type of your image used for the VM. Has to be either Linux, Unix, BSD, Windows, Darwin or Other. (Required for versions 0.0.12 and later)
MEMORY SIZE: Memory size of your VM in MiB. (Optional)
VCPUs: Number of vcpus for your VM. (Optional)

Example command
$ ./gig import vm ch-g8  "my-account" my-cloudspace ~/Downloads/myvm.ova --image-type Linux --memory 64 --vcpus 1 --json

Individual settings such as VM name, memory, number of CPUs can be overridden via command line flags.

Table of Contents