diff --git a/docs/index.md b/docs/index.md index 928b345..574a5fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,3 +11,10 @@ ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/angulo-solido/terrabutler/Release%20Terrabutler?color=8956c4&logo=Github&style=for-the-badge) ![GitHub](https://img.shields.io/github/license/angulo-solido/terrabutler?color=8956c4&logo=Github&style=for-the-badge) ![GitHub Repo stars](https://img.shields.io/github/stars/angulo-solido/terrabutler?color=8956c4&label=Repo%20Stars&style=for-the-badge) + +--- + +## What is Terrabutler? + +Terrabutler is a **wrapper** written in [Python](https://www.python.org/) that helps maintaining IaC (Infrastructure as code) projects +using [Terraform](https://www.terraform.io/) by managing the **environments**. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..b56da14 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,84 @@ +# Installation + +Before proceeding make sure that you have the [requirements](requirements.md). + +## Download the binaries and extract them + +All the binaries versions are available inside the [releases pages](https://github.com/angulo-solido/terrabutler/releases) + +To download the latest binaries run the following command: + +``` shell +wget -qO- https://terrabutler-public.s3.amazonaws.com/releases/terrabutler-linux-x86_64-latest.tar.gz | tar -zxvf - terrabutler +``` + +???+ tip + If you wanna get a specific version just change the `` in the command below. All the **Terrabutler releases** are + available in the [repository releases pages](https://github.com/angulo-solido/terrabutler/releases) + + ``` shell + wget -qO- https://terrabutler-public.s3.amazonaws.com/releases/terrabutler-linux-x86_64-.tar.gz | tar -zxvf - terrabutler + ``` + + For example, to download **Terrabutler v0.1.0**, just run: + + ``` + wget -qO- https://terrabutler-public.s3.amazonaws.com/releases/terrabutler-linux-x86_64-v0.1.0.tar.gz | tar -zxvf - terrabutler + ``` + +## Install the binaries + +To install the binaries into your system simply run the installer script inside the `terrabutler` folder: + +``` shell +sudo terrabutler/install +``` + +All the binaries will be placed inside the `/usr/share/terrabutler` folder and the bin inside the `/usr/bin` folder + +???+ tip + If you wanna set the location where terrabutler will be installed you can define it by passing arguments when running the install script. + This arguments can be seen by running: + + ``` shell + terrabutler/install -h + ``` + + Example of installing for local user only **(no need to run the install script as sudo)**: + + ``` shell + terrabutler/install -i ~/.local/share/terrabutler -b ~/.local/bin + ``` + +## Check if the installation was successful + +You should be able to run: + +``` shell +terrabutler --version +``` + +and the output should be: + + +``` shell +Terrabutler: v0.1.0 +``` + +If the output is not similar to the one above, then **something went wrong during the installation**. + +## How to update to a newer version? + +If you have **Terrabutler** already installed and want to update to a newer version just do all the installation process again. +When you will be running the installer script it should prompt if you want to upgrade the **Terrabutler**, as we can see below: + +``` shell +Found preexisting Terrabutler installation: /usr/share/terrabutler. +Do you want to replace it? [y/N] +``` + +Just press `y` and press *enter* and **Terrabutler** should be updated to the version that you downloaded. + +???+ danger + In case you have installed the **Terrabutler** earlier with different locations, you will need to pass them, otherwise the + install script **won't prompt** you to update it. diff --git a/docs/philosophy.md b/docs/philosophy.md new file mode 100644 index 0000000..8260be9 --- /dev/null +++ b/docs/philosophy.md @@ -0,0 +1,22 @@ +# Philosophy + +Before settling for **Terrabutler**, it's a good idea to understand the philosophy behind the project, +in order to make sure it aligns with your goals. This page explains the problem and the solution. + +## Problem + +All our IaC projects are backed by Terraform. Instead of having a folder with every resource, we have +created different folders that have resources from the same category, and we call them `sites`. For +example inside the `network site` we will have the creation of `VPC`, `SG` and `WAF`, so this site is +where we have all the resources related to network. By splitting the code into various `sites` we have +smaller plans and it's more easy to manage the code. By having all the code divided into various `sites` +it's a bit more difficult to manage all the terraform variable files. And we wanted all of this for each +**environment**, so it needs to be divided into different environments, for example production and development. +All of the `sites` state needs to be have a remote state and with a lock function, to prevent usage at the same +time. + +## Solution + +Create a IaC with the `inception site` that will be responsible to manage the project environments via Terraform +workspaces tool and where the backends for each site will be created. Use **Terrabutler** to manage all the IAC +between all the sites. \ No newline at end of file diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..4f18965 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,19 @@ +# Requirements + +Before you start using you will need to have some tools installed. + +- [direnv](https://direnv.net/) +- [tfenv](https://github.com/tfutils/tfenv) + +These tools are required to be installed for a **Terrabutler** to work properly. + +## Installing requirements + +In the list below you have the install instruction for each tool: + +- [direnv](https://direnv.net/docs/installation.html) +- [tfenv](https://github.com/tfutils/tfenv#installation) + +## After checking requirements + +You can now proceed to the [installation](installation.md) process of **Terrabutler**. \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..63f3e8f --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,93 @@ +# Basic Usage + +In this section we quickly cover the basic commands of **Terrabutler**. +The usage of it can always be seen by using the help menu inside of every +command or subcommand. + +Example: + +``` shell +terrabutler tf -site inception apply --help +``` + +The command above shows all the arguments and options that can be used when +running that command. + +## Usage + +``` shell +terrabutler [global options] command [subcommand] [arguments] [options] +``` + +## Global options + +All global options can be placed at the command level. + +* `--help`, `-help`, `-h`: Show help menu. +* `--version`, `-version`: Show version of **Terrabutler**. + +## Commands + +The commands are: + +- `env`: Manage environments +- `init`: Initialize the manager +- `tf`: Manage terraform commands + +### Command `env` + +Subcommands: + +- `delete`: "Delete an environment" +- `list`: "List environments" +- `new`: "Create a new environment" +- `select`: "Select a environment" +- `show`: "Show the name of the current environment" + +Example: + +``` shell +terrabutler env select staging +``` + +The command above change the current environment to `staging`. + +### Command `tf` + +???+ tip + The `tf` subcommands are the Terraform commands + +Subcommands: + +- `apply`: "Create or update infrastructure" +- `console`: "Try Terraform expressions at an interactive command..." +- `destroy`: "Prepare your working directory for other commands" +- `fmt`: "Reformat your configuration in the standardstyle" +- `force-unlock`: "Release a stuck lock on the current workspace" +- `generate-options`: "Generate terraform options" +- `import`: "Associate existing infrastructure with a Terraform..." +- `init`: "Prepare your working directory for other commands" +- `output`: "Show output values from your root module" +- `plan`: "Show changes required by the current configuration" +- `providers`: "Show the providers required for this configuration" +- `refresh`: "Update the state to match remote systems" +- `show`: "Show the current state or a saved plan" +- `state`: "Advanced state management" +- `taint`: "Mark a resource instance as not fully functional" +- `untaint`: "Remove the 'tainted' state from a resource instance" +- `validate`: "Validate the configuration files" +- `version`: "Show the current Terraform version" + +Example: + +``` shell +terrabutler tf -site inception apply +``` + +The command above run a `terraform apply` command inside the `site inception` in +the current environment. + +### Command `init` + +Has no subcommands + diff --git a/mkdocs.yml b/mkdocs.yml index b464a63..2f1e8e0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,8 +30,20 @@ theme: repo: fontawesome/brands/github markdown_extensions: + - admonition - attr_list + - codehilite - md_in_html + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:materialx.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.tabbed extra: social: @@ -40,3 +52,7 @@ extra: nav: - Home: index.md + - Philosophy: philosophy.md + - Requirements: requirements.md + - Installation: installation.md + - Basic Usage: usage.md