Getting started with Geodesic

Intro

In the landscape of developing infrastructure, there are dozens of tools that we all need on our personal machines to do our jobs. In SweetOps, instead of having you install each tool individually, we use Docker to package all of these tools into one convenient image that you can use as your infrastructure automation toolbox. We call it Geodesic and we use it as our DevOps automation shell and as the base Docker image for all of our DevOps scripting / CI jobs.

In this tutorial, we'll walk you through how to use Geodesic to execute Terraform and other tooling. We'll be sure to talk about what is going on under the hood to ensure you're getting the full picture.

Prerequisites

System Requirements

To accomplish this tutorial, you'll need to have Docker installed on your local machine. That's all.

Docker Primer

Before we jump in, it's important to note that Geodesic is built around some advanced features of Docker and the Docker CLI that are worth understanding. If you know the docker CLI well then feel free to skip over this section.

1. Geodesic overrides the default entrypoint with a custom script that enables starting a login shell or installing geodesic as an executable on your local machine. If you don't know much about Docker's ENTRYPOINT or CMD capabilities then we recommend reading this article before moving forward.
2. Geodesic can be thought of as just another shell that you open up on your machine like zsh or bash, but when running it inside of Docker means that it doesn't have access to your home directory or the projects you're looking to work on. To get around that, Geodesic is typically run using Docker volume bind mounts via the --volume / -v flag. You'll see this in our examples below, but if you would like to understand more about what is going on under the hood then we recommend reading up quickly on mounting local volumes via docker run.

Geodesic Usage Patterns

Let's talk about a few of the ways that one can run Geodesic. Our toolbox has been built to satisfy many use-cases, and each result in a different pattern of invocation:

1. You can run standalone Geodesic as a standard docker container using docker run. This enables you to quickly use most of the built-in tools. (Some tools require installing the wrapper script first, as explained in the next step.)
   1. Example: docker run -it --rm --volume $HOME:/localhost cloudposse/geodesic:latest-debian --login opens a bash login shell (--login is our Docker CMD here; it's actually just the arguments passed to the bash shell which is our ENTRYPOINT) in our Geodesic container.
   2. Example: docker run --rm cloudposse/geodesic:latest-debian -c "terraform version" executes the terraform version command as a one-off and outputs the result.
2. You can install Geodesic onto your local machine using what we call the docker-bash pattern (e.g. docker run ... | bash). Similar to above, this enables a quickstart process but supports longer lived usage as it creates a callable script on your machine that enables reuse any time you want to start a shell.
   1. Example: docker run --rm cloudposse/geodesic:latest-debian init | bash -s latest-debian installs /usr/local/bin/geodesic on your local machine which you can execute repeatedly via simply typing geodesic. In this example, we're pinning the script to use the cloudposse/geodesic:latest-debian docker image, but we could also pin to our own image or to a specific version.
3. Lastly, you can build your own toolbox on top of Geodesic. This is what SweetOps generally recommends to practitioners. We do this when we want to provide additional packages or customization to our team while building on the foundation that geodesic provides. This is simple to do by using Geodesic as your base image (e.g. FROM cloudposse/geodesic:latest-debian) in your own Dockerfile, adding your own Docker RUN commands or overriding environment variables, and then using docker build to create a new image that you distribute to your team. This is more advanced usage and we'll cover how to do this in a future how-to article.

In this tutorial, we'll be running Geodesic standalone using docker run to allow us to get up and running quickly.

Tutorial

1. Start the Geodesic Shell

First, at your terminal, let's start up the Geodesic shell!

docker run -it --rm --volume $HOME:/localhost cloudposse/geodesic:latest-debian --login

There are a few things going on there, so let's break that down a bit:

1. We're using docker run to start a new container using the image cloudposse/geodesic:latest-debian which is hosted on Docker Hub
2. We're using the -it flags (i.e. --interactive and --tty) to start an interactive terminal session with a TTY.
3. We're using the --rm flag to ensure that we clean up this container after we exit out of the session.
4. We're using the --volume flag to mount our $HOME directory to /localhost in our new container. This is a Geodesic standard practice which enables the container and your corresponding shell session to have access to your dotfiles, configurations, and the projects that you'll work on.
   1. NOTE: If you're running on Linux and using Geodesic, any files written to the --volume mounts will be owned by the user inside the container, which is root. See here for potential workarounds.
5. Finally, after the image name, we're passing --login. This is the Docker CMD that we're passing to our image. Since we override the Docker ENTRYPOINT with a small bash script, our --login CMD results in calling /bin/bash --login which creates a new bash login shell.
   1. It's worth noting that since Geodesic v0.143.2 (PR #693), you can now drop --login as the default CMD will provide the same functionality.

The result of running this command should look like this:

2. Download our Tutorial Project

Great -- we've started up Geodesic so now let's do something with it. How about we pull a terraform project and apply it? To accomplish this, let's do the following:

# Change to our /localhost directory so that we can pull our project's code to our
# local machine as well as our docker container
cd /localhost

# Clone our tutorials repository
git clone https://github.com/cloudposse/tutorials

# Change to our tutorial code
cd tutorials/01-geodesic

Easy! And since we changed into our /localhost directory inside Geodesic, the tutorials project that we git cloned is available both in the container that we're running our shell in and on our local machine in our $HOME directory. This enables us to share files between our local machine and our container, which should start to give you an idea of the value of mounting $HOME into Geodesic.

3. Apply our Terraform Project

Now that we've got some code to work with, let's apply it...

# Setup our terraform project
terraform init

# Apply our terraform project
terraform apply -auto-approve

Sweet, you should see a successful terraform apply with some detailed output data on the original star wars hero! 😎

Just to show some simple usage of another tool in the toolbox, how about we parse that data and get that hero's name?

4. Read some data from our Outputs

Let's utilize jq to grab some info from that terraform project's output:

# Pipe our terraform project's output into jq so we can pull out our hero's name
terraform output -json | jq .star_wars_data.value.name

Again, without having to install anything, we've grabbed a tool from our toolbox and were able to use it without a second thought.

Conclusion

The beautiful thing about all of this is that we didn't need to install anything except Docker on our local machine to make this happen. Tools like git, terraform(all versions), and jq all involve specific installation instructions to get up and running using the correct versions across various machines/teams, but by using Geodesic we're able to quickly skip over all of that and use a container that includes them out of the box alongside dozens of other tools as well. And with the mounting of our $HOME directory to /localhost of the container, our Geodesic shell just ends up being an extension of our local machine. That is why we call it a toolbox as it enables consistent usage of CLI tools across your entire organization!

If you want to see another usage of Geodesic, read our next tutorial in the SweetOps series about one of our most important tools: atmos.