Get Started with the Terraform Controller

Preflight Checks

To set up the Terraform Controller (TF-Controller), follow the steps in the preflight checks. Here is a summary of what you will need to do:

1. Install Flux v0.32.0 or later on your cluster. This includes installing the Flux CLI on your local machine and installing the Flux controllers on the cluster.
2. Configure the network firewall or security groups on your cluster to allow incoming connections to port 30000 on each Runner's Pod in each namespace. This will allow the Controller to communicate with the Runner's Pod via gRPC.
3. Configure the network firewall or security groups on your cluster to allow the Controller to download tar.gz BLOBs from the Source controller via port 80 and to post events to the Notification controller via port 80.

The exact steps for setting up the TF-controller will depend on the specific environment and infrastructure that you are using. The project's documentation provides additional information to help with setup.

Setup

Perform the following actions to set up TF-Controller:

1. Create a local cluster using a tool such as kind or minikube. This will allow you to develop and test TF-Controller in a local environment before deploying it to a production cluster.

   kind create cluster --name tf-controller

2. Install the Flux CLI on your local machine. This will allow you to interact with the Flux controllers on your cluster.

   brew install fluxcd/tap/flux

3. Prepare a Git repository to store the configuration files and manifests for Flux and TF-controller. For this example we'll use GitHub. To follow along, you'll need a GitHub account and personal access token with repo permissions. You'll also need to properly configure your Git client by setting your username and email address.

Assuming your username is $GITHUB_USER, you can create a new repository called gitops-tf-controller using the following command:

export GITHUB_USER=<your github username>
export GITHUB_TOKEN=<your github personal access token>

gh repo create $GITHUB_USER/gitops-tf-controller

4. Bootstrap the cluster with Flux v2 (v0.32.0 or later) using the path (for example) ./cluster/my-cluster. This will install Flux on the cluster and create a Flux system at ./cluster/my-cluster/flux-system.

   git clone git@github.com:$GITHUB_USER/gitops-tf-controller.git
   cd gitops-tf-controller
   
   flux bootstrap github \
     --owner=$GITHUB_USER \
     --repository=gitops-tf-controller \
     --branch=main \
      --path=./cluster/my-cluster \
      --personal \
      --token-auth

5. Create a directory at ./cluster/my-cluster/infra/:

   mkdir -p ./cluster/my-cluster/infra/

Download the TF-controller manifest from the release location and save it to ./cluster/my-cluster/infra/tf-controller.yaml—placing the file tf-controller.yaml in this directory:

```bash
curl -s https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml > ./cluster/my-cluster/infra/tf-controller.yaml
```

Add the manifest file to the Git repository, then push the changes to your repository.

6. In the same directory, create a kustomization.yaml file that contains the following:

   ```yaml
   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   resources:
     - tf-controller.yaml
   ```
   Add the kustomization.yaml file to your Git repository, then push the changes to your repository.

If you want to use TF-Controller with the Notification Controller, you will also need to modify the manifest to enable the two controllers to work together. The exact steps for doing this will depend on the specific requirements of your environment and the configuration of the Notification Controller. You may need to refer to the documentation for the TF-Controller and Notification Controller for more information on how to set this up.

Other Installation Methods

Before using TF-Controller, you must install Flux by using either flux install or the flux bootstrap command. Make sure you have the latest version of Flux. After that, you can install TF-controller with Flux HelmRelease with this command:

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

For the most recent TF-Controller release candidate, please use rc.yaml:

kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml

or manually with Helm by:

# Add tf-controller helm repository
helm repo add tf-controller https://weaveworks.github.io/tf-controller/

# Install tf-controller
helm upgrade -i tf-controller tf-controller/tf-controller \
    --namespace flux-system

For details on configurable parameters of the TF-controller chart, please see this chart Readme.

Alternatively, you can install TF-controller via kubectl:

export TF_CON_VER=v0.14.0
kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.crds.yaml
kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.rbac.yaml
kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.deployment.yaml

Quick Start

Here's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.

Define Source

First, define a Source controller's source (GitRepository, Bucket, OCIRepository)—for example:

apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: helloworld
  namespace: flux-system
spec:
  interval: 30s
  url: https://github.com/tf-controller/helloworld
  ref:
    branch: main

The GitOps Automation Mode

In this mode, Terraform resources will be planned and automatically applied for you. Enable it by setting .spec.approvePlan=auto:

apiVersion: infra.contrib.fluxcd.io/v1alpha2
kind: Terraform
metadata:
  name: helloworld
  namespace: flux-system
spec:
  interval: 1m
  approvePlan: auto
  path: ./
  sourceRef:
    kind: GitRepository
    name: helloworld
    namespace: flux-system

For a full list of features and how to use them, please visit the Terraform overview.

Troubleshooting

Getting a drift detected event message when it's a change of source that triggered the update

Whenever you change a source, you will get a new plan. TF-controller picks up the new plan and applies it. Drift happens if, and only if, the live system changes intentionally. Then TF-controller will generate a lengthy message see an example stating that a drift has occurred. If there is drift, the icon will be red in the TF Objects > Status column of the WGE UI.

Other Examples

• A Terraform GitOps with Flux to automatically reconcile your AWS IAM Policies.
• GitOps an existing EKS cluster by partially importing its nodegroup and managing it with TF-controller: An EKS scaling example.