|
| 1 | +--- |
| 2 | +title: "Getting started with Geodesic v4" |
| 3 | +description: "Learn what Geodesic is and how you can start using it to simplify your local infrastructure development." |
| 4 | +sidebar_position: 1 |
| 5 | +--- |
| 6 | + |
| 7 | +import Intro from '@site/src/components/Intro'; |
| 8 | +import Note from '@site/src/components/Note'; |
| 9 | +import Steps from '@site/src/components/Steps'; |
| 10 | +import Step from '@site/src/components/Step'; |
| 11 | +import StepNumber from '@site/src/components/StepNumber'; |
| 12 | + |
| 13 | +<Intro> |
| 14 | +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](/learn/toolchain/#geodesic) and we use it as our DevOps automation shell and as the base Docker image for all of our DevOps scripting / CI jobs. |
| 15 | + |
| 16 | +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. |
| 17 | +</Intro> |
| 18 | + |
| 19 | +<Note> |
| 20 | +Geodesic v4 is the current version |
| 21 | +This documentation is for Geodesic v4, which is the current version. |
| 22 | +While it is largely the same as earlier versions, there are some significant |
| 23 | +differences, and we have retained documentation on Geodesic v3 for those who |
| 24 | +have yet to make the switch. Please be aware of which version of Geodesic |
| 25 | +and which version of the documentation you are using in case you find |
| 26 | +inconsistencies. |
| 27 | +</Note> |
| 28 | + |
| 29 | + |
| 30 | +## Prerequisites |
| 31 | + |
| 32 | +### System Requirements |
| 33 | + |
| 34 | +To accomplish this tutorial, you'll need to have [Docker installed](https://docs.docker.com/get-docker/) on your local machine. **That's all**. |
| 35 | + |
| 36 | +Although Geodesic is supplied as a Docker image, it is best used by installing a wrapper shell script |
| 37 | +that configures the Docker container to mount directories and files from your local machine and support |
| 38 | +running multiple `bash` shells simultaneously. To install the wrapper script, you must have write |
| 39 | +access to either `/usr/local/bin` or `$HOME/.local/bin` on your local machine, and you must have |
| 40 | +the installed directory in your `$PATH`. |
| 41 | + |
| 42 | +### Geodesic Usage Patterns |
| 43 | + |
| 44 | +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: |
| 45 | + |
| 46 | +<Steps> |
| 47 | + <Step> |
| 48 | + ### <StepNumber/> Install Geodesic |
| 49 | + |
| 50 | + You can **install** Geodesic onto your local machine running `make install` with the [Makefile](https://github.com/cloudposse/geodesic/blob/main/Makefile) provided in the Geodesic repository. |
| 51 | + </Step> |
| 52 | + <Step> |
| 53 | + ### <StepNumber/> Build Your Own Toolbox |
| 54 | + |
| 55 | + You can **build your own toolbox** on top of Geodesic. This is what Cloud Posse generally recommends to |
| 56 | + practitioners. |
| 57 | + |
| 58 | + We do this when we want to provide additional packages or customization to our team while building on the foundation |
| 59 | + that Geodesic provides. This is relatively to do by using Geodesic as your base image (e.g. `FROM |
| 60 | + cloudposse/geodesic:latest-debian`) in your own `Dockerfile`, adding your own Docker `RUN` commands or overriding |
| 61 | + environment variables, and then customizing the [Geodesic Makefile](https://github.com/cloudposse/geodesic/blob/main/Makefile) with your own `DOCKER_ORG`, `DOCKER_IMAGE`, `DOCKER_FILE`, and `APP_NAME` variables. (There are other variables you can customize as well, but these are the most common ones.) Then you can run `make build` to create a new image, `make install` to install the wrapper script that will run it, and then run it via the `APP_NAME` you configured. If you like, you can do this all in one step by running `make all`. |
| 62 | + </Step> |
| 63 | + <Step> |
| 64 | + ### <StepNumber/> Quick Install |
| 65 | + |
| 66 | + You can skip using `make` and just install Geodesic |
| 67 | + |
| 68 | + Example: `docker run --rm cloudposse/geodesic:latest-debian |
| 69 | + init | bash` installs `/usr/local/bin/geodesic` (or `$HOME/.local/bin/geodesic`) on your local machine which you can |
| 70 | + 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. |
| 71 | + </Step> |
| 72 | + <Step> |
| 73 | + ### <StepNumber/> Run Standalone |
| 74 | + |
| 75 | + You can **run standalone** Geodesic as a standard docker container using `docker run`, but in this mode, Geodesic |
| 76 | + will not have access to your local machine's files, so it is less useful. Some use cases are to provide tools to |
| 77 | + debug a Kubernetes cluster by installing Geodesic as a pod in the cluster, or to use it as a CI/CD tool where the |
| 78 | + tool takes care of mounting the required files and directories. |
| 79 | + </Step> |
| 80 | + <Step> |
| 81 | + ### <StepNumber/> Interactive Shell Example |
| 82 | + |
| 83 | + Example: `docker run -it --rm --volume $PWD:/workspace cloudposse/geodesic:latest-debian --login` opens a bash login |
| 84 | + shell (`--login` is our Docker `CMD` here; it's actually just [the arguments passed to the `bash` shell](https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html) which is our `ENTRYPOINT`) in our Geodesic container. |
| 85 | + </Step> |
| 86 | + <Step> |
| 87 | + ### <StepNumber/> One-Off Command Example |
| 88 | + |
| 89 | + Example: `docker run --rm cloudposse/geodesic:latest-debian -c "terraform version"` executes the `terraform version` command as a one-off and outputs the result. |
| 90 | + </Step> |
| 91 | +</Steps> |
| 92 | + |
| 93 | +In this tutorial, we'll be running the installed Geodesic `geodesic` to allow us to take advantage of the wrapper script's features. |
| 94 | + |
| 95 | +## Tutorial |
| 96 | + |
| 97 | +<Steps> |
| 98 | + |
| 99 | + <Step> |
| 100 | + ### <StepNumber/> Install the Geodesic Wrapper Script |
| 101 | + |
| 102 | + First, at your terminal, let's install the Geodesic shell! |
| 103 | + |
| 104 | + ```bash |
| 105 | + # Since the "latest" tag changes, ensure we do not have a stale image |
| 106 | + docker image rm cloudposse/geodesic:latest-debian # OK if image not found |
| 107 | + docker run --rm cloudposse/geodesic:latest-debian init | bash |
| 108 | + ``` |
| 109 | + |
| 110 | + The result of running this command should look something like this: |
| 111 | + |
| 112 | + ```bash |
| 113 | + # Installing geodesic from cloudposse/geodesic:latest-debian... |
| 114 | + # Installed geodesic to /usr/local/bin/geodesic |
| 115 | + ``` |
| 116 | + </Step> |
| 117 | + |
| 118 | + <Step> |
| 119 | + ### <StepNumber/> Start the Geodesic Shell |
| 120 | + |
| 121 | + You should now be able to launch a Geodesic shell just by typing `geodesic` at your terminal: |
| 122 | + |
| 123 | + ```bash |
| 124 | + geodesic |
| 125 | + ``` |
| 126 | + |
| 127 | +  |
| 128 | + |
| 129 | + Exit it for now by typing `exit` or pressing `logout`. |
| 130 | + |
| 131 | + </Step> |
| 132 | + |
| 133 | + <Step> |
| 134 | + ### <StepNumber/> Download our Tutorial Project |
| 135 | + |
| 136 | + 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: |
| 137 | + |
| 138 | + </Step> |
| 139 | + |
| 140 | + <Step> |
| 141 | + ### <StepNumber/> TODO: Continue updates from here |
| 142 | + |
| 143 | + ```bash |
| 144 | + # Change to our /localhost directory so that we can pull our project's code to our |
| 145 | + # local machine as well as our docker container |
| 146 | + cd /localhost |
| 147 | + |
| 148 | + # Clone our tutorials repository |
| 149 | + git clone https://github.com/cloudposse/tutorials |
| 150 | + |
| 151 | + # Change to our tutorial code |
| 152 | + cd tutorials/01-geodesic |
| 153 | + ``` |
| 154 | + |
| 155 | + 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. |
| 156 | + |
| 157 | + </Step> |
| 158 | + <Step> |
| 159 | + ### <StepNumber/> Apply our Terraform Project |
| 160 | + |
| 161 | + Now that we've got some code to work with, let's apply it... |
| 162 | + |
| 163 | + ```bash |
| 164 | + # Setup our terraform project |
| 165 | + terraform init |
| 166 | + |
| 167 | + # Apply our terraform project |
| 168 | + terraform apply -auto-approve |
| 169 | + ``` |
| 170 | + |
| 171 | + Sweet, you should see a successful `terraform apply` with some detailed `output` data on the original star wars hero! 😎 |
| 172 | + |
| 173 | + Just to show some simple usage of another tool in the toolbox, how about we parse that data and get that hero's name? |
| 174 | + |
| 175 | + </Step> |
| 176 | + <Step> |
| 177 | + ### <StepNumber/> Read some data from our Outputs |
| 178 | + |
| 179 | + Let's utilize [`jq`](https://github.com/stedolan/jq) to grab some info from that terraform project's output: |
| 180 | + |
| 181 | + ```bash |
| 182 | + # Pipe our terraform project's output into jq so we can pull out our hero's name |
| 183 | + terraform output -json | jq .star_wars_data.value.name |
| 184 | + ``` |
| 185 | + |
| 186 | + Again, without having to install anything, we've grabbed a tool from our toolbox and were able to use it without a second thought. |
| 187 | + </Step> |
| 188 | +</Steps> |
| 189 | + |
| 190 | +## Conclusion |
| 191 | + |
| 192 | +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](https://github.com/cloudposse/packages/tree/master/vendor). 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! |
| 193 | + |
| 194 | +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`.](https://atmos.tools/quick-start/introduction) |
0 commit comments