github.com/kanishk98/terraform@v1.3.0-dev.0.20220917174235-661ca8088a6a/website/docs/intro/core-workflow.mdx (about)

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