Categories

GIG CLI Quickstart Guide

You are here:
< All Topics

Introduction

The gig tool allows to manage resources (such as VMs and vdisks) in a G8 on the command line. It is available for the 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 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

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:

$ ./gig config credentials add my-g8-credentials my-g8-user-id my-g8-secret

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:

$ ./gig config environment add my-g8 https://my-g8.gig.tech my-g8-credentials

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:

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

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:

./gig import vm my-g8 my-account my-cloudspace my-vm-image.ova --json

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

Table of Contents