Skip to main content

Get Started with BLOX

In a Nutshell
What will I learn?Let's discover how to get started with BLOX in less than 10 minutes. We'll load some AWS credentials and look at how we can make use of different versions of Terraform.
Difficulty

What you'll need​

  • Docker version 16.14 or above:
info

If you don't yet have Docker installed or access to Docker then you can follow the official documentation from the folks at Docker to find the right version for your operating system and get up and running

https://docs.docker.com/get-docker/

Tutorial​

Starting BLOX​

To run BLOX in its simplest form just launch a new terminal from within your Operating System and start the BLOX Container directly

docker run -it --rm hestio/blox

Running that command should give you a terminal window with a running instance of BLOX

asciicast

Persistent Data​

Using BLOX without any data or configuration persistance is probably not what you want. You will benefit much more from having your configuration persist between sessions so that you can resume right where you left off next time you launch BLOX again

To do that we will create a simple wrapper script blox that will create a persistent data store and share some useful files you have in your HOME directory with the BLOX container.

/usr/local/bin/blox
#!/usr/bin/env bash

PUID=$(id -u)
PGID=$(id -g)

# Ensure paths exist
[ -d "${HOME}/.awsh/identities" ] || mkdir -p "${HOME}/.awsh/identities"
[ -d "${HOME}/workspace" ] || mkdir -p "${HOME}/workspace"

# Ensure config files exist
touch ${HOME}/.bashrc_local ${HOME}/.netrc ${HOME}/.terraformrc

# Start the container
docker run \
    -it \
    --rm \
    --network=host \
    --user ${PUID}:${PGID} \
    -v ${HOME}/.awsh:/home/awsh/.awsh \
    -v ${HOME}/.bashrc_local:/home/awsh/.bashrc_local \
    -v ${HOME}/.netrc:/home/awsh/.netrc \
    -v ${HOME}/.terraformrc:/home/awsh/.terraformrc \
    -v ${HOME}/workspace:/home/awsh/workspace \
    -v /tmp:/tmp \
    -e "HOME=/home/awsh" \
    -e "PUID=${PUID}" \
    -e "PGID=${PGID}" \
    -e "http_proxy=${http_proxy}" \
    -e "https_proxy=${https_proxy}" \
    -e "no_proxy=${no_proxy}" \
    hestio/blox

Now that we've created our wrapper script we can use it to launch a new BLOX session and start using it with AWS

blox

Running that command should give you a terminal window with a running instance of BLOX and map in several useful paths from your HOME directory that are commonly used by many of the tools in the AWS ecosystem.

asciicast

tip

If you'd like the ability to add or import other customizations to your BLOX sessions you can take advantage of the hook built into both AWSH and BLOX that will check for the existance of ${HOME}/.bashrc_local on startup and process it as part of normal shell init

~/.bashrc_local
#!/bin/bash

## Aliases
alias vim="vi"

cat > ~/.gitconfig <<EOF
[credential "https://git.com"]
  username = [email protected]
  helper = store
[user]
  name = Lukasz Czarnota
  email = [email protected]
EOF

For more detailed information please see the full documentation here. For now, let's continue with loading some credentials and having a look around.

Load some AWS credentials​

At the BLOX prompt, load some existing credentials for your AWS account. The BLOX container is built on top of AWSH, which is how we will load our credentials. These can be IAM User or IAM STS Temperary credentials. Simply paste them into the BLOX terminal and use CTRL+D when done.

BLOX❯
awsh creds load

showcase

Once you have loaded some credentials your default terminal prompt will update to provide more useful information to help you navigate AWS at the CLI. Let's have a look;

Loading AWS Credentials into AWSH or BLOX
Figure: Loading AWS Credentials into AWSH or BLOX
  1. Which container you are using. This will be BLOX or AWSH depending on which set of containerized tools you are using
  2. AWS credentials, either from temporary (STS) or persistent (IAM User) API access
  3. Once loaded, some summary information about the credentials is shown for use with any AWS tooling that does not support the default order of precedence (command line -> environment -> files)
  4. Time. Yes, boring maybe but it is extremely useful when reviewing how long commands took to complete previously. Some of those API calls to manage AWS resources can take up to an hour!
  5. AWS Account alias.
  6. The name of the AWS identity that the credentials provided are for
  7. The default AWS Region that will be used when not adding --region ab-cdef-n to any commands
  8. The remaining duration on your temporary credentials if known.

What identity is active?​

Because the BLOX container is built on top of AWSH, we can benefit from all of the commands and utilities present

BLOX❯
awsh whoami

What versions of Terraform?​

Several versions of Terraform are included, from older versions with legacy provider management all the way up to modern and recent versions.

BLOX❯
tf default

Changing the Terraform version​

If your Terraform state is local you can take advantage of the detection built into the tf helper. The autover feature can be used when working with multiple repositories with different Terraform states that were run with different Terraform versions.

BLOX❯
tf autover

By using tf autover, our automation can inspect the Terraform state file and set a default Terraform version that will be compliant with previous deployments. This can help ensure consistency across multiple repositories and reduce the risk of errors due to version mismatches.

You can also manually change the Terraform version using the same tf helper

BLOX❯
tf default 0.13.7

asciicast

Now that you've had a look around why not check out the full documentation here.


Open Source

Did you know that both AWSH and BLOX are completely Open Source? That's right - the software is available free of charge, and we make some of our revenue by helping others install, use, and troubleshoot it. Take copy for yourself!

AWSH: Containerized tools with lightweight access to AWS CLI and APIs in mind.
GitHub license Docker Pulls

BLOX: Containerized tools for engineering teams who need to work with AWS and IAC every day.
GitHub license Docker Pulls