Before proceeding make sure that you have followed the Installation.
+For direnv to work properly it needs to be hooked into the shell. +Check direnv docs to know more: https://direnv.net/docs/hook.html
+Make sure that you have followed direnv documentation before proceeding.
+Start by downloading the Terrabutler Template Project from the repository source below:
+
Copy the files inside ./terrabutler-template/ to the root of your project folder.
Before configuring terrabutler, inside <project_name>/site_inception folder, you will need to create a Terraform Workspace:
+For example, we are gonna call it "staging"
Run the script ./<project_name>/config_template.sh, with the following arguments, located inside the project folder root:
$ ./config_template.sh -d <domain> -e <environment_name> -p <project_name>
+
+USAGE:
+ ./config_template [FLAG] [STRING]
+
+FLAGS:
+ -o <organization_name> The name for your organization.
+ Example: -o example
+
+ -d <domain> The domain of your organization.
+ Example: -d example.com
+
+ -e <environment_name> The environment name of your organization.
+ Example: -e staging
+This script only works with the template folder! Don't use it in another project folders!
+./terrabutler-template/config_template.sh
Start by installing Terraform with tfenv:
+ +Perform an Terraform Initialization inside site_inception:
+ +Perform an Terraform Apply with the.tfvars inside /config/variables/:
+./configs/variables/global.tfvars
+./configs/variables/<project_name>-<environment_name>.tfvars"
+./configs/variables/<project_name>-<environment_name>-inception.tfvars"
$ terraform apply -var-file="../configs/variables/global.tfvars" -var-file="../configs/variables/<project_name>-<environment_name>.tfvars" -var-file="../configs/variables/<project_name>-<environment_name>-inception.tfvars"
+Remove the commented line as below, in the terrabutler-template in the path ./site-inception/terraform.tf to change from local to remote.
Perform an Terraform initialization with the backend config file,located in /configs/backend/ to update the new changes:
Example:
+ $ terraform init -backend-config="./configs/backends/
Delete the local state in /site_inception, as it is not necessary:
Perform an Terrabutler Plan to ensure everything is ok, and plan any changes:
+ +Perform an Terrabutler Apply to apply the planned changes:
+ +Perform an Terrabutler Destroy to delete or undo any changes made in the provider:
+ + + + + + + +Before proceeding make sure that you have the requirements.
+All the binaries versions are available inside the releases pages
+To download the latest binaries run the following command:
+
+
+
+
wget -qO- https://github.com/montblu/terrabutler/releases/download/<VERSION>/terrabutler-<OS>-<ARCH>-<VERSION>.tar.gz | tar -zxvf - terrabutler
+Where <VERSION> is the version of the release.
For example, to download Terrabutler v0.2.0 for Linux x64, just run:
+wget -qO- https://github.com/montblu/terrabutler/releases/download/v0.2.0/terrabutler-linux-x64-v0.2.0.tar.gz | tar -zxvf - terrabutler
+To install the binaries into your system simply run the installer script inside the terrabutler folder:
All the binaries will be placed inside the /usr/share/terrabutler folder and the bin inside the /usr/bin folder
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:
+ +Example of installing for local user only (no need to run the install script as sudo):
+ +You should be able to run:
+ +and the output should be:
+ +If the output is not similar to the one above, then something went wrong during the installation.
+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:
+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.
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.
+In the project folder root, create a new diretory called site_<site-name>:
Replace <site-name> with your new site name!
site_inception variables fileAdd <site-name> to the following file, in inception_projects = [] line:
Add <site-name> to the following file, in sites: ordered: - <site-name> line:
Create a new file called <project-name>-<env>-<site-name>.tfvars to the following directory:
site_inceptionRun the following command, to update the new configuration on site_inception:
Run the following commands to copy the following Terraform files to the site_<site-name>:
Run the following commands to create the Symbolic Links:
+ + + + +Run the following command:
+ + + + + + + +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.
+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.
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.
Before you start using you will need to have some tools installed.
+ +These tools are required to be installed for a Terrabutler to work properly.
+This repository only works on Intel based Processors (x86/x64). Arm/Arm64 or another processor architectures are incompatible!
+In the list below you have the install instruction for each tool:
+ +You can now proceed to the installation process of Terrabutler.
+ + + + + + +The utility that helps keeping your IaC in one piece
"},{"location":"#what-is-terrabutler","title":"What is Terrabutler?","text":"
Terrabutler is a wrapper written in Python that helps maintaining IaC (Infrastructure as code) projects using Terraform by managing the environments.
"},{"location":"create-project/","title":"Create a new project","text":"Before proceeding make sure that you have followed the Installation.
"},{"location":"create-project/#configure-direnv","title":"Configure direnv","text":"For direnv to work properly it needs to be hooked into the shell. Check direnv docs to know more: https://direnv.net/docs/hook.html
Make sure that you have followed direnv documentation before proceeding.
"},{"location":"create-project/#configure-terrabutler","title":"Configure Terrabutler","text":""},{"location":"create-project/#create-your-project-folder","title":"Create your project folder","text":"mkdir <project_name>\nStart by downloading the Terrabutler Template Project from the repository source below:
Copy the files inside ./terrabutler-template/ to the root of your project folder.
$ cp -a /terrabutler-template/. /<project_name>/\nBefore configuring terrabutler, inside <project_name>/site_inception folder, you will need to create a Terraform Workspace: For example, we are gonna call it \"staging\"
$ cd site_inception\n$ terraform workspace new staging\nRun the script ./<project_name>/config_template.sh, with the following arguments, located inside the project folder root:
$ ./config_template.sh -d <domain> -e <environment_name> -p <project_name>\n\nUSAGE:\n ./config_template [FLAG] [STRING]\nFLAGS:\n -o <organization_name> The name for your organization. Example: -o example\n\n-d <domain> The domain of your organization. Example: -d example.com\n\n-e <environment_name> The environment name of your organization. Example: -e staging\nThis script only works with the template folder! Don't use it in another project folders! ./terrabutler-template/config_template.sh
Start by installing Terraform with tfenv:
$ tfenv install Perform an Terraform Initialization inside site_inception:
$ cd /site_inception/\n$ terraform init\n.tfvars inside /config/variables/: ./configs/variables/global.tfvars ./configs/variables/<project_name>-<environment_name>.tfvars\" ./configs/variables/<project_name>-<environment_name>-inception.tfvars\"
$ terraform apply -var-file=\"../configs/variables/global.tfvars\" -var-file=\"../configs/variables/<project_name>-<environment_name>.tfvars\" -var-file=\"../configs/variables/<project_name>-<environment_name>-inception.tfvars\"\nRemove the commented line as below, in the terrabutler-template in the path ./site-inception/terraform.tf to change from local to remote.
backend \"s3\" {}\nPerform an Terraform initialization with the backend config file,located in /configs/backend/ to update the new changes:
$ terraform init -backend-config=<inception_backend_path> Example: $ terraform init -backend-config=\"./configs/backends/--inception.tfvars\""},{"location":"create-project/#delete-the-local-state","title":"Delete the local state","text":"
Delete the local state in /site_inception, as it is not necessary:
$ rm -rf terraform.tfstate.d/ terraform.tfstate terraform.tfstate.backup\nPerform an Terrabutler Plan to ensure everything is ok, and plan any changes:
$ terrabutler tf -site inception plan\nPerform an Terrabutler Apply to apply the planned changes:
$ terrabutler tf -site inception apply\nPerform an Terrabutler Destroy to delete or undo any changes made in the provider:
$ terrabutler tf -site inception destroy\nBefore proceeding make sure that you have the requirements.
"},{"location":"installation/#download-the-binaries-and-extract-them","title":"Download the binaries and extract them","text":"All the binaries versions are available inside the releases pages
To download the latest binaries run the following command:
wget -qO- https://github.com/montblu/terrabutler/releases/download/<VERSION>/terrabutler-<OS>-<ARCH>-<VERSION>.tar.gz | tar -zxvf - terrabutler\nWhere <VERSION> is the version of the release.
For example, to download Terrabutler v0.2.0 for Linux x64, just run:
wget -qO- https://github.com/montblu/terrabutler/releases/download/v0.2.0/terrabutler-linux-x64-v0.2.0.tar.gz | tar -zxvf - terrabutler\nTo install the binaries into your system simply run the installer script inside the terrabutler folder:
sudo terrabutler/install\nAll the binaries will be placed inside the /usr/share/terrabutler folder and the bin inside the /usr/bin folder
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:
terrabutler/install -h\nExample of installing for local user only (no need to run the install script as sudo):
terrabutler/install -i ~/.local/share/terrabutler -b ~/.local/bin\nYou should be able to run:
terrabutler --version\nand the output should be:
Terrabutler: v0.2.0\nIf the output is not similar to the one above, then something went wrong during the installation.
"},{"location":"installation/#how-to-update-to-a-newer-version","title":"How to update to a newer version?","text":"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:
Found preexisting Terrabutler installation: /usr/share/terrabutler.\nDo you want to replace it? [y/N]\nJust press y and press enter and Terrabutler should be updated to the version that you downloaded.
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.
"},{"location":"new-site/","title":"Add a new site","text":""},{"location":"new-site/#create-a-new-directory","title":"Create a new directory","text":"In the project folder root, create a new diretory called site_<site-name>:
$ mkdir site_<site-name>\nReplace <site-name> with your new site name!
site_inception variables file","text":"Add <site-name> to the following file, in inception_projects = [] line:
./configs/variables/<project>-<env>-inception.tfvars\nAdd <site-name> to the following file, in sites: ordered: - <site-name> line:
./configs/settings.yml\nCreate a new file called <project-name>-<env>-<site-name>.tfvars to the following directory:
./configs/variables/<project-name>-<env>-<site-name>.tfvars\nsite_inception","text":"Run the following command, to update the new configuration on site_inception:
$ terrabutler tf -site inception apply\nRun the following commands to copy the following Terraform files to the site_<site-name>:
$ cd site_<site-name>\n$ cp ../site_inception/terraform.tf .\n$ cp ../site_inception/provider.tf .\nRun the following commands to create the Symbolic Links:
$ cd site_<site-name>\n$ ln -s ../globals/data.tf ./data_global.tf\n$ ln -s ../globals/locals.tf ./locals_globals.tf\n$ ln -s ../globals/variables.tf ./variables_globals.tf\nRun the following command:
$ terrabutler tf -site data init 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.
"},{"location":"philosophy/#problem","title":"Problem","text":"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.
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.
Before you start using you will need to have some tools installed.
These tools are required to be installed for a Terrabutler to work properly.
DangerThis repository only works on Intel based Processors (x86/x64). Arm/Arm64 or another processor architectures are incompatible!
"},{"location":"requirements/#installing-requirements","title":"Installing requirements","text":"In the list below you have the install instruction for each tool:
You can now proceed to the installation process of Terrabutler.
"},{"location":"usage/","title":"Basic Usage","text":"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:
terrabutler tf -site inception apply --help\nThe command above shows all the arguments and options that can be used when running that command.
"},{"location":"usage/#usage","title":"Usage","text":"terrabutler [global options] command [subcommand] [arguments] [options]\nAll global options can be placed at the command level.
--help, -help, -h: Show help menu.--version, -version: Show version of Terrabutler.The commands are:
env: Manage environmentsinit: Initialize the managertf: Manage terraform commandsenv","text":"Subcommands:
delete: \"Delete an environment\"list: \"List environments\"new: \"Create a new environment\"reload: \"Reload the current environment\"select: \"Select a environment\"show: \"Show the name of the current environment\"Example:
terrabutler env select staging\nThe command above change the current environment to staging.
tf","text":"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:
terrabutler tf -site inception apply\nThe command above run a terraform apply command inside the site inception in the current environment.
init","text":"Has no subcommands
"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 00000000..2acae104 --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,38 @@ + +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:
+ +The command above shows all the arguments and options that can be used when +running that command.
+All global options can be placed at the command level.
+--help, -help, -h: Show help menu.--version, -version: Show version of Terrabutler.The commands are:
+env: Manage environmentsinit: Initialize the managertf: Manage terraform commandsenvSubcommands:
+delete: "Delete an environment"list: "List environments"new: "Create a new environment"reload: "Reload the current environment"select: "Select a environment"show: "Show the name of the current environment"Example:
+ +The command above change the current environment to staging.
tfThe 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:
+ +The command above run a terraform apply command inside the site inception in
+the current environment.
initHas no subcommands
+ + + + + + +