+(Appears on: +TerraformSpec) +
+| Field | +Description | +
|---|---|
+enablePathScope+ +bool + + |
+
+(Optional)
+ EnablePathScope specifies if the Branch Planner should or shouldn’t check
+if a Pull Request has changes under |
+
@@ -2090,6 +2124,19 @@
branchPlannerBarnchPlanner configuration.
+branchPlannerBarnchPlanner configuration.
+~> BREAKING NEWS: The Technology Preview of the Branch Planner is now available! Learn more or Get started with the Branch Planner.
TF-controller is a reliable controller for Flux to reconcile Terraform resources in the GitOps way. With the power of Flux together with Terraform, TF-controller allows you to GitOps-ify infrastructure, and application resources, in the Kubernetes and Terraform universe, at your own pace.
\"At your own pace\" means you don't need to GitOps-ify everything at once.
TF-controller offers many GitOps models:
To get started, follow the getting started guide.
"},{"location":"#features","title":"Features","text":"plan and apply inside Runner Pods. When specifying .metadata.namespace and .spec.serviceAccountName, the Runner Pod uses the specified ServiceAccount and runs inside the specified Namespace. These settings enable the soft multi-tenancy model, which can be used within the Flux multi-tenancy setup. This feature is available since v0.9.0..spec.approvePlan=auto, it allows a Terraform object to be reconciled and act as the representation of your Terraform resources. The TF-controller uses the spec of the Terraform object to perform plan, apply its associated Terraform resources. It then stores the TFSTATE of the applied resources as a Secret inside the Kubernetes cluster. After .spec.interval passes, the controller performs drift detection to check if there is a drift occurred between your live system, and your Terraform resources. If a drift occurs, the plan to fix that drift will be generated and applied automatically. This feature is available since v0.3.0.TFSTATE. This feature is available since v0.5.0..spec.disableDriftDetection to disable this behaviour. This feature is available since v0.7.0.plan, out of the apply step, just like the Terraform workflow you are familiar with. A good thing about this is that it is done in a GitOps way. When a plan is generated, the controller shows you a message like 'set approvePlan: \"plan-main-123\" to apply this plan.'. You make change to the field .spec.approvePlan, commit and push to tell the TF-controller to apply the plan for you. With this GitOps workflow, you can optionally create and push this change to a new branch for your team member to review and approve too. This feature is available since v0.6.0.Terraform object in v0.13.0+ allows you to better configure your Terraform resources via YAMLs, but without introducing any extra CRDs to your cluster. Together with a new generator called Tofu-Jet, we'll now be able to ship pre-generated primitive Terraform modules for all major cloud providers. A primitive Terraform module is a module that only contains a single primitive resource, like aws_iam_role, or aws_iam_policy. With this concept, we would be able to use Terraform without writing Terraform codes, and make it more GitOps-friendly at the same time. This feature is available since v0.13.0.Terraform object in v0.13.0+ allows you to specify a list of Terraform objects that it depends on. The controller will wait for the dependencies to be ready before it starts to reconcile the Terraform object. This allows you to create a dependency graph of your Terraform modules, and make sure the modules are applied in the correct order. Please use .spec.retryInterval (a small value like 20s) to control the retry interval when using this feature. This feature is available since v0.13.0.Here are the requirements you need to set up before you start:
Before using TF-controller, you have to install Flux by using either flux install or flux bootstrap command. Please note that TF-controller now requires Flux v2.0 or later, so please make sure you have the latest version of Flux. After that you can install TF-controller with Flux HelmRelease by:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\nFor the most recent release candidate of TF-controller, please use rc.yaml.
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml\nkubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/release.yaml\nFor the most recent release candidate of TF-controller with Branch Planner, please use branch_planner/rc.yaml.
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/rc.yaml\nFor more details about the Branch Planner, please visit the Branch Planner documentation.
"},{"location":"getting_started/#manual-installation","title":"Manual installation","text":"With Helm by:
# Add tf-controller helm repository\nhelm repo add tf-controller https://weaveworks.github.io/tf-controller/\n\n# Install tf-controller\nhelm upgrade -i tf-controller tf-controller/tf-controller \\\n--namespace flux-system\nFor details on configurable parameters of the TF-controller chart, please see chart readme.
Alternatively, you can install TF-controller via kubectl:
export TF_CON_VER=v0.15.1\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.crds.yaml\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.rbac.yaml\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.deployment.yaml\nHere's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.
"},{"location":"getting_started/#define-source","title":"Define source","text":"First, we need to define a Source controller's source (GitRepository, Bucket, OCIRepository), for example:
apiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\ninterval: 30s\nurl: https://github.com/tf-controller/helloworld\nref:\nbranch: main\nThe GitOps automation mode could be enabled by setting .spec.approvePlan=auto. In this mode, Terraform resources will be planned, and automatically applied for you.
apiVersion: infra.contrib.fluxcd.io/v1\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\ninterval: 1m\napprovePlan: auto\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nFor a full list of features and how to use them, please follow the Use TF-controller guide.
"},{"location":"getting_started/#other-examples","title":"Other Examples","text":"tfctl is a command-line utility to help with tf-controller operations.
To install tfctl via Homebrew, run the following command:
brew install weaveworks/tap/tfctl\nYou can also download the tfctl binary via the GitHub releases page: https://github.com/weaveworks/tf-controller/releases.
Usage:\n tfctl [command]\n\nAvailable Commands:\n completion Generate the autocompletion script for the specified shell\n create Create a Terraform resource\n delete Delete a Terraform resource\n get Get Terraform resources\n help Help about any command\n install Install the tf-controller\n plan Plan a Terraform configuration\n reconcile Trigger a reconcile of the provided resource\n resume Resume reconciliation for the provided resource\n suspend Suspend reconciliation for the provided resource\n uninstall Uninstall the tf-controller\n version Prints tf-controller and tfctl version information\n\nFlags:\n -h, --help help for tfctl\n --kubeconfig string Path to the kubeconfig file to use for CLI requests.\n -n, --namespace string The kubernetes namespace to use for CLI requests. (default \"flux-system\")\n --terraform string The location of the terraform binary. (default \"/usr/bin/terraform\")\n\nUse \"tfctl [command] --help\" for more information about a command.\nPackages:
Resource Types:
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigSpec","title":"BackendConfigSpec","text":"(Appears on: TerraformSpec)
BackendConfigSpec is for specifying configuration for Terraform\u2019s Kubernetes backend
Field Descriptiondisable bool (Optional) Disable is to completely disable the backend configuration.
secretSuffix string (Optional) inClusterConfig bool (Optional) customConfiguration string (Optional) configPath string (Optional) labels map[string]string (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigsReference","title":"BackendConfigsReference","text":"(Appears on: TerraformSpec)
Field Descriptionkind string Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).
name string Name of the configs referent. Should reside in the same namespace as the referring resource.
keys []string (Optional) Keys is the data key where a specific value can be found at. Defaults to all keys.
optional bool (Optional) Optional marks this BackendConfigsReference as optional. When set, a not found error for the values reference is ignored, but any Key or transient error will still result in a reconciliation failure.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudSpec","title":"CloudSpec","text":"(Appears on: TerraformSpec)
Field Descriptionorganization string workspaces CloudWorkspacesSpec hostname string (Optional) token string (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudWorkspacesSpec","title":"CloudWorkspacesSpec","text":"(Appears on: CloudSpec)
Field Descriptionname string (Optional) tags []string (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CrossNamespaceSourceReference","title":"CrossNamespaceSourceReference","text":"(Appears on: TerraformSpec)
CrossNamespaceSourceReference contains enough information to let you locate the typed Kubernetes resource object at cluster level.
Field DescriptionapiVersion string (Optional) API version of the referent.
kind string Kind of the referent.
name string Name of the referent.
namespace string (Optional) Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.FileMapping","title":"FileMapping","text":"(Appears on: TerraformSpec)
Field DescriptionsecretRef github.com/fluxcd/pkg/apis/meta.SecretKeyReference Reference to a Secret that contains the file content
location string Location can be either user\u2019s home directory or the Terraform workspace
path string Path of the file - relative to the \u201clocation\u201d
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ForceUnlockEnum","title":"ForceUnlockEnum (string alias)","text":"(Appears on: TFStateSpec)
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.HealthCheck","title":"HealthCheck","text":"(Appears on: TerraformSpec)
HealthCheck contains configuration needed to perform a health check after terraform is applied.
Field Descriptionname string Name of the health check.
type string Type of the health check, valid values are (\u2018tcp\u2019, \u2018http\u2019). If tcp is specified, address is required. If http is specified, url is required.
url string (Optional) URL to perform http health check on. Required when http type is specified. Go template can be used to reference values from the terraform output (e.g. https://example.org, {{.output_url}}).
address string (Optional) Address to perform tcp health check on. Required when tcp type is specified. Go template can be used to reference values from the terraform output (e.g. 127.0.0.1:8080, {{.address}}:{{.port}}).
timeout Kubernetes meta/v1.Duration (Optional) The timeout period at which the connection should timeout if unable to complete the request. When not specified, default 20s timeout is used.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.LockStatus","title":"LockStatus","text":"(Appears on: TerraformStatus)
LockStatus defines the observed state of a Terraform State Lock
Field DescriptionlastApplied string (Optional) pending string (Optional) Pending holds the identifier of the Lock Holder to be used with Force Unlock
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.PlanStatus","title":"PlanStatus","text":"(Appears on: TerraformStatus)
Field DescriptionlastApplied string (Optional) pending string (Optional) isDestroyPlan bool (Optional) isDriftDetectionPlan bool (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ReadInputsFromSecretSpec","title":"ReadInputsFromSecretSpec","text":"(Appears on: TerraformSpec)
Field Descriptionname string as string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceInventory","title":"ResourceInventory","text":"(Appears on: TerraformStatus)
ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.
Field Descriptionentries []ResourceRef Entries of Kubernetes resource object references.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceRef","title":"ResourceRef","text":"(Appears on: ResourceInventory)
ResourceRef contains the information necessary to locate a resource within a cluster.
Field Descriptionn string Terraform resource\u2019s name.
t string Type is Terraform resource\u2019s type
id string ID is the resource identifier. This is cloud-specific. For example, ARN is an ID on AWS.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodMetadata","title":"RunnerPodMetadata","text":"(Appears on: RunnerPodTemplate)
Field Descriptionlabels map[string]string (Optional) Labels to add to the runner pod
annotations map[string]string (Optional) Annotations to add to the runner pod
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodSpec","title":"RunnerPodSpec","text":"(Appears on: RunnerPodTemplate)
Field Descriptionimage string (Optional) Runner pod image to use other than default
envFrom []Kubernetes core/v1.EnvFromSource (Optional) List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
env []Kubernetes core/v1.EnvVar (Optional) List of environment variables to set in the container. Cannot be updated.
nodeSelector map[string]string (Optional) Set the NodeSelector for the Runner Pod
affinity Kubernetes core/v1.Affinity (Optional) Set the Affinity for the Runner Pod
tolerations []Kubernetes core/v1.Toleration (Optional) Set the Tolerations for the Runner Pod
volumeMounts []Kubernetes core/v1.VolumeMount (Optional) Set Volume Mounts for the Runner Pod
volumes []Kubernetes core/v1.Volume (Optional) Set Volumes for the Runner Pod
initContainers []Kubernetes core/v1.Container (Optional) Set up Init Containers for the Runner
hostAliases []Kubernetes core/v1.HostAlias (Optional) Set host aliases for the Runner Pod
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodTemplate","title":"RunnerPodTemplate","text":"(Appears on: TerraformSpec)
Field Descriptionmetadata RunnerPodMetadata (Optional) spec RunnerPodSpec (Optional) image string (Optional) Runner pod image to use other than default
envFrom []Kubernetes core/v1.EnvFromSource (Optional) List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
env []Kubernetes core/v1.EnvVar (Optional) List of environment variables to set in the container. Cannot be updated.
nodeSelector map[string]string (Optional) Set the NodeSelector for the Runner Pod
affinity Kubernetes core/v1.Affinity (Optional) Set the Affinity for the Runner Pod
tolerations []Kubernetes core/v1.Toleration (Optional) Set the Tolerations for the Runner Pod
volumeMounts []Kubernetes core/v1.VolumeMount (Optional) Set Volume Mounts for the Runner Pod
volumes []Kubernetes core/v1.Volume (Optional) Set Volumes for the Runner Pod
initContainers []Kubernetes core/v1.Container (Optional) Set up Init Containers for the Runner
hostAliases []Kubernetes core/v1.HostAlias (Optional) Set host aliases for the Runner Pod
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TFStateSpec","title":"TFStateSpec","text":"(Appears on: TerraformSpec)
TFStateSpec allows the user to set ForceUnlock
Field DescriptionforceUnlock ForceUnlockEnum (Optional) ForceUnlock a Terraform state if it has become locked for any reason. Defaults to no.
This is an Enum and has the expected values of:
WARNING: Only use auto in the cases where you are absolutely certain that no other system is using this state, you could otherwise end up in a bad place See https://www.terraform.io/language/state/locking#force-unlock for more information on the terraform state lock and force unlock.
lockIdentifier string (Optional) LockIdentifier holds the Identifier required by Terraform to unlock the state if it ever gets into a locked state.
You\u2019ll need to put the Lock Identifier in here while setting ForceUnlock to either yes or auto.
Leave this empty to do nothing, set this to the value of the Lock Info: ID: [value], e.g. f2ab685b-f84d-ac0b-a125-378a22877e8d, to force unlock the state.
Terraform is the Schema for the terraforms API
Field Descriptionmetadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec TerraformSpec approvePlan string (Optional) ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.
destroy bool (Optional) Destroy produces a destroy plan. Applying the plan will destroy all resources.
backendConfig BackendConfigSpec (Optional) backendConfigsFrom []BackendConfigsReference (Optional) cloud CloudSpec (Optional) workspace string (Optional) vars []Variable (Optional) List of input variables to set for the Terraform program.
varsFrom []VarsReference (Optional) List of references to a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey. Values of the later Secret / ConfigMap with the same keys will override those of the former.
values Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Values map to the Terraform variable \u201cvalues\u201d, which is an object of arbitrary values. It is a convenient way to pass values to Terraform resources without having to define a variable for each value. To use this feature, your Terraform file must define the variable \u201cvalues\u201d.
fileMappings []FileMapping (Optional) List of all configuration files to be created in initialization.
interval Kubernetes meta/v1.Duration The interval at which to reconcile the Terraform.
retryInterval Kubernetes meta/v1.Duration (Optional) The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.
path string (Optional) Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.
sourceRef CrossNamespaceSourceReference SourceRef is the reference of the source where the Terraform files are stored.
suspend bool (Optional) Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.
force bool (Optional) Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.
readInputsFromSecrets []ReadInputsFromSecretSpec (Optional) writeOutputsToSecret WriteOutputsToSecretSpec (Optional) A list of target secrets for the outputs to be written as.
disableDriftDetection bool (Optional) Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.
cliConfigSecretRef Kubernetes core/v1.SecretReference (Optional) healthChecks []HealthCheck (Optional) List of health checks to be performed.
destroyResourcesOnDeletion bool (Optional) Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.
serviceAccountName string (Optional) Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.
alwaysCleanupRunnerPod bool (Optional) Clean the runner pod up after each reconciliation cycle
runnerTerminationGracePeriodSeconds int64 (Optional) Configure the termination grace period for the runner pod. Use this parameter to allow the Terraform process to gracefully shutdown. Consider increasing for large, complex or slow-moving Terraform managed resources.
refreshBeforeApply bool (Optional) RefreshBeforeApply forces refreshing of the state before the apply step.
runnerPodTemplate RunnerPodTemplate (Optional) enableInventory bool (Optional) EnableInventory enables the object to store resource entries as the inventory for external use.
tfstate TFStateSpec (Optional) targets []string (Optional) Targets specify the resource, module or collection of resources to target.
parallelism int32 (Optional) Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.
storeReadablePlan string (Optional) StoreReadablePlan enables storing the plan in a readable format.
webhooks []Webhook (Optional) dependsOn []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference (Optional) enterprise Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Enterprise is the enterprise configuration placeholder.
planOnly bool (Optional) PlanOnly specifies if the reconciliation should or should not stop at plan phase.
breakTheGlass bool (Optional) BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.
status TerraformStatus"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformSpec","title":"TerraformSpec","text":"(Appears on: Terraform)
TerraformSpec defines the desired state of Terraform
Field DescriptionapprovePlan string (Optional) ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.
destroy bool (Optional) Destroy produces a destroy plan. Applying the plan will destroy all resources.
backendConfig BackendConfigSpec (Optional) backendConfigsFrom []BackendConfigsReference (Optional) cloud CloudSpec (Optional) workspace string (Optional) vars []Variable (Optional) List of input variables to set for the Terraform program.
varsFrom []VarsReference (Optional) List of references to a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey. Values of the later Secret / ConfigMap with the same keys will override those of the former.
values Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Values map to the Terraform variable \u201cvalues\u201d, which is an object of arbitrary values. It is a convenient way to pass values to Terraform resources without having to define a variable for each value. To use this feature, your Terraform file must define the variable \u201cvalues\u201d.
fileMappings []FileMapping (Optional) List of all configuration files to be created in initialization.
interval Kubernetes meta/v1.Duration The interval at which to reconcile the Terraform.
retryInterval Kubernetes meta/v1.Duration (Optional) The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.
path string (Optional) Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.
sourceRef CrossNamespaceSourceReference SourceRef is the reference of the source where the Terraform files are stored.
suspend bool (Optional) Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.
force bool (Optional) Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.
readInputsFromSecrets []ReadInputsFromSecretSpec (Optional) writeOutputsToSecret WriteOutputsToSecretSpec (Optional) A list of target secrets for the outputs to be written as.
disableDriftDetection bool (Optional) Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.
cliConfigSecretRef Kubernetes core/v1.SecretReference (Optional) healthChecks []HealthCheck (Optional) List of health checks to be performed.
destroyResourcesOnDeletion bool (Optional) Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.
serviceAccountName string (Optional) Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.
alwaysCleanupRunnerPod bool (Optional) Clean the runner pod up after each reconciliation cycle
runnerTerminationGracePeriodSeconds int64 (Optional) Configure the termination grace period for the runner pod. Use this parameter to allow the Terraform process to gracefully shutdown. Consider increasing for large, complex or slow-moving Terraform managed resources.
refreshBeforeApply bool (Optional) RefreshBeforeApply forces refreshing of the state before the apply step.
runnerPodTemplate RunnerPodTemplate (Optional) enableInventory bool (Optional) EnableInventory enables the object to store resource entries as the inventory for external use.
tfstate TFStateSpec (Optional) targets []string (Optional) Targets specify the resource, module or collection of resources to target.
parallelism int32 (Optional) Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.
storeReadablePlan string (Optional) StoreReadablePlan enables storing the plan in a readable format.
webhooks []Webhook (Optional) dependsOn []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference (Optional) enterprise Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Enterprise is the enterprise configuration placeholder.
planOnly bool (Optional) PlanOnly specifies if the reconciliation should or should not stop at plan phase.
breakTheGlass bool (Optional) BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformStatus","title":"TerraformStatus","text":"(Appears on: Terraform)
TerraformStatus defines the observed state of Terraform
Field DescriptionReconcileRequestStatus github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus (Members of ReconcileRequestStatus are embedded into this type.)
observedGeneration int64 (Optional) ObservedGeneration is the last reconciled generation.
conditions []Kubernetes meta/v1.Condition (Optional) lastAppliedRevision string (Optional) The last successfully applied revision. The revision format for Git sources is /. lastAttemptedRevision string (Optional)
LastAttemptedRevision is the revision of the last reconciliation attempt.
lastPlannedRevision string (Optional) LastPlannedRevision is the revision used by the last planning process. The result could be either no plan change or a new plan generated.
lastPlanAt Kubernetes meta/v1.Time (Optional) LastPlanAt is the time when the last terraform plan was performed
lastDriftDetectedAt Kubernetes meta/v1.Time (Optional) LastDriftDetectedAt is the time when the last drift was detected
lastAppliedByDriftDetectionAt Kubernetes meta/v1.Time (Optional) LastAppliedByDriftDetectionAt is the time when the last drift was detected and terraform apply was performed as a result
availableOutputs []string (Optional) plan PlanStatus (Optional) inventory ResourceInventory (Optional) Inventory contains the list of Terraform resource object references that have been successfully applied.
lock LockStatus (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Variable","title":"Variable","text":"(Appears on: TerraformSpec)
Field Descriptionname string Name is the name of the variable
value Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) valueFrom Kubernetes core/v1.EnvVarSource (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.VarsReference","title":"VarsReference","text":"(Appears on: TerraformSpec)
VarsReference contain a reference of a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey.
Field Descriptionkind string Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).
name string Name of the values referent. Should reside in the same namespace as the referring resource.
varsKeys []string (Optional) VarsKeys is the data key at which a specific value can be found. Defaults to all keys.
optional bool (Optional) Optional marks this VarsReference as optional. When set, a not found error for the values reference is ignored, but any VarsKey or transient error will still result in a reconciliation failure.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Webhook","title":"Webhook","text":"(Appears on: TerraformSpec)
Field Descriptionstage string enabled bool (Optional) url string payloadType string (Optional) errorMessageTemplate string (Optional) testExpression string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.WriteOutputsToSecretSpec","title":"WriteOutputsToSecretSpec","text":"(Appears on: TerraformSpec)
WriteOutputsToSecretSpec defines where to store outputs, and which outputs to be stored.
Field Descriptionname string Name is the name of the Secret to be written
labels map[string]string (Optional) Labels to add to the outputted secret
annotations map[string]string (Optional) Annotations to add to the outputted secret
outputs []string (Optional) Outputs contain the selected names of outputs to be written to the secret. Empty array means writing all outputs, which is default.
This page was automatically generated with gen-crd-api-reference-docs
Decisions that affect the development of Terraform Controller that are not captured via a proposal need to be captured in some way. We need a method that is lightweight and easy to discover the decision that have been made. The record of decisions will help future contributors to the project to understand why something has been implemented or is done a certain way.
"},{"location":"adr/0000-use-adrs-for-decisions/#decision","title":"Decision","text":"The project will use Architectural Decision Records (ADR) to record decisions that are made outside of a proposal.
A template has been created based on prior work:
When decisions are made that affect the entire project then a new ADR needs to be created. Likewise, if a decision has been superseded then we need to capture this as a new ADR and mark the previous ADR as superseded. Maintainers and contributors will need to decide when an ADR is to be created.
"},{"location":"adr/0001-pr-polling-workflow/","title":"1. Pull Request Polling","text":"To detect pull request changes, we can use webhooks or polling using GitHub's API.
"},{"location":"adr/0001-pr-polling-workflow/#decision","title":"Decision","text":"We decided to start with polling for security reasons. Using webhooks would require users to open an ingress to the cluster. Because of this requirement, we think security conscious folks may refuse to roll this out on production clusters especially in an air-gapped environment. This does not mean that we will never consider using webhooks for this, but that initially, polling is what we have chosen to implement.
The Branch-Based Planner has two components:
The list Pull Requests endpoint returns all required fields to detect new and closed pull requests. It's one request per repository, but listing comments has to use an API request per pull request. So we have to add a mechanism to avoid hitting API rate limits.
"},{"location":"adr/0002-deny-cross-ns-by-default/","title":"2. Deny cross-namespace refs by default","text":"Like Flux, the tf-controller API has a handful of places where it accepts cross-namespace references.
Terraform.spec.sourceRef -- refers to the Flux source object with the Terraform programTerraform.spec.dependsOn[] -- refers to other objects that must be ready before this object can be run.data.resources[] -- in the config struct used by the branch plannerIn general in Kubernetes, references to objects in other namespaces are frowned upon, because
Both of these effects make a system less secure.
However: removing cross-namespace refs entirely would break some installations in a way that would be difficult to fix, because Flux deployments often rely on defining sources away from objects that use them.
"},{"location":"adr/0002-deny-cross-ns-by-default/#decision","title":"Decision","text":"Deny cross-namespace references by default, but allow them to be enabled with a flag.
So that the default value means the right thing, the flag name must be enable-cross-namespace-refs, and the default false. To avoid confusion when people try to use the Flux version of this flag --disable-cross-namespace-refs, it should be supported too, but only respected if supplied.
The changed default will break deployments that rely on cross-namespace refs, but they are easily fixed with the flag.
New deployments will be more secure, by default.
"},{"location":"branch_planner/","title":"Branch Planner User Guide","text":""},{"location":"branch_planner/#overview","title":"Overview","text":"The Branch Planner, a new component of the Terraform Controller, is specifically designed to enhance the flexibility and robustness of Terraform Controller planning operations. This feature, currently in its technology preview phase, facilitates Terraform planning across branches, creating a streamlined and familiar PR-based workflow for users.
"},{"location":"branch_planner/#how-does-it-work","title":"How does it work?","text":"When the Branch Planner starts, it polls repositories that contain Terraform resources at regular intervals, in order to detect Pull Requests (PR) that change those resources. Upon detecting that a PR exists, the Branch Planner initialises a Terraform object in Plan Only mode for the corresponding branch. In this mode, Terraform Controller generates Terraform plans but does not apply them. Once the plan is generated, Branch Planner posts the plan under the PR as a comment enabling users to review the plan. When the Terraform files of the corresponding branch get updated, Branch Planner posts the updated plan under the PR as new comment, keeping the PR up-to-date with the latest Terraform plan.
"},{"location":"branch_planner/#replan-commands","title":"Replan commands","text":"The Branch Planner also allows users to manually trigger the replan process. By simply commenting !replan under the PR, the Branch Planner will be instructed to generate a new plan and post it under the PR as a new comment.
Now that you know what Branch Planner can do for you, follow the guide to get started.
"},{"location":"branch_planner/getting-started/","title":"Getting Started With Branch Planner","text":"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.
"},{"location":"branch_planner/getting-started/#prerequisites","title":"Prerequisites","text":"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\nInstall Flux. Please make sure you have the latest version of Flux (v2 GA).
flux install\nCreate 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)\n\nkubectl create secret generic branch-planner-token \\\n --namespace=flux-system \\\n --from-literal=\"token=${GITHUB_TOKEN}\"\nInstall 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/main/docs/branch_planner/release.yaml\nCreate 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>\nexport GITHUB_REPO=<your repo>\n\ncat <<EOF | kubectl apply -f -\n---\napiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\n name: branch-planner-demo\n namespace: flux-system\nspec:\n interval: 30s\n url: https://github.com/${GITHUB_USER}/${GITHUB_REPO}\n ref:\n branch: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n name: branch-planner-demo\n namespace: flux-system\nspec:\n approvePlan: auto\n path: ./\n interval: 1m\n sourceRef:\n kind: GitRepository\n name: branch-planner-demo\n namespace: flux-system\nEOF\nBranch Planner uses a ConfigMap as configuration. That ConfigMap is optional to use but useful for fine-tuning Branch Planner.
"},{"location":"branch_planner/getting-started/#custom-configuration","title":"Custom Configuration","text":"By default Branch Planner will look for a 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.---\napiVersion: v1\nkind: ConfigMap\nmetadata:\nnamespace: flux-system\nname: branch-planner\ndata:\nsecretName: branch-planner-token\nresources: |-\n- namespace: terraform\nBranch 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 \\\n--namespace=flux-system \\\n--from-literal=\"token=${GITHUB_TOKEN}\"\nIf 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:\nresources:\n- namespace: default\nname: exact-terraform-object\n- namespace: terraform\nIf 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.
To enable branch planner, set the branchPlanner.enabled to true in the Helm values files.
---\nbranchPlanner:\n enabled: true\nFor public repositories, it's sufficient to enable Public Repositories, without any additional permissions.
For private repositories the following permissions are required:
Issues with Read and Write access. This is required to list and read comments for commands, and to create comments with the Plan output.Pull requests with Read-Only access. This is required to check Pull Request changes.Metadata with Read-only access. This is automatically marked as \"mandatory\" because of the permissions listed above.Assume that we have the my-stack Terraform object with its .spec.workspace set to \"default\".
kubectl get terraform\n\nNAME READY STATUS AGE\nmy-stack Unknown Initializing 28s\nWe can backup its tfstate out of the cluster, like this:
WORKSPACE=default\nNAME=my-stack\n\nkubectl get secret tfstate-${WORKSPACE}-${NAME} \\\n-ojsonpath='{.data.tfstate}' \\\n| base64 -d | gzip -d > terraform.tfstate\nTo restore the tfstate file or import an existing tfstate file to the cluster, we can use the following operation:
gzip terraform.tfstate\n\nWORKSPACE=default\nNAME=my-stack\n\nkubectl create secret \\\ngeneric tfstate-${WORKSPACE}-${NAME} \\\n--from-file=tfstate=terraform.tfstate.gz \\\n--dry-run=client -o=yaml \\\n| yq e '.metadata.annotations[\"encoding\"]=\"gzip\"' - \\\n> tfstate-${WORKSPACE}-${NAME}.yaml\n\nkubectl apply -f tfstate-${WORKSPACE}-${NAME}.yaml\nThis document describes the requeue behavior of the Reconcile method in the TerraformReconciler struct in the code base. Understanding these behaviors can be crucial for troubleshooting, as well as for future development and refinement of the system.
"},{"location":"how_to/interval_and_retryInterval/#requeue-behaviors","title":"Requeue Behaviors","text":"The Reconcile method has several requeue behaviors based on different conditions and errors. We will group them into four categories based on their requeue behavior:
"},{"location":"how_to/interval_and_retryInterval/#1-immediate-requeue-not-using-specified-interval-retryinterval","title":"1. Immediate Requeue (Not using specified interval / retryInterval)","text":"In these scenarios, the Reconcile method returns an error which leads to an immediate requeue orchestrated by the Controller Runtime. The interval is based on the controller's configuration and not specified in the method itself:
spec.retryInterval)","text":"In these scenarios, the method specifically asks for a requeue after a certain interval specified by spec.retryInterval (default to 15s).
spec.sourceRef is not found.spec.interval)","text":"In this scenario, the method specifically asks for a requeue after a successful reconciliation:
The interval for the requeue is spec.interval.
In these scenarios, the method returns without asking for a requeue, and the Controller Runtime will stop the reconciliation process until there is a manual intervention:
This document discusses potential difficulties you may encounter when deleting Terraform resources through the Terraform Controller and the necessary components to facilitate a smooth deletion process.
"},{"location":"how_to/resource_deletion/#source-object","title":"Source Object","text":"The source object (e.g., GitRepository or OCIRepository) is a critical component of the Terraform resource deletion process. This object houses the Terraform source files (.tf files) that describe the configuration of the infrastructure resources.
During the deletion process, the Terraform Controller uses these source files to conduct a re-planning operation. This operation is instrumental to deleting the Terraform Custom Resource (CR).
However, if the source object is unavailable or has been deleted, the re-planning operation fails. As a result, the Terraform Controller cannot locate the resource state, leading to an infinite deletion attempt cycle, commonly known as a looping process.
"},{"location":"how_to/resource_deletion/#role-bindings","title":"Role Bindings","text":"Role bindings assign permissions to Terraform runners, allowing them to execute operations within the Kubernetes cluster. These bindings define the actions that the Terraform runners are authorized to carry out.
If role bindings are missing or misconfigured, the Terraform runners may lack the necessary permissions to execute the deletion process, causing the process to fail.
"},{"location":"how_to/resource_deletion/#secrets-and-configmaps","title":"Secrets and ConfigMaps","text":"Before initiating the resource deletion process, the Terraform Controller leverages Secrets and ConfigMaps to generate a complete source before planning. Secrets store confidential data like API keys or passwords, while ConfigMaps hold configuration data in a key-value format.
Should any of these components be missing or misconfigured, the Terraform Controller may fail to generate an accurate deletion plan, which could impede the resource deletion process.
"},{"location":"how_to/resource_deletion/#troubleshooting","title":"Troubleshooting","text":"To prevent the aforementioned issues, ensure the availability and proper configuration of the source object, role bindings, and Secrets and ConfigMaps during the deletion process.
As of now, we are actively working to address these limitations in the Terraform Controller. We appreciate your patience and welcome any feedback to help enhance the Terraform Controller's performance.
"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/","title":"Break the glass","text":""},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#what-is-break-the-glass","title":"What is break the glass?","text":"\"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. This feature is available in the Terraform controller v0.15.0 and above.
~> WARNING: Please note that you cannot use this feature to fix the Terraform resources with v1alpha1 version of the Terraform CRD. It works only with v1alpha2 version of the Terraform CRD.
~> WARNING: Please also make sure that you have enough privileges to exec pods in your namespaces. Otherwise, you will not be able to use this feature.
There are two primary methods of initiating this mode:
tfctl command-line tool.spec.breakTheGlass field to true in the Terraform object.tfctl to Break the Glass","text":"To start a one-time troubleshooting session, you can use the tfctl break-glass command. For instance:
tfctl break-glass hello-world\nThis 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.
"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#break-the-glass-with-specbreaktheglass-field","title":"Break the glass withspec.breakTheGlass field","text":"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:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\nbreakTheGlass: true\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nWe 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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\napprovePlan: disable\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nIn some situations, you may need to perform the Terraform 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 recommended way is to do manual force unlock. To manually force-unlock, you need to:
forceUnlock to yes, andas the following example:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\ntfstate:\nforceUnlock: \"yes\"\nlockIdentifier: f2ab685b-f84d-ac0b-a125-378a22877e8d\nIn this guide, we will walk through the steps of using TF-controller to plan and manually apply Terraform resources.
We will start by creating the Terraform object and specifying the necessary fields, including the approvePlan field.
We will then create the GitRepository object, which points to the Git repository containing the Terraform configuration.
Once these objects are created, we will 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.
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.
For the plan & manual approval workflow, please start by either setting .spec.approvePlan to be the blank value, or omitting the field. This will tell TF-controller to use the plan & manual approval workflow, rather than the auto-apply workflow. If you want to use the auto-apply workflow, you will need to set the spec.approvePlan field to \"auto\".
In addition to setting the spec.approvePlan field, you will also need to specify the interval, path, and sourceRef fields in the spec field. The interval field determines how often TF-controller will run the Terraform configuration, the path field specifies the location of the configuration files, and the sourceRef field points to the GitRepository object.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: \"\" # or you can omit this field\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nThen after a reconciliation loop, the controller will generate a plan, and tell you how to use field .spec.approvePlan to approve the plan. You can run the following command to obtain that message.
kubectl -n flux-system get tf/helloworld\nThis command will output the message containing the approvePlan value that you will need to use to approve the plan. Once you have this value, you can 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. 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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\napprovePlan: plan-main-b8e362c206 # first 8 digits of a commit hash is enough\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nFor 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:
For example, our Terraform file is provisioned and contains the following outputs.
# main.tf\noutput \"rdsAddress\" {\nvalue = \"mydb.xyz.us-east-1.rds.amazonaws.com\"\n}\noutput \"rdsPort\" {\nvalue = \"3306\"\n}\noutput \"myappURL\" {\nvalue = \"https://example.com/\"\n}\nWe can use standard Go template expressions, like ${{ .rdsAddress }}, to refer to those output values and use them to verify that the resources are up and running.
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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nhealthChecks:\n- name: rds\ntype: tcp\naddress: ${{ .rdsAddress }}:${{ .rdsPort }} timeout: 10s # optional, defaults to 20s\n- name: myapp\ntype: http\nurl: ${{ .myappURL }}\ntimeout: 5s\n- name: url_not_from_output\ntype: http\nurl: \"https://example.org\"\nTo provision resources with TF-controller, you need to create a Terraform object and a Flux source object, such as a GitRepository or OCIRepository object.
The Terraform object is a Kubernetes custom resource definition (CRD) object. It is the core object of TF-controller and defines the Terraform module, backend configuration, and GitOps automation mode..
It defines the Terraform module, the backend configuration, and the GitOps automation mode.
The Terraform module is a Terraform configuration that can be used to provision resources. It can be placed inside a Git repository, or packaged as an OCI image in an OCI registry.
The backend configuration is the configuration for the Terraform backend to be used to store the Terraform state. It is optional. If not specified, the Kubernetes backend will be used by default.
"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/#gitops-automation-mode","title":"GitOps automation mode","text":"The GitOps automation mode is the GitOps automation mode to be used to run the Terraform module. It determines how Terraform runs and manages your infrastructure. It is optional. If not specified, the \"plan-and-manually-apply\" mode will be used by default. In the \"plan-and-manually-apply\" mode, TF-controller will run a Terraform plan and output the proposed changes to a Git repository. A human must then review and manually apply the changes. This is the default GitOps automation mode if none is specified.
In the \"auto-apply\" mode, TF-controller will automatically apply the changes after a Terraform plan is run. This can be useful for environments where changes can be made automatically, but it is important to ensure that the proper controls, like policies, are in place to prevent unintended changes from being applied.
To specify the GitOps automation mode in a Terraform object, you can set the spec.approvePlan field to the desired value. For example, to use the \"auto-apply\" mode, y ou would set it to spec.approvePlan: auto.
It is important to carefully consider which GitOps automation mode is appropriate for your use case to ensure that your infrastructure is properly managed and controlled.
The following is an example of a Terraform object; we use the \"auto-apply\" mode:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nspec:\npath: ./helloworld\ninterval: 10m\napprovePlan: auto\nsourceRef:\nkind: GitRepository\nname: helloworld\nThis code is defining a Terraform object in Kubernetes. The apiVersion field specifies the version of the Kubernetes API being used, and the kind field specifies that it is a Terraform object. The metadata block contains information about the object, including its name.
The spec field contains the specification for the Terraform object. The path field specifies the path to the Terraform configuration files, in this case a directory named \"helloworld\". The interval field specifies the frequency at which TF-controller should run the Terraform configuration, in this case every 10 minutes. The approvePlan field specifies whether or not to automatically approve the changes proposed by a Terraform plan. In this case, it is set to auto, meaning that changes will be automatically approved.
The sourceRef field specifies the Flux source object to be used. In this case, it is a GitRepository object with the name \"helloworld\". This indicates that the Terraform configuration is stored in a Git repository object with the name helloworld.
The resources provisioned by a Terraform object are not destroyed by default, and the tfstate of that Terraform object still remains in the cluster.
It means that you are safe to delete the Terraform object in the cluster and re-create it. If you re-create a new Terraform object with the same name, namespace and workspace, it will continue to use the tfstate inside the cluster as the starting point to reconcile.
However, you may want to destroy provisioned resources when delete the Terraform object in many scenarios. To enable destroy resources on object deletion, set .spec.destroyResourcesOnDeletion to true.
~> WARNING: This feature will destroy your resources on the cloud if the Terraform object gets deleted. Please use it with cautions.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ndestroyResourcesOnDeletion: true\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nOutputs created by Terraform can be written to a secret using .spec.writeOutputsToSecret.
We can specify a target secret in .spec.writeOutputsToSecret.name, and the controller will write all outputs to the secret by default.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\nWe can choose only a subset of outputs by specify output names we'd like to write in the .spec.writeOutputsToSecret.outputs array.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\noutputs:\n- hello_world\n- my_sensitive_data\nSome time we'd like to use rename an output, so that it can be consumed by other Kubernetes controllers. For example, we might retrieve a key from a Secret manager, and it's an AGE key, which must be ending with \".agekey\" in the secret. In this case, we need to rename the output.
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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\noutputs:\n- age_key:age.agekey\nIn some situations, it is needed to add custom labels and annotations to the outputted secret. As an example, operators such as kubernetes-replicator allow replicating secrets from one namespace to another but use annotations to do so.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\nlabels:\nmy-label: true\nannotations:\nmy-annotation: \"very long string\"\nIn some situations, it is needed to add custom labels and annotations to the runner pod used to reconcile Terraform. For example, for Azure AKS to grant pod active directory permissions using Azure Active Directory (AAD) Pod Identity, a label like aadpodidbinding: myIdentity on the pod is required.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nrunnerPodTemplate:\nmetadata:\nlabels:\naadpodidbinding: myIdentity\nannotations:\ncompany.com/abc: xyz\nBy 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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nrunnerPodTemplate:\nspec:\nimage: registry.io/tf-runner:xyz\nYou can use runner.Dockerfile as a basis of customizing runner pod image.
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 for a list of the configurable Runner Pod spec fields.
~> BREAKING CHANGE: This is a breaking change of the v1alpha1 API.
Users who are upgrading from TF-controller <= 0.7.0 require updating varsFrom, from a single object:
varsFrom:\nkind: ConfigMap\nname: cluster-config\nto be an array of object, like this:
varsFrom:\n- kind: ConfigMap\nname: cluster-config\nvars and varsFrom","text":"You can pass variables to Terraform using the vars and varsFrom fields.
Inline variables can be set using vars. The varsFrom field accepts a list of ConfigMaps / Secrets. You may use the varsKeys property of varsFrom to select specific keys from the input or omit this field to select all keys from the input source.
Note that in the case of the same variable key being passed multiple times, the controller will use the lattermost instance of the key passed to varsFrom.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nvars:\n- name: region\nvalue: us-east-1\n- name: env\nvalue: dev\n- name: instanceType\nvalue: t3-small\nvarsFrom:\n- kind: ConfigMap\nname: cluster-config\nvarsKeys:\n- nodeCount\n- instanceType\n- kind: Secret\nname: cluster-creds\nThe vars field supports HCL string, number, bool, object and list types. For example, the following variable can be populated using the accompanying Terraform spec:
variable \"cluster_spec\" {\ntype = object({\nregion = string\nenv = string\nnode_count = number\npublic = bool\n})\n}\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nvars:\n- name: cluster_spec\nvalue:\nregion: us-east-1\nenv: dev\nnode_count: 10\npublic: false\nTo rename a variable, you can use the varsKeys key within the varsFrom field. Here's the basic structure:
spec:\nvarsFrom:\n- kind: Secret\nname: <secret_name>\nvarsKeys:\n- <original_variable_name>:<new_variable_name>\noriginal_variable_name corresponds to the initial name of the variable in the referenced secret, while new_variable_name represents the alias you want to use within the Terraform code. Consider this example below, where we rename nodeCount to node_count and instanceType to instance_type:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nvarsFrom:\n- kind: Secret\nname: cluster-config\nvarsKeys:\n- nodeCount:node_count\n- instanceType:instance_type\nSee Rename outputs for more details.
"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-input-secrets","title":"Rename input secrets","text":"See Rename input secrets for more details.
"},{"location":"use_tf_controller/with_AWS_EKS_IRSA/","title":"Use TF-controller with AWS EKS IRSA","text":"AWS Elastic Kubernetes Service (EKS) offers IAM Roles for Service Accounts (IRSA) as a mechanism by which to provide credentials to Kubernetes pods. This can be used to provide the required AWS credentials to Terraform runners for performing plans and applies.
You can use eksctl to associate an OIDC provider with your EKS cluster, for example:
eksctl utils associate-iam-oidc-provider --cluster CLUSTER_NAME --approve\nThen follow the instructions here to add a trust policy to the IAM role which grants the necessary permissions for Terraform. Please note that if you have installed the controller following the README, then the namespace:serviceaccountname will be flux-system:tf-runner. You'll obtain a Role ARN to use in the next step.
Finally, annotate the ServiceAccount for the tf-runner with the obtained Role ARN in your cluster:
kubectl annotate -n flux-system serviceaccount tf-runner eks.amazonaws.com/role-arn=ROLE_ARN\nIf deploying the tf-controller via Helm, this can be accomplished as follows:
values:\nrunner:\nserviceAccount:\nannotations:\neks.amazonaws.com/role-arn: ROLE_ARN\nTF-controller supports GitOps dependency management. The GitOps dependency management feature is based on the similar technique implemented in the Kustomization controller of Flux.
This means that you can use TF-controller to provision resources that depend on other resources at the GitOps level. For example, you can use TF-controller to provision an S3 bucket, and then use TF-controller to provision another resource to configure ACL for that bucket.
GitOps dependency management is different from Terraform's HCL dependency management in the way that it is not based on Terraform's mechanism, which is controlled by the Terraform binary. Instead, it is implemented at the controller level, which means that each Terraform module is reconciled and can be managed independently, while still being able to depend on other modules.
"},{"location":"use_tf_controller/with_GitOps_dependency_management/#create-a-terraform-object","title":"Create a Terraform object","text":"Similar to the same feature in the Kustomization controller, the dependency management feature is enabled by setting the dependsOn field in the Terraform object. The dependsOn field is a list of Terraform objects.
When the dependency is not satisfied, the Terraform object will be in the Unknown state, and it will be retry again every spec.retryInterval. The retry interval is same as the spec.interval by default, and it can be configured separately by setting the spec.retryInterval field.
First, create a Terraform object to provision the S3 bucket, name it aws-s3-bucket. The S3 bucket is provisioned by the Terraform module aws_s3_bucket in the OCI image aws-package. It is configured to use the auto-apply mode, and write outputs to the secret aws-s3-bucket-outputs.
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: aws-s3-bucket\nnamespace: flux-system\nspec:\npath: aws_s3_bucket\nvalues:\nbucket: my-tf-controller-test-bucket\ntags:\nEnvironment: Dev\nName: My bucket\nsourceRef:\nkind: OCIRepository\nname: aws-package\napprovePlan: auto\ninterval: 2m\ndestroyResourcesOnDeletion: true\nwriteOutputsToSecret:\nname: aws-s3-bucket-outputs\noutputs:\n- arn\n- bucket\nrunnerPodTemplate:\nspec:\nenvFrom:\n- secretRef:\nname: aws-credentials\nSecond, create a Terraform object to configure ACL for the S3 bucket, name it aws-s3-bucket-acl. The ACL is provisioned by the Terraform module aws_s3_bucket_acl, also from the OCI image aws-package-v4.33.0.
In the dependsOn field, specify the Terraform object that provisions the S3 bucket. This means that the ACL will be configured only after the S3 bucket is provisioned, and has its outputs Secret written. We can read the outputs of the S3 bucket from the Secret aws-s3-bucket-outputs, by specifying the spec.readInputsFromSecrets field. The spec.readInputsFromSecrets field is a list of Secret objects. Its name field is the name of the Secret, and its as field is the name of variable that can be used in the spec.values block.
For example, the spec.values.bucket field in the aws-s3-bucket-acl Terraform object is set to ${{ .aws_s3_bucket.bucket }}.
Please note that we use ${{ and }} as the delimiters for the variable name, instead of the Helm default ones, {{ and }}.
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: aws-s3-bucket-acl\nnamespace: flux-system\nspec:\npath: aws_s3_bucket_acl\nvalues:\nacl: private\nbucket: ${{ .aws_s3_bucket.bucket }}\nsourceRef:\nkind: OCIRepository\nname: aws-package\napprovePlan: auto\ninterval: 3m\ndependsOn:\n- name: aws-s3-bucket\nreadInputsFromSecrets:\n- name: aws-s3-bucket-outputs\nas: aws_s3_bucket\nrunnerPodTemplate:\nspec:\nenvFrom:\n- secretRef:\nname: aws-credentials\nThe Kustomization controller will substitute variables in the Terraform object, which will cause conflicts with the variable substitution in the GitOps dependency management feature. To avoid this, we need to add the kustomize.toolkit.fluxcd.io/substitute: disabled annotation to the Terraform object.
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: aws-s3-bucket-acl\nnamespace: flux-system\nannotations:\nkustomize.toolkit.fluxcd.io/substitute: disabled\nspec:\npath: aws_s3_bucket_acl\nvalues:\nacl: private\nbucket: ${{ .aws_s3_bucket.bucket }}\nsourceRef:\nkind: OCIRepository\nname: aws-package\napprovePlan: auto\ninterval: 3m\ndependsOn:\n- name: aws-s3-bucket\nreadInputsFromSecrets:\n- name: aws-s3-bucket-outputs\nas: aws_s3_bucket\nrunnerPodTemplate:\nspec:\nenvFrom:\n- secretRef:\nname: aws-credentials\nStarting 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.
"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-login","title":"Terraform Login","text":"First, you need to obtain an API token from your TFE. You can use terraform login command to do so.
terraform login tfe.dev.example.com\nThen you can find your API token inside $HOME/.terraform.d/credentials.tfrc.json. Content of the file will look like this:
{\n\"credentials\": {\n\"tfe.dev.example.com\": {\n\"token\": \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n}\n}\n}\nTF-controller accepts an TFRC file in the HCL format. So you have to prepare terraform.tfrc file using contents from above.
credentials \"tfe.dev.example.com\" {\ntoken = \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n}\nWe will now create a Kubernetes Secret from yourterraform.tfrc file, name it tfe-cli-config and put it inside the flux-system namespace.
kubectl create secret generic \\\ntfe-cli-config \\\n--namespace=flux-system \\\n--from-file=terraform.tfrc=./terraform.tfrc\nIn your Terraform object, you'll have to 1. disable the backend by setting spec.backendConfig.disable: true, and 2. point spec.cliConfigSecretRef: to the Secret created in the previous step, like this:
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: tfe-demo\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 2m\npath: ./terraform/tfe-demo\nbackendConfig:\ndisable: true\ncliConfigSecretRef:\nname: tfe-cli-config\nnamespace: flux-system\nvars:\n- name: subject\nvalue: World\nsourceRef:\nkind: GitRepository\nname: flux-system\nnamespace: flux-system\nwriteOutputsToSecret:\nname: tfe-helloworld-output\noutputs:\n- greeting\nDon't forget that you need to tell your Terraform model to use your enterprise instance as well. Here's an example,
terraform {\nrequired_version = \">= 1.1.0\"\ncloud {\nhostname = \"tfe.dev.example.com\"\norganization = \"weaveworks\"\nworkspaces {\nname = \"dev\"\n}\n}\n}\nvariable \"subject\" {\ntype = string\ndefault = \"World\"\ndescription = \"Subject to hello\"\n}\noutput \"greeting\" {\nvalue = \"Hello ${var.subject} from Terraform Enterprise\"\n}\nFor connecting to Terraform Cloud, please replace your hostname to app.terraform.io.
By default, tf-controller will use the Kubernetes backend to store the Terraform state file (tfstate) in cluster.
The tfstate is stored in a secret named: tfstate-${workspace}-${secretSuffix}. The default suffix will be the name of the Terraform resource, however you may override this setting using .spec.backendConfig.secretSuffix. The default workspace name is \"default\", you can also override the workspace by setting .spec.workspace to another value.
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:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\nbackendConfig:\ncustomConfiguration: |\nbackend \"s3\" {\nbucket = \"s3-terraform-state1\"\nkey = \"dev/terraform.tfstate\"\nregion = \"us-east-1\"\nendpoint = \"http://localhost:4566\"\nskip_credentials_validation = true\nskip_metadata_api_check = true\nforce_path_style = true\ndynamodb_table = \"terraformlock\"\ndynamodb_endpoint = \"http://localhost:4566\"\nencrypt = true\n}\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nrunnerPodTemplate:\nspec:\nimage: registry.io/tf-runner:xyz\nTo use OCI artifacts as the source of Terraform objects, you need Flux 2 version v0.32.0 or higher.
Assuming that you have Terraform files (your root module may contain sub-modules) under ./modules, you can use Flux CLI to create an OCI artifact for your Terraform modules by running the following commands:
flux push artifact oci://ghcr.io/tf-controller/helloworld:$(git rev-parse --short HEAD) \\\n--path=\"./modules\" \\\n--source=\"$(git config --get remote.origin.url)\" \\\n--revision=\"$(git branch --show-current)/$(git rev-parse HEAD)\"\nflux tag artifact oci://ghcr.io/tf-controller/helloworld:$(git rev-parse --short HEAD) \\\n--tag main\nThen you define a source (OCIRepository), and use it as the sourceRef of your Terraform object.
---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\nname: helloworld-oci\nspec:\ninterval: 1m\nurl: oci://ghcr.io/tf-controller/helloworld\nref:\ntag: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld-tf-oci\nspec:\npath: ./\napprovePlan: auto\ninterval: 1m\nsourceRef:\nkind: OCIRepository\nname: helloworld-oci\nwriteOutputsToSecret:\nname: helloworld-outputs\nDrift detection is enabled by default. You can set .spec.disableDriftDetection: true to disable it.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ndisableDriftDetection: true\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nThis plan-only mode is designed to be used in conjunction with the Branch Planner. But you can also use it in a circumstance where you want to run terraform plan only.
If planOnly is set to true, the controller will skip the apply part and runs only terraform plan and saves the output.
apiVersion: infra.contrib.fluxcd.io/v1\nkind: Terraform\nmetadata:\n name: helloworld\n namespace: flux-system\nspec:\n interval: 1m\n planOnly: true\n path: ./\n sourceRef:\n kind: GitRepository\n name: helloworld\n namespace: flux-system\nThis document describes how to use the Weave TF-controller with a primitive module. It requires TF-controller v0.13+ to run the example.
"},{"location":"use_tf_controller/with_primitive_modules/#what-is-a-primitive-module","title":"What is a primitive module?","text":"It's a Terraform module that contains only a single resource.
Here is an example of how a primitive module can be defined in YAML. Assume that we have a ready-to-use OCI image with a primitive module for the imaginary resource aws_hello_world, and the image is tagged as ghcr.io/tf-controller/hello-primitive-modules/v4.32.0:v1.
We'll use the following Terraform object definition to provision the resource.
First, we need to create a Terraform object with the spec.sourceRef.kind field set to OCIRepository and the spec.sourceRef.name field set to the name of the OCIRepository object.
Second, we need to set the spec.path field to the name of the resource, in this case aws_hello_world.
Third, we need to set the spec.values field to the values of the resource. This is a YAML object that will be converted to an HCL variable, and passed to the Terraform module.
Finally, we need to set the spec.approvePlan field to auto to automatically approve the plan.
---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\nname: hello-package-v4.32.0\nnamespace: flux-system\nspec:\ninterval: 30s\nurl: oci://ghcr.io/tf-controller/hello-primitive-modules/v4.32.0\nref:\ntag: v1\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\npath: aws_hello_world\nvalues:\ngreeting: Hi\nsubject: my world\nsourceRef:\nkind: OCIRepository\nname: hello-package-v4.32.0\ninterval: 1h0m\napprovePlan: auto\nA Terraform Runner uses two environment variables, DISABLE_TF_LOGS and ENABLE_SENSITIVE_TF_LOGS, to control the logging behavior of the Terraform execution.
To use these environment variables, they need to be set on each Terraform Runner pod where the Terraform code is being executed. This can typically be done by adding them to the pod's environment variables in the Terraform Runner deployment configuration.
DISABLE_TF_LOGS variable, when set to \"1\", will disable all Terraform output logs to stdout and stderr.ENABLE_SENSITIVE_TF_LOGS variable, when set to \"1\", will enable logging of sensitive Terraform data, such as secret variables, to the local log. However, it is important to note that for the ENABLE_SENSITIVE_TF_LOGS to take effect, the DISABLE_TF_LOGS variable must also be set to \"1\".tf-runner is configured at the info level.DISABLE_TF_LOGS variable is not activated as part of the default settings.ENABLE_SENSITIVE_TF_LOGS variable remains inactive in the default configuration.ShowPlan and ShowPlanRaw on the runner are not logged by default.Plan calls made on the runner, error messages are sanitized as a part of the default configuration.For more information on configuring the Terraform Runner and its environment variables, please consult the documentation on customizing runners within the Weave TF-controller.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/","title":"with the ready to use AWS package","text":""},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#use-tf-controller-with-the-ready-to-use-aws-package","title":"Use TF-controller with the ready-to-use AWS package","text":"This document describes how to use the Weave TF-controller with the ready-to-use AWS package. It requires TF-controller v0.13+ to run the example.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#what-is-a-package","title":"What is a package?","text":"A package is a collection of primitive Terraform modules that are bundled into an OCI image. You can think of a TF-controller's package as a thin wrapper around a Terraform module provider, and a TF-controller primitive module as a thin wrapper around a Terraform resource or a root module.
We will provide a set of ready-to-use packages for the most popular cloud providers. Currently, we ship the package for AWS only.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#aws-package","title":"AWS Package","text":"To provide the out-of-the-box experience, the AWS Package is installed by default when you installed the TF-controller. Unlike other IaC implementation, our package model is designed to be very lightweight as a package is just a set of TF files in the form of OCI. Packages would not put any burden to your cluster. However, you can opt this package out by setting awsPackage.install: false in your Helm chart values.
If you run flux get sources oci you should see the AWS package installed in your cluster listed as aws-package.
flux get sources oci\nNAME REVISION SUSPENDED READY MESSAGE aws-package v4.38.0-v1alpha11/6033f3b False True stored artifact for digest 'v4.38.0-v1alpha11/6033f3b'\nThis section describes how to use the AWS package to provision an S3 bucket with ACL using the TF-controller.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#create-a-kind-local-cluster","title":"Create a KinD local cluster","text":"If you don't have a Kubernetes cluster, you can create a KinD cluster with the following command:
kind create cluster\nAfter you have a Kubernetes cluster, you can install Flux with the following command:
flux install\nThen, you can install the TF-controller with the following command:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\nTo provision AWS resources, you need to provide the AWS credentials to your Terraform objects. You can do this by creating a secret with the AWS credentials and reference it in each of your Terraform objects.
```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n name: aws-credentials\n namespace: flux-system\ntype: Opaque\nstringData:\n AWS_ACCESS_KEY_ID: Axxxxxxxxxxxxxxxxxxx\n AWS_SECRET_ACCESS_KEY: qxxxxxxxxxxxxxxxxxxxxxxxxx\n AWS_REGION: us-east-1 # the region you want\nTo apply the secret, run the following command:
kubectl apply -f aws-credentials.yaml\nNow, you can create two Terraform objects, one for an S3 bucket, another one for ACL. Please note that we are using GitOps dependencies to make sure the ACL is created after the bucket is created. You can read more about the GitOps dependencies in the GitOps dependencies document.
```yaml\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n name: aws-s3-bucket\n namespace: flux-system\n labels:\n tf.weave.works/composite: s3-bucket\nspec:\n path: aws_s3_bucket\n values:\n bucket: my-tf-controller-test-bucket\n tags:\n Environment: Dev\n Name: My bucket\n sourceRef:\n kind: OCIRepository\n name: aws-package\n approvePlan: auto\n retryInterval: 10s\n interval: 2m\n destroyResourcesOnDeletion: true\nwriteOutputsToSecret:\n name: aws-s3-bucket-outputs\n outputs:\n - arn\n - bucket\n runnerPodTemplate:\n spec:\n envFrom:\n - secretRef:\n name: aws-credentials\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n name: example-bucket-acl\n namespace: flux-system\n labels:\n tf.weave.works/composite: s3-bucket\nspec:\n path: aws_s3_bucket_acl\n values:\n acl: private\n bucket: ${{ .aws_s3_bucket.bucket }}\nsourceRef:\n kind: OCIRepository\n name: aws-package\n approvePlan: auto\n retryInterval: 10s\n interval: 3m\n dependsOn:\n - name: aws-s3-bucket\n readInputsFromSecrets:\n - name: aws-s3-bucket-outputs\n as: aws_s3_bucket\n destroyResourcesOnDeletion: true\nrunnerPodTemplate:\n spec:\n envFrom:\n - secretRef:\n name: aws-credentials\nThe spec.readInputsFromSecrets field allows you to reference the Terraform outputs from other Terraform objects. In the context of this field, renaming makes it easier to reference the secrets in the spec.values field.
To rename a secret, you need to use the as key in the spec.readInputsFromSecrets field. The name key corresponds to the original name of the secret, while the as key represents the new name that you want to use to reference the secret.
In the example below, we can reference the bucket value from our aws_s3_bucket secret using ${{ .aws_s3_bucket.bucket }} instead of using the original secret name, which is aws-s3-bucket-outputs.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: example-bucket-acl\nnamespace: flux-system\nspec:\n# ...\nreadInputsFromSecrets:\n- name: aws-s3-bucket-outputs\nas: aws_s3_bucket\nvalues:\nacl: private\nbucket: ${{ .aws_s3_bucket.bucket }}\n# ...\n~> BREAKING NEWS: The Technology Preview of the Branch Planner is now available! Learn more or Get started with the Branch Planner.
TF-controller is a reliable controller for Flux to reconcile Terraform resources in the GitOps way. With the power of Flux together with Terraform, TF-controller allows you to GitOps-ify infrastructure, and application resources, in the Kubernetes and Terraform universe, at your own pace.
\"At your own pace\" means you don't need to GitOps-ify everything at once.
TF-controller offers many GitOps models:
To get started, follow the getting started guide.
"},{"location":"#features","title":"Features","text":"plan and apply inside Runner Pods. When specifying .metadata.namespace and .spec.serviceAccountName, the Runner Pod uses the specified ServiceAccount and runs inside the specified Namespace. These settings enable the soft multi-tenancy model, which can be used within the Flux multi-tenancy setup. This feature is available since v0.9.0..spec.approvePlan=auto, it allows a Terraform object to be reconciled and act as the representation of your Terraform resources. The TF-controller uses the spec of the Terraform object to perform plan, apply its associated Terraform resources. It then stores the TFSTATE of the applied resources as a Secret inside the Kubernetes cluster. After .spec.interval passes, the controller performs drift detection to check if there is a drift occurred between your live system, and your Terraform resources. If a drift occurs, the plan to fix that drift will be generated and applied automatically. This feature is available since v0.3.0.TFSTATE. This feature is available since v0.5.0..spec.disableDriftDetection to disable this behaviour. This feature is available since v0.7.0.plan, out of the apply step, just like the Terraform workflow you are familiar with. A good thing about this is that it is done in a GitOps way. When a plan is generated, the controller shows you a message like 'set approvePlan: \"plan-main-123\" to apply this plan.'. You make change to the field .spec.approvePlan, commit and push to tell the TF-controller to apply the plan for you. With this GitOps workflow, you can optionally create and push this change to a new branch for your team member to review and approve too. This feature is available since v0.6.0.Terraform object in v0.13.0+ allows you to better configure your Terraform resources via YAMLs, but without introducing any extra CRDs to your cluster. Together with a new generator called Tofu-Jet, we'll now be able to ship pre-generated primitive Terraform modules for all major cloud providers. A primitive Terraform module is a module that only contains a single primitive resource, like aws_iam_role, or aws_iam_policy. With this concept, we would be able to use Terraform without writing Terraform codes, and make it more GitOps-friendly at the same time. This feature is available since v0.13.0.Terraform object in v0.13.0+ allows you to specify a list of Terraform objects that it depends on. The controller will wait for the dependencies to be ready before it starts to reconcile the Terraform object. This allows you to create a dependency graph of your Terraform modules, and make sure the modules are applied in the correct order. Please use .spec.retryInterval (a small value like 20s) to control the retry interval when using this feature. This feature is available since v0.13.0.Here are the requirements you need to set up before you start:
Before using TF-controller, you have to install Flux by using either flux install or flux bootstrap command. Please note that TF-controller now requires Flux v2.0 or later, so please make sure you have the latest version of Flux. After that you can install TF-controller with Flux HelmRelease by:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\nFor the most recent release candidate of TF-controller, please use rc.yaml.
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml\nkubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/release.yaml\nFor the most recent release candidate of TF-controller with Branch Planner, please use branch_planner/rc.yaml.
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/rc.yaml\nFor more details about the Branch Planner, please visit the Branch Planner documentation.
"},{"location":"getting_started/#manual-installation","title":"Manual installation","text":"With Helm by:
# Add tf-controller helm repository\nhelm repo add tf-controller https://weaveworks.github.io/tf-controller/\n\n# Install tf-controller\nhelm upgrade -i tf-controller tf-controller/tf-controller \\\n--namespace flux-system\nFor details on configurable parameters of the TF-controller chart, please see chart readme.
Alternatively, you can install TF-controller via kubectl:
export TF_CON_VER=v0.15.1\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.crds.yaml\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.rbac.yaml\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.deployment.yaml\nHere's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.
"},{"location":"getting_started/#define-source","title":"Define source","text":"First, we need to define a Source controller's source (GitRepository, Bucket, OCIRepository), for example:
apiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\ninterval: 30s\nurl: https://github.com/tf-controller/helloworld\nref:\nbranch: main\nThe GitOps automation mode could be enabled by setting .spec.approvePlan=auto. In this mode, Terraform resources will be planned, and automatically applied for you.
apiVersion: infra.contrib.fluxcd.io/v1\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\ninterval: 1m\napprovePlan: auto\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nFor a full list of features and how to use them, please follow the Use TF-controller guide.
"},{"location":"getting_started/#other-examples","title":"Other Examples","text":"tfctl is a command-line utility to help with tf-controller operations.
To install tfctl via Homebrew, run the following command:
brew install weaveworks/tap/tfctl\nYou can also download the tfctl binary via the GitHub releases page: https://github.com/weaveworks/tf-controller/releases.
Usage:\n tfctl [command]\n\nAvailable Commands:\n completion Generate the autocompletion script for the specified shell\n create Create a Terraform resource\n delete Delete a Terraform resource\n get Get Terraform resources\n help Help about any command\n install Install the tf-controller\n plan Plan a Terraform configuration\n reconcile Trigger a reconcile of the provided resource\n resume Resume reconciliation for the provided resource\n suspend Suspend reconciliation for the provided resource\n uninstall Uninstall the tf-controller\n version Prints tf-controller and tfctl version information\n\nFlags:\n -h, --help help for tfctl\n --kubeconfig string Path to the kubeconfig file to use for CLI requests.\n -n, --namespace string The kubernetes namespace to use for CLI requests. (default \"flux-system\")\n --terraform string The location of the terraform binary. (default \"/usr/bin/terraform\")\n\nUse \"tfctl [command] --help\" for more information about a command.\nPackages:
Resource Types:
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigSpec","title":"BackendConfigSpec","text":"(Appears on: TerraformSpec)
BackendConfigSpec is for specifying configuration for Terraform\u2019s Kubernetes backend
Field Descriptiondisable bool (Optional) Disable is to completely disable the backend configuration.
secretSuffix string (Optional) inClusterConfig bool (Optional) customConfiguration string (Optional) configPath string (Optional) labels map[string]string (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigsReference","title":"BackendConfigsReference","text":"(Appears on: TerraformSpec)
Field Descriptionkind string Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).
name string Name of the configs referent. Should reside in the same namespace as the referring resource.
keys []string (Optional) Keys is the data key where a specific value can be found at. Defaults to all keys.
optional bool (Optional) Optional marks this BackendConfigsReference as optional. When set, a not found error for the values reference is ignored, but any Key or transient error will still result in a reconciliation failure.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BranchPlanner","title":"BranchPlanner","text":"(Appears on: TerraformSpec)
Field DescriptionenablePathScope bool (Optional) EnablePathScope specifies if the Branch Planner should or shouldn\u2019t check if a Pull Request has changes under .spec.path. If enabled extra resources will be created only if there are any changes in terraform files.
(Appears on: TerraformSpec)
Field Descriptionorganization string workspaces CloudWorkspacesSpec hostname string (Optional) token string (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudWorkspacesSpec","title":"CloudWorkspacesSpec","text":"(Appears on: CloudSpec)
Field Descriptionname string (Optional) tags []string (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CrossNamespaceSourceReference","title":"CrossNamespaceSourceReference","text":"(Appears on: TerraformSpec)
CrossNamespaceSourceReference contains enough information to let you locate the typed Kubernetes resource object at cluster level.
Field DescriptionapiVersion string (Optional) API version of the referent.
kind string Kind of the referent.
name string Name of the referent.
namespace string (Optional) Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.FileMapping","title":"FileMapping","text":"(Appears on: TerraformSpec)
Field DescriptionsecretRef github.com/fluxcd/pkg/apis/meta.SecretKeyReference Reference to a Secret that contains the file content
location string Location can be either user\u2019s home directory or the Terraform workspace
path string Path of the file - relative to the \u201clocation\u201d
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ForceUnlockEnum","title":"ForceUnlockEnum (string alias)","text":"(Appears on: TFStateSpec)
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.HealthCheck","title":"HealthCheck","text":"(Appears on: TerraformSpec)
HealthCheck contains configuration needed to perform a health check after terraform is applied.
Field Descriptionname string Name of the health check.
type string Type of the health check, valid values are (\u2018tcp\u2019, \u2018http\u2019). If tcp is specified, address is required. If http is specified, url is required.
url string (Optional) URL to perform http health check on. Required when http type is specified. Go template can be used to reference values from the terraform output (e.g. https://example.org, {{.output_url}}).
address string (Optional) Address to perform tcp health check on. Required when tcp type is specified. Go template can be used to reference values from the terraform output (e.g. 127.0.0.1:8080, {{.address}}:{{.port}}).
timeout Kubernetes meta/v1.Duration (Optional) The timeout period at which the connection should timeout if unable to complete the request. When not specified, default 20s timeout is used.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.LockStatus","title":"LockStatus","text":"(Appears on: TerraformStatus)
LockStatus defines the observed state of a Terraform State Lock
Field DescriptionlastApplied string (Optional) pending string (Optional) Pending holds the identifier of the Lock Holder to be used with Force Unlock
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.PlanStatus","title":"PlanStatus","text":"(Appears on: TerraformStatus)
Field DescriptionlastApplied string (Optional) pending string (Optional) isDestroyPlan bool (Optional) isDriftDetectionPlan bool (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ReadInputsFromSecretSpec","title":"ReadInputsFromSecretSpec","text":"(Appears on: TerraformSpec)
Field Descriptionname string as string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceInventory","title":"ResourceInventory","text":"(Appears on: TerraformStatus)
ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.
Field Descriptionentries []ResourceRef Entries of Kubernetes resource object references.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceRef","title":"ResourceRef","text":"(Appears on: ResourceInventory)
ResourceRef contains the information necessary to locate a resource within a cluster.
Field Descriptionn string Terraform resource\u2019s name.
t string Type is Terraform resource\u2019s type
id string ID is the resource identifier. This is cloud-specific. For example, ARN is an ID on AWS.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodMetadata","title":"RunnerPodMetadata","text":"(Appears on: RunnerPodTemplate)
Field Descriptionlabels map[string]string (Optional) Labels to add to the runner pod
annotations map[string]string (Optional) Annotations to add to the runner pod
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodSpec","title":"RunnerPodSpec","text":"(Appears on: RunnerPodTemplate)
Field Descriptionimage string (Optional) Runner pod image to use other than default
envFrom []Kubernetes core/v1.EnvFromSource (Optional) List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
env []Kubernetes core/v1.EnvVar (Optional) List of environment variables to set in the container. Cannot be updated.
nodeSelector map[string]string (Optional) Set the NodeSelector for the Runner Pod
affinity Kubernetes core/v1.Affinity (Optional) Set the Affinity for the Runner Pod
tolerations []Kubernetes core/v1.Toleration (Optional) Set the Tolerations for the Runner Pod
volumeMounts []Kubernetes core/v1.VolumeMount (Optional) Set Volume Mounts for the Runner Pod
volumes []Kubernetes core/v1.Volume (Optional) Set Volumes for the Runner Pod
initContainers []Kubernetes core/v1.Container (Optional) Set up Init Containers for the Runner
hostAliases []Kubernetes core/v1.HostAlias (Optional) Set host aliases for the Runner Pod
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodTemplate","title":"RunnerPodTemplate","text":"(Appears on: TerraformSpec)
Field Descriptionmetadata RunnerPodMetadata (Optional) spec RunnerPodSpec (Optional) image string (Optional) Runner pod image to use other than default
envFrom []Kubernetes core/v1.EnvFromSource (Optional) List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
env []Kubernetes core/v1.EnvVar (Optional) List of environment variables to set in the container. Cannot be updated.
nodeSelector map[string]string (Optional) Set the NodeSelector for the Runner Pod
affinity Kubernetes core/v1.Affinity (Optional) Set the Affinity for the Runner Pod
tolerations []Kubernetes core/v1.Toleration (Optional) Set the Tolerations for the Runner Pod
volumeMounts []Kubernetes core/v1.VolumeMount (Optional) Set Volume Mounts for the Runner Pod
volumes []Kubernetes core/v1.Volume (Optional) Set Volumes for the Runner Pod
initContainers []Kubernetes core/v1.Container (Optional) Set up Init Containers for the Runner
hostAliases []Kubernetes core/v1.HostAlias (Optional) Set host aliases for the Runner Pod
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TFStateSpec","title":"TFStateSpec","text":"(Appears on: TerraformSpec)
TFStateSpec allows the user to set ForceUnlock
Field DescriptionforceUnlock ForceUnlockEnum (Optional) ForceUnlock a Terraform state if it has become locked for any reason. Defaults to no.
This is an Enum and has the expected values of:
WARNING: Only use auto in the cases where you are absolutely certain that no other system is using this state, you could otherwise end up in a bad place See https://www.terraform.io/language/state/locking#force-unlock for more information on the terraform state lock and force unlock.
lockIdentifier string (Optional) LockIdentifier holds the Identifier required by Terraform to unlock the state if it ever gets into a locked state.
You\u2019ll need to put the Lock Identifier in here while setting ForceUnlock to either yes or auto.
Leave this empty to do nothing, set this to the value of the Lock Info: ID: [value], e.g. f2ab685b-f84d-ac0b-a125-378a22877e8d, to force unlock the state.
Terraform is the Schema for the terraforms API
Field Descriptionmetadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec TerraformSpec approvePlan string (Optional) ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.
destroy bool (Optional) Destroy produces a destroy plan. Applying the plan will destroy all resources.
backendConfig BackendConfigSpec (Optional) backendConfigsFrom []BackendConfigsReference (Optional) cloud CloudSpec (Optional) workspace string (Optional) vars []Variable (Optional) List of input variables to set for the Terraform program.
varsFrom []VarsReference (Optional) List of references to a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey. Values of the later Secret / ConfigMap with the same keys will override those of the former.
values Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Values map to the Terraform variable \u201cvalues\u201d, which is an object of arbitrary values. It is a convenient way to pass values to Terraform resources without having to define a variable for each value. To use this feature, your Terraform file must define the variable \u201cvalues\u201d.
fileMappings []FileMapping (Optional) List of all configuration files to be created in initialization.
interval Kubernetes meta/v1.Duration The interval at which to reconcile the Terraform.
retryInterval Kubernetes meta/v1.Duration (Optional) The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.
path string (Optional) Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.
sourceRef CrossNamespaceSourceReference SourceRef is the reference of the source where the Terraform files are stored.
suspend bool (Optional) Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.
force bool (Optional) Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.
readInputsFromSecrets []ReadInputsFromSecretSpec (Optional) writeOutputsToSecret WriteOutputsToSecretSpec (Optional) A list of target secrets for the outputs to be written as.
disableDriftDetection bool (Optional) Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.
cliConfigSecretRef Kubernetes core/v1.SecretReference (Optional) healthChecks []HealthCheck (Optional) List of health checks to be performed.
destroyResourcesOnDeletion bool (Optional) Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.
serviceAccountName string (Optional) Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.
alwaysCleanupRunnerPod bool (Optional) Clean the runner pod up after each reconciliation cycle
runnerTerminationGracePeriodSeconds int64 (Optional) Configure the termination grace period for the runner pod. Use this parameter to allow the Terraform process to gracefully shutdown. Consider increasing for large, complex or slow-moving Terraform managed resources.
refreshBeforeApply bool (Optional) RefreshBeforeApply forces refreshing of the state before the apply step.
runnerPodTemplate RunnerPodTemplate (Optional) enableInventory bool (Optional) EnableInventory enables the object to store resource entries as the inventory for external use.
tfstate TFStateSpec (Optional) targets []string (Optional) Targets specify the resource, module or collection of resources to target.
parallelism int32 (Optional) Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.
storeReadablePlan string (Optional) StoreReadablePlan enables storing the plan in a readable format.
webhooks []Webhook (Optional) dependsOn []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference (Optional) enterprise Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Enterprise is the enterprise configuration placeholder.
planOnly bool (Optional) PlanOnly specifies if the reconciliation should or should not stop at plan phase.
breakTheGlass bool (Optional) BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.
branchPlanner BranchPlanner BarnchPlanner configuration.
status TerraformStatus"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformSpec","title":"TerraformSpec","text":"(Appears on: Terraform)
TerraformSpec defines the desired state of Terraform
Field DescriptionapprovePlan string (Optional) ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.
destroy bool (Optional) Destroy produces a destroy plan. Applying the plan will destroy all resources.
backendConfig BackendConfigSpec (Optional) backendConfigsFrom []BackendConfigsReference (Optional) cloud CloudSpec (Optional) workspace string (Optional) vars []Variable (Optional) List of input variables to set for the Terraform program.
varsFrom []VarsReference (Optional) List of references to a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey. Values of the later Secret / ConfigMap with the same keys will override those of the former.
values Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Values map to the Terraform variable \u201cvalues\u201d, which is an object of arbitrary values. It is a convenient way to pass values to Terraform resources without having to define a variable for each value. To use this feature, your Terraform file must define the variable \u201cvalues\u201d.
fileMappings []FileMapping (Optional) List of all configuration files to be created in initialization.
interval Kubernetes meta/v1.Duration The interval at which to reconcile the Terraform.
retryInterval Kubernetes meta/v1.Duration (Optional) The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.
path string (Optional) Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.
sourceRef CrossNamespaceSourceReference SourceRef is the reference of the source where the Terraform files are stored.
suspend bool (Optional) Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.
force bool (Optional) Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.
readInputsFromSecrets []ReadInputsFromSecretSpec (Optional) writeOutputsToSecret WriteOutputsToSecretSpec (Optional) A list of target secrets for the outputs to be written as.
disableDriftDetection bool (Optional) Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.
cliConfigSecretRef Kubernetes core/v1.SecretReference (Optional) healthChecks []HealthCheck (Optional) List of health checks to be performed.
destroyResourcesOnDeletion bool (Optional) Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.
serviceAccountName string (Optional) Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.
alwaysCleanupRunnerPod bool (Optional) Clean the runner pod up after each reconciliation cycle
runnerTerminationGracePeriodSeconds int64 (Optional) Configure the termination grace period for the runner pod. Use this parameter to allow the Terraform process to gracefully shutdown. Consider increasing for large, complex or slow-moving Terraform managed resources.
refreshBeforeApply bool (Optional) RefreshBeforeApply forces refreshing of the state before the apply step.
runnerPodTemplate RunnerPodTemplate (Optional) enableInventory bool (Optional) EnableInventory enables the object to store resource entries as the inventory for external use.
tfstate TFStateSpec (Optional) targets []string (Optional) Targets specify the resource, module or collection of resources to target.
parallelism int32 (Optional) Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.
storeReadablePlan string (Optional) StoreReadablePlan enables storing the plan in a readable format.
webhooks []Webhook (Optional) dependsOn []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference (Optional) enterprise Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) Enterprise is the enterprise configuration placeholder.
planOnly bool (Optional) PlanOnly specifies if the reconciliation should or should not stop at plan phase.
breakTheGlass bool (Optional) BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.
branchPlanner BranchPlanner BarnchPlanner configuration.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformStatus","title":"TerraformStatus","text":"(Appears on: Terraform)
TerraformStatus defines the observed state of Terraform
Field DescriptionReconcileRequestStatus github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus (Members of ReconcileRequestStatus are embedded into this type.)
observedGeneration int64 (Optional) ObservedGeneration is the last reconciled generation.
conditions []Kubernetes meta/v1.Condition (Optional) lastAppliedRevision string (Optional) The last successfully applied revision. The revision format for Git sources is /. lastAttemptedRevision string (Optional)
LastAttemptedRevision is the revision of the last reconciliation attempt.
lastPlannedRevision string (Optional) LastPlannedRevision is the revision used by the last planning process. The result could be either no plan change or a new plan generated.
lastPlanAt Kubernetes meta/v1.Time (Optional) LastPlanAt is the time when the last terraform plan was performed
lastDriftDetectedAt Kubernetes meta/v1.Time (Optional) LastDriftDetectedAt is the time when the last drift was detected
lastAppliedByDriftDetectionAt Kubernetes meta/v1.Time (Optional) LastAppliedByDriftDetectionAt is the time when the last drift was detected and terraform apply was performed as a result
availableOutputs []string (Optional) plan PlanStatus (Optional) inventory ResourceInventory (Optional) Inventory contains the list of Terraform resource object references that have been successfully applied.
lock LockStatus (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Variable","title":"Variable","text":"(Appears on: TerraformSpec)
Field Descriptionname string Name is the name of the variable
value Kubernetes pkg/apis/apiextensions/v1.JSON (Optional) valueFrom Kubernetes core/v1.EnvVarSource (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.VarsReference","title":"VarsReference","text":"(Appears on: TerraformSpec)
VarsReference contain a reference of a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey.
Field Descriptionkind string Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).
name string Name of the values referent. Should reside in the same namespace as the referring resource.
varsKeys []string (Optional) VarsKeys is the data key at which a specific value can be found. Defaults to all keys.
optional bool (Optional) Optional marks this VarsReference as optional. When set, a not found error for the values reference is ignored, but any VarsKey or transient error will still result in a reconciliation failure.
"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Webhook","title":"Webhook","text":"(Appears on: TerraformSpec)
Field Descriptionstage string enabled bool (Optional) url string payloadType string (Optional) errorMessageTemplate string (Optional) testExpression string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.WriteOutputsToSecretSpec","title":"WriteOutputsToSecretSpec","text":"(Appears on: TerraformSpec)
WriteOutputsToSecretSpec defines where to store outputs, and which outputs to be stored.
Field Descriptionname string Name is the name of the Secret to be written
labels map[string]string (Optional) Labels to add to the outputted secret
annotations map[string]string (Optional) Annotations to add to the outputted secret
outputs []string (Optional) Outputs contain the selected names of outputs to be written to the secret. Empty array means writing all outputs, which is default.
This page was automatically generated with gen-crd-api-reference-docs
Decisions that affect the development of Terraform Controller that are not captured via a proposal need to be captured in some way. We need a method that is lightweight and easy to discover the decision that have been made. The record of decisions will help future contributors to the project to understand why something has been implemented or is done a certain way.
"},{"location":"adr/0000-use-adrs-for-decisions/#decision","title":"Decision","text":"The project will use Architectural Decision Records (ADR) to record decisions that are made outside of a proposal.
A template has been created based on prior work:
When decisions are made that affect the entire project then a new ADR needs to be created. Likewise, if a decision has been superseded then we need to capture this as a new ADR and mark the previous ADR as superseded. Maintainers and contributors will need to decide when an ADR is to be created.
"},{"location":"adr/0001-pr-polling-workflow/","title":"1. Pull Request Polling","text":"To detect pull request changes, we can use webhooks or polling using GitHub's API.
"},{"location":"adr/0001-pr-polling-workflow/#decision","title":"Decision","text":"We decided to start with polling for security reasons. Using webhooks would require users to open an ingress to the cluster. Because of this requirement, we think security conscious folks may refuse to roll this out on production clusters especially in an air-gapped environment. This does not mean that we will never consider using webhooks for this, but that initially, polling is what we have chosen to implement.
The Branch-Based Planner has two components:
The list Pull Requests endpoint returns all required fields to detect new and closed pull requests. It's one request per repository, but listing comments has to use an API request per pull request. So we have to add a mechanism to avoid hitting API rate limits.
"},{"location":"adr/0002-deny-cross-ns-by-default/","title":"2. Deny cross-namespace refs by default","text":"Like Flux, the tf-controller API has a handful of places where it accepts cross-namespace references.
Terraform.spec.sourceRef -- refers to the Flux source object with the Terraform programTerraform.spec.dependsOn[] -- refers to other objects that must be ready before this object can be run.data.resources[] -- in the config struct used by the branch plannerIn general in Kubernetes, references to objects in other namespaces are frowned upon, because
Both of these effects make a system less secure.
However: removing cross-namespace refs entirely would break some installations in a way that would be difficult to fix, because Flux deployments often rely on defining sources away from objects that use them.
"},{"location":"adr/0002-deny-cross-ns-by-default/#decision","title":"Decision","text":"Deny cross-namespace references by default, but allow them to be enabled with a flag.
So that the default value means the right thing, the flag name must be enable-cross-namespace-refs, and the default false. To avoid confusion when people try to use the Flux version of this flag --disable-cross-namespace-refs, it should be supported too, but only respected if supplied.
The changed default will break deployments that rely on cross-namespace refs, but they are easily fixed with the flag.
New deployments will be more secure, by default.
"},{"location":"branch_planner/","title":"Branch Planner User Guide","text":""},{"location":"branch_planner/#overview","title":"Overview","text":"The Branch Planner, a new component of the Terraform Controller, is specifically designed to enhance the flexibility and robustness of Terraform Controller planning operations. This feature, currently in its technology preview phase, facilitates Terraform planning across branches, creating a streamlined and familiar PR-based workflow for users.
"},{"location":"branch_planner/#how-does-it-work","title":"How does it work?","text":"When the Branch Planner starts, it polls repositories that contain Terraform resources at regular intervals, in order to detect Pull Requests (PR) that change those resources. Upon detecting that a PR exists, the Branch Planner initialises a Terraform object in Plan Only mode for the corresponding branch. In this mode, Terraform Controller generates Terraform plans but does not apply them. Once the plan is generated, Branch Planner posts the plan under the PR as a comment enabling users to review the plan. When the Terraform files of the corresponding branch get updated, Branch Planner posts the updated plan under the PR as new comment, keeping the PR up-to-date with the latest Terraform plan.
"},{"location":"branch_planner/#replan-commands","title":"Replan commands","text":"The Branch Planner also allows users to manually trigger the replan process. By simply commenting !replan under the PR, the Branch Planner will be instructed to generate a new plan and post it under the PR as a new comment.
Now that you know what Branch Planner can do for you, follow the guide to get started.
"},{"location":"branch_planner/getting-started/","title":"Getting Started With Branch Planner","text":"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.
"},{"location":"branch_planner/getting-started/#prerequisites","title":"Prerequisites","text":"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\nInstall Flux. Please make sure you have the latest version of Flux (v2 GA).
flux install\nCreate 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)\n\nkubectl create secret generic branch-planner-token \\\n --namespace=flux-system \\\n --from-literal=\"token=${GITHUB_TOKEN}\"\nInstall 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/main/docs/branch_planner/release.yaml\nCreate 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>\nexport GITHUB_REPO=<your repo>\n\ncat <<EOF | kubectl apply -f -\n---\napiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\n name: branch-planner-demo\n namespace: flux-system\nspec:\n interval: 30s\n url: https://github.com/${GITHUB_USER}/${GITHUB_REPO}\n ref:\n branch: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n name: branch-planner-demo\n namespace: flux-system\nspec:\n approvePlan: auto\n path: ./\n interval: 1m\n sourceRef:\n kind: GitRepository\n name: branch-planner-demo\n namespace: flux-system\nEOF\nBranch Planner uses a ConfigMap as configuration. That ConfigMap is optional to use but useful for fine-tuning Branch Planner.
"},{"location":"branch_planner/getting-started/#custom-configuration","title":"Custom Configuration","text":"By default Branch Planner will look for a 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.---\napiVersion: v1\nkind: ConfigMap\nmetadata:\nnamespace: flux-system\nname: branch-planner\ndata:\nsecretName: branch-planner-token\nresources: |-\n- namespace: terraform\nBranch 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 \\\n--namespace=flux-system \\\n--from-literal=\"token=${GITHUB_TOKEN}\"\nIf 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:\nresources:\n- namespace: default\nname: exact-terraform-object\n- namespace: terraform\nIf 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.
To enable branch planner, set the branchPlanner.enabled to true in the Helm values files.
---\nbranchPlanner:\n enabled: true\nFor public repositories, it's sufficient to enable Public Repositories, without any additional permissions.
For private repositories the following permissions are required:
Issues with Read and Write access. This is required to list and read comments for commands, and to create comments with the Plan output.Pull requests with Read-Only access. This is required to check Pull Request changes.Metadata with Read-only access. This is automatically marked as \"mandatory\" because of the permissions listed above.Assume that we have the my-stack Terraform object with its .spec.workspace set to \"default\".
kubectl get terraform\n\nNAME READY STATUS AGE\nmy-stack Unknown Initializing 28s\nWe can backup its tfstate out of the cluster, like this:
WORKSPACE=default\nNAME=my-stack\n\nkubectl get secret tfstate-${WORKSPACE}-${NAME} \\\n-ojsonpath='{.data.tfstate}' \\\n| base64 -d | gzip -d > terraform.tfstate\nTo restore the tfstate file or import an existing tfstate file to the cluster, we can use the following operation:
gzip terraform.tfstate\n\nWORKSPACE=default\nNAME=my-stack\n\nkubectl create secret \\\ngeneric tfstate-${WORKSPACE}-${NAME} \\\n--from-file=tfstate=terraform.tfstate.gz \\\n--dry-run=client -o=yaml \\\n| yq e '.metadata.annotations[\"encoding\"]=\"gzip\"' - \\\n> tfstate-${WORKSPACE}-${NAME}.yaml\n\nkubectl apply -f tfstate-${WORKSPACE}-${NAME}.yaml\nThis document describes the requeue behavior of the Reconcile method in the TerraformReconciler struct in the code base. Understanding these behaviors can be crucial for troubleshooting, as well as for future development and refinement of the system.
"},{"location":"how_to/interval_and_retryInterval/#requeue-behaviors","title":"Requeue Behaviors","text":"The Reconcile method has several requeue behaviors based on different conditions and errors. We will group them into four categories based on their requeue behavior:
"},{"location":"how_to/interval_and_retryInterval/#1-immediate-requeue-not-using-specified-interval-retryinterval","title":"1. Immediate Requeue (Not using specified interval / retryInterval)","text":"In these scenarios, the Reconcile method returns an error which leads to an immediate requeue orchestrated by the Controller Runtime. The interval is based on the controller's configuration and not specified in the method itself:
spec.retryInterval)","text":"In these scenarios, the method specifically asks for a requeue after a certain interval specified by spec.retryInterval (default to 15s).
spec.sourceRef is not found.spec.interval)","text":"In this scenario, the method specifically asks for a requeue after a successful reconciliation:
The interval for the requeue is spec.interval.
In these scenarios, the method returns without asking for a requeue, and the Controller Runtime will stop the reconciliation process until there is a manual intervention:
This document discusses potential difficulties you may encounter when deleting Terraform resources through the Terraform Controller and the necessary components to facilitate a smooth deletion process.
"},{"location":"how_to/resource_deletion/#source-object","title":"Source Object","text":"The source object (e.g., GitRepository or OCIRepository) is a critical component of the Terraform resource deletion process. This object houses the Terraform source files (.tf files) that describe the configuration of the infrastructure resources.
During the deletion process, the Terraform Controller uses these source files to conduct a re-planning operation. This operation is instrumental to deleting the Terraform Custom Resource (CR).
However, if the source object is unavailable or has been deleted, the re-planning operation fails. As a result, the Terraform Controller cannot locate the resource state, leading to an infinite deletion attempt cycle, commonly known as a looping process.
"},{"location":"how_to/resource_deletion/#role-bindings","title":"Role Bindings","text":"Role bindings assign permissions to Terraform runners, allowing them to execute operations within the Kubernetes cluster. These bindings define the actions that the Terraform runners are authorized to carry out.
If role bindings are missing or misconfigured, the Terraform runners may lack the necessary permissions to execute the deletion process, causing the process to fail.
"},{"location":"how_to/resource_deletion/#secrets-and-configmaps","title":"Secrets and ConfigMaps","text":"Before initiating the resource deletion process, the Terraform Controller leverages Secrets and ConfigMaps to generate a complete source before planning. Secrets store confidential data like API keys or passwords, while ConfigMaps hold configuration data in a key-value format.
Should any of these components be missing or misconfigured, the Terraform Controller may fail to generate an accurate deletion plan, which could impede the resource deletion process.
"},{"location":"how_to/resource_deletion/#troubleshooting","title":"Troubleshooting","text":"To prevent the aforementioned issues, ensure the availability and proper configuration of the source object, role bindings, and Secrets and ConfigMaps during the deletion process.
As of now, we are actively working to address these limitations in the Terraform Controller. We appreciate your patience and welcome any feedback to help enhance the Terraform Controller's performance.
"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/","title":"Break the glass","text":""},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#what-is-break-the-glass","title":"What is break the glass?","text":"\"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. This feature is available in the Terraform controller v0.15.0 and above.
~> WARNING: Please note that you cannot use this feature to fix the Terraform resources with v1alpha1 version of the Terraform CRD. It works only with v1alpha2 version of the Terraform CRD.
~> WARNING: Please also make sure that you have enough privileges to exec pods in your namespaces. Otherwise, you will not be able to use this feature.
There are two primary methods of initiating this mode:
tfctl command-line tool.spec.breakTheGlass field to true in the Terraform object.tfctl to Break the Glass","text":"To start a one-time troubleshooting session, you can use the tfctl break-glass command. For instance:
tfctl break-glass hello-world\nThis 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.
"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#break-the-glass-with-specbreaktheglass-field","title":"Break the glass withspec.breakTheGlass field","text":"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:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\nbreakTheGlass: true\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nWe 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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\napprovePlan: disable\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nIn some situations, you may need to perform the Terraform 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 recommended way is to do manual force unlock. To manually force-unlock, you need to:
forceUnlock to yes, andas the following example:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\ntfstate:\nforceUnlock: \"yes\"\nlockIdentifier: f2ab685b-f84d-ac0b-a125-378a22877e8d\nIn this guide, we will walk through the steps of using TF-controller to plan and manually apply Terraform resources.
We will start by creating the Terraform object and specifying the necessary fields, including the approvePlan field.
We will then create the GitRepository object, which points to the Git repository containing the Terraform configuration.
Once these objects are created, we will 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.
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.
For the plan & manual approval workflow, please start by either setting .spec.approvePlan to be the blank value, or omitting the field. This will tell TF-controller to use the plan & manual approval workflow, rather than the auto-apply workflow. If you want to use the auto-apply workflow, you will need to set the spec.approvePlan field to \"auto\".
In addition to setting the spec.approvePlan field, you will also need to specify the interval, path, and sourceRef fields in the spec field. The interval field determines how often TF-controller will run the Terraform configuration, the path field specifies the location of the configuration files, and the sourceRef field points to the GitRepository object.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: \"\" # or you can omit this field\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nThen after a reconciliation loop, the controller will generate a plan, and tell you how to use field .spec.approvePlan to approve the plan. You can run the following command to obtain that message.
kubectl -n flux-system get tf/helloworld\nThis command will output the message containing the approvePlan value that you will need to use to approve the plan. Once you have this value, you can 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. 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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\napprovePlan: plan-main-b8e362c206 # first 8 digits of a commit hash is enough\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nFor 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:
For example, our Terraform file is provisioned and contains the following outputs.
# main.tf\noutput \"rdsAddress\" {\nvalue = \"mydb.xyz.us-east-1.rds.amazonaws.com\"\n}\noutput \"rdsPort\" {\nvalue = \"3306\"\n}\noutput \"myappURL\" {\nvalue = \"https://example.com/\"\n}\nWe can use standard Go template expressions, like ${{ .rdsAddress }}, to refer to those output values and use them to verify that the resources are up and running.
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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nhealthChecks:\n- name: rds\ntype: tcp\naddress: ${{ .rdsAddress }}:${{ .rdsPort }} timeout: 10s # optional, defaults to 20s\n- name: myapp\ntype: http\nurl: ${{ .myappURL }}\ntimeout: 5s\n- name: url_not_from_output\ntype: http\nurl: \"https://example.org\"\nTo provision resources with TF-controller, you need to create a Terraform object and a Flux source object, such as a GitRepository or OCIRepository object.
The Terraform object is a Kubernetes custom resource definition (CRD) object. It is the core object of TF-controller and defines the Terraform module, backend configuration, and GitOps automation mode..
It defines the Terraform module, the backend configuration, and the GitOps automation mode.
The Terraform module is a Terraform configuration that can be used to provision resources. It can be placed inside a Git repository, or packaged as an OCI image in an OCI registry.
The backend configuration is the configuration for the Terraform backend to be used to store the Terraform state. It is optional. If not specified, the Kubernetes backend will be used by default.
"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/#gitops-automation-mode","title":"GitOps automation mode","text":"The GitOps automation mode is the GitOps automation mode to be used to run the Terraform module. It determines how Terraform runs and manages your infrastructure. It is optional. If not specified, the \"plan-and-manually-apply\" mode will be used by default. In the \"plan-and-manually-apply\" mode, TF-controller will run a Terraform plan and output the proposed changes to a Git repository. A human must then review and manually apply the changes. This is the default GitOps automation mode if none is specified.
In the \"auto-apply\" mode, TF-controller will automatically apply the changes after a Terraform plan is run. This can be useful for environments where changes can be made automatically, but it is important to ensure that the proper controls, like policies, are in place to prevent unintended changes from being applied.
To specify the GitOps automation mode in a Terraform object, you can set the spec.approvePlan field to the desired value. For example, to use the \"auto-apply\" mode, y ou would set it to spec.approvePlan: auto.
It is important to carefully consider which GitOps automation mode is appropriate for your use case to ensure that your infrastructure is properly managed and controlled.
The following is an example of a Terraform object; we use the \"auto-apply\" mode:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nspec:\npath: ./helloworld\ninterval: 10m\napprovePlan: auto\nsourceRef:\nkind: GitRepository\nname: helloworld\nThis code is defining a Terraform object in Kubernetes. The apiVersion field specifies the version of the Kubernetes API being used, and the kind field specifies that it is a Terraform object. The metadata block contains information about the object, including its name.
The spec field contains the specification for the Terraform object. The path field specifies the path to the Terraform configuration files, in this case a directory named \"helloworld\". The interval field specifies the frequency at which TF-controller should run the Terraform configuration, in this case every 10 minutes. The approvePlan field specifies whether or not to automatically approve the changes proposed by a Terraform plan. In this case, it is set to auto, meaning that changes will be automatically approved.
The sourceRef field specifies the Flux source object to be used. In this case, it is a GitRepository object with the name \"helloworld\". This indicates that the Terraform configuration is stored in a Git repository object with the name helloworld.
The resources provisioned by a Terraform object are not destroyed by default, and the tfstate of that Terraform object still remains in the cluster.
It means that you are safe to delete the Terraform object in the cluster and re-create it. If you re-create a new Terraform object with the same name, namespace and workspace, it will continue to use the tfstate inside the cluster as the starting point to reconcile.
However, you may want to destroy provisioned resources when delete the Terraform object in many scenarios. To enable destroy resources on object deletion, set .spec.destroyResourcesOnDeletion to true.
~> WARNING: This feature will destroy your resources on the cloud if the Terraform object gets deleted. Please use it with cautions.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ndestroyResourcesOnDeletion: true\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nOutputs created by Terraform can be written to a secret using .spec.writeOutputsToSecret.
We can specify a target secret in .spec.writeOutputsToSecret.name, and the controller will write all outputs to the secret by default.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\nWe can choose only a subset of outputs by specify output names we'd like to write in the .spec.writeOutputsToSecret.outputs array.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\noutputs:\n- hello_world\n- my_sensitive_data\nSome time we'd like to use rename an output, so that it can be consumed by other Kubernetes controllers. For example, we might retrieve a key from a Secret manager, and it's an AGE key, which must be ending with \".agekey\" in the secret. In this case, we need to rename the output.
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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\noutputs:\n- age_key:age.agekey\nIn some situations, it is needed to add custom labels and annotations to the outputted secret. As an example, operators such as kubernetes-replicator allow replicating secrets from one namespace to another but use annotations to do so.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nwriteOutputsToSecret:\nname: helloworld-output\nlabels:\nmy-label: true\nannotations:\nmy-annotation: \"very long string\"\nIn some situations, it is needed to add custom labels and annotations to the runner pod used to reconcile Terraform. For example, for Azure AKS to grant pod active directory permissions using Azure Active Directory (AAD) Pod Identity, a label like aadpodidbinding: myIdentity on the pod is required.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nrunnerPodTemplate:\nmetadata:\nlabels:\naadpodidbinding: myIdentity\nannotations:\ncompany.com/abc: xyz\nBy 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.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nrunnerPodTemplate:\nspec:\nimage: registry.io/tf-runner:xyz\nYou can use runner.Dockerfile as a basis of customizing runner pod image.
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 for a list of the configurable Runner Pod spec fields.
~> BREAKING CHANGE: This is a breaking change of the v1alpha1 API.
Users who are upgrading from TF-controller <= 0.7.0 require updating varsFrom, from a single object:
varsFrom:\nkind: ConfigMap\nname: cluster-config\nto be an array of object, like this:
varsFrom:\n- kind: ConfigMap\nname: cluster-config\nvars and varsFrom","text":"You can pass variables to Terraform using the vars and varsFrom fields.
Inline variables can be set using vars. The varsFrom field accepts a list of ConfigMaps / Secrets. You may use the varsKeys property of varsFrom to select specific keys from the input or omit this field to select all keys from the input source.
Note that in the case of the same variable key being passed multiple times, the controller will use the lattermost instance of the key passed to varsFrom.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nvars:\n- name: region\nvalue: us-east-1\n- name: env\nvalue: dev\n- name: instanceType\nvalue: t3-small\nvarsFrom:\n- kind: ConfigMap\nname: cluster-config\nvarsKeys:\n- nodeCount\n- instanceType\n- kind: Secret\nname: cluster-creds\nThe vars field supports HCL string, number, bool, object and list types. For example, the following variable can be populated using the accompanying Terraform spec:
variable \"cluster_spec\" {\ntype = object({\nregion = string\nenv = string\nnode_count = number\npublic = bool\n})\n}\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nvars:\n- name: cluster_spec\nvalue:\nregion: us-east-1\nenv: dev\nnode_count: 10\npublic: false\nTo rename a variable, you can use the varsKeys key within the varsFrom field. Here's the basic structure:
spec:\nvarsFrom:\n- kind: Secret\nname: <secret_name>\nvarsKeys:\n- <original_variable_name>:<new_variable_name>\noriginal_variable_name corresponds to the initial name of the variable in the referenced secret, while new_variable_name represents the alias you want to use within the Terraform code. Consider this example below, where we rename nodeCount to node_count and instanceType to instance_type:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nvarsFrom:\n- kind: Secret\nname: cluster-config\nvarsKeys:\n- nodeCount:node_count\n- instanceType:instance_type\nSee Rename outputs for more details.
"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-input-secrets","title":"Rename input secrets","text":"See Rename input secrets for more details.
"},{"location":"use_tf_controller/with_AWS_EKS_IRSA/","title":"Use TF-controller with AWS EKS IRSA","text":"AWS Elastic Kubernetes Service (EKS) offers IAM Roles for Service Accounts (IRSA) as a mechanism by which to provide credentials to Kubernetes pods. This can be used to provide the required AWS credentials to Terraform runners for performing plans and applies.
You can use eksctl to associate an OIDC provider with your EKS cluster, for example:
eksctl utils associate-iam-oidc-provider --cluster CLUSTER_NAME --approve\nThen follow the instructions here to add a trust policy to the IAM role which grants the necessary permissions for Terraform. Please note that if you have installed the controller following the README, then the namespace:serviceaccountname will be flux-system:tf-runner. You'll obtain a Role ARN to use in the next step.
Finally, annotate the ServiceAccount for the tf-runner with the obtained Role ARN in your cluster:
kubectl annotate -n flux-system serviceaccount tf-runner eks.amazonaws.com/role-arn=ROLE_ARN\nIf deploying the tf-controller via Helm, this can be accomplished as follows:
values:\nrunner:\nserviceAccount:\nannotations:\neks.amazonaws.com/role-arn: ROLE_ARN\nTF-controller supports GitOps dependency management. The GitOps dependency management feature is based on the similar technique implemented in the Kustomization controller of Flux.
This means that you can use TF-controller to provision resources that depend on other resources at the GitOps level. For example, you can use TF-controller to provision an S3 bucket, and then use TF-controller to provision another resource to configure ACL for that bucket.
GitOps dependency management is different from Terraform's HCL dependency management in the way that it is not based on Terraform's mechanism, which is controlled by the Terraform binary. Instead, it is implemented at the controller level, which means that each Terraform module is reconciled and can be managed independently, while still being able to depend on other modules.
"},{"location":"use_tf_controller/with_GitOps_dependency_management/#create-a-terraform-object","title":"Create a Terraform object","text":"Similar to the same feature in the Kustomization controller, the dependency management feature is enabled by setting the dependsOn field in the Terraform object. The dependsOn field is a list of Terraform objects.
When the dependency is not satisfied, the Terraform object will be in the Unknown state, and it will be retry again every spec.retryInterval. The retry interval is same as the spec.interval by default, and it can be configured separately by setting the spec.retryInterval field.
First, create a Terraform object to provision the S3 bucket, name it aws-s3-bucket. The S3 bucket is provisioned by the Terraform module aws_s3_bucket in the OCI image aws-package. It is configured to use the auto-apply mode, and write outputs to the secret aws-s3-bucket-outputs.
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: aws-s3-bucket\nnamespace: flux-system\nspec:\npath: aws_s3_bucket\nvalues:\nbucket: my-tf-controller-test-bucket\ntags:\nEnvironment: Dev\nName: My bucket\nsourceRef:\nkind: OCIRepository\nname: aws-package\napprovePlan: auto\ninterval: 2m\ndestroyResourcesOnDeletion: true\nwriteOutputsToSecret:\nname: aws-s3-bucket-outputs\noutputs:\n- arn\n- bucket\nrunnerPodTemplate:\nspec:\nenvFrom:\n- secretRef:\nname: aws-credentials\nSecond, create a Terraform object to configure ACL for the S3 bucket, name it aws-s3-bucket-acl. The ACL is provisioned by the Terraform module aws_s3_bucket_acl, also from the OCI image aws-package-v4.33.0.
In the dependsOn field, specify the Terraform object that provisions the S3 bucket. This means that the ACL will be configured only after the S3 bucket is provisioned, and has its outputs Secret written. We can read the outputs of the S3 bucket from the Secret aws-s3-bucket-outputs, by specifying the spec.readInputsFromSecrets field. The spec.readInputsFromSecrets field is a list of Secret objects. Its name field is the name of the Secret, and its as field is the name of variable that can be used in the spec.values block.
For example, the spec.values.bucket field in the aws-s3-bucket-acl Terraform object is set to ${{ .aws_s3_bucket.bucket }}.
Please note that we use ${{ and }} as the delimiters for the variable name, instead of the Helm default ones, {{ and }}.
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: aws-s3-bucket-acl\nnamespace: flux-system\nspec:\npath: aws_s3_bucket_acl\nvalues:\nacl: private\nbucket: ${{ .aws_s3_bucket.bucket }}\nsourceRef:\nkind: OCIRepository\nname: aws-package\napprovePlan: auto\ninterval: 3m\ndependsOn:\n- name: aws-s3-bucket\nreadInputsFromSecrets:\n- name: aws-s3-bucket-outputs\nas: aws_s3_bucket\nrunnerPodTemplate:\nspec:\nenvFrom:\n- secretRef:\nname: aws-credentials\nThe Kustomization controller will substitute variables in the Terraform object, which will cause conflicts with the variable substitution in the GitOps dependency management feature. To avoid this, we need to add the kustomize.toolkit.fluxcd.io/substitute: disabled annotation to the Terraform object.
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: aws-s3-bucket-acl\nnamespace: flux-system\nannotations:\nkustomize.toolkit.fluxcd.io/substitute: disabled\nspec:\npath: aws_s3_bucket_acl\nvalues:\nacl: private\nbucket: ${{ .aws_s3_bucket.bucket }}\nsourceRef:\nkind: OCIRepository\nname: aws-package\napprovePlan: auto\ninterval: 3m\ndependsOn:\n- name: aws-s3-bucket\nreadInputsFromSecrets:\n- name: aws-s3-bucket-outputs\nas: aws_s3_bucket\nrunnerPodTemplate:\nspec:\nenvFrom:\n- secretRef:\nname: aws-credentials\nStarting 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.
"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-login","title":"Terraform Login","text":"First, you need to obtain an API token from your TFE. You can use terraform login command to do so.
terraform login tfe.dev.example.com\nThen you can find your API token inside $HOME/.terraform.d/credentials.tfrc.json. Content of the file will look like this:
{\n\"credentials\": {\n\"tfe.dev.example.com\": {\n\"token\": \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n}\n}\n}\nTF-controller accepts an TFRC file in the HCL format. So you have to prepare terraform.tfrc file using contents from above.
credentials \"tfe.dev.example.com\" {\ntoken = \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n}\nWe will now create a Kubernetes Secret from yourterraform.tfrc file, name it tfe-cli-config and put it inside the flux-system namespace.
kubectl create secret generic \\\ntfe-cli-config \\\n--namespace=flux-system \\\n--from-file=terraform.tfrc=./terraform.tfrc\nIn your Terraform object, you'll have to 1. disable the backend by setting spec.backendConfig.disable: true, and 2. point spec.cliConfigSecretRef: to the Secret created in the previous step, like this:
---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: tfe-demo\nnamespace: flux-system\nspec:\napprovePlan: auto\ninterval: 2m\npath: ./terraform/tfe-demo\nbackendConfig:\ndisable: true\ncliConfigSecretRef:\nname: tfe-cli-config\nnamespace: flux-system\nvars:\n- name: subject\nvalue: World\nsourceRef:\nkind: GitRepository\nname: flux-system\nnamespace: flux-system\nwriteOutputsToSecret:\nname: tfe-helloworld-output\noutputs:\n- greeting\nDon't forget that you need to tell your Terraform model to use your enterprise instance as well. Here's an example,
terraform {\nrequired_version = \">= 1.1.0\"\ncloud {\nhostname = \"tfe.dev.example.com\"\norganization = \"weaveworks\"\nworkspaces {\nname = \"dev\"\n}\n}\n}\nvariable \"subject\" {\ntype = string\ndefault = \"World\"\ndescription = \"Subject to hello\"\n}\noutput \"greeting\" {\nvalue = \"Hello ${var.subject} from Terraform Enterprise\"\n}\nFor connecting to Terraform Cloud, please replace your hostname to app.terraform.io.
By default, tf-controller will use the Kubernetes backend to store the Terraform state file (tfstate) in cluster.
The tfstate is stored in a secret named: tfstate-${workspace}-${secretSuffix}. The default suffix will be the name of the Terraform resource, however you may override this setting using .spec.backendConfig.secretSuffix. The default workspace name is \"default\", you can also override the workspace by setting .spec.workspace to another value.
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:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\nbackendConfig:\ncustomConfiguration: |\nbackend \"s3\" {\nbucket = \"s3-terraform-state1\"\nkey = \"dev/terraform.tfstate\"\nregion = \"us-east-1\"\nendpoint = \"http://localhost:4566\"\nskip_credentials_validation = true\nskip_metadata_api_check = true\nforce_path_style = true\ndynamodb_table = \"terraformlock\"\ndynamodb_endpoint = \"http://localhost:4566\"\nencrypt = true\n}\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nrunnerPodTemplate:\nspec:\nimage: registry.io/tf-runner:xyz\nTo use OCI artifacts as the source of Terraform objects, you need Flux 2 version v0.32.0 or higher.
Assuming that you have Terraform files (your root module may contain sub-modules) under ./modules, you can use Flux CLI to create an OCI artifact for your Terraform modules by running the following commands:
flux push artifact oci://ghcr.io/tf-controller/helloworld:$(git rev-parse --short HEAD) \\\n--path=\"./modules\" \\\n--source=\"$(git config --get remote.origin.url)\" \\\n--revision=\"$(git branch --show-current)/$(git rev-parse HEAD)\"\nflux tag artifact oci://ghcr.io/tf-controller/helloworld:$(git rev-parse --short HEAD) \\\n--tag main\nThen you define a source (OCIRepository), and use it as the sourceRef of your Terraform object.
---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\nname: helloworld-oci\nspec:\ninterval: 1m\nurl: oci://ghcr.io/tf-controller/helloworld\nref:\ntag: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld-tf-oci\nspec:\npath: ./\napprovePlan: auto\ninterval: 1m\nsourceRef:\nkind: OCIRepository\nname: helloworld-oci\nwriteOutputsToSecret:\nname: helloworld-outputs\nDrift detection is enabled by default. You can set .spec.disableDriftDetection: true to disable it.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\napprovePlan: auto\ndisableDriftDetection: true\ninterval: 1m\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nThis plan-only mode is designed to be used in conjunction with the Branch Planner. But you can also use it in a circumstance where you want to run terraform plan only.
If planOnly is set to true, the controller will skip the apply part and runs only terraform plan and saves the output.
apiVersion: infra.contrib.fluxcd.io/v1\nkind: Terraform\nmetadata:\n name: helloworld\n namespace: flux-system\nspec:\n interval: 1m\n planOnly: true\n path: ./\n sourceRef:\n kind: GitRepository\n name: helloworld\n namespace: flux-system\nThis document describes how to use the Weave TF-controller with a primitive module. It requires TF-controller v0.13+ to run the example.
"},{"location":"use_tf_controller/with_primitive_modules/#what-is-a-primitive-module","title":"What is a primitive module?","text":"It's a Terraform module that contains only a single resource.
Here is an example of how a primitive module can be defined in YAML. Assume that we have a ready-to-use OCI image with a primitive module for the imaginary resource aws_hello_world, and the image is tagged as ghcr.io/tf-controller/hello-primitive-modules/v4.32.0:v1.
We'll use the following Terraform object definition to provision the resource.
First, we need to create a Terraform object with the spec.sourceRef.kind field set to OCIRepository and the spec.sourceRef.name field set to the name of the OCIRepository object.
Second, we need to set the spec.path field to the name of the resource, in this case aws_hello_world.
Third, we need to set the spec.values field to the values of the resource. This is a YAML object that will be converted to an HCL variable, and passed to the Terraform module.
Finally, we need to set the spec.approvePlan field to auto to automatically approve the plan.
---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\nname: hello-package-v4.32.0\nnamespace: flux-system\nspec:\ninterval: 30s\nurl: oci://ghcr.io/tf-controller/hello-primitive-modules/v4.32.0\nref:\ntag: v1\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: hello-world\nnamespace: flux-system\nspec:\npath: aws_hello_world\nvalues:\ngreeting: Hi\nsubject: my world\nsourceRef:\nkind: OCIRepository\nname: hello-package-v4.32.0\ninterval: 1h0m\napprovePlan: auto\nA Terraform Runner uses two environment variables, DISABLE_TF_LOGS and ENABLE_SENSITIVE_TF_LOGS, to control the logging behavior of the Terraform execution.
To use these environment variables, they need to be set on each Terraform Runner pod where the Terraform code is being executed. This can typically be done by adding them to the pod's environment variables in the Terraform Runner deployment configuration.
DISABLE_TF_LOGS variable, when set to \"1\", will disable all Terraform output logs to stdout and stderr.ENABLE_SENSITIVE_TF_LOGS variable, when set to \"1\", will enable logging of sensitive Terraform data, such as secret variables, to the local log. However, it is important to note that for the ENABLE_SENSITIVE_TF_LOGS to take effect, the DISABLE_TF_LOGS variable must also be set to \"1\".tf-runner is configured at the info level.DISABLE_TF_LOGS variable is not activated as part of the default settings.ENABLE_SENSITIVE_TF_LOGS variable remains inactive in the default configuration.ShowPlan and ShowPlanRaw on the runner are not logged by default.Plan calls made on the runner, error messages are sanitized as a part of the default configuration.For more information on configuring the Terraform Runner and its environment variables, please consult the documentation on customizing runners within the Weave TF-controller.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/","title":"with the ready to use AWS package","text":""},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#use-tf-controller-with-the-ready-to-use-aws-package","title":"Use TF-controller with the ready-to-use AWS package","text":"This document describes how to use the Weave TF-controller with the ready-to-use AWS package. It requires TF-controller v0.13+ to run the example.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#what-is-a-package","title":"What is a package?","text":"A package is a collection of primitive Terraform modules that are bundled into an OCI image. You can think of a TF-controller's package as a thin wrapper around a Terraform module provider, and a TF-controller primitive module as a thin wrapper around a Terraform resource or a root module.
We will provide a set of ready-to-use packages for the most popular cloud providers. Currently, we ship the package for AWS only.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#aws-package","title":"AWS Package","text":"To provide the out-of-the-box experience, the AWS Package is installed by default when you installed the TF-controller. Unlike other IaC implementation, our package model is designed to be very lightweight as a package is just a set of TF files in the form of OCI. Packages would not put any burden to your cluster. However, you can opt this package out by setting awsPackage.install: false in your Helm chart values.
If you run flux get sources oci you should see the AWS package installed in your cluster listed as aws-package.
flux get sources oci\nNAME REVISION SUSPENDED READY MESSAGE aws-package v4.38.0-v1alpha11/6033f3b False True stored artifact for digest 'v4.38.0-v1alpha11/6033f3b'\nThis section describes how to use the AWS package to provision an S3 bucket with ACL using the TF-controller.
"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#create-a-kind-local-cluster","title":"Create a KinD local cluster","text":"If you don't have a Kubernetes cluster, you can create a KinD cluster with the following command:
kind create cluster\nAfter you have a Kubernetes cluster, you can install Flux with the following command:
flux install\nThen, you can install the TF-controller with the following command:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\nTo provision AWS resources, you need to provide the AWS credentials to your Terraform objects. You can do this by creating a secret with the AWS credentials and reference it in each of your Terraform objects.
```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n name: aws-credentials\n namespace: flux-system\ntype: Opaque\nstringData:\n AWS_ACCESS_KEY_ID: Axxxxxxxxxxxxxxxxxxx\n AWS_SECRET_ACCESS_KEY: qxxxxxxxxxxxxxxxxxxxxxxxxx\n AWS_REGION: us-east-1 # the region you want\nTo apply the secret, run the following command:
kubectl apply -f aws-credentials.yaml\nNow, you can create two Terraform objects, one for an S3 bucket, another one for ACL. Please note that we are using GitOps dependencies to make sure the ACL is created after the bucket is created. You can read more about the GitOps dependencies in the GitOps dependencies document.
```yaml\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n name: aws-s3-bucket\n namespace: flux-system\n labels:\n tf.weave.works/composite: s3-bucket\nspec:\n path: aws_s3_bucket\n values:\n bucket: my-tf-controller-test-bucket\n tags:\n Environment: Dev\n Name: My bucket\n sourceRef:\n kind: OCIRepository\n name: aws-package\n approvePlan: auto\n retryInterval: 10s\n interval: 2m\n destroyResourcesOnDeletion: true\nwriteOutputsToSecret:\n name: aws-s3-bucket-outputs\n outputs:\n - arn\n - bucket\n runnerPodTemplate:\n spec:\n envFrom:\n - secretRef:\n name: aws-credentials\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n name: example-bucket-acl\n namespace: flux-system\n labels:\n tf.weave.works/composite: s3-bucket\nspec:\n path: aws_s3_bucket_acl\n values:\n acl: private\n bucket: ${{ .aws_s3_bucket.bucket }}\nsourceRef:\n kind: OCIRepository\n name: aws-package\n approvePlan: auto\n retryInterval: 10s\n interval: 3m\n dependsOn:\n - name: aws-s3-bucket\n readInputsFromSecrets:\n - name: aws-s3-bucket-outputs\n as: aws_s3_bucket\n destroyResourcesOnDeletion: true\nrunnerPodTemplate:\n spec:\n envFrom:\n - secretRef:\n name: aws-credentials\nThe spec.readInputsFromSecrets field allows you to reference the Terraform outputs from other Terraform objects. In the context of this field, renaming makes it easier to reference the secrets in the spec.values field.
To rename a secret, you need to use the as key in the spec.readInputsFromSecrets field. The name key corresponds to the original name of the secret, while the as key represents the new name that you want to use to reference the secret.
In the example below, we can reference the bucket value from our aws_s3_bucket secret using ${{ .aws_s3_bucket.bucket }} instead of using the original secret name, which is aws-s3-bucket-outputs.
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: example-bucket-acl\nnamespace: flux-system\nspec:\n# ...\nreadInputsFromSecrets:\n- name: aws-s3-bucket-outputs\nas: aws_s3_bucket\nvalues:\nacl: private\nbucket: ${{ .aws_s3_bucket.bucket }}\n# ...\n