github.com/kcburge/terraform@v0.11.12-beta1/website/guides/core-workflow.html.md (about) 1 --- 2 layout: "guides" 3 page_title: "The Core Terraform Workflow - Guides" 4 sidebar_current: "guides-core-workflow" 5 description: |- 6 This guide provides an overview of the core Terraform workflow and how it 7 applies in individual, team, and organization contexts across Terraform open 8 source and Terraform Enterprise. 9 --- 10 11 # The Core Terraform Workflow 12 13 The core Terraform workflow has three steps: 14 15 1. **Write** - Author infrastructure as code. 16 2. **Plan** - Preview changes before applying. 17 3. **Apply** - Provision reproducible infrastructure. 18 19 This guide walks through how each of these three steps plays out in the context 20 of working as an individual practitioner, how they evolve when a team is 21 collaborating on infrastructure, and how Terraform Enterprise enables this 22 workflow to run smoothly for entire organizations. 23 24 ## Working as an Individual Practitioner 25 26 Let's first walk through how these parts fit together as an individual working 27 on infrastructure as code. 28 29 ### Write 30 31 You write Terraform configuration just like you write code: in your editor of 32 choice. It's common practice to store your work in a version controlled 33 repository even when you're just operating as an individual. 34 35 ```sh 36 # Create repository 37 $ git init my-infra && cd my-infra 38 39 Initialized empty Git repository in /.../my-infra/.git/ 40 41 # Write initial config 42 $ vim main.tf 43 44 # Initialize Terraform 45 $ terraform init 46 47 Initializing provider plugins... 48 # ... 49 Terraform has been successfully initialized! 50 ``` 51 52 As you make progress on authoring your config, repeatedly running plans can help 53 flush out syntax errors and ensure that your config is coming together as you 54 expect. 55 56 ```sh 57 # Make edits to config 58 $ vim main.tf 59 60 # Review plan 61 $ terraform plan 62 63 # Make additional edits, and repeat 64 $ vim main.tf 65 ``` 66 67 This parallels working on application code as an individual, where a tight 68 feedback loop between editing code and running test commands is useful. 69 70 ### Plan 71 72 When the feedback loop of the Write step has yielded a change that looks good, 73 it's time to commit your work and review the final plan. 74 75 ```sh 76 $ git add main.tf 77 $ git commit -m 'Managing infrastructure as code!' 78 79 [master (root-commit) f735520] Managing infrastructure as code! 80 1 file changed, 1 insertion(+) 81 ``` 82 83 Because `terraform apply` will display a plan for confirmation before 84 proceeding to change any infrastructure, that's the command you run for final 85 review. 86 87 ```sh 88 $ terraform apply 89 90 An execution plan has been generated and is shown below. 91 # ... 92 ``` 93 94 ### Apply 95 96 After one last check, you are ready to tell Terraform to provision real 97 infrastructure. 98 99 ```sh 100 Do you want to perform these actions? 101 102 Terraform will perform the actions described above. 103 Only 'yes' will be accepted to approve. 104 Enter a value: yes 105 106 # ... 107 108 Apply complete! Resources: 1 added, 0 changed, 0 destroyed. 109 ``` 110 111 At this point, it's common to push your version control repository to a remote 112 location for safekeeping. 113 114 ```sh 115 $ git remote add origin https://github.com/*user*/*repo*.git 116 $ git push origin master 117 ``` 118 119 This core workflow is a loop; the next time you want to make changes, you start 120 the process over from the beginning. 121 122 Notice how closely this workflow parallels the process of writing application 123 code or scripts as an individual? This is what we mean when we talk about 124 Terraform enabling infrastructure as code. 125 126 ## Working as a Team 127 128 Once multiple people are collaborating on Terraform configuration, new steps 129 must be added to each part of the core workflow to ensure everyone is working 130 together smoothly. You'll see that many of these steps parallel the workflow 131 changes we make when we work on application code as teams rather than as 132 individuals. 133 134 ### Write 135 136 While each individual on a team still makes changes to Terraform configuration 137 in their editor of choice, they save their changes to version control _branches_ 138 to avoid colliding with each other's work. Working in branches enables team 139 members to resolve mutually incompatible infrastructure changes using their 140 normal merge conflict workflow. 141 142 ```sh 143 $ git checkout -b add-load-balancer 144 145 Switched to a new branch 'add-load-balancer' 146 ``` 147 148 Running iterative plans is still useful as a feedback loop while authoring 149 configuration, though having each team member's computer able to run them 150 becomes more difficult with time. As the team and the infrastructure grows, so 151 does the number of sensitive input variables (e.g. API Keys, SSL Cert Pairs) 152 required to run a plan. 153 154 To avoid the burden and the security risk of each team member arranging all 155 sensitive inputs locally, it's common for teams to migrate to a model in which 156 Terraform operations are executed in a shared Continuous Integration (CI) 157 environment. The work needed to create such a CI environment is nontrivial, and 158 is outside the scope of this core workflow overview, but a full deep dive on 159 this topic can be found in our 160 [Running Terraform in Automation](https://www.terraform.io/guides/running-terraform-in-automation.html) 161 guide. 162 163 This longer iteration cycle of committing changes to version control and then 164 waiting for the CI pipeline to execute is often lengthy enough to prohibit using 165 speculative plans as a feedback loop while authoring individual Terraform 166 configuration changes. Speculative plans are still useful before new Terraform 167 changes are applied or even merged to the main development branch, however, as 168 we'll see in a minute. 169 170 ### Plan 171 172 For teams collaborating on infrastructure, Terraform's plan output creates an 173 opportunity for team members to review each other's work. This allows the team 174 to ask questions, evaluate risks, and catch mistakes before any potentially 175 harmful changes are made. 176 177 The natural place for these reviews to occur is alongside pull requests within 178 version control--the point at which an individual proposes a merge from their 179 working branch to the shared team branch. If team members review proposed 180 config changes alongside speculative plan output, they can evaluate whether the 181 intent of the change is being achieved by the plan. 182 183 The problem becomes producing that speculative plan output for the team to 184 review. Some teams that still run Terraform locally make a practice that pull 185 requests should include an attached copy of speculative plan output generated 186 by the change author. Others arrange for their CI system to post speculative 187 plan output to pull requests automatically. 188 189  190 191 In addition to reviewing the plan for the proper expression of its author's 192 intent, the team can also make an evaluation whether they want this change to 193 happen now. For example, if a team notices that a certain change could result 194 in service disruption, they may decide to delay merging its pull request until 195 they can schedule a maintenance window. 196 197 ### Apply 198 199 Once a pull request has been approved and merged, it's important for the team 200 to review the final concrete plan that's run against the shared team branch and 201 the latest version of the state file. 202 203 This plan has the potential to be different than the one reviewed on the pull 204 request due to issues like merge order or recent infrastructural changes. For 205 example, if a manual change was made to your infrastructure since the plan was 206 reviewed, the plan might be different when you merge. 207 208 It is at this point that the team asks questions about the potential 209 implications of applying the change. Do we expect any service disruption from 210 this change? Is there any part of this change that is high risk? Is there 211 anything in our system that we should be watching as we apply this? Is there 212 anyone we need to notify that this change is happening? 213 214 Depending on the change, sometimes team members will want to watch the apply 215 output as it is happening. For teams that are running Terraform locally, this 216 may involve a screen share with the team. For teams running Terraform in CI, 217 this may involve gathering around the build log. 218 219 Just like the workflow for individuals, the core workflow for teams is a loop 220 that plays out for each change. For some teams this loop happens a few times a 221 week, for others, many times a day. 222 223 ## The Core Workflow Enhanced by Terraform Enterprise 224 225 While the above described workflows enable the safe, predictable, and 226 reproducible creating or changing of infrastructure, there are multiple 227 collaboration points that can be streamlined, especially as teams and 228 organizations scale. We designed Terraform Enterprise to support and enhance 229 the core Terraform workflow for anyone collaborating on infrastructure, from 230 small teams to large organizations. Let's look at how Terraform Enterprise makes 231 for a better experience at each step. 232 233 ### Write 234 235 Terraform Enterprise provides a centralized and secure location for storing 236 input variables and state while also bringing back a tight feedback loop for 237 speculative plans for config authors. Terraform configuration interacts with 238 Terraform Enterprise via the ["remote" backend](/docs/backends/types/remote.html). 239 240 ``` 241 terraform { 242 backend "remote" { 243 organization = "my-org" 244 workspaces { 245 prefix = "my-app-" 246 } 247 } 248 } 249 ``` 250 251 Once the backend is wired up, a Terraform Enterprise API key is all that's 252 needed by team members to be able to edit config and run speculative plans 253 against the latest version of the state file using all the remotely stored 254 input variables. 255 256 ```sh 257 $ terraform workspace select my-app-dev 258 Switched to workspace "my-app-dev". 259 260 $ terraform plan 261 262 Running plan remotely in Terraform Enterprise. 263 264 Output will stream here. To view this plan in a browser, visit: 265 266 https://app.terraform.io/my-org/my-app-dev/.../ 267 268 Refreshing Terraform state in-memory prior to plan... 269 270 # ... 271 272 Plan: 1 to add, 0 to change, 0 to destroy. 273 ``` 274 275 With the assistance of this plan output, team members can each work on 276 authoring config until it is ready to propose as a change via a pull request. 277 278 ### Plan 279 280 Once a pull request is ready for review, Terraform Enterprise makes the process 281 of reviewing a speculative plan easier for team members. First, the plan is 282 automatically run when the pull request is created. Status updates to the pull 283 request indicate while the plan is in progress. 284 285 Once the plan is complete, the status update indicates whether there were any 286 changes in the speculative plan, right from the pull request view. 287 288 <!-- TODO: [ Screenshot of PR with preview details ] --> 289 290 For certain types of changes, this information is all that's needed for a team 291 member to be able to approve the pull request. When a teammate needs to do a 292 full review of the plan, clicking the link to Terraform Enterprise brings up a 293 view that allows them to quickly analyze the full plan details. 294 295 <!-- TODO: [ Screenshot of speculative plan details page ] --> 296 297 This page allows the reviewer to quickly determine if the plan is matching the 298 config author's intent and evaluate the risk of the change. 299 300 ### Apply 301 302 After merge, Terraform Enterprise presents the concrete plan to the team for 303 review and approval. 304 305  306 307 The team can discuss any outstanding questions about the plan before the change 308 is made. 309 310  311 312 Once the Apply is confirmed, Terraform Enterprise displays the progress live 313 to anyone who'd like to watch. 314 315  316 317 <!-- 318 319 TODO: Add this back in w/ screenshot of notification 320 321 And after the change completes, the team can be notified of its outcome. 322 323 [ Multi-screenshot of Slack alert indicating Apply completed successfully and 324 with error; except it's not gonna be Slack anymore? ] 325 326 --> 327 328 ## Conclusion 329 330 There are many different ways to use Terraform: as an individual user, a single 331 team, or an entire organization at scale. Choosing the best approach for the 332 density of collaboration needed will provide the most return on your investment 333 in the core Terraform workflow. For organizations using Terraform at scale, 334 Terraform Enterprise introduces new layers that build on this core workflow to 335 solve problems unique to teams and organizations.