Hub CLI on Windows

Rick Richardson Updated by Rick Richardson

The Hub CLI tool is the core of Agile Stacks' powerful automation system. It's data management, templating and infrastructure transpareny isn't limited to just POSIX environments like Linux and Mac. It is available on Windows as well. It has been tested to work on Windows 10 Home and Professional, but it should work on any 64 bit Windows system with either a Bash environment or Docker Desktop or Docker Toolbox and Powershell environment.

Compared to it's Unix counterparts that are fully functional, the Windows hub.exe binary is limited mostly to hub api subset of commands to interact with SuperHub API. SuperHub can do everything the CLI can do - and more, yet it happens in the cloud and tailored more to actual provisioning of environments, while local workflow with CLI is more convenient for development of software components.

In case you're working from a Windows machine there are three major options to choose from:

  1. Use native hub.exe binary to access SuperHub API to interact with from command-line.
  2. Use Windows Subsystem for Linux to work from an environment that closely resembles Linux to access full Hub CLI capabilities.
  3. Use Docker Desktop to run agilestacks/toolbox that contains Hub CLI and various tools such as Terraform, kubectl, Helm, jq, AWS CLI, Vault, etc.

Native hub.exe

This is the easiest option in case you just want to call SuperHub API and do API scripting from command-line.

Download, rename to hub.exe, put in PATH, and you're done with the install.

Login into SuperHub

Next is to login into SuperHub with your Agile Stacks email and password:

hub login -u your-email@domain.tld
Password: ***

Add HUB_TOKEN to your environment. If you are in a Bash shell, you can simply export it via export HUB_TOKEN=<token> or insert it into your environment using Windows native environment variable system.

Once that is set and present in your shell, you can now runhub api -h to get help regarding the SuperHub API.

Deploying via SuperHub from command line

Kubernetes Cluster and Overlay stacks are Stack Instances. They are based on Templates generated by SuperHub. When you press Deploy in UI an automation task is created,and template is cloned from Git repository, and make deploy is invoked. These activities can also be executed via the hub CLI as follows:

hub api template get  # list all templates
hub api template get -g <name of the template>
git clone https://url-to-your-stack-template
cd template-1234
<change files>
git commit -am '...'
git push
hub api instance deploy -w <domain of stack instance>

Windows Subsystem for Linux

The Windows Subsystem for Linux lets developers run a GNU/Linux environment - including most command-line tools, utilities, and applications - directly on Windows, unmodified, without the overhead of a virtual machine.

Here we're assuming WSL 1 which is different from WSL 2. WSL 2 is a true virtual machine (Hyper-V) but it is still work in progress on Microsoft side - the experience is not as polished as WSL 1, and you must have Windows 10 build 18917 or later from the Windows Insider Program.

WSL could be installed from Microsoft Store. The examples below are given for the Ubuntu Linux distribution.

After Linux distribution is installed and initial user is configured, download and install hub:

curl -O
mv hub.linux_amd64 hub
chmod +x hub
sudo mv hub /usr/local/bin

Note, that this only gives you hub which is sufficient to access SuperHub API, yet actual software provisioning from local machine requires quite a bit of additional provisioning tools - such as Terraform, kubectl, Helm, etc., that you must install separately. Those steps are outlined in detail in the next section.

After you clone the template generated by SuperHub, there is a README file inside that describes follow-up steps.

Inside WSL C:\ is mounted under /mnt/c so it is straightforward to share files between Linux and Windows.

Provisioning and utility tools

Install tools from Linux distribution repository:

sudo apt-get update
sudo apt-get install git make python3-virtualenv python3.8 awscli wget zip unzip

Install Terraform 0.11 and 0.12:

unzip terraform_"$TF_VERSION"
chmod +x terraform
sudo mv terraform /usr/local/bin/terraform-v0.11

unzip terraform_"$TF_VERSION"
chmod +x terraform
sudo mv terraform /usr/local/bin/terraform-v0.12

Install kubectl 1.16:

chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Install Helm 2 and 3:

tar xvzf helm-v${HELM2_VERSION}-linux-amd64.tar.gz linux-amd64/helm --strip-components=1
chmod +x helm
sudo mv helm /usr/local/bin

tar xvzf helm-v${HELM3_VERSION}-linux-amd64.tar.gz linux-amd64/helm --strip-components=1
chmod +x helm
sudo mv helm /usr/local/bin/helm3

Install istioctl (optional)

tar xvzf istio-${ISTIOCTL_VERSION}-linux.tar.gz istio-${ISTIOCTL_VERSION}/bin/istioctl --strip-components=2
chmod +x istioctl
sudo mv istioctl /usr/local/bin

Install jq 1.6:

mv jq-linux64 jq
chmod +x jq
sudo mv jq /usr/local/bin

Optionally install and configure NVM and then install Node 12:

nvm install 12
nvm alias default 12
nvm use default

Optionally install and configure direnv.

Hub CLI extensions

Hub CLI is extendable via scripts. There is a number of well-know extensions, such as hub pull, hub ls, etc. hosted in hub-extensions.

To install:

hub extensions install

Running Hub CLI in Docker using Agile Stacks' Toolbox and Docker Desktop

Agile Stacks offers a "batteries included" docker container that has the Hub CLI as well as all of the automation dependencies that one could need.

You can read more about how to use the Toolbox in this article

Install Docker Desktop.

We recommend to also install Windows Terminal from Microsoft Store for better terminal experience - tabs, etc.

Powershell script

This script launches Toolbox container. You should go into Docker Desktop Settings > Resources > File Sharing and make drive C available to your containers > Apply & Restart.

Save the script as toolbox-run.ps1:

$IMAGE = "agilestacks/toolbox:stable"$TOOLBOX_SHELL = "/bin/bash"

$BASEDIR = (pwd).Path
$USER = $env:UserName$HOMEDIR = "/home/$USER"$WINHOME = "C:\Users\$USER"$homevol = "{0}:{1}" -f "$WINHOME", "$HOMEDIR"$basevol = "{0}:{1}" -f "$BASEDIR", "/workspace"

echo $homevol
echo $basevol

& "C:\Program Files\Docker\Docker\resources\bin\docker.exe" run -ti --rm `-h toolbox-"$env:computername" `-e "USER=$USER" `-e "UID=1000" `-e "GID=1000" `-e "HOME=$HOMEDIR" `-e "SHELL=$TOOLBOX_SHELL" `-e 'PS1=\u@\e[92m\h\e[0m \w $ ' `-v "$homevol" `-v "$basevol" `--privileged=true `--cap-add=NET_ADMIN `-w "/workspace" `"$IMAGE" "$args"

echo "Shutting down toolbox... bye!"

Run it and a PowerShell terminal window will open. The Toolbox is rather large image over 1GB size compressed so it will take a while to download an unpack first time.

Current directory will be mapped to /workspace and your Windows user home directory to /home/<user name>.

How did we do?

Create a Cloud Account

Stack Design