Merge pull request #1160 from weaveworks/docs-edits-dec5

Changes URLs for better SEO and fixes small typos
flux-iac · Dec 18, 2023 · 764ed48 · 764ed48
2 parents 12e53ed + c0bec46
commit 764ed48
Show file tree

Hide file tree

Showing 48 changed files with 289 additions and 228 deletions.
diff --git a/...planner/branch-planner-getting-started.md → ...planner/branch-planner-getting-started.md b/...planner/branch-planner-getting-started.md → ...planner/branch-planner-getting-started.md
diff --git a/...lanner-tfc-integration-getting-started.md → ...lanner-tfc-integration-getting-started.md b/...lanner-tfc-integration-getting-started.md → ...lanner-tfc-integration-getting-started.md
@@ -117,7 +117,3 @@ This enables you and your team to review the expected changes before they're app
     - 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.
-
-## Conclusion
-
-Combining tools like Terraform Cloud, TF-Controller with Branch Planner, and GitHub offers an innovative way for organization to streamline their infrastructure management. Being able to easily review and understand changes in a familiar platform like GitHub ensures clarity. With the immediate feedback provided by Branch Planner, teams can anticipate and discuss potential changes on different branches, before they're implemented. This combination doesn't just make updates safer and more predictable, but it promotes team-wide involvement. Furthermore, the collaboration between TF-Controller and Terraform Cloud guarantees consistency, minimizing errors, and being GitOps. As we navigate an increasingly complex IaC landscape, such simplified, integrated approaches are key to efficient, secure and error-free operations.
diff --git a/docs/branch_planner/branch-planner.png → docs/branch-planner/branch-planner.png b/docs/branch_planner/branch-planner.png → docs/branch-planner/branch-planner.png
diff --git a/docs/branch_planner/index.md → docs/branch-planner/index.md b/docs/branch_planner/index.md → docs/branch-planner/index.md
diff --git a/docs/branch_planner/rc.yaml → docs/branch-planner/rc.yaml b/docs/branch_planner/rc.yaml → docs/branch-planner/rc.yaml
diff --git a/docs/branch_planner/release.yaml → docs/branch-planner/release.yaml b/docs/branch_planner/release.yaml → docs/branch-planner/release.yaml
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -59,17 +59,17 @@ Tested with GKE Autopilot v1.27.3-gke.100.
 ### With Branch Planner
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/release.yaml
+kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch-planner/release.yaml
 ```
 
-For the most recent release candidate of TF-controller with Branch Planner, please use [branch_planner/rc.yaml](https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/rc.yaml).
+For the most recent release candidate of TF-controller with Branch Planner, please use [branch-planner/rc.yaml](https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch-planner/rc.yaml).
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/rc.yaml
+kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch-planner/rc.yaml
 ```
 
 For more details about the Branch Planner, please visit the
-[Branch Planner documentation](./branch_planner/getting-started.md).
+[Branch Planner documentation](./branch-planner/branch-planner-getting-started.md).
 
 ### Manual installation
 
@@ -138,7 +138,7 @@ spec:
     namespace: flux-system
 ```
 
-For a full list of features and how to use them, please follow the [Use TF-controller](use_tf_controller/index.md) guide.
+For a full list of features and how to use them, please follow the [Use TF-controller](use-tf-controller/index.md) guide.
 
 ## Other Examples
   * A Terraform GitOps with Flux to automatically reconcile your [AWS IAM Policies](https://github.com/tf-controller/aws-iam-policies).

diff --git a/docs/how_to/index.md b/docs/how_to/index.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # Overview
 
-~> **BREAKING NEWS:** The **Technology Preview** of the Branch Planner is now available! [Learn more](./branch_planner/index.md) or Get started with the [Branch Planner](./branch_planner/getting-started.md).
+~> **BREAKING NEWS:** The **Technology Preview** of the Branch Planner is now available! [Learn more](./branch-planner/index.md) or Get started with the [Branch Planner](./branch-planner/branch-planner-getting-started.md).
 
 TF-controller is a reliable controller for [Flux](https://fluxcd.io) to reconcile Terraform resources
 in the GitOps way.
@@ -9,6 +9,10 @@ and application resources, in the Kubernetes and Terraform universe, at your own
 
 "At your own pace" means you don't need to GitOps-ify everything at once.
 
+A high-level diagram of how TF-controller works is shown below:
+
+![TF-controller basic architecture](tf-controller-basic-architecture.png)
+
 TF-controller offers many GitOps models:
 
   1. **GitOps Automation Model:** GitOps your Terraform resources from the provision steps to the enforcement steps, like a whole EKS cluster.

diff --git a/docs/tf-controller-basic-architecture.png b/docs/tf-controller-basic-architecture.png
diff --git a/...o/backup_and_restore_a_Terraform_state.md → ...r/backup-and-restore-a-Terraform-state.md b/...o/backup_and_restore_a_Terraform_state.md → ...r/backup-and-restore-a-Terraform-state.md
diff --git a/...o/build-and-use-a-custom-runnner-image.md → ...er/build-and-use-a-custom-runner-image.md b/...o/build-and-use-a-custom-runnner-image.md → ...er/build-and-use-a-custom-runner-image.md
@@ -1,13 +1,12 @@
-# Using a custom runner image for TF-Controller
+# Build and Use a Custom Runner Image
 
-In order to build a custom runner image, you need a Dockerfile that extends the base image and that adds Terraform, plus any additional required tooling.
-The repository that contains the base images is [here](ghcr.io/weaveworks/tf-runner). All base image tags follow the following format: `${TF_CONTROLLER_VERSION}-base`
+To build a custom runner image, you need a Dockerfile that extends the base image and that adds Terraform, plus any additional required tooling. The repository that contains the base images is [here](ghcr.io/weaveworks/tf-runner). All base image tags follow the following format: `${TF_CONTROLLER_VERSION}-base`.
 
 ## Prerequisites
 
 You need Docker and Git to build the image.
 
-## Build the image
+## Build the Image
 
 1. Create a `Dockerfile` that extends the base image and that adds Terraform, plus any additional required tooling. For example:
 
@@ -60,7 +59,7 @@ values:
       tag: v0.16.0-rc.3
 ```
 
-4. Commit and push the changes to Git, and confirm that the HelmRelease has been updated:
+4. Commit and push the changes to Git. Confirm that the HelmRelease has been updated:
 
 ```bash
 kubectl get deployments.apps -n flux-system tf-controller -o jsonpath='{.spec.template.spec.containers[*]}' | jq '.env[] | select(.name == "RUNNER_POD_IMAGE")'
@@ -72,5 +71,4 @@ kubectl get deployments.apps -n flux-system tf-controller -o jsonpath='{.spec.te
 
 ### References
 
-A set of GitHub actions in the TF-Controller community repo facilitate a process that's similar to the above, but using GitHub Actions to build and push the image.
-You can find them [here](https://github.com/tf-controller/tf-runner-images/blob/main/.github/workflows/release-runner-images.yaml).
+A [set of GitHub actions in the TF-Controller community repo](https://github.com/tf-controller/tf-runner-images/blob/main/.github/workflows/release-runner-images.yaml) facilitates a process similar to the above, but uses GitHub Actions to build and push the image.
diff --git a/...tect_drifts_only_without_plan_or_apply.md → ...tect-drifts-only-without-plan-or-apply.md b/...tect_drifts_only_without_plan_or_apply.md → ...tect-drifts-only-without-plan-or-apply.md
@@ -1,4 +1,4 @@
-## Use TF-controller to detect drifts only without plan or apply
+## Use TF-Controller to detect drifts only without plan or apply
 
 We can set `.spec.approvePlan` to `disable` to tell the controller to detect drifts of your Terraform resources only. Doing so will skip the `plan` and `apply` stages.
 

diff --git a/docs/how_to/flux_receiver_and_alert.md → ...-tf-controller/flux-receiver-and-alert.md b/docs/how_to/flux_receiver_and_alert.md → ...-tf-controller/flux-receiver-and-alert.md
@@ -1,14 +1,14 @@
 # Integrate with Flux Receivers and Alerts
 
-These docs show how to customize your Flux installation so that Flux API
-resources like `Receivers` and `Alerts` can be used with third-party custom
+You can customize your Flux installation to use Flux API
+resources like `Receivers` and `Alerts` with third-party custom
 resource definitions such as the `Terraform` API CRD.
 
 You will need to add a patch to the `kustomization.yaml` in your Flux cluster
-installation's bootstrap manifests, find it under the `flux-system` directory.
+installation's bootstrap manifests. Find it under the `flux-system` directory.
 
 <!-- <a id="enable-notifications-for-third-party-controllers">&nbsp;</a> -->
-### Enable notifications for third party controllers
+### Enable Notifications for Third-Party Controllers
 
 Enable notifications for 3rd party Flux controllers such as [tf-controller](https://github.com/weaveworks/tf-controller):
 

diff --git a/...oller/to_force_unlock_Terraform_states.md → ...ntroller/force-unlock-terraform-states.md b/...oller/to_force_unlock_Terraform_states.md → ...ntroller/force-unlock-terraform-states.md
@@ -1,11 +1,11 @@
-# Use TF-controller to force unlock Terraform states
+# Use TF-Controller to force unlock Terraform states
 
 In some situations, you may need to perform the Terraform [force-unlock](https://www.terraform.io/language/state/locking#force-unlock) operation on the tfstate inside the cluster. 
 
 There are three possible values of `.spec.tfstate.forceUnlock`, which are `yes`, `no`, and `auto`.
 The default value is `no`, which means that you disable this behaviour.
 
-The `auto` force-unlock mode will automatically use the lock identifier produced by the associated state file instead of specified lock identifier.
+The `auto` force-unlock mode will automatically use the lock identifier produced by the associated state file instead of the specified lock identifier.
 
 The recommended way is to do manual force unlock. To manually `force-unlock`, you need to:
 

diff --git a/docs/use-tf-controller/index.md b/docs/use-tf-controller/index.md
@@ -0,0 +1,32 @@
+# Use TF-controller
+
+  - [Use TF-controller to provision resources and **auto approve**](provision-resources-and-auto-approve.md)
+  - [Use TF-controller to **plan and manually apply** Terraform resources](plan-and-manually-apply-terraform-resources.md)
+  - [Use TF-controller to provision resources and **obtain outputs**](provision-resources-obtain-outputs.md)
+  - [Use TF-controller to **detect drifts only** without plan or apply](detect-drifts-only-without-plan-or-apply.md)
+  - [Use TF-controller with **drift detection disabled**](with-drift-detection-disabled.md)
+  - [Use TF-controller with **AWS EKS IRSA**](with-aws-eks-irsa.md)
+  - [Use TF-controller to **set variables** for Terraform resources](set-variables-for-terraform-resources.md)
+  - [Use TF-controller with a **custom backend**](with-a-custom-backend.md)
+  - [Use TF-controller with an **OCI Artifact as Source**](with-an-oci-artifact-as-source.md)
+  - [Use TF-controller to provision Terraform resources that are required **health checks**](provision-Terraform-resources-that-are-required-health-checks.md)
+  - [Use TF-controller to provision resources and **destroy them when the Terraform object gets deleted**](provision-resources-and-destroy-them-when-terraform-object-gets-deleted.md)
+  - [Use TF-controller to **force unlock** Terraform states](force-unlock-terraform-states.md)
+  - [Use TF-controller with Terraform Runners enabled via Env Variables](with-tf-runner-logging.md)
+  - [Use TF-controller to provision resources with **customized Runner Pods**](provision-resources-with-customized-runner-pods.md)
+  - [Use TF-controller with **Terraform Enterprise**](integration-with-terraform-enterprise-or-cloud.md)
+  - [Use TF-controller with **primitive modules**](with-primitive-modules.md)
+  - [Use TF-controller with **GitOps dependency management**](with-gitops-dependency-management.md)
+  - [Use TF-controller with **the ready-to-use AWS package**](with-the-ready-to-use-aws-package.md)
+  - [User TF-controller with **plan-only mode**](with-plan-only-mode.md)
+  - [Use TF-controller with **external webhooks**](with-external-webhooks.md)
+  - [Use TF-controller with Terraform Runners **exposed via hostname/subdomain**](with-tf-runner-exposed-using-hostname-subdomain.md)
+  - [How to **backup and restore** a Terraform state](backup-and-restore-a-Terraform-state.md)
+  - [How to **build and use** a custom runner image](build-and-use-a-custom-runner-image.md)
+  - [How to integrate with Flux Receivers and Alerts?](flux-receiver-and-alert.md)
+  - [How does the interval and retryInterval work?](interval-and-retryInterval.md)
+  - [How does the resource deletion work?](resource-deletion.md)
+  - [How to troubleshoot with **Break the Glass** mode](troubleshooting-with-break-the-glass-mode.md)
+  - [How to enable cross-namespace references](use-cross-namespace-refs.md)
+  - [How to run TF-controller in Azure Kubernetes Service](with-azure.md)
+  - [How to upgrade TF-controller to a newer version](upgrade-tf-controller.md)
diff --git a/...f_controller/with_Terraform_Enterprise.md → ...ion-with-terraform-enterprise-or-cloud.md b/...f_controller/with_Terraform_Enterprise.md → ...ion-with-terraform-enterprise-or-cloud.md
@@ -1,9 +1,18 @@
-# Use TF-controller with Terraform Enterprise
+# Terraform Enterprise and Terraform Cloud Integration
 
-## Terraform Enterprise Integration
+Terraform is a secure and robust platform designed to store the Terraform states 
+for your production systems. When working with Infrastructure as Code, 
+managing and ensuring the state is both secure and consistent is critical. 
 
-Starting from v0.9.5, Weave TF-controller officially supports integration to Terraform Cloud (TFC) and 
-Terraform Enterprise (TFE). Here are the steps to set up TF-controller for your TFE instance.
+TF-Controller supports both Terraform Cloud and Terraform Enterprise. The `spec.cloud` in the Terraform CRD enables users to integrate their Kubernetes configurations with Terraform workflows.
+
+To get started, simply place your Terraform Cloud token in a Kubernetes Secret
+and specify it in the `spec.cliConfigSecretRef` field of the Terraform CR.
+The `spec.cloud` field specifies the organization and workspace name.
+
+## Terraform Enterprise
+
+Here are the steps to set up TF-Controller for your TFE instance.
 
 ![](tfe_integration_01.png)
 
@@ -29,7 +38,7 @@ Content of the file will look like this:
 ```
 
 ### Prepare an TFRC file
-TF-controller accepts an TFRC file in the HCL format. So you have to prepare `terraform.tfrc` file using contents from above.
+TF-Controller accepts an TFRC file in the HCL format. So you have to prepare `terraform.tfrc` file using contents from above.
 ```hcl
 credentials "tfe.dev.example.com" {
   token = "mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
@@ -109,4 +118,26 @@ output "greeting" {
 
 ### Terraform Cloud
 
-For connecting to Terraform Cloud, please replace your hostname to `app.terraform.io`.
+TF-Controller can send your Terraform resources to be planned and applied via Terraform Cloud. 
+States are automatically stored in your Terraform Cloud's workspace. 
+To use TF-Controller with Terraform Cloud, replace your hostname to `app.terraform.io`. Also, set `spec.approvalPlan` to `auto`. 
+
+Here's how the configuration looks:
+
+```yaml
+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
+```
diff --git a/docs/how_to/interval_and_retryInterval.md → ...-controller/interval-and-retryInterval.md b/docs/how_to/interval_and_retryInterval.md → ...-controller/interval-and-retryInterval.md
@@ -1,4 +1,4 @@
-# How does the interval and retryInterval work?
+# Troubleshooting with Interval and retryInterval
 
 ## Overview
 This document describes the requeue behavior of the Reconcile method in the TerraformReconciler struct in the code base. 

diff --git a/docs/use-tf-controller/plan-and-manually-apply-terraform-resources.md b/docs/use-tf-controller/plan-and-manually-apply-terraform-resources.md
@@ -0,0 +1,60 @@
+# Use TF-controller to plan and manually apply Terraform resources
+
+Assume that you have a `GitRepository` object named `helloworld` pointing to a Git repository, and you want to plan and apply the Terraform resources under `./` of that Git repo. Let's walk through the steps of using TF-Controller to plan and
+manually apply Terraform resources. 
+
+- Create a `Terraform` object and set the necessary fields in the spec:
+  - `approvePlan`, which sets the mode. For plan and manual approval mode, either keep this field blank or omit it entirely.
+  - `interval`, which determines how often TF-Controller will run the Terraform configuration
+  - `path`, which specifies the location of the configuration files, in this case `./`
+  - `sourceRef`, which points to the `helloworld` GitRepository object
+- Once this object is created, use kubectl to obtain the `approvePlan` value and set it in the `Terraform` object. 
+- After making our changes and pushing them to the Git repository, TF-Controller will apply the plan and create the real resources.
+
+Here is an example:
+
+```yaml hl_lines="7"
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
+kind: Terraform
+metadata:
+  name: helloworld
+  namespace: flux-system
+spec:
+  approvePlan: "" # or you can omit this field
+  interval: 1m
+  path: ./
+  sourceRef:
+    kind: GitRepository
+    name: helloworld
+    namespace: flux-system
+```
+
+## View the approval message
+
+After a reconciliation loop, TF-Controller will generate a plan. Run this command to receive the `.spec.approvePlan` value from TF-Controller, which you'll need to approve the plan:
+
+```bash
+kubectl -n flux-system get tf/helloworld
+```
+
+This value enables you to edit the Terraform object file and set the `spec.approvePlan` field
+to the value obtained from the message.
+
+After making your changes and pushing them to the Git repository,
+TF-Controller will apply the plan and create the real resources.
+
+```yaml hl_lines="7"
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
+kind: Terraform
+metadata:
+  name: hello-world
+  namespace: flux-system
+spec:
+  approvePlan: plan-main-b8e362c206 # first 8 digits of a commit hash is enough
+  interval: 1m
+  path: ./
+  sourceRef:
+    kind: GitRepository
+    name: helloworld
+    namespace: flux-system
+```
diff --git a/...ources_that_are_required_health_checks.md → ...ources-that-are-required-health-checks.md b/...ources_that_are_required_health_checks.md → ...ources-that-are-required-health-checks.md
@@ -1,4 +1,4 @@
-# Use TF-controller to provision Terraform resources that are required health checks
+# Use TF-Controller to provision Terraform resources that are required health checks
 
 For some Terraform resources, it may be useful to perform health checks on them to verify that they are ready to accept connection before the terraform goes into `Ready` state: