Getting Started With Branch Planner

When the Branch Planner is enabled through Helm values, it will watch all configured Terraform resources, check their referenced Source, and poll for Pull Requests using GitHub's API plus the provided token.

When the Branch Planner detects an open Pull Request, it either creates a new Terraform object or updates an existing one, applying Plan Only mode based on the original Terraform object.

When a Plan Output becomes available, the Branch Planner creates a new comment under the Pull Request with the content of the Plan Output included.

Prerequisites

Flux is installed on the cluster.
A GitHub API token.
Knowledge about GitOps Terraform Controller (see docs).

Quick Start Guide

This section describe how to install Branch Planner using HelmRelease object in the flux-system namespace with minimum configuration on a KinD cluster.

Create a KinD cluster.
```
kind create cluster
```
Install Flux. Please make sure you have the latest version of Flux (v2 GA).
```
flux install
```

Create a Secret that contains GitHub API token. If you do not use gh cli, please feel free to copy and paste the token from GitHub's website.

export GITHUB_TOKEN=$(gh auth token)

kubectl create secret generic branch-planner-token \
    --namespace=flux-system \
    --from-literal="token=${GITHUB_TOKEN}"

Install Branch Planner from a HelmRelease provided by the TF-controller repository. Please make sure that you use TF Controller v0.16.0-rc.2 or later.

kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/fa4b3b85d316340d897fda4fed757265ba2cd30e/docs/branch_planner/release.yaml

Create a Terraform object with a Source pointing to a repository. You repository must contain a Terraform file, for example main.tf. Please take a look at https://github.com/tf-controller/branch-planner-demo for an example.

export GITHUB_USER=<your user>
export GITHUB_REPO=<your repo>

cat <<EOF | kubectl apply -f -
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: branch-planner-demo
  namespace: flux-system
spec:
  interval: 30s
  url: https://github.com/${GITHUB_USER}/${GITHUB_REPO}
  ref:
    branch: main
---
apiVersion: infra.contrib.fluxcd.io/v1alpha2
kind: Terraform
metadata:
  name: branch-planner-demo
  namespace: flux-system
spec:
  approvePlan: auto
  path: ./
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: branch-planner-demo
    namespace: flux-system
EOF

Now you can go to your GitHub repo and create a Pull Request. The Branch Planner will create a new Terraform object with Plan Only mode enabled, and generate a new plan for you.

Configure Branch Planner

Branch Planner uses a ConfigMap as configuration. That ConfigMap is optional to use but useful for fine-tuning Branch Planner.

Custom Configuration

By default, Branch Planner will look for the branch-planner ConfigMap in the same namespace as where the tf-controller is installed. That ConfigMap allows users to precisely specify which Terraform resources in a cluster should be monitored by Branch Planner.

The ConfigMap has two fields:

secretName, which contains the API token to access GitHub.
resources, which defines a list of resources to watch.

---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: flux-system
  name: branch-planner
data:
  secretName: branch-planner-token
  resources: |-
    - namespace: terraform

Secret

Branch Planner uses the referenced Secret with a token field that acquires the API token to fetch Pull Request information.

kubectl create secret generic branch-planner-token \
    --namespace=flux-system \
    --from-literal="token=${GITHUB_TOKEN}"

Resources

If the resources list is empty, nothing will be watched. The resource definition can be exact or namespace-wide.

With the following configuration file, the Branch Planner will watch all Terraform objects in the terraform namespace, and the exact-terraform-object Terraform object in default namespace.

data:
  resources:
    - namespace: default
      name: exact-terraform-object
    - namespace: terraform

Default Configuration

If a ConfigMap is not found, it will watch the flux-system namespace for any Terraform resources and expect to find a GitHub token in a secret named branch-planner-token in the flux-system namespace. Note that supplying a secret with a token is a necessary task, otherwise Branch Planner will not be able to interact with the GitHub API.

Enable Branch Planner

To enable branch planner, set the branchPlanner.enabled to true in the Helm values files.

---
branchPlanner:
  enabled: true