|
| 1 | +# Bootstrap for Terraform deployments through Gitlab into Azure |
| 2 | + |
| 3 | +This directory contains [Terraform](https://www.terraform.io/) templates that can bootstrap Azure and Github resources in a way that enables running robust CICD of [Terraform](https://www.terraform.io/) templates using [Github CICD](https://github.com/features/actions). After applying this template, automated CI of terraform deployments should **just work**. |
| 4 | + |
| 5 | +> **Note**: This template is intended to be used alongside the CICD pipeline for infrastructure using Github. |
| 6 | +
|
| 7 | +At a high level, this template aims to: |
| 8 | + |
| 9 | +* Deploy Azure Dependencies required for automated CICD of Terraform deployments |
| 10 | +* Configure variables in Github required for automated CICD of Terraform deployments |
| 11 | +* Configure dependencies for each a multistage (`dev`, `integration`, `prod`, etc...) Terraform deployment |
| 12 | + |
| 13 | +> **Note**: This template only sets up the **dependencies** needed to do a production ready infrastructure deployment, such as backend state, deployment credentials, Azure Contianer Reigstry and Github variables. |
| 14 | +
|
| 15 | +There are many things deployed by this template, including: |
| 16 | + |
| 17 | +* Backend state storage account |
| 18 | +* Backend state containers for this deployment |
| 19 | +* ACR for storing docker images |
| 20 | +* Github variables needed for all deployments |
| 21 | +* For each deployment environment |
| 22 | + * Backend state container |
| 23 | + * Service principal used for deployments to that environment |
| 24 | + * Resource group |
| 25 | + * Role based security |
| 26 | + |
| 27 | +## Identities/Credentials Configured |
| 28 | + |
| 29 | +This template will generate some credentials, which are enumarated blow: |
| 30 | + |
| 31 | +| Description | Reason | Notes | |
| 32 | +| --- | --- | --- | |
| 33 | +| ACR Push/Pull | Needed by the pipeline that builds the base image used by all of the infrastructure CICD in Github | N/A | |
| 34 | +| Environment Deploy | Needed by each environment to execute a deployment of resources into Azure | One generated for each environment | |
| 35 | + |
| 36 | +## Usage |
| 37 | + |
| 38 | +There are a few use cases for the code in this repository. The sections below outline the usage for each of those cases |
| 39 | + |
| 40 | +### First Time Setup |
| 41 | + |
| 42 | +Among the many resources provisioned by this template is the [Backend Configuration](https://www.terraform.io/docs/backends/index.html) that hosts the [Terraform State](https://www.terraform.io/docs/state/index.html) for this template, as well as the state for each deployment. |
| 43 | + |
| 44 | +Because of this, we cannot have the backend state configured for the initial deployment of this template. These steps will take you through the following: |
| 45 | + |
| 46 | +* Initial deployment of this template |
| 47 | +* Enable the backend state for this deployment |
| 48 | + |
| 49 | +#### Requirements |
| 50 | + |
| 51 | +* `terraform` will need to be installed. Version `v0.12.28` or newer is recommended |
| 52 | +* A shell environment, preferrably bash |
| 53 | +* A Github personal access token. Instructions for generating one can be found [here](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). The token will need the `workflow` permission. |
| 54 | +* An Azure subscription |
| 55 | + |
| 56 | +#### Deployment Steps |
| 57 | + |
| 58 | +**Disable backend state** |
| 59 | + |
| 60 | +For the first deployment, the contents of `backend.tf` will need to be commented out. Don't worry -- we'll uncomment this later. |
| 61 | + |
| 62 | +**Configure your environment** |
| 63 | +```bash |
| 64 | +# Required to configure variables in Github |
| 65 | +export GITHUB_TOKEN="..." |
| 66 | + |
| 67 | +# The location in which to provision Azure resources |
| 68 | +export TF_VAR_location="..." |
| 69 | + |
| 70 | +# The prefix used for naming resources in Azure |
| 71 | +export TF_VAR_prefix="..." |
| 72 | + |
| 73 | +# Log into the Azure CLI |
| 74 | +az login |
| 75 | + |
| 76 | +# Set your default subscription - this will dictate where resources will be provisioned |
| 77 | +az account set --subscription "<your subscription ID>" |
| 78 | +``` |
| 79 | + |
| 80 | +**Run the deployment** |
| 81 | + |
| 82 | +> **Note**: If you see a log about `Initializing the backend...`, make sure that you followed the steps to disable the backend state. |
| 83 | +
|
| 84 | +```bash |
| 85 | +# Initialize the Terraform environment |
| 86 | +terraform init |
| 87 | + |
| 88 | +# See what the deployment will do. No changes will be applied, but you can review the changes that will be applied in the next step |
| 89 | +terraform plan |
| 90 | + |
| 91 | +# Deploy the changes |
| 92 | +terraform apply |
| 93 | +``` |
| 94 | + |
| 95 | +**Enable backend state** |
| 96 | + |
| 97 | +Enabling backend state will store the deployment state in Azure. This will allow others to run the deployment without you needing to worry about the state configuration. |
| 98 | + |
| 99 | +Start by uncommenting the contents of `backend.tf`, then run the following: |
| 100 | + |
| 101 | +```bash |
| 102 | +export ARM_ACCESS_KEY=$(terraform output backend-state-account-key) |
| 103 | +export ARM_ACCOUNT_NAME=$(terraform output backend-state-account-name) |
| 104 | +export ARM_CONTAINER_NAME=$(terraform output backend-state-bootstrap-container-name) |
| 105 | + |
| 106 | +# Initialize the deployment with the backend |
| 107 | +terraform init -backend-config "storage_account_name=${ARM_ACCOUNT_NAME}" -backend-config "container_name=${ARM_CONTAINER_NAME}" |
| 108 | +``` |
| 109 | + |
| 110 | +You should see something along the lines of the following, to which you want to answer `yes`: |
| 111 | + |
| 112 | +```bash |
| 113 | +Do you want to copy existing state to the new backend? |
| 114 | +``` |
| 115 | + |
| 116 | +If things work, you will see the following message and the state file should end up in Azure: |
| 117 | + |
| 118 | +```bash |
| 119 | +Successfully configured the backend "azurerm"! Terraform will automatically |
| 120 | +use this backend unless the backend configuration changes. |
| 121 | +``` |
| 122 | + |
| 123 | +### Deploying the Infrastructure |
| 124 | + |
| 125 | +Now that Azure and Github have been configured to support the Terraform deployment, you will need to do the following to actually deploy the environment. |
| 126 | + |
| 127 | +**Trigger IAC Pipeline** |
| 128 | + |
| 129 | +You are now ready to kick off a deployment of the IAC pipeline! You can do this through the Github actions UI. |
| 130 | + |
| 131 | +### Rotate Service Principal Passwords |
| 132 | + |
| 133 | +If the need arises to rotate the credentials for any of the generated service principals, the following command can be used to quickly rotate the credentials and also update all configuration in Github: |
| 134 | + |
| 135 | +```bash |
| 136 | +# configure environment (.envrc.template) |
| 137 | + |
| 138 | +az login |
| 139 | +az account set --subscription "<your subscription ID>" |
| 140 | + |
| 141 | +terraform init -backend-config "storage_account_name=${ARM_ACCOUNT_NAME}" -backend-config "container_name=${ARM_CONTAINER_NAME}" |
| 142 | + |
| 143 | +# `taint` all passwords - this triggers Terraform to regenerate these and update all dependent configuration |
| 144 | +terraform state list | grep random_password | xargs -L 1 terraform taint |
| 145 | +terraform plan |
| 146 | + |
| 147 | +# Note: this command might fail due to the rapid create/delete on Azure resources. If it fails, re-running it |
| 148 | +# should solve the issue |
| 149 | +terraform apply |
| 150 | +``` |
| 151 | + |
| 152 | +Done! |
| 153 | + |
| 154 | + |
| 155 | +### Adding a new environment |
| 156 | + |
| 157 | +Now that Azure and Github have been configured to deploy resources through Terraform, you can easily configure Azure and Github to support new application stages (environments) by using the `environment` module. |
| 158 | + |
| 159 | +> **Note**: This will only set up Azure and Github to support a new environment. The environment will need to be deployed using the infrastructure deployments project (not covered here). |
| 160 | +
|
| 161 | +This guide will take you through configuring Azure and Github to support a new `pre-prod` environment. |
| 162 | + |
| 163 | +**Add a new environment** |
| 164 | + |
| 165 | +You will need to open `azure.tf` to configure a new environment. A new environment can be configured by adding the following to the bottom of the file: |
| 166 | + |
| 167 | +```hcl |
| 168 | +module "preprod" { |
| 169 | + source = "./environment" |
| 170 | + acr_id = azurerm_container_registry.acr.id |
| 171 | + environment_name = "preprod" |
| 172 | + location = var.location |
| 173 | + subscription_id = data.azurerm_client_config.current.subscription_id |
| 174 | + backend_storage_account_name = azurerm_storage_account.ci.name |
| 175 | + prefix = var.prefix |
| 176 | +} |
| 177 | +``` |
| 178 | + |
| 179 | +You will then need to execute the following: |
| 180 | + |
| 181 | +```bash |
| 182 | +# configure environment (.envrc.template) |
| 183 | + |
| 184 | +az login |
| 185 | +az account set --subscription "<your subscription ID>" |
| 186 | + |
| 187 | +terraform init -backend-config "storage_account_name=${ARM_ACCOUNT_NAME}" -backend-config "container_name=${ARM_CONTAINER_NAME}" |
| 188 | +terraform plan |
| 189 | +terraform apply |
| 190 | +``` |
| 191 | + |
| 192 | +Done! |
0 commit comments