Skip to content

Branch Planner and Terraform Cloud Integration

Branch Planner and Terraform Cloud Integration: Getting Started

With Branch Planner, you can provision the main branch directly on Terraform Cloud. TF-Controller communicates with Terraform Cloud to run the necessary plans and apply your approved code. The state is securely stored on Terraform Cloud.

Note: For now, Branch Planner only supports GitHub as the Git provider. We plan to add other Git providers in time.

Step-by-step Guide

Step 1: Create a Terraform Cloud Token

Use the terraform login command to obtain a Terraform Cloud token. Then use the token to create a Kubernetes Secret.

kubectl create secret generic \
  tfc-cli-config \
  --namespace=flux-system \
  --from-file=terraform.tfrc=/dev/stdin << EOF
credentials "app.terraform.io" {
  token = "xxxxxxxxxxxxxx.atlasv1.zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"           
}
EOF

Step 2: Create a Terraform CR

Create a Terraform CR to automatically plan and apply Terraform configurations on Terraform Cloud. In this example, the Branch Planner reads the Terraform configurations from a Git repository to plan, apply, and store the state in a Terraform Cloud workspace.

The token from Step 1 is specified as the value of spec.cliConfigSecretRef and is used to authenticate with Terraform Cloud.

---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: branch-planner-demo
  namespace: flux-system
spec:
  interval: 30s
  url: https://github.com/tf-controller/branch-planner-demo
  ref:
    branch: main
---
apiVersion: infra.contrib.fluxcd.io/v1alpha2
kind: Terraform
metadata:
  name: branch-planner-tfc
  namespace: flux-system
spec:
  interval: 2m
  approvePlan: auto
  cloud:
    organization: weaveworks
    workspaces:
      name: branch-planner-tfc
  cliConfigSecretRef:
    name: tfc-cli-config
    namespace: flux-system
  vars:
  - name: subject
    value: "world"
  path: ./
  sourceRef:
    kind: GitRepository
    name: branch-planner-demo
    namespace: flux-system

Step 3: Edit File, Create a Branch, and Open a Pull Request

  1. Navigate to Your Repository: Open a web browser and visit your GitHub repository. For our example, navigate here.

  2. Locate the File to Edit: Browse through the repository's file structure and click on the Terraform configuration file you wish to edit.

  3. Edit the File: Click on the pencil icon (edit) located on the top right of the file content. Make your desired changes to the Terraform configurations. For instance, you might change the "Hello World" content in the main.tf file.

Once you've made your edits, scroll down to prepare to commit the changes.

  1. Commit the Changes to a New Branch: Instead of committing directly to the main branch, choose the option to "Create a new branch" for this commit and start a pull request. Name the branch something descriptive—for example, change-hello-world-message.

Click on the "Propose Changes" button.

  1. Open a Pull Request (PR): After proposing your changes, you'll be led to the "Open a pull request" page. Fill in the details of your PR, explaining the changes you made, their purpose, and any other pertinent information.

Click on the "Create Pull Request" button.

  1. Review Terraform Plan in PR Comments: Once the PR is created, the Branch Planner will trigger a Terraform plan. After the plan is completed, the results will be posted as a comment on the PR. This enables you and your team to review the expected changes before they're applied.

Step 4: Review, Approve and Merge the Pull Request

  1. Review the Changes:

    • Navigate to the Pull Requests tab in your GitHub repository.
    • Click on the title of your pull request to see the details.
    • Examine the Files changed section to see the exact modifications made to the Terraform configurations.
    • Check the comments for the Terraform plan output generated by Branch Planner. Ensure the plan matches your expectations.

  2. Iterate on Changes if Necessary:

    • If you spot any discrepancies or wish to make further adjustments, click on the file in the Files changed section.
    • After making the desired edits, commit the changes to the same branch. This will automatically prompt TF-Controller and Branch Planner to generate a new plan.
    • If, for any reason, the automatic replan doesn't occur or you believe there might be an inconsistency, you can manually trigger a new plan by commenting !replan on the PR. Branch Planner will then process the request and display the new plan results.

  3. Approve the Changes:

    • If you're content with the changes and the associated Terraform plan, move to the Review changes button on the PR page.
    • Select the Approve option from the dropdown and optionally add any final comments.
    • Click Submit review to finalize your approval.

  4. Merge the Pull Request:

    • With the changes approved, click on the Merge pull request button.
    • Choose your desired merge strategy from the options provided, such as "Squash and merge" or "Rebase and merge".
    • Click Confirm merge.
    • Following the merge, TF-Controller will take over. It will send the updated Terraform configuration to Terraform Cloud, where the changes will be planned and then applied. The resulting infrastructure state will be securely stored within your Terraform Cloud workspace.