add break-the-glass and update api version in docs

Signed-off-by: Chanwit Kaewkasi <chanwit@gmail.com>

api/v1alpha2/groupversion_info.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1alpha1 contains API Schema definitions for the infra v1alpha1 API group
+// Package v1alpha2 contains API Schema definitions for the infra v1alpha2 API group
 // +kubebuilder:object:generate=true
 // +groupName=infra.contrib.fluxcd.io
 package v1alpha2

docs/how_to/index.md

@@ -1,3 +1,4 @@
 # How to
 
+  - [How to troubleshoot with **Break the Glass** mode](troubleshooting_with_break_the_glass_mode.md)
   - [How to **backup and restore** a Terraform state](backup_and_restore_a_Terraform_state.md)

docs/how_to/troubleshooting_with_break_the_glass_mode.md

@@ -0,0 +1,50 @@
+# Break the glass
+
+## What is break the glass?
+
+"Break the glass" refers to a troubleshooting mode specifically designed
+to provide a manual solution when the Terraform controller (TF-controller) 
+is not performing as expected. There are two primary methods of initiating this mode:
+
+1. Using the `tfctl` command-line tool.
+2. Setting the `spec.breakTheGlass` field to `true` in the Terraform object.
+
+## Using `tfctl` to Break the Glass
+
+To start a one-time troubleshooting session, you can use the `tfctl break-glass` command. For instance:
+
+```shell
+tfctl break-glass hello-world
+```
+
+This command initiates a session that allows you to execute any Terraform command
+to rectify the issues with your Terraform resources. It is noteworthy that this command
+does not require setting the `spec.breakTheGlass` field to `true` in the Terraform object.
+
+After resolving the issues, you can simply exit the shell. 
+GitOps will then continue to reconcile the Terraform object.
+
+## Break the glass with `spec.breakTheGlass` field
+
+This feature is particularly useful for troubleshooting Terraform objects at their initialization stage or in situations with unexpected errors.
+It is generally not recommended to use this mode routinely for fixing Terraform resources.
+
+You can enable the 'Break the Glass' feature for every reconciliation by setting the `breakTheGlass` field to `true` in the `spec` of the Terraform object.
+
+Here is a sample example:
+
+```yaml
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
+kind: Terraform
+metadata:
+  name: hello-world
+  namespace: flux-system
+spec:
+  breakTheGlass: true
+  interval: 1m
+  path: ./
+  sourceRef:
+    kind: GitRepository
+    name: helloworld
+    namespace: flux-system
+```

docs/tfctl.md

@@ -4,7 +4,13 @@
 
 ## Installation
 
-You can download the `tfctl` binary via the GitHub releases page: [https://github.com/weaveworks/tf-controller/releases](https://github.com/weaveworks/tf-controller/releases)
+To install `tfctl` via Homebrew, run the following command:
+
+```shell
+brew install weaveworks/tap/tfctl
+```
+
+You can also download the `tfctl` binary via the GitHub releases page: [https://github.com/weaveworks/tf-controller/releases](https://github.com/weaveworks/tf-controller/releases).
 
 ```
 Usage:

docs/use_tf_controller/to_detect_drifts_only_without_plan_or_apply.md

@@ -3,7 +3,7 @@
 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.
 
 ```yaml hl_lines="7"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: hello-world

docs/use_tf_controller/to_force_unlock_Terraform_states.md

@@ -15,7 +15,7 @@ The recommended way is to do manual force unlock. To manually `force-unlock`, yo
 as the following example:
 
 ```yaml hl_lines="14-16"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/to_plan_and_manually_apply_Terraform_resources.md

@@ -27,7 +27,7 @@ the `path` field specifies the location of the configuration files,
 and the `sourceRef` field points to the GitRepository object.
 
 ```yaml hl_lines="7"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -62,7 +62,7 @@ This process is known as the plan & manual approval workflow,
 as it involves generating a plan and requiring manual approval before the changes are applied.
 
 ```yaml hl_lines="7"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: hello-world

docs/use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks.md

@@ -25,7 +25,7 @@ We can use standard Go template expressions, like `${{ .rdsAddress }}`, to refer
 We support two types of health checks, `tcp` amd `http`. The `tcp` type allows us to verify a TCP connection, while the `http` type is for verify an HTTP URL. The default timeout of each health check is 20 seconds.
 
 ```yaml hl_lines="14-25"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/to_provision_resources_and_auto_approve.md

@@ -40,7 +40,7 @@ your infrastructure is properly managed and controlled.
 The following is an example of a `Terraform` object; we use the "auto-apply" mode:
 
 ```yaml hl_lines="8"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted.md

@@ -11,7 +11,7 @@ To enable destroy resources on object deletion, set `.spec.destroyResourcesOnDel
 ~> **WARNING:** This feature will destroy your resources on the cloud if the Terraform object gets deleted. Please use it with cautions.
 
 ```yaml hl_lines="8"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/to_provision_resources_and_obtain_outputs.md

@@ -7,7 +7,7 @@ Outputs created by Terraform can be written to a secret using `.spec.writeOutput
 We can specify a target secret in `.spec.writeOutputsToSecret.name`, and the controller will write all outputs to the secret by default.
 
 ```yaml hl_lines="14-15"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -29,7 +29,7 @@ spec:
 We can choose only a subset of outputs by specify output names we'd like to write in the `.spec.writeOutputsToSecret.outputs` array.
 
 ```yaml hl_lines="16-18"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -59,7 +59,7 @@ TF-controller supports mapping output name using the `old_name:new_name` format.
 In the following example, we renamed `age_key` output as `age.agekey` entry for the `helloworld-output` Secret's data, so that other components in the GitOps pipeline could consume it.
 
 ```yaml hl_lines="16-17"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -84,7 +84,7 @@ As an example, operators such as [kubernetes-replicator](https://github.com/mitt
 allow replicating secrets from one namespace to another but use annotations to do so.
 
 ```yaml hl_lines="16-19"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/to_provision_resources_with_customized_Runner_Pods.md

@@ -7,7 +7,7 @@ For example, for Azure AKS to grant pod active directory permissions using Azure
 a label like `aadpodidbinding: myIdentity` on the pod is required.
 
 ```yaml
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -33,7 +33,7 @@ spec:
 By default, the Terraform controller uses `RUNNER_POD_IMAGE` environment variable to identify the Runner Pod's image to use. You can customize the image on the global level by updating the value of the environment variable or, you can specify an image to use per Terraform object for its reconciliation.
 
 ```yaml
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -56,4 +56,4 @@ You can use [`runner.Dockerfile`](https://github.com/weaveworks/tf-controller/bl
 ## Customize Runner Pod Specifications
 
 You can also customize various Runner Pod `spec` fields to control and configure how the Runner Pod runs. 
-For example, you can configure Runner Pod `spec` affinity and tolerations if you need to run in on a specific set of nodes. Please see [RunnerPodSpec](https://weaveworks.github.io/tf-controller/References/terraform/#infra.contrib.fluxcd.io/v1alpha1.RunnerPodSpec) for a list of the configurable Runner Pod `spec` fields.
+For example, you can configure Runner Pod `spec` affinity and tolerations if you need to run in on a specific set of nodes. Please see [RunnerPodSpec](https://weaveworks.github.io/tf-controller/References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodSpec) for a list of the configurable Runner Pod `spec` fields.

docs/use_tf_controller/to_set_variables_for_Terraform_resources.md

@@ -31,7 +31,7 @@ Note that in the case of the same variable key being passed multiple times, the
 the lattermost instance of the key passed to `varsFrom`.
 
 ```yaml hl_lines="15-20 22-28"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld
@@ -77,7 +77,7 @@ variable "cluster_spec" {
 ```
 
 ```yaml hl_lines="17-20"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/with_GitOps_dependency_management.md

@@ -23,7 +23,7 @@ It is configured to use the `auto-apply` mode, and write outputs to the secret `
 
 ```yaml hl_lines="20-24"
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: aws-s3-bucket
@@ -68,7 +68,7 @@ Please note that we use `${{` and  `}}` as the delimiters for the variable name,
 
 ```yaml hl_lines="11 18 20-21"
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: aws-s3-bucket-acl
@@ -102,7 +102,7 @@ To avoid this, we need to add the `kustomize.toolkit.fluxcd.io/substitute: disab
 
 ```yaml hl_lines="8"
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: aws-s3-bucket-acl

docs/use_tf_controller/with_Terraform_Enterprise.md

@@ -53,7 +53,7 @@ In your Terraform object, you'll have to 1. disable the backend by setting `spec
 
 ```yaml hl_lines="10-14"
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: tfe-demo

docs/use_tf_controller/with_a_custom_backend.md

@@ -7,7 +7,7 @@ The tfstate is stored in a secret named: `tfstate-${workspace}-${secretSuffix}`.
 If you wish to use a custom backend, you can configure it by defining the `.spec.backendConfig.customConfiguration` with one of the backends such as **GCS** or **S3**, for example:
 
 ```yaml hl_lines="9-21"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/with_an_OCI_Artifact_as_Source.md

@@ -30,7 +30,7 @@ spec:
   ref:
     tag: main
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld-tf-oci

docs/use_tf_controller/with_drift_detection_disabled.md

@@ -3,7 +3,7 @@
 Drift detection is enabled by default. You can set `.spec.disableDriftDetection: true` to disable it.
 
 ```yaml hl_lines="8"
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: helloworld

docs/use_tf_controller/with_primitive_modules.md

@@ -43,7 +43,7 @@ spec:
   ref:
     tag: v1
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: hello-world

docs/use_tf_controller/with_the_ready_to_use_AWS_package.md

@@ -90,7 +90,7 @@ You can read more about the GitOps dependencies in the [GitOps dependencies](./w
 
 ```yaml
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: aws-s3-bucket
@@ -122,7 +122,7 @@ spec:
       - secretRef:
           name: aws-credentials
 ---
-apiVersion: infra.contrib.fluxcd.io/v1alpha1
+apiVersion: infra.contrib.fluxcd.io/v1alpha2
 kind: Terraform
 metadata:
   name: example-bucket-acl