From 291385d2772b203b14c8598adeb05e49dec90b73 Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Fri, 1 Dec 2023 11:14:12 +0000
Subject: [PATCH] Publish docs from f48ea1bb25ad8d805d1e9a23fb6e72594a7d606e

---
 404.html                                      |   2 +-
 References/terraform/index.html               |   2 +-
 adr/0000-template/index.html                  |   2 +-
 adr/0000-use-adrs-for-decisions/index.html    |   2 +-
 adr/0001-pr-polling-workflow/index.html       |   2 +-
 adr/0002-deny-cross-ns-by-default/index.html  |   2 +-
 adr/0003-workspace-blob-caching/index.html    |   2 +-
 .../branch-planner-getting-started/index.html |   2 +-
 .../index.html                                |   2 +-
 .../{branch-planner-overview => }/index.html  | 107 +++++++++++++-----
 getting_started/index.html                    |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 how_to/flux_receiver_and_alert/index.html     |   2 +-
 how_to/index.html                             |   4 +-
 how_to/interval_and_retryInterval/index.html  |   2 +-
 how_to/resource_deletion/index.html           |   2 +-
 .../index.html                                |   2 +-
 how_to/upgrade-tf-controller/index.html       |   2 +-
 how_to/use-cross-namespace-refs/index.html    |   2 +-
 index.html                                    |   4 +-
 search/search_index.json                      |   2 +-
 sitemap.xml.gz                                | Bin 127 -> 127 bytes
 tfctl/index.html                              |   2 +-
 use_tf_controller/index.html                  |   4 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 .../index.html                                |   2 +-
 use_tf_controller/with-azure/index.html       |   2 +-
 use_tf_controller/with-ipv6/index.html        |   2 +-
 .../with_AWS_EKS_IRSA/index.html              |   2 +-
 .../index.html                                |   2 +-
 .../with_Terraform_Enterprise/index.html      |   2 +-
 .../with_a_custom_backend/index.html          |   2 +-
 .../with_an_OCI_Artifact_as_Source/index.html |   2 +-
 .../with_drift_detection_disabled/index.html  |   2 +-
 .../with_external_webhooks/index.html         |   2 +-
 .../with_plan_only_mode/index.html            |   4 +-
 .../with_primitive_modules/index.html         |   2 +-
 .../index.html                                |   2 +-
 .../with_tf_runner_logging/index.html         |   2 +-
 .../index.html                                |   2 +-
 48 files changed, 131 insertions(+), 76 deletions(-)
 rename branch_planner/{branch-planner-overview => }/index.html (83%)

diff --git a/404.html b/404.html
index 4b99cb04..70f2044e 100644
--- a/404.html
+++ b/404.html
@@ -339,7 +339,7 @@
   
   
     <li class="md-nav__item">
-      <a href="/branch_planner/index.md" class="md-nav__link">
+      <a href="/branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/References/terraform/index.html b/References/terraform/index.html
index 27719bd8..e8f7e76e 100644
--- a/References/terraform/index.html
+++ b/References/terraform/index.html
@@ -343,7 +343,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/adr/0000-template/index.html b/adr/0000-template/index.html
index bc137742..0d221395 100644
--- a/adr/0000-template/index.html
+++ b/adr/0000-template/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/adr/0000-use-adrs-for-decisions/index.html b/adr/0000-use-adrs-for-decisions/index.html
index ddd735c0..d7ec62bc 100644
--- a/adr/0000-use-adrs-for-decisions/index.html
+++ b/adr/0000-use-adrs-for-decisions/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/adr/0001-pr-polling-workflow/index.html b/adr/0001-pr-polling-workflow/index.html
index 6bcbc7aa..31e2501d 100644
--- a/adr/0001-pr-polling-workflow/index.html
+++ b/adr/0001-pr-polling-workflow/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/adr/0002-deny-cross-ns-by-default/index.html b/adr/0002-deny-cross-ns-by-default/index.html
index 86df9038..24a57724 100644
--- a/adr/0002-deny-cross-ns-by-default/index.html
+++ b/adr/0002-deny-cross-ns-by-default/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/adr/0003-workspace-blob-caching/index.html b/adr/0003-workspace-blob-caching/index.html
index 3b66f031..35062748 100644
--- a/adr/0003-workspace-blob-caching/index.html
+++ b/adr/0003-workspace-blob-caching/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/branch_planner/branch-planner-getting-started/index.html b/branch_planner/branch-planner-getting-started/index.html
index 2d0a7751..2ea63848 100644
--- a/branch_planner/branch-planner-getting-started/index.html
+++ b/branch_planner/branch-planner-getting-started/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../index.md" class="md-nav__link">
+      <a href="../" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/branch_planner/branch-planner-tfc-integration-getting-started/index.html b/branch_planner/branch-planner-tfc-integration-getting-started/index.html
index 7586b9bd..fa5fbfe7 100644
--- a/branch_planner/branch-planner-tfc-integration-getting-started/index.html
+++ b/branch_planner/branch-planner-tfc-integration-getting-started/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../index.md" class="md-nav__link">
+      <a href="../" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/branch_planner/branch-planner-overview/index.html b/branch_planner/index.html
similarity index 83%
rename from branch_planner/branch-planner-overview/index.html
rename to branch_planner/index.html
index 70185c03..a091c641 100644
--- a/branch_planner/branch-planner-overview/index.html
+++ b/branch_planner/index.html
@@ -9,21 +9,25 @@
       
       
       
+        <link rel="prev" href="../use_tf_controller/">
       
       
-      <link rel="icon" href="../../assets/images/favicon.png">
+        <link rel="next" href="../how_to/">
+      
+      
+      <link rel="icon" href="../assets/images/favicon.png">
       <meta name="generator" content="mkdocs-1.5.3, mkdocs-material-9.4.14">
     
     
       
-        <title>Branch Planner Overview - Weave GitOps Terraform Controller</title>
+        <title>User Guide - Weave GitOps Terraform Controller</title>
       
     
     
-      <link rel="stylesheet" href="../../assets/stylesheets/main.fad675c6.min.css">
+      <link rel="stylesheet" href="../assets/stylesheets/main.fad675c6.min.css">
       
         
-        <link rel="stylesheet" href="../../assets/stylesheets/palette.356b1318.min.css">
+        <link rel="stylesheet" href="../assets/stylesheets/palette.356b1318.min.css">
       
       
 
@@ -42,7 +46,7 @@
       
     
     
-    <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
+    <script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
     
       
 
@@ -87,7 +91,7 @@
 
 <header class="md-header md-header--shadow" data-md-component="header">
   <nav class="md-header__inner md-grid" aria-label="Header">
-    <a href="../.." title="Weave GitOps Terraform Controller" class="md-header__button md-logo" aria-label="Weave GitOps Terraform Controller" data-md-component="logo">
+    <a href=".." title="Weave GitOps Terraform Controller" class="md-header__button md-logo" aria-label="Weave GitOps Terraform Controller" data-md-component="logo">
       
   
   <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg>
@@ -107,7 +111,7 @@
         <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
             
-              Branch Planner Overview
+              User Guide
             
           </span>
         </div>
@@ -217,7 +221,7 @@
 
 <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
   <label class="md-nav__title" for="__drawer">
-    <a href="../.." title="Weave GitOps Terraform Controller" class="md-nav__button md-logo" aria-label="Weave GitOps Terraform Controller" data-md-component="logo">
+    <a href=".." title="Weave GitOps Terraform Controller" class="md-nav__button md-logo" aria-label="Weave GitOps Terraform Controller" data-md-component="logo">
       
   
   <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg>
@@ -247,7 +251,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../.." class="md-nav__link">
+      <a href=".." class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -267,7 +271,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../getting_started/" class="md-nav__link">
+      <a href="../getting_started/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -287,7 +291,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../use_tf_controller/" class="md-nav__link">
+      <a href="../use_tf_controller/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -304,6 +308,8 @@
       
   
   
+    
+  
   
   
     
@@ -311,12 +317,12 @@
     
     
     
-    <li class="md-nav__item md-nav__item--nested">
+    <li class="md-nav__item md-nav__item--active md-nav__item--nested">
       
         
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked>
         
           
           <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
@@ -330,7 +336,7 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="true">
           <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Branch Planner
@@ -341,10 +347,30 @@
                 
   
   
+    
   
   
-    <li class="md-nav__item">
-      <a href="../index.md" class="md-nav__link">
+  
+    <li class="md-nav__item md-nav__item--active">
+      
+      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
+      
+      
+        
+      
+      
+        <label class="md-nav__link md-nav__link--active" for="__toc">
+          
+  
+  <span class="md-ellipsis">
+    User Guide
+  </span>
+  
+
+          <span class="md-nav__icon md-icon"></span>
+        </label>
+      
+      <a href="./" class="md-nav__link md-nav__link--active">
         
   
   <span class="md-ellipsis">
@@ -353,6 +379,35 @@
   
 
       </a>
+      
+        
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+  
+  
+  
+    
+  
+  
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#replan-commands" class="md-nav__link">
+    <span class="md-ellipsis">
+      Replan commands
+    </span>
+  </a>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+      
     </li>
   
 
@@ -365,7 +420,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../getting-started.md" class="md-nav__link">
+      <a href="getting-started.md" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -386,7 +441,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../least-required-permissions.md" class="md-nav__link">
+      <a href="least-required-permissions.md" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -407,7 +462,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../tfc-integration.md" class="md-nav__link">
+      <a href="tfc-integration.md" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -435,7 +490,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../how_to/" class="md-nav__link">
+      <a href="../how_to/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -455,7 +510,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../References/terraform/" class="md-nav__link">
+      <a href="../References/terraform/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -475,7 +530,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../tfctl/" class="md-nav__link">
+      <a href="../tfctl/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -544,10 +599,10 @@
 <h1 id="branch-planner-overview">Branch Planner Overview</h1>
 <p>The GitOps methodology streamlines infrastructure provisioning and management, using Git as the source of truth. The Branch Planner, a component of TF-Controller, aims to take this a step further by allowing developers and operations teams to plan Terraform configurations on a branch that's separate from the <code>main</code> branch. This makes it easier to review and understand the potential impact of your changes before you run <code>terraform apply</code>.</p>
 <p>The Branch Planner's most important feature is its seamless integration with the PR (Pull Request) user interface. When enabled through Helm values, it watches repositories that contain Terraform resources at regular intervals—checking their referenced Source, and polling for Pull Requests using GitHub's API and the provided token. When changes are proposed on a new branch, Branch Planner runs a plan in the cluster and displays the results directly as comments on your PR. Once you're satisfied with the results, you can merge your branch into the <code>main</code> branch to trigger the TF-Controller to reconcile the updated code.</p>
-<p><img alt="branch planner" src="../branch-planner.png" /></p>
+<p><img alt="branch planner" src="branch-planner.png" /></p>
 <h3 id="replan-commands">Replan commands</h3>
 <p>The Branch Planner also allows users to manually trigger the replan process. By simply commenting <code>!replan</code> under the PR, the Branch Planner will be instructed to generate a new plan and post it under the PR as a new comment.</p>
-<p>Now that you know what Branch Planner can do for you, follow the <a href="../branch-planner-getting-started/">guide to get started</a>.</p>
+<p>Now that you know what Branch Planner can do for you, follow the <a href="branch-planner-getting-started/">guide to get started</a>.</p>
 
 
 
@@ -586,10 +641,10 @@ <h3 id="replan-commands">Replan commands</h3>
     </div>
     
     
-    <script id="__config" type="application/json">{"base": "../..", "features": ["content.code.annotate", "content.code.copy"], "search": "../../assets/javascripts/workers/search.f886a092.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
+    <script id="__config" type="application/json">{"base": "..", "features": ["content.code.annotate", "content.code.copy"], "search": "../assets/javascripts/workers/search.f886a092.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
     
     
-      <script src="../../assets/javascripts/bundle.cd18aaf1.min.js"></script>
+      <script src="../assets/javascripts/bundle.cd18aaf1.min.js"></script>
       
     
   </body>
diff --git a/getting_started/index.html b/getting_started/index.html
index 6a0a1bb6..00a17766 100644
--- a/getting_started/index.html
+++ b/getting_started/index.html
@@ -481,7 +481,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../branch_planner/index.md" class="md-nav__link">
+      <a href="../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/backup_and_restore_a_Terraform_state/index.html b/how_to/backup_and_restore_a_Terraform_state/index.html
index d1fd092b..4982fc70 100644
--- a/how_to/backup_and_restore_a_Terraform_state/index.html
+++ b/how_to/backup_and_restore_a_Terraform_state/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/build-and-use-a-custom-runnner-image/index.html b/how_to/build-and-use-a-custom-runnner-image/index.html
index c4eeb8db..e119ff15 100644
--- a/how_to/build-and-use-a-custom-runnner-image/index.html
+++ b/how_to/build-and-use-a-custom-runnner-image/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/flux_receiver_and_alert/index.html b/how_to/flux_receiver_and_alert/index.html
index ba4d5c65..271b1ead 100644
--- a/how_to/flux_receiver_and_alert/index.html
+++ b/how_to/flux_receiver_and_alert/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/index.html b/how_to/index.html
index 8a6190ac..520a5557 100644
--- a/how_to/index.html
+++ b/how_to/index.html
@@ -9,7 +9,7 @@
       
       
       
-        <link rel="prev" href="../use_tf_controller/">
+        <link rel="prev" href="../branch_planner/">
       
       
         <link rel="next" href="../References/terraform/">
@@ -348,7 +348,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../branch_planner/index.md" class="md-nav__link">
+      <a href="../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/interval_and_retryInterval/index.html b/how_to/interval_and_retryInterval/index.html
index 79a86d96..c9613bd1 100644
--- a/how_to/interval_and_retryInterval/index.html
+++ b/how_to/interval_and_retryInterval/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/resource_deletion/index.html b/how_to/resource_deletion/index.html
index e873507f..4ab55308 100644
--- a/how_to/resource_deletion/index.html
+++ b/how_to/resource_deletion/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/troubleshooting_with_break_the_glass_mode/index.html b/how_to/troubleshooting_with_break_the_glass_mode/index.html
index 72a6b5c3..faf2b4fc 100644
--- a/how_to/troubleshooting_with_break_the_glass_mode/index.html
+++ b/how_to/troubleshooting_with_break_the_glass_mode/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/upgrade-tf-controller/index.html b/how_to/upgrade-tf-controller/index.html
index 50a965d4..d2645468 100644
--- a/how_to/upgrade-tf-controller/index.html
+++ b/how_to/upgrade-tf-controller/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/how_to/use-cross-namespace-refs/index.html b/how_to/use-cross-namespace-refs/index.html
index eeba078b..55263575 100644
--- a/how_to/use-cross-namespace-refs/index.html
+++ b/how_to/use-cross-namespace-refs/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/index.html b/index.html
index a6baf26c..dd8cb3d3 100644
--- a/index.html
+++ b/index.html
@@ -404,7 +404,7 @@
   
   
     <li class="md-nav__item">
-      <a href="branch_planner/index.md" class="md-nav__link">
+      <a href="branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -611,7 +611,7 @@
 
 
 <h1 id="overview">Overview</h1>
-<p>~&gt; <strong>BREAKING NEWS:</strong> The <strong>Technology Preview</strong> of the Branch Planner is now available! <a href="./branch_planner/index.md">Learn more</a> or Get started with the <a href="./branch_planner/getting-started.md">Branch Planner</a>.</p>
+<p>~&gt; <strong>BREAKING NEWS:</strong> The <strong>Technology Preview</strong> of the Branch Planner is now available! <a href="branch_planner/">Learn more</a> or Get started with the <a href="./branch_planner/getting-started.md">Branch Planner</a>.</p>
 <p>TF-controller is a reliable controller for <a href="https://fluxcd.io">Flux</a> to reconcile Terraform resources
 in the GitOps way.
 With the power of Flux together with Terraform, TF-controller allows you to GitOps-ify infrastructure,
diff --git a/search/search_index.json b/search/search_index.json
index e5ede063..d6ac51d5 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Overview","text":"<p>~&gt; BREAKING NEWS: The Technology Preview of the Branch Planner is now available! Learn more or Get started with the Branch Planner.</p> <p>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.</p> <p>\"At your own pace\" means you don't need to GitOps-ify everything at once.</p> <p>TF-controller offers many GitOps models:</p> <ol> <li>GitOps Automation Model: GitOps your Terraform resources from the provision steps to the enforcement steps, like a whole EKS cluster.</li> <li>Hybrid GitOps Automation Model: GitOps parts of your existing infrastructure resources. For example, you have an existing EKS cluster.      You can choose to GitOps only its nodegroup, or its security group.</li> <li>State Enforcement Model: You have a TFSTATE file, and you'd like to use GitOps enforce it, without changing anything else.</li> <li>Drift Detection Model: You have a TFSTATE file, and you'd like to use GitOps just for drift detection, so you can decide to do things later when a drift occurs.</li> </ol> <p>To get started, follow the getting started guide.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Multi-Tenancy: TF-controller supports multi-tenancy by running Terraform <code>plan</code> and <code>apply</code> inside Runner Pods.     When specifying <code>.metadata.namespace</code> and <code>.spec.serviceAccountName</code>, 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.</li> <li>GitOps Automation for Terraform: With setting <code>.spec.approvePlan=auto</code>, it allows a <code>Terraform</code> object     to be reconciled and act as the representation of your Terraform resources. The TF-controller uses the spec of     the <code>Terraform</code> object to perform <code>plan</code>, <code>apply</code> its associated Terraform resources. It then stores     the <code>TFSTATE</code> of the applied resources as a <code>Secret</code> inside the Kubernetes cluster. After <code>.spec.interval</code> 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.</li> <li>Drift detection: This feature is a part of the GitOps automation feature. The controller detects and fixes drift     for your infrastructures, based on the Terraform resources and their <code>TFSTATE</code>. This feature is available since v0.5.0.<ul> <li>Drift detection is enabled by default. You can use the field <code>.spec.disableDriftDetection</code> to disable this behaviour.   This feature is available since v0.7.0.</li> <li>The Drift detection only mode, without plan or apply steps, allows you to perform read-only drift detection.   This feature is available since v0.8.0.</li> </ul> </li> <li>Plan and Manual Approve: This feature allows you to separate the <code>plan</code>, out of the <code>apply</code> 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 <code>.spec.approvePlan</code>, 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.</li> <li>First-class YAML-based Terraform: The <code>Terraform</code> 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 <code>aws_iam_role</code>, or <code>aws_iam_policy</code>.     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.</li> <li>GitOps Dependency for Terraform: The <code>Terraform</code> object in v0.13.0+ allows you to specify a list of <code>Terraform</code> objects     that it depends on. The controller will wait for the dependencies to be ready before it starts to reconcile the     <code>Terraform</code> 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 <code>.spec.retryInterval</code> (a small value like <code>20s</code>) to control      the retry interval when using this feature. This feature is available since v0.13.0.</li> </ul>"},{"location":"#support-matrix","title":"Support Matrix","text":"Version Terraform Source Controller Flux v2 v0.15 v1.3.9 v1.0.x v2.0.x v0.14 v1.3.9 v0.31.0 v0.41.x v0.13 v1.3.1 v0.31.0 v0.36.x v0.12 v1.1.9 v0.26.1 v0.32.x"},{"location":"getting_started/","title":"Getting Started","text":""},{"location":"getting_started/#preflight-checks","title":"Preflight Checks","text":"<p>Here are the requirements you need to set up before you start:</p> <ol> <li>For Terraform Controller v0.15+, it requires Flux v2.0 or later (not only the CLI, but also the controllers on the cluster). If you are not sure about the Flux version on your cluster, please re-bootstrap your cluster.</li> <li>For Terraform Controller v0.13 and v0.14, Flux 2 v0.32 - v0.41 (of course, not only the CLI, but also the controllers on the cluster).</li> <li>TF-controller uses the Controller/Runner architecture. The Controller acts as a client, and talks to each Runner's Pod via gRPC. Please make sure <ol> <li>Each Runner's Pod in each Namespace is allowed to open, and serve at port 30000 (the gRPC port of a Runner), and the Controller can connect to it.</li> <li>The Controller needs to download tar.gz BLOBs from the Source controller via port 80.</li> <li>The Controller needs to post the events to the Notification controller via port 80.</li> </ol> </li> </ol>"},{"location":"getting_started/#installation","title":"Installation","text":"<p>Before using TF-controller, you have to install Flux by using either <code>flux install</code> or <code>flux bootstrap</code> 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:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\n</code></pre> <p>For the most recent release candidate of TF-controller, please use rc.yaml.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml\n</code></pre>"},{"location":"getting_started/#installation-on-gke","title":"Installation on GKE","text":"<p>As of September 2023, GKE Autopilot clusters will use Cloud DNS for internal DNS resolution. This means that the default DNS resolution method used by TF-controller will not work. To use TF-controller on GKE Autopilot, you must set flag <code>--use-pod-subdomain-resolution=true</code> on the TF-controller deployment. This flag can be set by adding the following to the TF-controller HelmRelease:</p> <pre><code>spec:\n  values:\n    usePodSubdomainResolution: true\n    runner:\n      allowedNamespaces:\n      - flux-system\n      - dev-team\n</code></pre> <p>Enabling this value will cause TF-controller to use the Pod's subdomain for DNS resolution instead of the default Pod resolution method. Pod's subdomain resolution requires a Service to be created for the Pod. The HelmRelease above will create a Service named <code>tf-runner</code> in each namespace specified by the <code>runner.allowedNamespaces</code> value.</p> <p>We have provided a HelmRelease to install TF-controller on GKE Autopilot with Pod's subdomain resolution enabled here.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc-gke.yaml\n</code></pre> <p>Tested with GKE Autopilot v1.27.3-gke.100.</p>"},{"location":"getting_started/#with-branch-planner","title":"With Branch Planner","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/release.yaml\n</code></pre> <p>For the most recent release candidate of TF-controller with Branch Planner, please use branch_planner/rc.yaml.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/rc.yaml\n</code></pre> <p>For more details about the Branch Planner, please visit the Branch Planner documentation.</p>"},{"location":"getting_started/#manual-installation","title":"Manual installation","text":"<p>With Helm by:</p> <pre><code># 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\n</code></pre> <p>For details on configurable parameters of the TF-controller chart, please see chart readme.</p> <p>Alternatively, you can install TF-controller via <code>kubectl</code>:</p> <pre><code>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\n</code></pre>"},{"location":"getting_started/#quick-start","title":"Quick start","text":"<p>Here's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.</p>"},{"location":"getting_started/#define-source","title":"Define source","text":"<p>First, we need to define a Source controller's source (<code>GitRepository</code>, <code>Bucket</code>, <code>OCIRepository</code>), for example:</p> <pre><code>apiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  interval: 30s\n  url: https://github.com/tf-controller/helloworld\n  ref:\n    branch: main\n</code></pre>"},{"location":"getting_started/#the-gitops-automation-mode","title":"The GitOps Automation mode","text":"<p>The GitOps automation mode could be enabled by setting <code>.spec.approvePlan=auto</code>. In this mode, Terraform resources will be planned, and automatically applied for you.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  interval: 1m\n  approvePlan: auto\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre> <p>For a full list of features and how to use them, please follow the Use TF-controller guide.</p>"},{"location":"getting_started/#other-examples","title":"Other Examples","text":"<ul> <li>A Terraform GitOps with Flux to automatically reconcile your AWS IAM Policies.</li> <li>GitOps an existing EKS cluster, by partially import its nodegroup and manage it with TF-controller: An EKS scaling example.</li> </ul>"},{"location":"tfctl/","title":"tfctl","text":"<p><code>tfctl</code> is a command-line utility to help with tf-controller operations.</p>"},{"location":"tfctl/#installation","title":"Installation","text":"<p>To install <code>tfctl</code> via Homebrew, run the following command:</p> <pre><code>brew install weaveworks/tap/tfctl\n</code></pre> <p>You can also download the <code>tfctl</code> binary via the GitHub releases page: https://github.com/weaveworks/tf-controller/releases.</p> <pre><code>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.\n</code></pre>"},{"location":"References/terraform/","title":"API References","text":"Terraform API reference <p>Packages:</p> <ul> <li> infra.contrib.fluxcd.io/v1alpha2 </li> </ul>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2","title":"infra.contrib.fluxcd.io/v1alpha2","text":"<p>Resource Types:</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigSpec","title":"BackendConfigSpec","text":"<p> (Appears on: TerraformSpec) </p> <p>BackendConfigSpec is for specifying configuration for Terraform\u2019s Kubernetes backend</p> Field Description <code>disable</code>  bool  (Optional) <p>Disable is to completely disable the backend configuration.</p> <code>secretSuffix</code>  string  (Optional) <code>inClusterConfig</code>  bool  (Optional) <code>customConfiguration</code>  string  (Optional) <code>configPath</code>  string  (Optional) <code>labels</code>  map[string]string  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigsReference","title":"BackendConfigsReference","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>kind</code>  string  <p>Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).</p> <code>name</code>  string  <p>Name of the configs referent. Should reside in the same namespace as the referring resource.</p> <code>keys</code>  []string  (Optional) <p>Keys is the data key where a specific value can be found at. Defaults to all keys.</p> <code>optional</code>  bool  (Optional) <p>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.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BranchPlanner","title":"BranchPlanner","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>enablePathScope</code>  bool  (Optional) <p>EnablePathScope specifies if the Branch Planner should or shouldn\u2019t check if a Pull Request has changes under <code>.spec.path</code>. If enabled extra resources will be created only if there are any changes in terraform files.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudSpec","title":"CloudSpec","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>organization</code>  string  <code>workspaces</code>  CloudWorkspacesSpec  <code>hostname</code>  string  (Optional) <code>token</code>  string  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudWorkspacesSpec","title":"CloudWorkspacesSpec","text":"<p> (Appears on: CloudSpec) </p> Field Description <code>name</code>  string  (Optional) <code>tags</code>  []string  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CrossNamespaceSourceReference","title":"CrossNamespaceSourceReference","text":"<p> (Appears on: TerraformSpec) </p> <p>CrossNamespaceSourceReference contains enough information to let you locate the typed Kubernetes resource object at cluster level.</p> Field Description <code>apiVersion</code>  string  (Optional) <p>API version of the referent.</p> <code>kind</code>  string  <p>Kind of the referent.</p> <code>name</code>  string  <p>Name of the referent.</p> <code>namespace</code>  string  (Optional) <p>Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.FileMapping","title":"FileMapping","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>secretRef</code>  github.com/fluxcd/pkg/apis/meta.SecretKeyReference  <p>Reference to a Secret that contains the file content</p> <code>location</code>  string  <p>Location can be either user\u2019s home directory or the Terraform workspace</p> <code>path</code>  string  <p>Path of the file - relative to the \u201clocation\u201d</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ForceUnlockEnum","title":"ForceUnlockEnum (<code>string</code> alias)","text":"<p> (Appears on: TFStateSpec) </p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.HealthCheck","title":"HealthCheck","text":"<p> (Appears on: TerraformSpec) </p> <p>HealthCheck contains configuration needed to perform a health check after terraform is applied.</p> Field Description <code>name</code>  string  <p>Name of the health check.</p> <code>type</code>  string  <p>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.</p> <code>url</code>  string  (Optional) <p>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}}).</p> <code>address</code>  string  (Optional) <p>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}}).</p> <code>timeout</code>  Kubernetes meta/v1.Duration  (Optional) <p>The timeout period at which the connection should timeout if unable to complete the request. When not specified, default 20s timeout is used.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.LockStatus","title":"LockStatus","text":"<p> (Appears on: TerraformStatus) </p> <p>LockStatus defines the observed state of a Terraform State Lock</p> Field Description <code>lastApplied</code>  string  (Optional) <code>pending</code>  string  (Optional) <p>Pending holds the identifier of the Lock Holder to be used with Force Unlock</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.PlanStatus","title":"PlanStatus","text":"<p> (Appears on: TerraformStatus) </p> Field Description <code>lastApplied</code>  string  (Optional) <code>pending</code>  string  (Optional) <code>isDestroyPlan</code>  bool  (Optional) <code>isDriftDetectionPlan</code>  bool  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ReadInputsFromSecretSpec","title":"ReadInputsFromSecretSpec","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>name</code>  string  <code>as</code>  string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Remediation","title":"Remediation","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>retries</code>  int64  (Optional) <p>Retries is the number of retries that should be attempted on failures before bailing. Defaults to \u20180\u2019, a negative integer denotes unlimited retries.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceInventory","title":"ResourceInventory","text":"<p> (Appears on: TerraformStatus) </p> <p>ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.</p> Field Description <code>entries</code>  []ResourceRef  <p>Entries of Kubernetes resource object references.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceRef","title":"ResourceRef","text":"<p> (Appears on: ResourceInventory) </p> <p>ResourceRef contains the information necessary to locate a resource within a cluster.</p> Field Description <code>n</code>  string  <p>Terraform resource\u2019s name.</p> <code>t</code>  string  <p>Type is Terraform resource\u2019s type</p> <code>id</code>  string  <p>ID is the resource identifier. This is cloud-specific. For example, ARN is an ID on AWS.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodMetadata","title":"RunnerPodMetadata","text":"<p> (Appears on: RunnerPodTemplate) </p> Field Description <code>labels</code>  map[string]string  (Optional) <p>Labels to add to the runner pod</p> <code>annotations</code>  map[string]string  (Optional) <p>Annotations to add to the runner pod</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodSpec","title":"RunnerPodSpec","text":"<p> (Appears on: RunnerPodTemplate) </p> Field Description <code>image</code>  string  (Optional) <p>Runner pod image to use other than default</p> <code>envFrom</code>  []Kubernetes core/v1.EnvFromSource  (Optional) <p>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.</p> <code>env</code>  []Kubernetes core/v1.EnvVar  (Optional) <p>List of environment variables to set in the container. Cannot be updated.</p> <code>nodeSelector</code>  map[string]string  (Optional) <p>Set the NodeSelector for the Runner Pod</p> <code>affinity</code>  Kubernetes core/v1.Affinity  (Optional) <p>Set the Affinity for the Runner Pod</p> <code>tolerations</code>  []Kubernetes core/v1.Toleration  (Optional) <p>Set the Tolerations for the Runner Pod</p> <code>volumeMounts</code>  []Kubernetes core/v1.VolumeMount  (Optional) <p>Set Volume Mounts for the Runner Pod</p> <code>volumes</code>  []Kubernetes core/v1.Volume  (Optional) <p>Set Volumes for the Runner Pod</p> <code>initContainers</code>  []Kubernetes core/v1.Container  (Optional) <p>Set up Init Containers for the Runner</p> <code>hostAliases</code>  []Kubernetes core/v1.HostAlias  (Optional) <p>Set host aliases for the Runner Pod</p> <code>priorityClassName</code>  string  (Optional) <p>Set PriorityClassName for the Runner Pod container</p> <code>securityContext</code>  Kubernetes core/v1.SecurityContext  (Optional) <p>Set SecurityContext for the Runner Pod container</p> <code>resources</code>  Kubernetes core/v1.ResourceRequirements  (Optional) <p>Set Resources for the Runner Pod container</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodTemplate","title":"RunnerPodTemplate","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>metadata</code>  RunnerPodMetadata  (Optional) <code>spec</code>  RunnerPodSpec  (Optional) <code>image</code>  string  (Optional) <p>Runner pod image to use other than default</p> <code>envFrom</code>  []Kubernetes core/v1.EnvFromSource  (Optional) <p>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.</p> <code>env</code>  []Kubernetes core/v1.EnvVar  (Optional) <p>List of environment variables to set in the container. Cannot be updated.</p> <code>nodeSelector</code>  map[string]string  (Optional) <p>Set the NodeSelector for the Runner Pod</p> <code>affinity</code>  Kubernetes core/v1.Affinity  (Optional) <p>Set the Affinity for the Runner Pod</p> <code>tolerations</code>  []Kubernetes core/v1.Toleration  (Optional) <p>Set the Tolerations for the Runner Pod</p> <code>volumeMounts</code>  []Kubernetes core/v1.VolumeMount  (Optional) <p>Set Volume Mounts for the Runner Pod</p> <code>volumes</code>  []Kubernetes core/v1.Volume  (Optional) <p>Set Volumes for the Runner Pod</p> <code>initContainers</code>  []Kubernetes core/v1.Container  (Optional) <p>Set up Init Containers for the Runner</p> <code>hostAliases</code>  []Kubernetes core/v1.HostAlias  (Optional) <p>Set host aliases for the Runner Pod</p> <code>priorityClassName</code>  string  (Optional) <p>Set PriorityClassName for the Runner Pod container</p> <code>securityContext</code>  Kubernetes core/v1.SecurityContext  (Optional) <p>Set SecurityContext for the Runner Pod container</p> <code>resources</code>  Kubernetes core/v1.ResourceRequirements  (Optional) <p>Set Resources for the Runner Pod container</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TFStateSpec","title":"TFStateSpec","text":"<p> (Appears on: TerraformSpec) </p> <p>TFStateSpec allows the user to set ForceUnlock</p> Field Description <code>forceUnlock</code>  ForceUnlockEnum  (Optional) <p>ForceUnlock a Terraform state if it has become locked for any reason. Defaults to <code>no</code>.</p> <p>This is an Enum and has the expected values of:</p> <ul> <li>auto</li> <li>yes</li> <li>no</li> </ul> <p>WARNING: Only use <code>auto</code> 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.</p> <code>lockIdentifier</code>  string  (Optional) <p>LockIdentifier holds the Identifier required by Terraform to unlock the state if it ever gets into a locked state.</p> <p>You\u2019ll need to put the Lock Identifier in here while setting ForceUnlock to either <code>yes</code> or <code>auto</code>.</p> <p>Leave this empty to do nothing, set this to the value of the <code>Lock Info: ID: [value]</code>, e.g. <code>f2ab685b-f84d-ac0b-a125-378a22877e8d</code>, to force unlock the state.</p> <code>lockTimeout</code>  Kubernetes meta/v1.Duration  (Optional) <p>LockTimeout is a Duration string that instructs Terraform to retry acquiring a lock for the specified period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as <code>3s</code> for three seconds.</p> <p>Defaults to <code>0s</code> which will behave as though <code>LockTimeout</code> was not set</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Terraform","title":"Terraform","text":"<p>Terraform is the Schema for the terraforms API</p> Field Description <code>metadata</code>  Kubernetes meta/v1.ObjectMeta   Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.  <code>spec</code>  TerraformSpec  <code>approvePlan</code>  string  (Optional) <p>ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.</p> <code>destroy</code>  bool  (Optional) <p>Destroy produces a destroy plan. Applying the plan will destroy all resources.</p> <code>backendConfig</code>  BackendConfigSpec  (Optional) <code>backendConfigsFrom</code>  []BackendConfigsReference  (Optional) <code>cloud</code>  CloudSpec  (Optional) <code>workspace</code>  string  (Optional) <code>vars</code>  []Variable  (Optional) <p>List of input variables to set for the Terraform program.</p> <code>varsFrom</code>  []VarsReference  (Optional) <p>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.</p> <code>values</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>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.</p> <code>fileMappings</code>  []FileMapping  (Optional) <p>List of all configuration files to be created in initialization.</p> <code>interval</code>  Kubernetes meta/v1.Duration  <p>The interval at which to reconcile the Terraform.</p> <code>retryInterval</code>  Kubernetes meta/v1.Duration  (Optional) <p>The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.</p> <code>path</code>  string  (Optional) <p>Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.</p> <code>sourceRef</code>  CrossNamespaceSourceReference  <p>SourceRef is the reference of the source where the Terraform files are stored.</p> <code>suspend</code>  bool  (Optional) <p>Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.</p> <code>force</code>  bool  (Optional) <p>Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.</p> <code>readInputsFromSecrets</code>  []ReadInputsFromSecretSpec  (Optional) <code>writeOutputsToSecret</code>  WriteOutputsToSecretSpec  (Optional) <p>A list of target secrets for the outputs to be written as.</p> <code>disableDriftDetection</code>  bool  (Optional) <p>Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.</p> <code>cliConfigSecretRef</code>  Kubernetes core/v1.SecretReference  (Optional) <code>healthChecks</code>  []HealthCheck  (Optional) <p>List of health checks to be performed.</p> <code>destroyResourcesOnDeletion</code>  bool  (Optional) <p>Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.</p> <code>serviceAccountName</code>  string  (Optional) <p>Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.</p> <code>alwaysCleanupRunnerPod</code>  bool  (Optional) <p>Clean the runner pod up after each reconciliation cycle</p> <code>runnerTerminationGracePeriodSeconds</code>  int64  (Optional) <p>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.</p> <code>refreshBeforeApply</code>  bool  (Optional) <p>RefreshBeforeApply forces refreshing of the state before the apply step.</p> <code>runnerPodTemplate</code>  RunnerPodTemplate  (Optional) <code>enableInventory</code>  bool  (Optional) <p>EnableInventory enables the object to store resource entries as the inventory for external use.</p> <code>tfstate</code>  TFStateSpec  (Optional) <code>targets</code>  []string  (Optional) <p>Targets specify the resource, module or collection of resources to target.</p> <code>parallelism</code>  int32  (Optional) <p>Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.</p> <code>storeReadablePlan</code>  string  (Optional) <p>StoreReadablePlan enables storing the plan in a readable format.</p> <code>webhooks</code>  []Webhook  (Optional) <code>dependsOn</code>  []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference  (Optional) <code>enterprise</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>Enterprise is the enterprise configuration placeholder.</p> <code>planOnly</code>  bool  (Optional) <p>PlanOnly specifies if the reconciliation should or should not stop at plan phase.</p> <code>breakTheGlass</code>  bool  (Optional) <p>BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.</p> <code>branchPlanner</code>  BranchPlanner  (Optional) <p>BranchPlanner configuration.</p> <code>remediation</code>  Remediation  (Optional) <p>Remediation specifies what the controller should do when reconciliation fails. The default is to not perform any action.</p> <code>status</code>  TerraformStatus"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformSpec","title":"TerraformSpec","text":"<p> (Appears on: Terraform) </p> <p>TerraformSpec defines the desired state of Terraform</p> Field Description <code>approvePlan</code>  string  (Optional) <p>ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.</p> <code>destroy</code>  bool  (Optional) <p>Destroy produces a destroy plan. Applying the plan will destroy all resources.</p> <code>backendConfig</code>  BackendConfigSpec  (Optional) <code>backendConfigsFrom</code>  []BackendConfigsReference  (Optional) <code>cloud</code>  CloudSpec  (Optional) <code>workspace</code>  string  (Optional) <code>vars</code>  []Variable  (Optional) <p>List of input variables to set for the Terraform program.</p> <code>varsFrom</code>  []VarsReference  (Optional) <p>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.</p> <code>values</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>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.</p> <code>fileMappings</code>  []FileMapping  (Optional) <p>List of all configuration files to be created in initialization.</p> <code>interval</code>  Kubernetes meta/v1.Duration  <p>The interval at which to reconcile the Terraform.</p> <code>retryInterval</code>  Kubernetes meta/v1.Duration  (Optional) <p>The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.</p> <code>path</code>  string  (Optional) <p>Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.</p> <code>sourceRef</code>  CrossNamespaceSourceReference  <p>SourceRef is the reference of the source where the Terraform files are stored.</p> <code>suspend</code>  bool  (Optional) <p>Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.</p> <code>force</code>  bool  (Optional) <p>Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.</p> <code>readInputsFromSecrets</code>  []ReadInputsFromSecretSpec  (Optional) <code>writeOutputsToSecret</code>  WriteOutputsToSecretSpec  (Optional) <p>A list of target secrets for the outputs to be written as.</p> <code>disableDriftDetection</code>  bool  (Optional) <p>Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.</p> <code>cliConfigSecretRef</code>  Kubernetes core/v1.SecretReference  (Optional) <code>healthChecks</code>  []HealthCheck  (Optional) <p>List of health checks to be performed.</p> <code>destroyResourcesOnDeletion</code>  bool  (Optional) <p>Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.</p> <code>serviceAccountName</code>  string  (Optional) <p>Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.</p> <code>alwaysCleanupRunnerPod</code>  bool  (Optional) <p>Clean the runner pod up after each reconciliation cycle</p> <code>runnerTerminationGracePeriodSeconds</code>  int64  (Optional) <p>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.</p> <code>refreshBeforeApply</code>  bool  (Optional) <p>RefreshBeforeApply forces refreshing of the state before the apply step.</p> <code>runnerPodTemplate</code>  RunnerPodTemplate  (Optional) <code>enableInventory</code>  bool  (Optional) <p>EnableInventory enables the object to store resource entries as the inventory for external use.</p> <code>tfstate</code>  TFStateSpec  (Optional) <code>targets</code>  []string  (Optional) <p>Targets specify the resource, module or collection of resources to target.</p> <code>parallelism</code>  int32  (Optional) <p>Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.</p> <code>storeReadablePlan</code>  string  (Optional) <p>StoreReadablePlan enables storing the plan in a readable format.</p> <code>webhooks</code>  []Webhook  (Optional) <code>dependsOn</code>  []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference  (Optional) <code>enterprise</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>Enterprise is the enterprise configuration placeholder.</p> <code>planOnly</code>  bool  (Optional) <p>PlanOnly specifies if the reconciliation should or should not stop at plan phase.</p> <code>breakTheGlass</code>  bool  (Optional) <p>BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.</p> <code>branchPlanner</code>  BranchPlanner  (Optional) <p>BranchPlanner configuration.</p> <code>remediation</code>  Remediation  (Optional) <p>Remediation specifies what the controller should do when reconciliation fails. The default is to not perform any action.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformStatus","title":"TerraformStatus","text":"<p> (Appears on: Terraform) </p> <p>TerraformStatus defines the observed state of Terraform</p> Field Description <code>ReconcileRequestStatus</code>  github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus  <p> (Members of <code>ReconcileRequestStatus</code> are embedded into this type.) </p> <code>observedGeneration</code>  int64  (Optional) <p>ObservedGeneration is the last reconciled generation.</p> <code>conditions</code>  []Kubernetes meta/v1.Condition  (Optional) <code>lastAppliedRevision</code>  string  (Optional) <p>The last successfully applied revision. The revision format for Git sources is /. <code>lastAttemptedRevision</code>  string  (Optional) <p>LastAttemptedRevision is the revision of the last reconciliation attempt.</p> <code>lastPlannedRevision</code>  string  (Optional) <p>LastPlannedRevision is the revision used by the last planning process. The result could be either no plan change or a new plan generated.</p> <code>lastPlanAt</code>  Kubernetes meta/v1.Time  (Optional) <p>LastPlanAt is the time when the last terraform plan was performed</p> <code>lastDriftDetectedAt</code>  Kubernetes meta/v1.Time  (Optional) <p>LastDriftDetectedAt is the time when the last drift was detected</p> <code>lastAppliedByDriftDetectionAt</code>  Kubernetes meta/v1.Time  (Optional) <p>LastAppliedByDriftDetectionAt is the time when the last drift was detected and terraform apply was performed as a result</p> <code>availableOutputs</code>  []string  (Optional) <code>plan</code>  PlanStatus  (Optional) <code>inventory</code>  ResourceInventory  (Optional) <p>Inventory contains the list of Terraform resource object references that have been successfully applied.</p> <code>lock</code>  LockStatus  (Optional) <code>reconciliationFailures</code>  int64  (Optional) <p>ReconciliationFailures is the number of reconciliation failures since the last success or update.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Variable","title":"Variable","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>name</code>  string  <p>Name is the name of the variable</p> <code>value</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <code>valueFrom</code>  Kubernetes core/v1.EnvVarSource  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.VarsReference","title":"VarsReference","text":"<p> (Appears on: TerraformSpec) </p> <p>VarsReference contain a reference of a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey.</p> Field Description <code>kind</code>  string  <p>Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).</p> <code>name</code>  string  <p>Name of the values referent. Should reside in the same namespace as the referring resource.</p> <code>varsKeys</code>  []string  (Optional) <p>VarsKeys is the data key at which a specific value can be found. Defaults to all keys.</p> <code>optional</code>  bool  (Optional) <p>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.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Webhook","title":"Webhook","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>stage</code>  string  <code>enabled</code>  bool  (Optional) <code>url</code>  string  <code>payloadType</code>  string  (Optional) <code>errorMessageTemplate</code>  string  (Optional) <code>testExpression</code>  string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.WriteOutputsToSecretSpec","title":"WriteOutputsToSecretSpec","text":"<p> (Appears on: TerraformSpec) </p> <p>WriteOutputsToSecretSpec defines where to store outputs, and which outputs to be stored.</p> Field Description <code>name</code>  string  <p>Name is the name of the Secret to be written</p> <code>labels</code>  map[string]string  (Optional) <p>Labels to add to the outputted secret</p> <code>annotations</code>  map[string]string  (Optional) <p>Annotations to add to the outputted secret</p> <code>outputs</code>  []string  (Optional) <p>Outputs contain the selected names of outputs to be written to the secret. Empty array means writing all outputs, which is default.</p> <p>This page was automatically generated with <code>gen-crd-api-reference-docs</code></p>"},{"location":"adr/0000-template/","title":"0. Title","text":"<ul> <li>Status: [proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005] </li> <li>Date: 2020-10-29 [YYY-MM-DD - date of the decision] </li> <li>Authors: [list of GitHub handles for the authors]</li> <li>Deciders: [list of GitHub handles for those that made the decision]  </li> </ul>"},{"location":"adr/0000-template/#context","title":"Context","text":""},{"location":"adr/0000-template/#decision","title":"Decision","text":""},{"location":"adr/0000-template/#consequences","title":"Consequences","text":""},{"location":"adr/0000-use-adrs-for-decisions/","title":"1. Use ADRs to record decisions","text":"<ul> <li>Status: proposed</li> <li>Date: 2023-06-20</li> <li>Authors: @yitsushi</li> <li>Deciders: @yitsushi @chanwit @yiannistri</li> </ul>"},{"location":"adr/0000-use-adrs-for-decisions/#context","title":"Context","text":"<p>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.</p>"},{"location":"adr/0000-use-adrs-for-decisions/#decision","title":"Decision","text":"<p>The project will use Architectural Decision Records (ADR) to record decisions that are made outside of a proposal.</p> <p>A template has been created based on prior work:</p> <ul> <li>https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions</li> <li>https://adr.github.io/madr/</li> </ul>"},{"location":"adr/0000-use-adrs-for-decisions/#consequences","title":"Consequences","text":"<p>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.</p>"},{"location":"adr/0001-pr-polling-workflow/","title":"1. Pull Request Polling","text":"<ul> <li>Status: proposed</li> <li>Date: 2023-06-20 </li> <li>Authors: @yitsushi</li> <li>Deciders: @yitsushi @chanwit @yiannistri</li> </ul>"},{"location":"adr/0001-pr-polling-workflow/#context","title":"Context","text":"<p>To detect pull request changes, we can use webhooks or polling using GitHub's API.</p>"},{"location":"adr/0001-pr-polling-workflow/#decision","title":"Decision","text":"<p>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.</p> <p>The Branch-Based Planner has two components:</p> <ol> <li>Polling Server: Detect Pull Request changes and manage Teraform resource    state.</li> <li>Informer: Make a comment when new plan output is available.</li> </ol>"},{"location":"adr/0001-pr-polling-workflow/#consequences","title":"Consequences","text":"<p>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.</p>"},{"location":"adr/0002-deny-cross-ns-by-default/","title":"2. Deny cross-namespace refs by default","text":"<ul> <li>Status: [ proposed | rejected | accepted | deprecated ]</li> <li>Date: 2023-07-18</li> <li>Authors: @squaremo</li> <li>Deciders: [list of GitHub handles for those that made the decision]</li> </ul>"},{"location":"adr/0002-deny-cross-ns-by-default/#context","title":"Context","text":"<p>Like Flux, the tf-controller API has a handful of places where it accepts cross-namespace references.</p> <ul> <li><code>Terraform.spec.sourceRef</code> -- refers to the Flux source object with    the Terraform program</li> <li><code>Terraform.spec.dependsOn[]</code> -- refers to other objects that must    be ready before this object can be run</li> <li><code>.data.resources[]</code> -- in the config struct used by the branch    planner</li> </ul> <p>In general in Kubernetes, references to objects in other namespaces are frowned upon, because</p> <ul> <li>they break namespace isolation assurances; and,</li> <li>they encourage the proliferation of permissions.</li> </ul> <p>Both of these effects make a system less secure.</p> <p>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.</p>"},{"location":"adr/0002-deny-cross-ns-by-default/#decision","title":"Decision","text":"<p>Deny cross-namespace references by default, but allow them to be enabled with a flag.</p> <p>So that the default value means the right thing, the flag name must be <code>enable-cross-namespace-refs</code>, and the default <code>false</code>. To avoid confusion when people try to use the Flux version of this flag <code>--disable-cross-namespace-refs</code>, it should be supported too, but only respected if supplied.</p>"},{"location":"adr/0002-deny-cross-ns-by-default/#consequences","title":"Consequences","text":"<p>The changed default will break deployments that rely on cross-namespace refs, but they are easily fixed with the flag.</p> <p>New deployments will be more secure, by default.</p>"},{"location":"adr/0003-workspace-blob-caching/","title":"3. Workspace BLOB Caching","text":"<ul> <li>Status: [ proposed | rejected | accepted | deprecated ]</li> <li>Date: 2023-09-20 </li> <li>Authors: @chanwit</li> <li>Deciders: TBD </li> </ul>"},{"location":"adr/0003-workspace-blob-caching/#context","title":"Context","text":"<p>The TF-Controller currently faces challenges related to the deletion of Terraform resources. These problems span across three categories:</p> <ol> <li>Single object deletion,</li> <li>Resources with dependencies deletion, and</li> <li>Namespace deletion.</li> </ol> <p>These problems must be fixed in the above order as (2) and (3) require single object deletion to be resolved first.</p> <p>Deleting a single TF object can sometimes be obstructed because it's tied to other resources like Source objects, Secrets, and ConfigMaps. If we try to remove it without deleting these resources, the TF object gets stuck in an inconsistent state, making it harder for users to manage their infrastructure smoothly. Therefore, the TF-Controller is being enhanced to address this problem more efficiently, using the contents of generated Workspace BLOBs. Each BLOB contains all necessary information from the associated Source, Secrets, and ConfigMaps to ensure that TF-Controller finalization procedures can delete objects correctly.</p> <p>Currently, the TF-Controller downloads a Source BLOB and pushes it to a tf-runner. The tf-runner processes this BLOB to create a Workspace file system. It generates a backend configuration file, variable files, and other necessary files for the Workspace file system, using data from associated Secrets and ConfigMaps. This newly created Workspace file system is then compressed, sent back to the TF-Controller, and stored as a Workspace BLOB in the controller's storage. A caching mechanism for these BLOBs is essential to fixing the single TF object deletion process.</p>"},{"location":"adr/0003-workspace-blob-caching/#decision","title":"Decision","text":"<ol> <li>BLOB Creation and Storage</li> <li>A gRPC function named <code>CreateWorkspaceBlob</code> will be invoked by the TF-Controller       to tell tf-runner to compress the Workspace file system into a tar.gz BLOB, which is then retrieved back to the controller.</li> <li>The caching mechanism will be executed right before the Terraform Initialization step, ensuring that the latest and most relevant data is used.</li> <li>Each Workspace Blob will be cached on the TF-Controller's local disk, using the UUID of the Terraform object as the filename,<code>${uuid}.tar.gz</code>.</li> <li>To reduce the risk of unauthorized access to the cache entries, and cache collisions, the cache file will be deleted after the finalization process is complete.</li> <li>Persistence </li> <li>The persistence mechanism used by the Source Controller will be adopted for the TF-Controller's persistence volume.</li> <li>BLOB Encryption</li> <li>The encryption and decryption of the BLOBs will be tasked to the runner, with the controller solely responsible for storing encrypted BLOBs.</li> <li>Each namespace will require a service account, preferably named \"tf-runner\".</li> <li>The token of this service account, which is natively supported by Kubernetes, will serve as the most appropriate encryption key because it's stored in a Secret, access to which can be controlled by RBAC. Storing it in a Secret also allows the key to be rotated.</li> <li>Security Measures (Based on STRIDE Analysis)</li> <li>Spoofing: Implement Kubernetes RBAC for access restrictions and use mutual authentication for gRPC communications.</li> <li>Tampering: Use checksums for integrity verification and 0600 permissions to write-protect local disk storage.</li> <li>Repudiation: Ensure strong logging and auditing mechanisms for tracking activities.</li> <li>Information Disclosure: Utilize robust encryption algorithms, rotate encryption keys periodically, and secure service account tokens.</li> <li>Denial of Service: Monitor storage space and automate cleanup processes.</li> <li>Elevation of Privilege: Minimize permissions associated with service account tokens.</li> <li>First MVP &amp; Future Planning</li> <li>For the initial MVP, the default pod local volume will be used.</li> <li>Since a controller restart will erase the BLOB cache, consideration for using persistent volumes should be made for subsequent versions.</li> </ol>"},{"location":"adr/0003-workspace-blob-caching/#consequence","title":"Consequence","text":"<ol> <li>With the implementation of this architecture:</li> <li>Single object deletions will succeed in circumstances in which they previously got stuck.</li> <li>Security measures will ensure the safety of the new Workspace BLOB storage mechanics, minimizing potential risks.</li> <li>Using the default pod local volume might limit storage capabilities and risk data loss upon controller restart. This warrants the need for considering persistent volumes in future versions.</li> <li>Encryption and security measures will demand regular maintenance and monitoring, especially concerning key rotations and integrity checks.</li> </ol>"},{"location":"branch_planner/branch-planner-getting-started/","title":"Getting Started With Branch Planner","text":""},{"location":"branch_planner/branch-planner-getting-started/#prerequisites","title":"Prerequisites","text":"<ol> <li>Flux is installed on the cluster.</li> <li>A GitHub API token. For public repositories, it's sufficient to enable <code>Public Repositories</code> without any additional permissions. For private repositories, you need the following permissions:</li> <li><code>Pull requests</code> with Read-Write access. This is required to check Pull Request   changes, list comments, and create or update comments.</li> <li><code>Metadata</code> with Read-only access. This is automatically marked as \"mandatory\"   because of the permissions listed above.</li> <li>General knowledge about TF-Controller (see docs).</li> </ol>"},{"location":"branch_planner/branch-planner-getting-started/#quick-start","title":"Quick Start","text":"<p>This section describes how to install Branch Planner using a HelmRelease object in the <code>flux-system</code> namespace with minimum configuration on a KinD cluster.</p> <ol> <li> <p>Create a KinD cluster. <pre><code>kind create cluster\n</code></pre></p> </li> <li> <p>Install Flux. Make sure you have the latest version of Flux (v2 GA).</p> </li> </ol> <pre><code>flux install\n</code></pre> <ol> <li>Create a secret that contains a GitHub API token. If you do not use the <code>gh</code> CLI, copy and paste the token from GitHub's website.</li> </ol> <pre><code>export GITHUB_TOKEN=$(gh auth token)\n\nkubectl create secret generic branch-planner-token \\\n    --namespace=flux-system \\\n    --from-literal=\"token=${GITHUB_TOKEN}\"\n</code></pre> <ol> <li>Install Branch Planner from a HelmRelease provided by the TF-Controller repository. Use TF-Controller v0.16.0-rc.2 or later.</li> </ol> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/fa4b3b85d316340d897fda4fed757265ba2cd30e/docs/branch_planner/release.yaml\n</code></pre> <ol> <li>Create a Terraform object with a Source pointing to a repository. Your repository must contain a Terraform file\u2014for example, <code>main.tf</code>. Check out this demo for an example.</li> </ol> <pre><code>export GITHUB_USER=&lt;your user&gt;\nexport GITHUB_REPO=&lt;your repo&gt;\n\ncat &lt;&lt;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\n</code></pre> <ol> <li>Now you can create a pull request on your GitHub repo. The Branch Planner will create a new Terraform object with the plan-only mode enabled and will generate a new plan for you. It will post the plan as a new comment in the pull request.</li> </ol>"},{"location":"branch_planner/branch-planner-getting-started/#configure-branch-planner","title":"Configure Branch Planner","text":"<p>Branch Planner uses a ConfigMap as configuration. The ConfigMap is optional but useful for fine-tuning Branch Planner.</p>"},{"location":"branch_planner/branch-planner-getting-started/#configuration","title":"Configuration","text":"<p>By default, Branch Planner will look for the <code>branch-planner</code> ConfigMap in the same namespace as where the TF-Controller is installed. That ConfigMap allows users to specify which Terraform resources in a cluster the Brach Planner should monitor.</p> <p>The ConfigMap has two fields:</p> <ol> <li><code>secretName</code>, which contains the API token to access GitHub.</li> <li><code>resources</code>, which defines a list of resources to watch.</li> </ol> <pre><code>---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  namespace: flux-system\n  name: branch-planner\ndata:\n  secretName: branch-planner-token\n  resources: |-\n    - namespace: terraform\n    - namespace: flux-system\n</code></pre>"},{"location":"branch_planner/branch-planner-getting-started/#secret","title":"Secret","text":"<p>Branch Planner uses the referenced Secret with a <code>token</code> field that acquires the API token to fetch pull request information.</p> <pre><code>kubectl create secret generic branch-planner-token \\\n    --namespace=flux-system \\\n    --from-literal=\"token=${GITHUB_TOKEN}\"\n</code></pre>"},{"location":"branch_planner/branch-planner-getting-started/#resources","title":"Resources","text":"<p>If the <code>resources</code> list is empty, nothing will be watched. The resource definition can be exact or namespace-wide.</p> <p>With the following configuration file, the Branch Planner will watch all Terraform objects in the <code>terraform</code> namespace, and the <code>exact-terraform-object</code> Terraform object in <code>default</code> namespace.</p> <pre><code>data:\n  resources:\n    - namespace: default\n      name: exact-terraform-object\n    - namespace: terraform\n</code></pre>"},{"location":"branch_planner/branch-planner-getting-started/#default-configuration","title":"Default Configuration","text":"<p>If no ConfigMap is found, the Branch Planner will not watch any namespaces for Terraform resources and look for a GitHub token in a secret named <code>branch-planner-token</code> in the <code>flux-system</code> namespace. Supplying a secret with a token is a necessary task, otherwise Branch Planner will not be able to interact with the GitHub API.</p>"},{"location":"branch_planner/branch-planner-getting-started/#enable-branch-planner","title":"Enable Branch Planner","text":"<p>To enable branch planner, set the <code>branchPlanner.enabled</code> to <code>true</code> in the Helm values files.</p> <pre><code>---\nbranchPlanner:\n  enabled: true\n</code></pre>"},{"location":"branch_planner/branch-planner-overview/","title":"Branch Planner Overview","text":"<p>The GitOps methodology streamlines infrastructure provisioning and management, using Git as the source of truth. The Branch Planner, a component of TF-Controller, aims to take this a step further by allowing developers and operations teams to plan Terraform configurations on a branch that's separate from the <code>main</code> branch. This makes it easier to review and understand the potential impact of your changes before you run <code>terraform apply</code>.</p> <p>The Branch Planner's most important feature is its seamless integration with the PR (Pull Request) user interface. When enabled through Helm values, it watches repositories that contain Terraform resources at regular intervals\u2014checking their referenced Source, and polling for Pull Requests using GitHub's API and the provided token. When changes are proposed on a new branch, Branch Planner runs a plan in the cluster and displays the results directly as comments on your PR. Once you're satisfied with the results, you can merge your branch into the <code>main</code> branch to trigger the TF-Controller to reconcile the updated code.</p> <p></p>"},{"location":"branch_planner/branch-planner-overview/#replan-commands","title":"Replan commands","text":"<p>The Branch Planner also allows users to manually trigger the replan process. By simply commenting <code>!replan</code> under the PR, the Branch Planner will be instructed to generate a new plan and post it under the PR as a new comment.</p> <p>Now that you know what Branch Planner can do for you, follow the guide to get started.</p>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/","title":"Branch planner tfc integration getting started","text":""},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#branch-planner-and-terraform-cloud-integration-getting-started","title":"Branch Planner and Terraform Cloud Integration: Getting Started","text":"<p>With Branch Planner, you can provision the <code>main</code> branch directly on Terraform Cloud. TF-Controller communicates with Terraform Cloud to run the necessary plans and apply your approved code. The state is securely stored on Terraform Cloud.</p> <p>Note: For now, Branch Planner only supports GitHub as the Git provider. We plan to add other Git providers in time.</p>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-by-step-guide","title":"Step-by-step Guide","text":""},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-1-create-a-terraform-cloud-token","title":"Step 1: Create a Terraform Cloud Token","text":"<p>Use the <code>terraform login</code> command to obtain a Terraform Cloud token. Then use the token to create a Kubernetes Secret.</p> <pre><code>kubectl create secret generic \\\n  tfc-cli-config \\\n  --namespace=flux-system \\\n  --from-file=terraform.tfrc=/dev/stdin &lt;&lt; EOF\ncredentials \"app.terraform.io\" {\n  token = \"xxxxxxxxxxxxxx.atlasv1.zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz\"           \n}\nEOF\n</code></pre>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-2-create-a-terraform-cr","title":"Step 2: Create a Terraform CR","text":"<p>Create a Terraform CR to automatically plan and apply Terraform configurations on Terraform Cloud. In this example, the Branch Planner reads the Terraform configurations from a Git repository to plan, apply, and store the state in a Terraform Cloud workspace.</p> <p>The token from Step 1 is specified as the value of <code>spec.cliConfigSecretRef</code> and is used to authenticate with Terraform Cloud.</p> <pre><code>---\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/tf-controller/branch-planner-demo\n  ref:\n    branch: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: branch-planner-tfc\n  namespace: flux-system\nspec:\n  interval: 2m\n  approvePlan: auto\n  cloud:\n    organization: weaveworks\n    workspaces:\n      name: branch-planner-tfc\n  cliConfigSecretRef:\n    name: tfc-cli-config\n    namespace: flux-system\n  vars:\n  - name: subject\n    value: \"world\"\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: branch-planner-demo\n    namespace: flux-system\n</code></pre>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-3-edit-file-create-a-branch-and-open-a-pull-request","title":"Step 3: Edit File, Create a Branch, and Open a Pull Request","text":"<ol> <li> <p>Navigate to Your Repository: Open a web browser and visit your GitHub repository.  For our example, navigate here.</p> </li> <li> <p>Locate the File to Edit: Browse through the repository's file structure and  click on the Terraform configuration file you wish to edit.</p> </li> <li> <p>Edit the File: Click on the pencil icon (edit) located on the top right of the file content. Make your desired changes to the Terraform configurations. For instance, you might change the \"Hello World\" content in the <code>main.tf</code> file.</p> </li> </ol> <p>Once you've made your edits, scroll down to prepare to commit the changes.</p> <ol> <li>Commit the Changes to a New Branch: Instead of committing directly to the <code>main</code> branch,  choose the option to \"Create a new branch\" for this commit and start a pull request. Name the branch something descriptive\u2014for example, <code>change-hello-world-message</code>.</li> </ol> <p>Click on the \"Propose Changes\" button.</p> <ol> <li>Open a Pull Request (PR): After proposing your changes, you'll be led to the \"Open a pull request\" page. Fill in the details of your PR, explaining the changes you made, their purpose, and any other pertinent information.</li> </ol> <p>Click on the \"Create Pull Request\" button.</p> <ol> <li>Review Terraform Plan in PR Comments: Once the PR is created, the Branch Planner will trigger a Terraform plan. After the plan is completed, the results will be posted as a comment on the PR. This enables you and your team to review the expected changes before they're applied.</li> </ol>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-4-review-approve-and-merge-the-pull-request","title":"Step 4: Review, Approve and Merge the Pull Request","text":"<ol> <li> <p>Review the Changes:</p> <ul> <li>Navigate to the <code>Pull Requests</code> tab in your GitHub repository.</li> <li>Click on the title of your pull request to see the details.</li> <li>Examine the <code>Files changed</code> section to see the exact modifications made to the Terraform configurations.</li> <li>Check the comments for the Terraform plan output generated by Branch Planner. Ensure the plan matches your expectations.</li> </ul> </li> <li> <p>Iterate on Changes if Necessary:</p> <ul> <li>If you spot any discrepancies or wish to make further adjustments, click on the file in the <code>Files changed</code> section.</li> <li>After making the desired edits, commit the changes to the same branch. This will automatically prompt TF-Controller and Branch Planner to generate a new plan.</li> <li>If, for any reason, the automatic replan doesn't occur or you believe there might be an inconsistency, you can manually trigger a new plan by commenting <code>!replan</code> on the PR. Branch Planner will then process the request and display the new plan results.</li> </ul> </li> <li> <p>Approve the Changes:</p> <ul> <li>If you're content with the changes and the associated Terraform plan, move to the <code>Review changes</code> button on the PR page.</li> <li>Select the <code>Approve</code> option from the dropdown and optionally add any final comments.</li> <li>Click <code>Submit review</code> to finalize your approval.</li> </ul> </li> <li> <p>Merge the Pull Request:</p> <ul> <li>With the changes approved, click on the <code>Merge pull request</code> button.</li> <li>Choose your desired merge strategy from the options provided, such as \"Squash and merge\" or \"Rebase and merge\".</li> <li>Click <code>Confirm merge</code>.</li> <li>Following the merge, TF-Controller will take over. It will send the updated Terraform configuration to Terraform Cloud, where the changes will be planned and then applied. The resulting infrastructure state will be securely stored within your Terraform Cloud workspace.</li> </ul> </li> </ol>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#conclusion","title":"Conclusion","text":"<p>Combining tools like Terraform Cloud, TF-Controller with Branch Planner, and GitHub offers an innovative way for organization to streamline their infrastructure management. Being able to easily review and understand changes in a familiar platform like GitHub ensures clarity. With the immediate feedback provided by Branch Planner, teams can anticipate and discuss potential changes on different branches, before they're implemented. This combination doesn't just make updates safer and more predictable, but it promotes team-wide involvement. Furthermore, the collaboration between TF-Controller and Terraform Cloud guarantees consistency, minimizing errors, and being GitOps. As we navigate an increasingly complex IaC landscape, such simplified, integrated approaches are key to efficient, secure and error-free operations.</p>"},{"location":"how_to/","title":"How to","text":"<ul> <li>How to troubleshoot with Break the Glass mode</li> <li>How to backup and restore a Terraform state</li> <li>How does the interval and retryInterval work?</li> <li>How does the resource deletion work?</li> <li>How to integrate with Flux Receivers and Alerts?</li> <li>How to enable cross-namespace references</li> </ul>"},{"location":"how_to/backup_and_restore_a_Terraform_state/","title":"Backup and restore a Terraform state","text":""},{"location":"how_to/backup_and_restore_a_Terraform_state/#backup-the-tfstate","title":"Backup the tfstate","text":"<p>Assume that we have the <code>my-stack</code> Terraform object with its <code>.spec.workspace</code> set to \"default\".</p> <pre><code>kubectl get terraform\n\nNAME       READY     STATUS         AGE\nmy-stack   Unknown   Initializing   28s\n</code></pre> <p>We can backup its tfstate out of the cluster, like this:</p> <pre><code>WORKSPACE=default\nNAME=my-stack\n\nkubectl get secret tfstate-${WORKSPACE}-${NAME} \\\n  -ojsonpath='{.data.tfstate}' \\\n  | base64 -d | gzip -d &gt; terraform.tfstate\n</code></pre>"},{"location":"how_to/backup_and_restore_a_Terraform_state/#restore-the-tfstate","title":"Restore the tfstate","text":"<p>To restore the tfstate file or import an existing tfstate file to the cluster, we can use the following operation:</p> <pre><code>gzip terraform.tfstate\n\nWORKSPACE=default\nNAME=my-stack\n\nkubectl create secret \\\n  generic tfstate-${WORKSPACE}-${NAME} \\\n  --from-file=tfstate=terraform.tfstate.gz \\\n  --dry-run=client -o=yaml \\\n  | yq e '.metadata.annotations[\"encoding\"]=\"gzip\"' - \\\n  &gt; tfstate-${WORKSPACE}-${NAME}.yaml\n\nkubectl apply -f tfstate-${WORKSPACE}-${NAME}.yaml\n</code></pre>"},{"location":"how_to/build-and-use-a-custom-runnner-image/","title":"Using a custom runner image for TF-Controller","text":"<p>In order to build a custom runner image, you need a Dockerfile that extends the base image and that adds Terraform, plus any additional required tooling. The repository that contains the base images is here. All base image tags follow the following format: <code>${TF_CONTROLLER_VERSION}-base</code></p>"},{"location":"how_to/build-and-use-a-custom-runnner-image/#prerequisites","title":"Prerequisites","text":"<p>You need Docker and Git to build the image.</p>"},{"location":"how_to/build-and-use-a-custom-runnner-image/#build-the-image","title":"Build the image","text":"<ol> <li>Create a <code>Dockerfile</code> that extends the base image and that adds Terraform, plus any additional required tooling. For example:</li> </ol> <pre><code>ARG BASE_IMAGE\nFROM $BASE_IMAGE\n\nARG TARGETARCH\nARG TF_VERSION=1.3.9\n\n# Switch to root to have permissions for operations\nUSER root\n\nADD https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_linux_${TARGETARCH}.zip /terraform_${TF_VERSION}_linux_${TARGETARCH}.zip\nRUN unzip -q /terraform_${TF_VERSION}_linux_${TARGETARCH}.zip -d /usr/local/bin/ &amp;&amp; \\\n    rm /terraform_${TF_VERSION}_linux_${TARGETARCH}.zip &amp;&amp; \\\n    chmod +x /usr/local/bin/terraform\n\n# Switch back to the non-root user after operations\nUSER 65532:65532\n</code></pre> <p>Find the original Dockerfile for the runner here.</p> <ol> <li>Build the image from the directory containing the <code>Dockerfile</code> you created above:</li> </ol> <pre><code>export TF_CONTROLLER_VERSION=v0.16.0-rc.3\nexport TF_VERSION=1.3.9\nexport BASE_IMAGE=ghcr.io/weaveworks/tf-runner:${TF_CONTROLLER_VERSION}-base\nexport TARGETARCH=amd64\nexport REMOTE_REPO=ghcr.io/my-org/custom-runnner\ndocker build \\\n    --build-arg BASE_IMAGE=${BASE_IMAGE} \\\n    --build-arg TARGETARCH=${TARGETARCH} \\\n    --tag my-custom-runner:${TF_CONTROLLER_VERSION} .\ndocker tag my-custom-runner:${TF_CONTROLLER_VERSION} $REMOTE_REPO:${TF_CONTROLLER_VERSION}\ndocker push $REMOTE_REPO:${TF_CONTROLLER_VERSION}\n</code></pre> <p>Replace the relevant values above with the corresponding values in your organisation/implementation.</p> <ol> <li>Update the <code>values.runner.image</code> values in the TF-Controller Helm chart values to point to the new image:</li> </ol> <pre><code>values:\n  runner:\n    image:\n      repository: ghcr.io/my-org/custom-runnner\n      tag: v0.16.0-rc.3\n</code></pre> <ol> <li>Commit and push the changes to Git, and confirm that the HelmRelease has been updated:</li> </ol> <pre><code>kubectl get deployments.apps -n flux-system tf-controller -o jsonpath='{.spec.template.spec.containers[*]}' | jq '.env[] | select(.name == \"RUNNER_POD_IMAGE\")'\n{\n  \"name\": \"RUNNER_POD_IMAGE\",\n  \"value\": \"ghcr.io/my-org/custom-runner:v0.16.0-rc3\"\n}\n</code></pre>"},{"location":"how_to/build-and-use-a-custom-runnner-image/#references","title":"References","text":"<p>A set of GitHub actions in the TF-Controller community repo facilitate a process that's similar to the above, but using GitHub Actions to build and push the image. You can find them here.</p>"},{"location":"how_to/flux_receiver_and_alert/","title":"Integrate with Flux Receivers and Alerts","text":"<p>These docs show how to customize your Flux installation so that Flux API resources like <code>Receivers</code> and <code>Alerts</code> can be used with third-party custom resource definitions such as the <code>Terraform</code> API CRD.</p> <p>You will need to add a patch to the <code>kustomization.yaml</code> in your Flux cluster installation's bootstrap manifests, find it under the <code>flux-system</code> directory.</p>"},{"location":"how_to/flux_receiver_and_alert/#enable-notifications-for-third-party-controllers","title":"Enable notifications for third party controllers","text":"<p>Enable notifications for 3rd party Flux controllers such as tf-controller:</p> <pre><code>apiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nresources:\n  - gotk-components.yaml\n  - gotk-sync.yaml\npatches:\n  - patch: |\n      - op: add\n        path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/-\n        value: Terraform\n      - op: add\n        path: /spec/versions/1/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/-\n        value: Terraform\n    target:\n      kind: CustomResourceDefinition\n      name:  alerts.notification.toolkit.fluxcd.io\n  - patch: |\n      - op: add\n        path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/resources/items/properties/kind/enum/-\n        value: Terraform\n      - op: add\n        path: /spec/versions/1/schema/openAPIV3Schema/properties/spec/properties/resources/items/properties/kind/enum/-\n        value: Terraform\n    target:\n      kind: CustomResourceDefinition\n      name:  receivers.notification.toolkit.fluxcd.io\n  - patch: |\n      - op: add\n        path: /rules/-\n        value:\n          apiGroups: [ 'infra.contrib.fluxcd.io' ]\n          resources: [ '*' ]\n          verbs: [ '*' ]\n    target:\n      kind: ClusterRole\n      name:  crd-controller-flux-system\n</code></pre>"},{"location":"how_to/interval_and_retryInterval/","title":"How does the interval and retryInterval work?","text":""},{"location":"how_to/interval_and_retryInterval/#overview","title":"Overview","text":"<p>This 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.</p>"},{"location":"how_to/interval_and_retryInterval/#requeue-behaviors","title":"Requeue Behaviors","text":"<p>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:</p>"},{"location":"how_to/interval_and_retryInterval/#1-immediate-requeue-not-using-specified-interval-retryinterval","title":"1. Immediate Requeue (Not using specified interval / retryInterval)","text":"<p>In these scenarios, the <code>Reconcile</code> 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:</p> <ul> <li>When there's an error retrieving the Terraform object from the Kubernetes API.</li> <li>After adding the finalizer, if there's an error in patching the Terraform object.</li> <li>If there's a non-access-denied error in retrieving the source object.</li> <li>When the ready condition is unknown or the status of the ready condition isn't unknown, and there's an error in patching the Terraform object.</li> <li>In multiple situations where there's an error in patching the Terraform object's status.</li> <li>If there's an error in creating or looking up the runner.</li> <li>If there's an error while attempting to finalize the Terraform object.</li> </ul>"},{"location":"how_to/interval_and_retryInterval/#2-requeue-after-a-specific-interval-specretryinterval","title":"2. Requeue After a Specific Interval (<code>spec.retryInterval</code>)","text":"<p>In these scenarios, the method specifically asks for a requeue after a certain interval specified by <code>spec.retryInterval</code> (default to 15s).</p> <ul> <li>The Terraform object is being deleted but there are still dependent resources that haven't been deleted.</li> <li>The source object specified by <code>spec.sourceRef</code> is not found.</li> <li>The source object doesn't have an associated artifact.</li> <li>The dependencies do not meet the ready condition.</li> <li>There's an error during the main reconciliation process.</li> <li>Drift is detected during the reconciliation process.</li> </ul>"},{"location":"how_to/interval_and_retryInterval/#3-requeue-after-a-specific-interval-specinterval","title":"3. Requeue After a Specific Interval (<code>spec.interval</code>)","text":"<p>In this scenario, the method specifically asks for a requeue after a successful reconciliation:</p> <p>The interval for the requeue is <code>spec.interval</code>.</p>"},{"location":"how_to/interval_and_retryInterval/#4-no-requeue-wait-for-manual-intervention","title":"4. No Requeue, wait for manual intervention","text":"<p>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:</p> <ul> <li>Access is denied when retrieving the source object.</li> <li>The status of the plan is pending, and it's not set to force or auto-apply.</li> </ul>"},{"location":"how_to/resource_deletion/","title":"Resource Deletion Dependencies in Terraform Controller","text":"<p>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.</p>"},{"location":"how_to/resource_deletion/#source-object","title":"Source Object","text":"<p>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.</p> <p>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).</p> <p>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.</p> <p>If the source object was deleted and the deletion of a Terraform resource is stuck, clearing the <code>finalizers</code> let the system delete the resource skipping the finalizer of the Terraform Controller.</p> <ol> <li>Suspend the <code>kustomization</code>:    <pre><code>flux suspend kustomization tf-stk\n</code></pre></li> <li>Patch the Terraform resource:    <pre><code>kubectl patch terraforms.infra.contrib.fluxcd.io \\\n  -n stk helloworld \\\n  -p '{\"metadata\":{\"finalizers\":null}}' \\\n  --type=merge\n</code></pre></li> </ol> <p>As it skips the finalizer of the Terraform controller, any cleanup the controller would do will be skipped too.</p>"},{"location":"how_to/resource_deletion/#role-bindings","title":"Role Bindings","text":"<p>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.</p> <p>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.</p>"},{"location":"how_to/resource_deletion/#secrets-and-configmaps","title":"Secrets and ConfigMaps","text":"<p>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.</p> <p>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.</p>"},{"location":"how_to/resource_deletion/#troubleshooting","title":"Troubleshooting","text":"<p>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.</p> <p>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.</p>"},{"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":"<p>\"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.</p> <p>~&gt; WARNING: Please note that you cannot use this feature to fix the Terraform resources with <code>v1alpha1</code> version of the Terraform CRD.  It works only with <code>v1alpha2</code> version of the Terraform CRD.</p> <p>~&gt; 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.</p> <p>There are two primary methods of initiating this mode:</p> <ol> <li>Using the <code>tfctl</code> command-line tool.</li> <li>Setting the <code>spec.breakTheGlass</code> field to <code>true</code> in the Terraform object.</li> </ol>"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#using-tfctl-to-break-the-glass","title":"Using <code>tfctl</code> to Break the Glass","text":"<p>In order to use this functionality, it needs to be enabled at the controller level; in order to do that, you can set the following Helm chart value to <code>true</code>:</p> <pre><code>allowBreakTheGlass: true\n</code></pre> <p>After the feature is enabled, to start a one-time troubleshooting session, you can use the <code>tfctl break-glass</code> command. For instance:</p> <pre><code>tfctl break-glass hello-world\n</code></pre> <p>This command initiates a session that allows you to execute any Terraform command to rectify the issues with your Terraform resources. It is noteworthy that this command does not require setting the <code>spec.breakTheGlass</code> field to <code>true</code> in the Terraform object.</p> <p>After resolving the issues, you can simply exit the shell.  GitOps will then continue to reconcile the Terraform object.</p>"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#break-the-glass-with-specbreaktheglass-field","title":"Break the glass with <code>spec.breakTheGlass</code> field","text":"<p>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.</p> <p>You can enable the 'Break the Glass' feature for every reconciliation by setting the <code>breakTheGlass</code> field to <code>true</code> in the <code>spec</code> of the Terraform object.</p> <p>Here is a sample example:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  breakTheGlass: true\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"how_to/upgrade-tf-controller/","title":"Upgrading TF-Controller","text":"<p>Please follow these steps to upgrade TF-Controller:</p> <ol> <li>Read the latest release changelogs.</li> <li>Check your API versions.</li> <li>To make sure you don't get new state changes, suspend Terraform resources (<code>tfctl suspend --all</code>) to minimize the impact on live systems.</li> <li>Back up Terraform tfstates to avoid losing data. If you're using the default backend with secrets in Kubernetes, use your backup toolset (i.e., Velero) to back up the state data.</li> <li>Upgrade Flux first, following the Flux documentation.</li> <li>Disable auto-approval by either removing the approvePlan value or setting it to \"\".</li> <li>To prevent unintentional resource deletions, set the <code>spec.destroyResourcesOnDeletion</code> flag to <code>false</code> for critical or production systems (the default value is <code>false</code>)</li> <li>If the Flux upgrade goes well, proceed to upgrade the TF-controller via its image tag. Adjust the values in the HelmRelease to match the new version to which you are upgrading.</li> <li>Check the pod logs for the TF-Controller deployment and any runner logs in order to identify potential issues. If you check the <code>warnings</code> in the logs, you can also identify any required API changes. For example: <code>v1alpha1 Terraform is deprecated, upgrade to v1alpha2</code>.</li> <li>Push the changes you made.</li> <li>Resume your Terraform resources\u2014either one-by-one for critical resources, or all of them with <code>tfctl resume --all</code></li> <li>Ensure no changes are planned for deletion. If you changed the value in step 6 from <code>spec.destroyResourcesOnDeletion</code> to <code>false</code>, resources will not be automatically removed.</li> <li>Revert back to auto-approval mode after ensuring stability.</li> <li>Resume any suspended Kustomization objects to restore GitOps automation.</li> <li>Restore <code>spec.destroyResourcesOnDeletion</code>, if this has been disabled for any resources in critical or production systems.</li> </ol> <p>TF-Controller supports v1alpha1 for backward compatibility. This means that you need v1alpha2 for newer (as of September 2023) features such as: - the branch planner - pod sub-domain DNS resolutions - new PodSpec fields like PriorityClass, SecurityContext, and ResourceRequirements (Limits / Requests)</p>"},{"location":"how_to/use-cross-namespace-refs/","title":"Using cross-namespace references","text":"<p>The Terraform CRD in the API for TF-controller includes fields which are references to other objects:</p> Name Purpose .spec.sourceRef Refers to a Flux source .spec.dependsOn[*] Each entry refers to a dependency .spec.cliConfigSecretRef Secret with <code>tf</code> config to use <p>The branch planner configuration can also have cross-namespace references:</p> Name Purpose .secretNamespace Namespace of secret containing a GitHub token .resources[*] Each entry refers to a Terraform object to include in branch planning <p>All of these can refer to an object in a namespace different to that of the Terraform object. However, giving access to objects in other namespaces is generally considered a security risk, so this is disallowed by default. Only references that mention the same namespace, or omit the namespace field, will be accepted. References using a different namespace will cause the controller to stop processing the Terraform object and put it in a non-Ready state.</p> <p>To allow cross-namespace references, use the flag <code>--allow-cross-namespace-refs</code> with the controller and branch-planner. When using the Helm chart to install or update the controller and branch-planner, the value <code>allowCrossNamespaceRefs</code> will allow cross-namespace references for both.</p>"},{"location":"use_tf_controller/","title":"Use TF-controller","text":"<ul> <li>Use TF-controller to provision resources and auto approve</li> <li>Use TF-controller to plan and manually apply Terraform resources</li> <li>Use TF-controller to provision resources and obtain outputs</li> <li>Use TF-controller to detect drifts only without plan or apply</li> <li>Use TF-controller with drift detection disabled</li> <li>Use TF-controller with AWS EKS IRSA</li> <li>Use TF-controller to set variables for Terraform resources</li> <li>Use TF-controller with a custom backend</li> <li>Use TF-controller with an OCI Artifact as Source</li> <li>Use TF-controller to provision Terraform resources that are required health checks</li> <li>Use TF-controller to provision resources and destroy them when the Terraform object gets deleted</li> <li>Use TF-controller to force unlock Terraform states</li> <li>Use TF-controller with Terraform Runners enabled via Env Variables</li> <li>Use TF-controller to provision resources with customized Runner Pods</li> <li>Use TF-controller with Terraform Enterprise</li> <li>Use TF-controller with primitive modules</li> <li>Use TF-controller with GitOps dependency management</li> <li>Use TF-controller with the ready-to-use AWS package</li> <li>User TF-controller with plan-only mode</li> <li>Use TF-controller with external webhooks</li> <li>Use TF-controller with Terraform Runners exposed via hostname/subdomain</li> </ul>"},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/","title":"To detect drifts only without plan or apply","text":""},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/#use-tf-controller-to-detect-drifts-only-without-plan-or-apply","title":"Use TF-controller to detect drifts only without plan or apply","text":"<p>We can set <code>.spec.approvePlan</code> to <code>disable</code> to tell the controller to detect drifts of your Terraform resources only. Doing so will skip the <code>plan</code> and <code>apply</code> stages.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  approvePlan: disable\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/#troubleshooting","title":"Troubleshooting","text":""},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/#when-terraform-resource-detects-drift-but-no-plan-is-generated-for-approval","title":"When Terraform resource detects drift, but no plan is generated for approval","text":"<p>In this situation, you may not have <code>spec.approvePlan</code> set to <code>disable</code>. Try setting <code>spec.approvePlan: auto</code> and using <code>tfctl replan</code> to trigger a replan. After the drift disappears, you can set the <code>spec.approvePlan: \"\"</code> to get into the manual mode again.</p>"},{"location":"use_tf_controller/to_force_unlock_Terraform_states/","title":"Use TF-controller to force unlock Terraform states","text":"<p>In some situations, you may need to perform the Terraform force-unlock operation on the tfstate inside the cluster. </p> <p>There are three possible values of <code>.spec.tfstate.forceUnlock</code>, which are <code>yes</code>, <code>no</code>, and <code>auto</code>. The default value is <code>no</code>, which means that you disable this behaviour.</p> <p>The <code>auto</code> force-unlock mode will automatically use the lock identifier produced by the associated state file instead of specified lock identifier.</p> <p>The recommended way is to do manual force unlock. To manually <code>force-unlock</code>, you need to:</p> <ol> <li>set <code>forceUnlock</code> to <code>yes</code>, and</li> <li>specify a lock identifier to unlock a specific locked state,</li> </ol> <p>as the following example:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  tfstate:\n    forceUnlock: \"yes\"\n    lockIdentifier: f2ab685b-f84d-ac0b-a125-378a22877e8d\n</code></pre>"},{"location":"use_tf_controller/to_plan_and_manually_apply_Terraform_resources/","title":"Use TF-controller to plan and manually apply Terraform resources","text":"<p>In this guide, we will walk through the steps of using TF-controller to plan and manually apply Terraform resources.</p> <p>We will start by creating the <code>Terraform</code> object and specifying the necessary fields, including the <code>approvePlan</code> field.</p> <p>We will then create the <code>GitRepository</code> object, which points to the Git repository containing the Terraform configuration.</p> <p>Once these objects are created, we will use kubectl to obtain the <code>approvePlan</code> value and set it in the <code>Terraform</code> object. After making our changes and pushing them to the Git repository, TF-controller will apply the plan and create the real resources.</p>"},{"location":"use_tf_controller/to_plan_and_manually_apply_Terraform_resources/#define-the-terraform-object","title":"Define the Terraform object","text":"<p>Assume that you have a <code>GitRepository</code> object named <code>helloworld</code> pointing to a Git repository, and you want to plan and apply the Terraform resources under <code>./</code> of that Git repo.</p> <p>For the plan &amp; manual approval workflow, please start by either setting <code>.spec.approvePlan</code> to be the blank value, or omitting the field. This will tell TF-controller to use the plan &amp; manual approval workflow, rather than the auto-apply workflow. If you want to use the auto-apply workflow, you will need to set the <code>spec.approvePlan</code> field to \"auto\".</p> <p>In addition to setting the <code>spec.approvePlan</code> field, you will also need to specify the <code>interval</code>, <code>path</code>, and <code>sourceRef</code> fields in the spec field. The <code>interval</code> field determines how often TF-controller will run the Terraform configuration, the <code>path</code> field specifies the location of the configuration files, and the <code>sourceRef</code> field points to the GitRepository object.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: \"\" # or you can omit this field\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_plan_and_manually_apply_Terraform_resources/#view-the-approval-message","title":"View the approval message","text":"<p>Then after a reconciliation loop, the controller will generate a plan, and tell you how to use field <code>.spec.approvePlan</code> to approve the plan. You can run the following command to obtain that message.</p> <pre><code>kubectl -n flux-system get tf/helloworld\n</code></pre> <p>This 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 <code>spec.approvePlan</code> field to the value obtained from the message.</p> <p>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 &amp; manual approval workflow, as it involves generating a plan and requiring manual approval before the changes are applied.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  approvePlan: plan-main-b8e362c206 # first 8 digits of a commit hash is enough\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks/","title":"Use TF-controller to provision Terraform resources that are required health checks","text":"<p>For some Terraform resources, it may be useful to perform health checks on them to verify that they are ready to accept connection before the terraform goes into <code>Ready</code> state:</p> <p>For example, our Terraform file is provisioned and contains the following outputs.</p> <pre><code># main.tf\n\noutput \"rdsAddress\" {\n  value = \"mydb.xyz.us-east-1.rds.amazonaws.com\"\n}\n\noutput \"rdsPort\" {\n  value = \"3306\"\n}\n\noutput \"myappURL\" {\n  value = \"https://example.com/\"\n}\n</code></pre> <p>We can use standard Go template expressions, like <code>${{ .rdsAddress }}</code>, to refer to those output values and use them to verify that the resources are up and running.</p> <p>We support two types of health checks, <code>tcp</code> amd <code>http</code>. The <code>tcp</code> type allows us to verify a TCP connection, while the <code>http</code> type is for verify an HTTP URL. The default timeout of each health check is 20 seconds.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  healthChecks:\n    - name: rds\n      type: tcp\n      address: ${{ .rdsAddress }}:${{ .rdsPort }} \n      timeout: 10s # optional, defaults to 20s\n    - name: myapp\n      type: http\n      url: ${{ .myappURL }}\n      timeout: 5s\n    - name: url_not_from_output\n      type: http\n      url: \"https://example.org\"\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/","title":"Use TF-controller to provision resources and auto approve","text":"<p>To provision resources with TF-controller, you need to create a <code>Terraform</code> object and a Flux source object,  such as a <code>GitRepository</code> or <code>OCIRepository</code> object.</p>"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/#create-a-terraform-object","title":"Create a Terraform object","text":"<p>The <code>Terraform</code> 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.. </p> <p>It defines the Terraform module, the backend configuration, and the GitOps automation mode.</p> <p>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.</p> <p>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.</p>"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/#gitops-automation-mode","title":"GitOps automation mode","text":"<p>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.</p> <p>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.</p> <p>To specify the GitOps automation mode in a Terraform object, you can set the <code>spec.approvePlan</code> field to the desired value. For example, to use the \"auto-apply\" mode, y ou would set it to <code>spec.approvePlan: auto</code>.</p> <p>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.</p> <p>The following is an example of a <code>Terraform</code> object; we use the \"auto-apply\" mode:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\nspec:\n  path: ./helloworld\n  interval: 10m\n  approvePlan: auto\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n</code></pre> <p>This code is defining a <code>Terraform</code> object in Kubernetes. The <code>apiVersion</code> field specifies the version of the Kubernetes API being used, and the <code>kind</code> field specifies that it is a <code>Terraform</code> object. The <code>metadata</code> block contains information about the object, including its <code>name</code>.</p> <p>The <code>spec</code> field contains the specification for the <code>Terraform</code> object. The <code>path</code> field specifies the path to the Terraform configuration files, in this case a directory named \"helloworld\". The <code>interval</code> field specifies the frequency at which TF-controller should run the Terraform configuration, in this case every 10 minutes. The <code>approvePlan</code> field specifies whether or not to automatically approve the changes proposed by a Terraform plan. In this case, it is set to <code>auto</code>, meaning that changes will be automatically approved.</p> <p>The <code>sourceRef</code> field specifies the Flux source object to be used. In this case, it is a <code>GitRepository</code> object with the name \"helloworld\". This indicates that the Terraform configuration is stored in a Git repository object with the name <code>helloworld</code>.</p>"},{"location":"use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted/","title":"Use TF-controller to provision resources and destroy them when the Terraform object gets deleted","text":"<p>The resources provisioned by a Terraform object are not destroyed by default, and the tfstate of that Terraform object still remains in the cluster.</p> <p>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.</p> <p>However, you may want to destroy provisioned resources when delete the Terraform object in many scenarios. To enable destroy resources on object deletion, set <code>.spec.destroyResourcesOnDeletion</code> to <code>true</code>.</p> <p>~&gt; WARNING: This feature will destroy your resources on the cloud if the Terraform object gets deleted. Please use it with cautions.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  destroyResourcesOnDeletion: true\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/","title":"Use TF-controller to provision resources and obtain outputs","text":"<p>Outputs created by Terraform can be written to a secret using <code>.spec.writeOutputsToSecret</code>.</p>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#write-all-outputs","title":"Write all outputs","text":"<p>We can specify a target secret in <code>.spec.writeOutputsToSecret.name</code>, and the controller will write all outputs to the secret by default.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#write-outputs-selectively","title":"Write outputs selectively","text":"<p>We can choose only a subset of outputs by specify output names we'd like to write in the <code>.spec.writeOutputsToSecret.outputs</code> array.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n    outputs:\n    - hello_world\n    - my_sensitive_data\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#rename-outputs","title":"Rename outputs","text":"<p>Some 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. </p> <p>TF-controller supports mapping output name using the <code>old_name:new_name</code> format.</p> <p>In the following example, we renamed <code>age_key</code> output as <code>age.agekey</code> entry for the <code>helloworld-output</code> Secret's data, so that other components in the GitOps pipeline could consume it.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n    outputs:\n    - age_key:age.agekey\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#customize-metadata-of-the-outputted-secret","title":"Customize metadata of the outputted secret","text":"<p>In 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.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n    labels:\n      my-label: true\n    annotations:\n      my-annotation: \"very long string\"\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/","title":"Use TF-controller to provision resources with customized Runner Pods","text":""},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/#customize-runner-pods-metadata","title":"Customize Runner Pod's metadata","text":"<p>In 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 <code>aadpodidbinding: myIdentity</code> on the pod is required.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  runnerPodTemplate:\n    metadata:\n      labels:\n        aadpodidbinding: myIdentity\n      annotations:\n        company.com/abc: xyz\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/#customize-runner-pod-image","title":"Customize Runner Pod Image","text":"<p>By default, the Terraform controller uses <code>RUNNER_POD_IMAGE</code> 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.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  runnerPodTemplate:\n    spec:\n      image: registry.io/tf-runner:xyz\n</code></pre> <p>You can use <code>runner.Dockerfile</code> as a basis of customizing runner pod image.</p>"},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/#customize-runner-pod-specifications","title":"Customize Runner Pod Specifications","text":"<p>You can also customize various Runner Pod <code>spec</code> fields to control and configure how the Runner Pod runs.  For example, you can configure Runner Pod <code>spec</code> 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 <code>spec</code> fields.</p>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/","title":"Use TF-controller to set variables for Terraform resources","text":"<p>~&gt; BREAKING CHANGE: This is a breaking change of the <code>v1alpha1</code> API.</p> <p>Users who are upgrading from TF-controller &lt;= 0.7.0 require updating <code>varsFrom</code>, from a single object:</p> <pre><code>  varsFrom:\n    kind: ConfigMap\n    name: cluster-config\n</code></pre> <p>to be an array of object, like this:</p> <pre><code>  varsFrom:\n  - kind: ConfigMap\n    name: cluster-config\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#vars-and-varsfrom","title":"<code>vars</code> and <code>varsFrom</code>","text":"<p>You can pass variables to Terraform using the <code>vars</code> and <code>varsFrom</code> fields.</p> <p>Inline variables can be set using <code>vars</code>. The <code>varsFrom</code> field accepts a list of ConfigMaps / Secrets. You may use the <code>varsKeys</code> property of <code>varsFrom</code> to select specific keys from the input or omit this field to select all keys from the input source.</p> <p>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 <code>varsFrom</code>.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  vars:\n  - name: region\n    value: us-east-1\n  - name: env\n    value: dev\n  - name: instanceType\n    value: t3-small\n  varsFrom:\n  - kind: ConfigMap\n    name: cluster-config\n    varsKeys:\n    - nodeCount\n    - instanceType\n  - kind: Secret\n    name: cluster-creds\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#variable-value-as-hcl","title":"Variable value as HCL","text":"<p>The <code>vars</code> field supports HCL string, number, bool, object and list types. For example, the following variable can be populated using the accompanying Terraform spec:</p> <pre><code>variable \"cluster_spec\" {\n  type = object({\n      region     = string\n      env        = string\n      node_count = number\n      public     = bool\n  })\n}\n</code></pre> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  vars:\n  - name: cluster_spec\n    value:\n      region: us-east-1\n      env: dev\n      node_count: 10\n      public: false\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-variables-in-varsfrom","title":"Rename variables in varsFrom","text":"<p>To rename a variable, you can use the varsKeys key within the varsFrom field.  Here's the basic structure:</p> <p><pre><code>spec:\n  varsFrom:\n  - kind: Secret\n    name: &lt;secret_name&gt;\n    varsKeys:\n    - &lt;original_variable_name&gt;:&lt;new_variable_name&gt;\n</code></pre> <code>original_variable_name</code> corresponds to the initial name of the variable in the referenced secret, while <code>new_variable_name</code> represents the alias you want to use within the Terraform code.</p> <p>Consider this example below, where we rename <code>nodeCount</code> to <code>node_count</code>  and <code>instanceType</code> to <code>instance_type</code>:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  varsFrom:\n  - kind: Secret\n    name: cluster-config\n    varsKeys:\n    - nodeCount:node_count\n    - instanceType:instance_type\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-output-variables","title":"Rename output variables","text":"<p>See Rename outputs for more details.</p>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-input-secrets","title":"Rename input secrets","text":"<p>See Rename input secrets for more details.</p>"},{"location":"use_tf_controller/with-azure/","title":"With azure","text":""},{"location":"use_tf_controller/with-azure/#use-tf-controller-with-azure","title":"Use TF-Controller with Azure","text":"<p>This content was provided by users @mingmingshiliyu and @maciekdude.</p> <p>Use the OIDC flag and explicitly point to the token. Due to a bug in AzureRM 3.44.x, use version 3.47.x or later.</p> <p>Set env variables on the runner pod:</p> <pre><code>        - name: ARM_USE_OIDC\n          value: \"true\"\n        - name: ARM_OIDC_TOKEN_FILE_PATH\n          value: \"/var/run/secrets/azure/tokens/azure-identity-token\"\n</code></pre> <p>Example yaml:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha1\nkind: Terraform\nmetadata:\n  name: terraformhello\n  namespace: default\nspec:\n  tfstate:\n    forceUnlock: auto\n  backendConfig:\n    customConfiguration: |\n      backend \"azurerm\" {\n        resource_group_name  = \"l\"\n        storage_account_name = \"\"\n        container_name       = \"tfstate\"\n        key                  = \"helloworld.tfstate\"\n        use_oidc             = true\n      }\n  interval: 1m\n  serviceAccountName: service_account_registered_in_aad\n  approvePlan: auto\n  destroy: true\n  path: ./tests/fixture\n  sourceRef:\n    kind: GitRepository\n    name: terraformhello\n    namespace: flux-system\n  runnerPodTemplate:\n    spec:\n      image: azure_cli_runner.xxx\n      env:\n        - name: ARM_USE_OIDC\n          value: \"true\"\n        - name: ARM_SUBSCRIPTION_ID\n          value: \"\"\n        - name: ARM_TENANT_ID\n          value: \"\"\n        - name: ARM_CLIENT_ID\n          value: \"\"\n        - name: ARM_OIDC_TOKEN_FILE_PATH\n          value: \"/var/run/secrets/azure/tokens/azure-identity-token\"\n</code></pre> <p>Import existing resources to a tfstate file stored on a storage account.</p>"},{"location":"use_tf_controller/with-ipv6/","title":"Use TF-Controller with IPv6 addresses.","text":"<p>TF-Controller uses pod IPv4 address to generate the in-cluster hostname to communicate with the runner instance. This logic fails when the runner pod has IPv6 address instead of IPv4.</p> <p>The TF-Controller has a flag to use pod subdomain resolution instead of an IP address, with that enabled the controller will use cluster subdomains, and it works with IPv6 addresses as the resolution is happening at cluster level.</p> <p>To enable this feature, you can set <code>usePodSubdomainResolution</code> to <code>true</code> in the Helm values file:</p> <pre><code>usePodSubdomainResolution: true\n</code></pre>"},{"location":"use_tf_controller/with_AWS_EKS_IRSA/","title":"Use TF-controller with AWS EKS IRSA","text":"<p>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.</p> <p>You can use <code>eksctl</code> to associate an OIDC provider with your EKS cluster, for example:</p> <pre><code>eksctl utils associate-iam-oidc-provider --cluster CLUSTER_NAME --approve\n</code></pre> <p>Then 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 <code>namespace:serviceaccountname</code> will be <code>flux-system:tf-runner</code>. You'll obtain a Role ARN to use in the next step.</p> <p>Finally, annotate the ServiceAccount for the <code>tf-runner</code> with the obtained Role ARN in your cluster:</p> <pre><code>kubectl annotate -n flux-system serviceaccount tf-runner eks.amazonaws.com/role-arn=ROLE_ARN\n</code></pre> <p>If deploying the <code>tf-controller</code> via Helm, this can be accomplished as follows:</p> <pre><code>values:\n  runner:\n    serviceAccount:\n      annotations:\n        eks.amazonaws.com/role-arn: ROLE_ARN\n</code></pre>"},{"location":"use_tf_controller/with_GitOps_dependency_management/","title":"Use TF-controller with GitOps dependency management","text":"<p>TF-controller supports GitOps dependency management. The GitOps dependency management feature is based on the similar technique implemented in the Kustomization controller of Flux.</p> <p>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.</p> <p>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.</p>"},{"location":"use_tf_controller/with_GitOps_dependency_management/#create-a-terraform-object","title":"Create a Terraform object","text":"<p>Similar to the same feature in the Kustomization controller, the dependency management feature is enabled by setting the <code>dependsOn</code> field in the <code>Terraform</code> object. The <code>dependsOn</code> field is a list of <code>Terraform</code> objects.</p> <p>When the dependency is not satisfied, the Terraform object will be in the <code>Unknown</code> state, and it will be retry again every <code>spec.retryInterval</code>. The retry interval is same as the <code>spec.interval</code> by default, and it can be configured separately by setting the <code>spec.retryInterval</code> field.</p> <p>First, create a <code>Terraform</code> object to provision the S3 bucket, name it <code>aws-s3-bucket</code>. The S3 bucket is provisioned by the Terraform module <code>aws_s3_bucket</code> in the OCI image <code>aws-package</code>. It is configured to use the <code>auto-apply</code> mode, and write outputs to the secret <code>aws-s3-bucket-outputs</code>.</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: aws-s3-bucket\n  namespace: flux-system\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  interval: 2m\n  destroyResourcesOnDeletion: true\n  writeOutputsToSecret:\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</code></pre> <p>Second, create a <code>Terraform</code> object to configure ACL for the S3 bucket, name it <code>aws-s3-bucket-acl</code>. The ACL is provisioned by the Terraform module <code>aws_s3_bucket_acl</code>, also from the OCI image <code>aws-package-v4.33.0</code>.</p> <p>In the <code>dependsOn</code> field, specify the <code>Terraform</code> 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 <code>aws-s3-bucket-outputs</code>, by specifying the <code>spec.readInputsFromSecrets</code> field. The <code>spec.readInputsFromSecrets</code> field is a list of Secret objects.  Its <code>name</code> field is the name of the Secret, and its <code>as</code> field is the name of variable that can be used in the <code>spec.values</code> block.</p> <p>For example, the <code>spec.values.bucket</code> field in the <code>aws-s3-bucket-acl</code> Terraform object is set to <code>${{ .aws_s3_bucket.bucket }}</code>.</p> <p>Please note that we use <code>${{</code> and  <code>}}</code> as the delimiters for the variable name, instead of the Helm default ones, <code>{{</code> and <code>}}</code>.</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: aws-s3-bucket-acl\n  namespace: flux-system\nspec:\n  path: aws_s3_bucket_acl\n  values:\n    acl: private\n    bucket: ${{ .aws_s3_bucket.bucket }}\n  sourceRef:\n    kind: OCIRepository\n    name: aws-package\n  approvePlan: auto\n  interval: 3m\n  dependsOn:\n  - name: aws-s3-bucket\n  readInputsFromSecrets:\n  - name: aws-s3-bucket-outputs\n    as: aws_s3_bucket\n  runnerPodTemplate:\n    spec:\n      envFrom:\n      - secretRef:\n          name: aws-credentials\n</code></pre>"},{"location":"use_tf_controller/with_GitOps_dependency_management/#avoid-kustomization-controllers-variable-substitution","title":"Avoid Kustomization controller's variable substitution","text":"<p>The Kustomization controller will substitute variables in the <code>Terraform</code> object, which will cause conflicts with the variable substitution in the GitOps dependency management feature. To avoid this, we need to add the <code>kustomize.toolkit.fluxcd.io/substitute: disabled</code> annotation to the <code>Terraform</code> object.</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: aws-s3-bucket-acl\n  namespace: flux-system\n  annotations:\n    kustomize.toolkit.fluxcd.io/substitute: disabled\nspec:\n  path: aws_s3_bucket_acl\n  values:\n    acl: private\n    bucket: ${{ .aws_s3_bucket.bucket }}\n  sourceRef:\n    kind: OCIRepository\n    name: aws-package\n  approvePlan: auto\n  interval: 3m\n  dependsOn:\n  - name: aws-s3-bucket\n  readInputsFromSecrets:\n  - name: aws-s3-bucket-outputs\n    as: aws_s3_bucket\n  runnerPodTemplate:\n    spec:\n      envFrom:\n      - secretRef:\n          name: aws-credentials\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/","title":"Use TF-controller with Terraform Enterprise","text":""},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-enterprise-integration","title":"Terraform Enterprise Integration","text":"<p>Starting from v0.9.5, Weave TF-controller officially supports integration to Terraform Cloud (TFC) and  Terraform Enterprise (TFE). Here are the steps to set up TF-controller for your TFE instance.</p> <p></p>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-login","title":"Terraform Login","text":"<p>First, you need to obtain an API token from your TFE. You can use <code>terraform login</code> command to do so.</p> <pre><code>terraform login tfe.dev.example.com\n</code></pre> <p>Then you can find your API token inside <code>$HOME/.terraform.d/credentials.tfrc.json</code>. Content of the file will look like this:</p> <pre><code>{\n  \"credentials\": {\n    \"tfe.dev.example.com\": {\n      \"token\": \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n    }\n  }\n}\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#prepare-an-tfrc-file","title":"Prepare an TFRC file","text":"<p>TF-controller accepts an TFRC file in the HCL format. So you have to prepare <code>terraform.tfrc</code> file using contents from above. <pre><code>credentials \"tfe.dev.example.com\" {\n  token = \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n}\n</code></pre></p>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#create-a-secret","title":"Create a Secret","text":"<p>We will now create a Kubernetes Secret from your<code>terraform.tfrc</code> file,  name it <code>tfe-cli-config</code> and put it inside the <code>flux-system</code> namespace.</p> <pre><code>kubectl create secret generic \\\n  tfe-cli-config \\\n  --namespace=flux-system \\\n  --from-file=terraform.tfrc=./terraform.tfrc\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-object","title":"Terraform Object","text":"<p>In your Terraform object, you'll have to 1. disable the backend by setting <code>spec.backendConfig.disable: true</code>, and 2. point <code>spec.cliConfigSecretRef:</code> to the Secret created in the previous step, like this:</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: tfe-demo\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 2m\n  path: ./terraform/tfe-demo\n  backendConfig:\n    disable: true\n  cliConfigSecretRef:\n    name: tfe-cli-config\n    namespace: flux-system\n  vars:\n  - name: subject\n    value: World\n  sourceRef:\n    kind: GitRepository\n    name: flux-system\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: tfe-helloworld-output\n    outputs:\n    - greeting\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-module","title":"Terraform Module","text":"<p>Don't forget that you need to tell your Terraform model to use your enterprise instance as well. Here's an example, <pre><code>terraform {\n  required_version = \"&gt;= 1.1.0\"\n  cloud {\n    hostname = \"tfe.dev.example.com\"\n    organization = \"weaveworks\"\n\n    workspaces {\n      name = \"dev\"\n    }\n  }\n}\n\nvariable \"subject\" {\n   type = string\n   default = \"World\"\n   description = \"Subject to hello\"\n}\n\noutput \"greeting\" {\n  value = \"Hello ${var.subject} from Terraform Enterprise\"\n}\n</code></pre></p>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-cloud","title":"Terraform Cloud","text":"<p>For connecting to Terraform Cloud, please replace your hostname to <code>app.terraform.io</code>.</p>"},{"location":"use_tf_controller/with_a_custom_backend/","title":"Use TF-controller with a custom backend","text":"<p>By default, <code>tf-controller</code> will use the Kubernetes backend to store the Terraform state file (tfstate) in cluster.</p> <p>The tfstate is stored in a secret named: <code>tfstate-${workspace}-${secretSuffix}</code>. The default <code>suffix</code> will be the name of the Terraform resource, however you may override this setting using <code>.spec.backendConfig.secretSuffix</code>. The default <code>workspace</code> name is \"default\", you can also override the workspace by setting <code>.spec.workspace</code> to another value.</p> <p>If you wish to use a custom backend, you can configure it by defining the <code>.spec.backendConfig.customConfiguration</code> with one of the backends such as GCS or S3, for example:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  backendConfig:\n    customConfiguration: |\n      backend \"s3\" {\n        bucket                      = \"s3-terraform-state1\"\n        key                         = \"dev/terraform.tfstate\"\n        region                      = \"us-east-1\"\n        endpoint                    = \"http://localhost:4566\"\n        skip_credentials_validation = true\n        skip_metadata_api_check     = true\n        force_path_style            = true\n        dynamodb_table              = \"terraformlock\"\n        dynamodb_endpoint           = \"http://localhost:4566\"\n        encrypt                     = true\n      }\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  runnerPodTemplate:\n    spec:\n      image: registry.io/tf-runner:xyz\n</code></pre>"},{"location":"use_tf_controller/with_an_OCI_Artifact_as_Source/","title":"Use TF-controller with an OCI Artifact as Source","text":"<p>To use OCI artifacts as the source of Terraform objects, you need Flux 2 version v0.32.0 or higher.</p> <p>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:</p> <pre><code>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)\"\n\nflux tag artifact oci://ghcr.io/tf-controller/helloworld:$(git rev-parse --short HEAD) \\\n    --tag main\n</code></pre> <p>Then you define a source (<code>OCIRepository</code>), and use it as the <code>sourceRef</code> of your Terraform object.</p> <pre><code>---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\n  name: helloworld-oci\nspec:\n  interval: 1m\n  url: oci://ghcr.io/tf-controller/helloworld\n  ref:\n    tag: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld-tf-oci\nspec:\n  path: ./\n  approvePlan: auto\n  interval: 1m\n  sourceRef:\n    kind: OCIRepository\n    name: helloworld-oci\n  writeOutputsToSecret:\n    name: helloworld-outputs\n</code></pre>"},{"location":"use_tf_controller/with_drift_detection_disabled/","title":"Use TF-controller with drift detection disabled","text":"<p>Drift detection is enabled by default. You can set <code>.spec.disableDriftDetection: true</code> to disable it.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  disableDriftDetection: true\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/with_external_webhooks/","title":"Use TF-Controller with an External Webhooks","text":"<p>The TF-Controller provides a way to integrate with webhooks to further validate Terraform plans and manage the Terraform execution process.  With the webhook feature, you can implement custom policy checks, validations, and other logic to determine if the Terraform process should proceed.</p>"},{"location":"use_tf_controller/with_external_webhooks/#setting-up-the-webhook","title":"Setting up the Webhook","text":"<ol> <li>Webhook URL: Specify the URL of your webhook, ensuring it points to a valid HTTPS endpoint.</li> <li>Expected Return: The webhook should return a valid JSON object. For instance: <pre><code>{\"passed\": true}\n</code></pre></li> <li>Accepted True Values: The true values can be <code>true</code>, <code>\"true\"</code>, and <code>\"yes\"</code>.</li> <li>Accepted False Values: The false values can be <code>flse</code>, <code>\"false\"</code>, and <code>\"no\"</code>.</li> </ol> <p>Below is a breakdown of the relevant parts of the configuration:</p> <ol> <li><code>webhooks:</code> This is the section where you specify all webhook related configurations.</li> <li><code>stage:</code> Define at which stage the webhook will be triggered. Currenly, we support only the <code>post-planning</code> stage.</li> <li><code>url:</code> The URL pointing to your webhook endpoint.</li> <li><code>testExpression:</code> This expression is used to evaluate the response from the webhook. If it evaluates to true, the controller proceeds with the operation. In the example, the expression checks for the passed value from the webhook's JSON response.</li> <li><code>errorMessageTemplate:</code> If testExpression evaluates to false, this template is used to extract the error message from the webhook's JSON response. This message will be displayed to the user.</li> </ol>"},{"location":"use_tf_controller/with_external_webhooks/#configuration-example","title":"Configuration Example","text":"<p>Here's a configuration example on how to use the webhook feature to integrate with Weave Policy Engine. <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld-tf\nspec:\n  path: ./terraform\n  approvePlan: \"auto\"\n  interval: 1m\n  storeReadablePlan: human\n  sourceRef:\n    kind: GitRepository\n    name: helloworld-tf\n  webhooks:\n  - stage: post-planning\n    url: https://policy-agent.policy-system.svc/terraform/admission\n    testExpression: \"${{ .passed }}\"\n    errorMessageTemplate: \"Violation: ${{ (index (index .violations 0).occurrences 0).message }}\"\n  writeOutputsToSecret:\n    name: helloworld-outputs\n</code></pre></p> <p>Important Considerations:</p> <ul> <li>Ensure that your webhook endpoint is secure, as the TF-Controller will be sending potentially sensitive Terraform plan data to it.</li> <li>Test your webhook implementation thoroughly before deploying to production, as any issues could interrupt or halt your Terraform process.</li> </ul> <p>With the webhook feature, you can create a more robust and flexible GitOps Terraform pipeline that respects custom organizational policies and other requirements.</p>"},{"location":"use_tf_controller/with_plan_only_mode/","title":"Use TF-controller with a plan-only mode","text":"<p>This 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 <code>terraform plan</code> only.</p> <p>If <code>planOnly</code> is set to <code>true</code>, the controller will skip the apply part and runs only <code>terraform plan</code> and saves the output.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\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\n</code></pre>"},{"location":"use_tf_controller/with_primitive_modules/","title":"Use TF-controller with primitive modules","text":"<p>This document describes how to use the Weave TF-controller with a primitive module. It requires TF-controller v0.13+ to run the example.</p>"},{"location":"use_tf_controller/with_primitive_modules/#what-is-a-primitive-module","title":"What is a primitive module?","text":"<p>It's a Terraform module that contains only a single resource.</p> <ul> <li>A Terraform primitive module must contains the \"values\" variable.</li> <li>The \"values\" variable must be an object with fields of optional types.</li> <li>The module must be placed under a directory, which is named after the resource.</li> <li>The directory can optionally contain other files, for example the .terraform.lock.hcl.</li> <li>We call a set of primitive modules bundled into an OCI image, a package.</li> </ul>"},{"location":"use_tf_controller/with_primitive_modules/#hello-world-primitive-module","title":"Hello World Primitive Module","text":"<p>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 <code>aws_hello_world</code>, and the image is tagged as <code>ghcr.io/tf-controller/hello-primitive-modules/v4.32.0:v1</code>.</p> <p>We'll use the following Terraform object definition to provision the resource.</p> <p>First, we need to create a Terraform object with the <code>spec.sourceRef.kind</code> field  set to <code>OCIRepository</code> and the <code>spec.sourceRef.name</code> field set to the name of the OCIRepository object.</p> <p>Second, we need to set the <code>spec.path</code> field to the name of the resource, in this case <code>aws_hello_world</code>.</p> <p>Third, we need to set the <code>spec.values</code> 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.</p> <p>Finally, we need to set the <code>spec.approvePlan</code> field to <code>auto</code> to automatically approve the plan.</p> <pre><code>---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\n  name: hello-package-v4.32.0\n  namespace: flux-system\nspec:\n  interval: 30s\n  url: oci://ghcr.io/tf-controller/hello-primitive-modules/v4.32.0\n  ref:\n    tag: v1\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  path: aws_hello_world\n  values:\n    greeting: Hi\n    subject: my world\n  sourceRef:\n    kind: OCIRepository\n    name: hello-package-v4.32.0\n  interval: 1h0m\n  approvePlan: auto\n</code></pre>"},{"location":"use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/","title":"Use TF-controller with Terraform Runners exposed via hostname/subdomain","text":"<p>TF-controller uses the Controller/Runner architecture. The Controller acts as a client, and talks to each Runner's Pod via gRPC over port 30000.</p> <p>TF-controller must thus be able to reliably connect to each Runner's pod regardless of the cluster network topology.</p>"},{"location":"use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/#the-default-runner-dns-resolution","title":"The Default Runner DNS resolution","text":"<p>By default, TF-controller fetches the Runner's pod IP address after it is instantiated (e.g. <code>1.2.3.4</code>).</p> <p>It then transforms the IP address into its <code>IP-based pod DNS A record</code> (e.g. <code>1.2.3.4.&lt;namespace&gt;.pod.&lt;cluster-domain&gt;</code>) which is used to connect to the Runner pod using gRPC protocol.</p> <p>In standard Kubernetes cluster deployment, <code>IP-based pod DNS resolution</code> is usually provided by Coredns and especially the <code>pods</code> option of the Kubernetes plugin.</p> <pre><code>cluster.local {\n    kubernetes {\n        pods verified\n    }\n}\n</code></pre> <p>[!IMPORTANT] The gRPC communication between TF-controller and Runner's pod is secured with mTLS. TF-controller generates a valid wildcard TLS certificate for <code>*.&lt;namespace&gt;.pod.&lt;cluster-domain&gt;</code> hosts on the Runner's namespace. The Runner's pod present this certificate during TLS handshake with TF-controller. </p>"},{"location":"use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/#hostnamesubdomain-runner-dns-resolution","title":"Hostname/Subdomain Runner DNS resolution","text":"<p>The default configuration described above works for standard Kubernetes deployments. It does not work however when the cluster DNS provider do not support <code>IP-based pod DNS resolution</code>. This is the case for <code>GCP Cloud DNS</code> for example.</p> <p>For such setup, you can switch the DNS resolution mode to Hostname/Subdomain. Enabling this option will :</p> <ul> <li>Create a <code>Headless service</code> named <code>tf-runner</code> in each allowed namespace</li> </ul> <p>```yaml hl_lines=\"4-5,8-10\" apiVersion: v1 kind: Service metadata:   name: tf-runner   namespace: hello-world spec:   clusterIP: None   ports:   - name: grpc     port: 30000   selector:     app.kubernetes.io/created-by: tf-controller     app.kubernetes.io/name: tf-runner <pre><code>- Set Runner's pod spec with `hostname: &lt;terraform_object_name&gt;` and `subdomain: tf-runner`\n\n```yaml hl_lines=\"12-13\"\napiVersion: v1\nkind: Pod\n  labels:\n    app.kubernetes.io/created-by: tf-controller\n    app.kubernetes.io/instance: tf-runner-3ac83e0f\n    app.kubernetes.io/name: tf-runner\n    infra.contrib.fluxcd.io/terraform: hello-world\n    tf.weave.works/tls-secret-name: terraform-runner.tls-1693866794\n  name: helloworld-tf-runner\n  namespace: hello-world\nspec:\n  hostname: helloworld\n  subdomain: tf-runner\n  containers:\n  - args:\n    - --grpc-port\n    - \"30000\"\n    - --tls-secret-name\n    - terraform-runner.tls-1693866794\n    - --grpc-max-message-size\n    - \"4\"\n    image: ghcr.io/weaveworks/tf-runner:v0.16.0-rc.2\n    name: tf-runner\n    ports:\n    - containerPort: 30000\n      name: grpc\n    resources:\n      limits:\n        cpu: 500m\n        ephemeral-storage: 1Gi\n        memory: 2Gi\n    securityContext:\n      allowPrivilegeEscalation: false\n      capabilities:\n        drop:\n        - ALL\n      readOnlyRootFilesystem: true\n      runAsNonRoot: true\n      runAsUser: 65532\n      seccompProfile:\n        type: RuntimeDefault\n  preemptionPolicy: PreemptLowerPriority\n  priority: 0\n  schedulerName: gke.io/optimize-utilization-scheduler\n  securityContext:\n    seccompProfile:\n      type: RuntimeDefault\n  serviceAccountName: tf-runner\n</code></pre></p> <p>The Runner's pod can then be targeted by TF-controller using <code>&lt;terraform_object_name&gt;.tf-runner.&lt;namespace&gt;.svc.&lt;cluster-domain&gt; (helloworld.tf-runner.hello-world.svc.cluster.local)</code> as per Kubernetes specification instead of <code>IP-based pod DNS resolution</code>.</p> <p>The switch is performed by setting the following Helm value <code>usePodSubdomainResolution: true</code> or running directly TF-controller with the option <code>--use-pod-subdomain-resolution=true</code></p> <p>[!IMPORTANT] The gRPC communication between TF-controller and Runner's pod is secured with mTLS. TF-controller generates a valid wildcard TLS certificate for <code>*.&lt;namespace&gt;.pod.&lt;cluster-domain&gt;</code> and <code>*.tf-runner.&lt;namespace&gt;.svc.&lt;cluster-domain&gt;</code> hosts on the Runner's namespace. The Runner's pod present this certificate during TLS handshake with TF-controller. </p>"},{"location":"use_tf_controller/with_tf_runner_logging/","title":"Use TF-controller with Terraform Runners enabled via Env Variables","text":"<p>A Terraform Runner uses two environment variables, <code>DISABLE_TF_LOGS</code> and <code>ENABLE_SENSITIVE_TF_LOGS</code>, to control the logging behavior of the Terraform execution.</p> <p>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.</p> <ul> <li>The <code>DISABLE_TF_LOGS</code> variable, when set to \"1\", will disable all Terraform output logs to stdout and stderr.</li> <li>The <code>ENABLE_SENSITIVE_TF_LOGS</code> 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 <code>ENABLE_SENSITIVE_TF_LOGS</code> to take effect, the <code>DISABLE_TF_LOGS</code> variable must also be set to \"1\".</li> </ul>"},{"location":"use_tf_controller/with_tf_runner_logging/#the-default-logging-behavior","title":"The Default Logging Behavior","text":"<ul> <li>By default, the logging level for the <code>tf-runner</code> is configured at the <code>info</code> level.</li> <li>The <code>DISABLE_TF_LOGS</code> variable is not activated as part of the default settings.</li> <li>The <code>ENABLE_SENSITIVE_TF_LOGS</code> variable remains inactive in the default configuration.</li> <li>Calls to <code>ShowPlan</code> and <code>ShowPlanRaw</code> on the runner are not logged by default.</li> <li>For <code>Plan</code> calls made on the runner, error messages are sanitized as a part of the default configuration.</li> </ul> <p>For more information on configuring the Terraform Runner and its environment variables, please consult the documentation on customizing runners within the Weave TF-controller.</p>"},{"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":"<p>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.</p>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#what-is-a-package","title":"What is a package?","text":"<p>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.</p> <p>We will provide a set of ready-to-use packages for the most popular cloud providers. Currently, we ship the package for AWS only.</p>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#aws-package","title":"AWS Package","text":"<p>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 <code>awsPackage.install: false</code> in your Helm chart values.</p> <p>If you run <code>flux get sources oci</code> you should see the AWS package installed in your cluster listed as <code>aws-package</code>.</p> <pre><code>flux get sources oci\nNAME          REVISION                    SUSPENDED   READY   MESSAGE                                                                                                         \naws-package   v4.38.0-v1alpha11/6033f3b   False       True    stored artifact for digest 'v4.38.0-v1alpha11/6033f3b'\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#a-step-by-step-tutorial","title":"A step-by-step tutorial","text":"<p>This section describes how to use the AWS package to provision an S3 bucket with ACL using the TF-controller.</p>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#create-a-kind-local-cluster","title":"Create a KinD local cluster","text":"<p>If you don't have a Kubernetes cluster, you can create a KinD cluster with the following command:</p> <pre><code>kind create cluster\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#install-flux","title":"Install Flux","text":"<p>After you have a Kubernetes cluster, you can install Flux with the following command:</p> <pre><code>flux install\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#install-tf-controller","title":"Install TF-controller","text":"<p>Then, you can install the TF-controller with the following command:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#setup-aws-credentials","title":"Setup AWS credentials","text":"<p>To 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.</p> <pre><code>```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\n</code></pre> <p>To apply the secret, run the following command:</p> <pre><code>kubectl apply -f aws-credentials.yaml\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#setup-aws-bucket-and-acl","title":"Setup AWS Bucket and ACL","text":"<p>Now, 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.</p> <pre><code>```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\n  writeOutputsToSecret:\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 }}\n  sourceRef:\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\n  runnerPodTemplate:\n    spec:\n      envFrom:\n      - secretRef:\n          name: aws-credentials\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#rename-input-secrets","title":"Rename input secrets","text":"<p>The <code>spec.readInputsFromSecrets</code> 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 <code>spec.values</code> field.</p> <p>To rename a secret, you need to use the <code>as</code> key in the <code>spec.readInputsFromSecrets</code> field. The <code>name</code> key corresponds to the original name of the secret,  while the <code>as</code> key represents the new name that you want to use to reference the secret.</p> <p>In the example below, we can reference the bucket value  from our <code>aws_s3_bucket</code> secret using ${{ .aws_s3_bucket.bucket }} instead of using the original secret name, which is <code>aws-s3-bucket-outputs</code>.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: example-bucket-acl\n  namespace: flux-system\nspec:\n  # ...\n  readInputsFromSecrets:\n  - name: aws-s3-bucket-outputs\n    as: aws_s3_bucket\n  values:\n    acl: private\n    bucket: ${{ .aws_s3_bucket.bucket }}\n  # ...\n</code></pre>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Overview","text":"<p>~&gt; BREAKING NEWS: The Technology Preview of the Branch Planner is now available! Learn more or Get started with the Branch Planner.</p> <p>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.</p> <p>\"At your own pace\" means you don't need to GitOps-ify everything at once.</p> <p>TF-controller offers many GitOps models:</p> <ol> <li>GitOps Automation Model: GitOps your Terraform resources from the provision steps to the enforcement steps, like a whole EKS cluster.</li> <li>Hybrid GitOps Automation Model: GitOps parts of your existing infrastructure resources. For example, you have an existing EKS cluster.      You can choose to GitOps only its nodegroup, or its security group.</li> <li>State Enforcement Model: You have a TFSTATE file, and you'd like to use GitOps enforce it, without changing anything else.</li> <li>Drift Detection Model: You have a TFSTATE file, and you'd like to use GitOps just for drift detection, so you can decide to do things later when a drift occurs.</li> </ol> <p>To get started, follow the getting started guide.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Multi-Tenancy: TF-controller supports multi-tenancy by running Terraform <code>plan</code> and <code>apply</code> inside Runner Pods.     When specifying <code>.metadata.namespace</code> and <code>.spec.serviceAccountName</code>, 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.</li> <li>GitOps Automation for Terraform: With setting <code>.spec.approvePlan=auto</code>, it allows a <code>Terraform</code> object     to be reconciled and act as the representation of your Terraform resources. The TF-controller uses the spec of     the <code>Terraform</code> object to perform <code>plan</code>, <code>apply</code> its associated Terraform resources. It then stores     the <code>TFSTATE</code> of the applied resources as a <code>Secret</code> inside the Kubernetes cluster. After <code>.spec.interval</code> 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.</li> <li>Drift detection: This feature is a part of the GitOps automation feature. The controller detects and fixes drift     for your infrastructures, based on the Terraform resources and their <code>TFSTATE</code>. This feature is available since v0.5.0.<ul> <li>Drift detection is enabled by default. You can use the field <code>.spec.disableDriftDetection</code> to disable this behaviour.   This feature is available since v0.7.0.</li> <li>The Drift detection only mode, without plan or apply steps, allows you to perform read-only drift detection.   This feature is available since v0.8.0.</li> </ul> </li> <li>Plan and Manual Approve: This feature allows you to separate the <code>plan</code>, out of the <code>apply</code> 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 <code>.spec.approvePlan</code>, 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.</li> <li>First-class YAML-based Terraform: The <code>Terraform</code> 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 <code>aws_iam_role</code>, or <code>aws_iam_policy</code>.     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.</li> <li>GitOps Dependency for Terraform: The <code>Terraform</code> object in v0.13.0+ allows you to specify a list of <code>Terraform</code> objects     that it depends on. The controller will wait for the dependencies to be ready before it starts to reconcile the     <code>Terraform</code> 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 <code>.spec.retryInterval</code> (a small value like <code>20s</code>) to control      the retry interval when using this feature. This feature is available since v0.13.0.</li> </ul>"},{"location":"#support-matrix","title":"Support Matrix","text":"Version Terraform Source Controller Flux v2 v0.15 v1.3.9 v1.0.x v2.0.x v0.14 v1.3.9 v0.31.0 v0.41.x v0.13 v1.3.1 v0.31.0 v0.36.x v0.12 v1.1.9 v0.26.1 v0.32.x"},{"location":"getting_started/","title":"Getting Started","text":""},{"location":"getting_started/#preflight-checks","title":"Preflight Checks","text":"<p>Here are the requirements you need to set up before you start:</p> <ol> <li>For Terraform Controller v0.15+, it requires Flux v2.0 or later (not only the CLI, but also the controllers on the cluster). If you are not sure about the Flux version on your cluster, please re-bootstrap your cluster.</li> <li>For Terraform Controller v0.13 and v0.14, Flux 2 v0.32 - v0.41 (of course, not only the CLI, but also the controllers on the cluster).</li> <li>TF-controller uses the Controller/Runner architecture. The Controller acts as a client, and talks to each Runner's Pod via gRPC. Please make sure <ol> <li>Each Runner's Pod in each Namespace is allowed to open, and serve at port 30000 (the gRPC port of a Runner), and the Controller can connect to it.</li> <li>The Controller needs to download tar.gz BLOBs from the Source controller via port 80.</li> <li>The Controller needs to post the events to the Notification controller via port 80.</li> </ol> </li> </ol>"},{"location":"getting_started/#installation","title":"Installation","text":"<p>Before using TF-controller, you have to install Flux by using either <code>flux install</code> or <code>flux bootstrap</code> 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:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\n</code></pre> <p>For the most recent release candidate of TF-controller, please use rc.yaml.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml\n</code></pre>"},{"location":"getting_started/#installation-on-gke","title":"Installation on GKE","text":"<p>As of September 2023, GKE Autopilot clusters will use Cloud DNS for internal DNS resolution. This means that the default DNS resolution method used by TF-controller will not work. To use TF-controller on GKE Autopilot, you must set flag <code>--use-pod-subdomain-resolution=true</code> on the TF-controller deployment. This flag can be set by adding the following to the TF-controller HelmRelease:</p> <pre><code>spec:\n  values:\n    usePodSubdomainResolution: true\n    runner:\n      allowedNamespaces:\n      - flux-system\n      - dev-team\n</code></pre> <p>Enabling this value will cause TF-controller to use the Pod's subdomain for DNS resolution instead of the default Pod resolution method. Pod's subdomain resolution requires a Service to be created for the Pod. The HelmRelease above will create a Service named <code>tf-runner</code> in each namespace specified by the <code>runner.allowedNamespaces</code> value.</p> <p>We have provided a HelmRelease to install TF-controller on GKE Autopilot with Pod's subdomain resolution enabled here.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc-gke.yaml\n</code></pre> <p>Tested with GKE Autopilot v1.27.3-gke.100.</p>"},{"location":"getting_started/#with-branch-planner","title":"With Branch Planner","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/release.yaml\n</code></pre> <p>For the most recent release candidate of TF-controller with Branch Planner, please use branch_planner/rc.yaml.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/branch_planner/rc.yaml\n</code></pre> <p>For more details about the Branch Planner, please visit the Branch Planner documentation.</p>"},{"location":"getting_started/#manual-installation","title":"Manual installation","text":"<p>With Helm by:</p> <pre><code># 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\n</code></pre> <p>For details on configurable parameters of the TF-controller chart, please see chart readme.</p> <p>Alternatively, you can install TF-controller via <code>kubectl</code>:</p> <pre><code>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\n</code></pre>"},{"location":"getting_started/#quick-start","title":"Quick start","text":"<p>Here's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.</p>"},{"location":"getting_started/#define-source","title":"Define source","text":"<p>First, we need to define a Source controller's source (<code>GitRepository</code>, <code>Bucket</code>, <code>OCIRepository</code>), for example:</p> <pre><code>apiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  interval: 30s\n  url: https://github.com/tf-controller/helloworld\n  ref:\n    branch: main\n</code></pre>"},{"location":"getting_started/#the-gitops-automation-mode","title":"The GitOps Automation mode","text":"<p>The GitOps automation mode could be enabled by setting <code>.spec.approvePlan=auto</code>. In this mode, Terraform resources will be planned, and automatically applied for you.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  interval: 1m\n  approvePlan: auto\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre> <p>For a full list of features and how to use them, please follow the Use TF-controller guide.</p>"},{"location":"getting_started/#other-examples","title":"Other Examples","text":"<ul> <li>A Terraform GitOps with Flux to automatically reconcile your AWS IAM Policies.</li> <li>GitOps an existing EKS cluster, by partially import its nodegroup and manage it with TF-controller: An EKS scaling example.</li> </ul>"},{"location":"tfctl/","title":"tfctl","text":"<p><code>tfctl</code> is a command-line utility to help with tf-controller operations.</p>"},{"location":"tfctl/#installation","title":"Installation","text":"<p>To install <code>tfctl</code> via Homebrew, run the following command:</p> <pre><code>brew install weaveworks/tap/tfctl\n</code></pre> <p>You can also download the <code>tfctl</code> binary via the GitHub releases page: https://github.com/weaveworks/tf-controller/releases.</p> <pre><code>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.\n</code></pre>"},{"location":"References/terraform/","title":"API References","text":"Terraform API reference <p>Packages:</p> <ul> <li> infra.contrib.fluxcd.io/v1alpha2 </li> </ul>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2","title":"infra.contrib.fluxcd.io/v1alpha2","text":"<p>Resource Types:</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigSpec","title":"BackendConfigSpec","text":"<p> (Appears on: TerraformSpec) </p> <p>BackendConfigSpec is for specifying configuration for Terraform\u2019s Kubernetes backend</p> Field Description <code>disable</code>  bool  (Optional) <p>Disable is to completely disable the backend configuration.</p> <code>secretSuffix</code>  string  (Optional) <code>inClusterConfig</code>  bool  (Optional) <code>customConfiguration</code>  string  (Optional) <code>configPath</code>  string  (Optional) <code>labels</code>  map[string]string  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BackendConfigsReference","title":"BackendConfigsReference","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>kind</code>  string  <p>Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).</p> <code>name</code>  string  <p>Name of the configs referent. Should reside in the same namespace as the referring resource.</p> <code>keys</code>  []string  (Optional) <p>Keys is the data key where a specific value can be found at. Defaults to all keys.</p> <code>optional</code>  bool  (Optional) <p>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.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.BranchPlanner","title":"BranchPlanner","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>enablePathScope</code>  bool  (Optional) <p>EnablePathScope specifies if the Branch Planner should or shouldn\u2019t check if a Pull Request has changes under <code>.spec.path</code>. If enabled extra resources will be created only if there are any changes in terraform files.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudSpec","title":"CloudSpec","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>organization</code>  string  <code>workspaces</code>  CloudWorkspacesSpec  <code>hostname</code>  string  (Optional) <code>token</code>  string  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CloudWorkspacesSpec","title":"CloudWorkspacesSpec","text":"<p> (Appears on: CloudSpec) </p> Field Description <code>name</code>  string  (Optional) <code>tags</code>  []string  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.CrossNamespaceSourceReference","title":"CrossNamespaceSourceReference","text":"<p> (Appears on: TerraformSpec) </p> <p>CrossNamespaceSourceReference contains enough information to let you locate the typed Kubernetes resource object at cluster level.</p> Field Description <code>apiVersion</code>  string  (Optional) <p>API version of the referent.</p> <code>kind</code>  string  <p>Kind of the referent.</p> <code>name</code>  string  <p>Name of the referent.</p> <code>namespace</code>  string  (Optional) <p>Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.FileMapping","title":"FileMapping","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>secretRef</code>  github.com/fluxcd/pkg/apis/meta.SecretKeyReference  <p>Reference to a Secret that contains the file content</p> <code>location</code>  string  <p>Location can be either user\u2019s home directory or the Terraform workspace</p> <code>path</code>  string  <p>Path of the file - relative to the \u201clocation\u201d</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ForceUnlockEnum","title":"ForceUnlockEnum (<code>string</code> alias)","text":"<p> (Appears on: TFStateSpec) </p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.HealthCheck","title":"HealthCheck","text":"<p> (Appears on: TerraformSpec) </p> <p>HealthCheck contains configuration needed to perform a health check after terraform is applied.</p> Field Description <code>name</code>  string  <p>Name of the health check.</p> <code>type</code>  string  <p>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.</p> <code>url</code>  string  (Optional) <p>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}}).</p> <code>address</code>  string  (Optional) <p>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}}).</p> <code>timeout</code>  Kubernetes meta/v1.Duration  (Optional) <p>The timeout period at which the connection should timeout if unable to complete the request. When not specified, default 20s timeout is used.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.LockStatus","title":"LockStatus","text":"<p> (Appears on: TerraformStatus) </p> <p>LockStatus defines the observed state of a Terraform State Lock</p> Field Description <code>lastApplied</code>  string  (Optional) <code>pending</code>  string  (Optional) <p>Pending holds the identifier of the Lock Holder to be used with Force Unlock</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.PlanStatus","title":"PlanStatus","text":"<p> (Appears on: TerraformStatus) </p> Field Description <code>lastApplied</code>  string  (Optional) <code>pending</code>  string  (Optional) <code>isDestroyPlan</code>  bool  (Optional) <code>isDriftDetectionPlan</code>  bool  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ReadInputsFromSecretSpec","title":"ReadInputsFromSecretSpec","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>name</code>  string  <code>as</code>  string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Remediation","title":"Remediation","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>retries</code>  int64  (Optional) <p>Retries is the number of retries that should be attempted on failures before bailing. Defaults to \u20180\u2019, a negative integer denotes unlimited retries.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceInventory","title":"ResourceInventory","text":"<p> (Appears on: TerraformStatus) </p> <p>ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.</p> Field Description <code>entries</code>  []ResourceRef  <p>Entries of Kubernetes resource object references.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.ResourceRef","title":"ResourceRef","text":"<p> (Appears on: ResourceInventory) </p> <p>ResourceRef contains the information necessary to locate a resource within a cluster.</p> Field Description <code>n</code>  string  <p>Terraform resource\u2019s name.</p> <code>t</code>  string  <p>Type is Terraform resource\u2019s type</p> <code>id</code>  string  <p>ID is the resource identifier. This is cloud-specific. For example, ARN is an ID on AWS.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodMetadata","title":"RunnerPodMetadata","text":"<p> (Appears on: RunnerPodTemplate) </p> Field Description <code>labels</code>  map[string]string  (Optional) <p>Labels to add to the runner pod</p> <code>annotations</code>  map[string]string  (Optional) <p>Annotations to add to the runner pod</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodSpec","title":"RunnerPodSpec","text":"<p> (Appears on: RunnerPodTemplate) </p> Field Description <code>image</code>  string  (Optional) <p>Runner pod image to use other than default</p> <code>envFrom</code>  []Kubernetes core/v1.EnvFromSource  (Optional) <p>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.</p> <code>env</code>  []Kubernetes core/v1.EnvVar  (Optional) <p>List of environment variables to set in the container. Cannot be updated.</p> <code>nodeSelector</code>  map[string]string  (Optional) <p>Set the NodeSelector for the Runner Pod</p> <code>affinity</code>  Kubernetes core/v1.Affinity  (Optional) <p>Set the Affinity for the Runner Pod</p> <code>tolerations</code>  []Kubernetes core/v1.Toleration  (Optional) <p>Set the Tolerations for the Runner Pod</p> <code>volumeMounts</code>  []Kubernetes core/v1.VolumeMount  (Optional) <p>Set Volume Mounts for the Runner Pod</p> <code>volumes</code>  []Kubernetes core/v1.Volume  (Optional) <p>Set Volumes for the Runner Pod</p> <code>initContainers</code>  []Kubernetes core/v1.Container  (Optional) <p>Set up Init Containers for the Runner</p> <code>hostAliases</code>  []Kubernetes core/v1.HostAlias  (Optional) <p>Set host aliases for the Runner Pod</p> <code>priorityClassName</code>  string  (Optional) <p>Set PriorityClassName for the Runner Pod container</p> <code>securityContext</code>  Kubernetes core/v1.SecurityContext  (Optional) <p>Set SecurityContext for the Runner Pod container</p> <code>resources</code>  Kubernetes core/v1.ResourceRequirements  (Optional) <p>Set Resources for the Runner Pod container</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.RunnerPodTemplate","title":"RunnerPodTemplate","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>metadata</code>  RunnerPodMetadata  (Optional) <code>spec</code>  RunnerPodSpec  (Optional) <code>image</code>  string  (Optional) <p>Runner pod image to use other than default</p> <code>envFrom</code>  []Kubernetes core/v1.EnvFromSource  (Optional) <p>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.</p> <code>env</code>  []Kubernetes core/v1.EnvVar  (Optional) <p>List of environment variables to set in the container. Cannot be updated.</p> <code>nodeSelector</code>  map[string]string  (Optional) <p>Set the NodeSelector for the Runner Pod</p> <code>affinity</code>  Kubernetes core/v1.Affinity  (Optional) <p>Set the Affinity for the Runner Pod</p> <code>tolerations</code>  []Kubernetes core/v1.Toleration  (Optional) <p>Set the Tolerations for the Runner Pod</p> <code>volumeMounts</code>  []Kubernetes core/v1.VolumeMount  (Optional) <p>Set Volume Mounts for the Runner Pod</p> <code>volumes</code>  []Kubernetes core/v1.Volume  (Optional) <p>Set Volumes for the Runner Pod</p> <code>initContainers</code>  []Kubernetes core/v1.Container  (Optional) <p>Set up Init Containers for the Runner</p> <code>hostAliases</code>  []Kubernetes core/v1.HostAlias  (Optional) <p>Set host aliases for the Runner Pod</p> <code>priorityClassName</code>  string  (Optional) <p>Set PriorityClassName for the Runner Pod container</p> <code>securityContext</code>  Kubernetes core/v1.SecurityContext  (Optional) <p>Set SecurityContext for the Runner Pod container</p> <code>resources</code>  Kubernetes core/v1.ResourceRequirements  (Optional) <p>Set Resources for the Runner Pod container</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TFStateSpec","title":"TFStateSpec","text":"<p> (Appears on: TerraformSpec) </p> <p>TFStateSpec allows the user to set ForceUnlock</p> Field Description <code>forceUnlock</code>  ForceUnlockEnum  (Optional) <p>ForceUnlock a Terraform state if it has become locked for any reason. Defaults to <code>no</code>.</p> <p>This is an Enum and has the expected values of:</p> <ul> <li>auto</li> <li>yes</li> <li>no</li> </ul> <p>WARNING: Only use <code>auto</code> 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.</p> <code>lockIdentifier</code>  string  (Optional) <p>LockIdentifier holds the Identifier required by Terraform to unlock the state if it ever gets into a locked state.</p> <p>You\u2019ll need to put the Lock Identifier in here while setting ForceUnlock to either <code>yes</code> or <code>auto</code>.</p> <p>Leave this empty to do nothing, set this to the value of the <code>Lock Info: ID: [value]</code>, e.g. <code>f2ab685b-f84d-ac0b-a125-378a22877e8d</code>, to force unlock the state.</p> <code>lockTimeout</code>  Kubernetes meta/v1.Duration  (Optional) <p>LockTimeout is a Duration string that instructs Terraform to retry acquiring a lock for the specified period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as <code>3s</code> for three seconds.</p> <p>Defaults to <code>0s</code> which will behave as though <code>LockTimeout</code> was not set</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Terraform","title":"Terraform","text":"<p>Terraform is the Schema for the terraforms API</p> Field Description <code>metadata</code>  Kubernetes meta/v1.ObjectMeta   Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.  <code>spec</code>  TerraformSpec  <code>approvePlan</code>  string  (Optional) <p>ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.</p> <code>destroy</code>  bool  (Optional) <p>Destroy produces a destroy plan. Applying the plan will destroy all resources.</p> <code>backendConfig</code>  BackendConfigSpec  (Optional) <code>backendConfigsFrom</code>  []BackendConfigsReference  (Optional) <code>cloud</code>  CloudSpec  (Optional) <code>workspace</code>  string  (Optional) <code>vars</code>  []Variable  (Optional) <p>List of input variables to set for the Terraform program.</p> <code>varsFrom</code>  []VarsReference  (Optional) <p>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.</p> <code>values</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>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.</p> <code>fileMappings</code>  []FileMapping  (Optional) <p>List of all configuration files to be created in initialization.</p> <code>interval</code>  Kubernetes meta/v1.Duration  <p>The interval at which to reconcile the Terraform.</p> <code>retryInterval</code>  Kubernetes meta/v1.Duration  (Optional) <p>The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.</p> <code>path</code>  string  (Optional) <p>Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.</p> <code>sourceRef</code>  CrossNamespaceSourceReference  <p>SourceRef is the reference of the source where the Terraform files are stored.</p> <code>suspend</code>  bool  (Optional) <p>Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.</p> <code>force</code>  bool  (Optional) <p>Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.</p> <code>readInputsFromSecrets</code>  []ReadInputsFromSecretSpec  (Optional) <code>writeOutputsToSecret</code>  WriteOutputsToSecretSpec  (Optional) <p>A list of target secrets for the outputs to be written as.</p> <code>disableDriftDetection</code>  bool  (Optional) <p>Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.</p> <code>cliConfigSecretRef</code>  Kubernetes core/v1.SecretReference  (Optional) <code>healthChecks</code>  []HealthCheck  (Optional) <p>List of health checks to be performed.</p> <code>destroyResourcesOnDeletion</code>  bool  (Optional) <p>Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.</p> <code>serviceAccountName</code>  string  (Optional) <p>Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.</p> <code>alwaysCleanupRunnerPod</code>  bool  (Optional) <p>Clean the runner pod up after each reconciliation cycle</p> <code>runnerTerminationGracePeriodSeconds</code>  int64  (Optional) <p>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.</p> <code>refreshBeforeApply</code>  bool  (Optional) <p>RefreshBeforeApply forces refreshing of the state before the apply step.</p> <code>runnerPodTemplate</code>  RunnerPodTemplate  (Optional) <code>enableInventory</code>  bool  (Optional) <p>EnableInventory enables the object to store resource entries as the inventory for external use.</p> <code>tfstate</code>  TFStateSpec  (Optional) <code>targets</code>  []string  (Optional) <p>Targets specify the resource, module or collection of resources to target.</p> <code>parallelism</code>  int32  (Optional) <p>Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.</p> <code>storeReadablePlan</code>  string  (Optional) <p>StoreReadablePlan enables storing the plan in a readable format.</p> <code>webhooks</code>  []Webhook  (Optional) <code>dependsOn</code>  []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference  (Optional) <code>enterprise</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>Enterprise is the enterprise configuration placeholder.</p> <code>planOnly</code>  bool  (Optional) <p>PlanOnly specifies if the reconciliation should or should not stop at plan phase.</p> <code>breakTheGlass</code>  bool  (Optional) <p>BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.</p> <code>branchPlanner</code>  BranchPlanner  (Optional) <p>BranchPlanner configuration.</p> <code>remediation</code>  Remediation  (Optional) <p>Remediation specifies what the controller should do when reconciliation fails. The default is to not perform any action.</p> <code>status</code>  TerraformStatus"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformSpec","title":"TerraformSpec","text":"<p> (Appears on: Terraform) </p> <p>TerraformSpec defines the desired state of Terraform</p> Field Description <code>approvePlan</code>  string  (Optional) <p>ApprovePlan specifies name of a plan wanted to approve. If its value is \u201cauto\u201d, the controller will automatically approve every plan.</p> <code>destroy</code>  bool  (Optional) <p>Destroy produces a destroy plan. Applying the plan will destroy all resources.</p> <code>backendConfig</code>  BackendConfigSpec  (Optional) <code>backendConfigsFrom</code>  []BackendConfigsReference  (Optional) <code>cloud</code>  CloudSpec  (Optional) <code>workspace</code>  string  (Optional) <code>vars</code>  []Variable  (Optional) <p>List of input variables to set for the Terraform program.</p> <code>varsFrom</code>  []VarsReference  (Optional) <p>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.</p> <code>values</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>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.</p> <code>fileMappings</code>  []FileMapping  (Optional) <p>List of all configuration files to be created in initialization.</p> <code>interval</code>  Kubernetes meta/v1.Duration  <p>The interval at which to reconcile the Terraform.</p> <code>retryInterval</code>  Kubernetes meta/v1.Duration  (Optional) <p>The interval at which to retry a previously failed reconciliation. The default value is 15 when not specified.</p> <code>path</code>  string  (Optional) <p>Path to the directory containing Terraform (.tf) files. Defaults to \u2018None\u2019, which translates to the root path of the SourceRef.</p> <code>sourceRef</code>  CrossNamespaceSourceReference  <p>SourceRef is the reference of the source where the Terraform files are stored.</p> <code>suspend</code>  bool  (Optional) <p>Suspend is to tell the controller to suspend subsequent TF executions, it does not apply to already started executions. Defaults to false.</p> <code>force</code>  bool  (Optional) <p>Force instructs the controller to unconditionally re-plan and re-apply TF resources. Defaults to false.</p> <code>readInputsFromSecrets</code>  []ReadInputsFromSecretSpec  (Optional) <code>writeOutputsToSecret</code>  WriteOutputsToSecretSpec  (Optional) <p>A list of target secrets for the outputs to be written as.</p> <code>disableDriftDetection</code>  bool  (Optional) <p>Disable automatic drift detection. Drift detection may be resource intensive in the context of a large cluster or complex Terraform statefile. Defaults to false.</p> <code>cliConfigSecretRef</code>  Kubernetes core/v1.SecretReference  (Optional) <code>healthChecks</code>  []HealthCheck  (Optional) <p>List of health checks to be performed.</p> <code>destroyResourcesOnDeletion</code>  bool  (Optional) <p>Create destroy plan and apply it to destroy terraform resources upon deletion of this object. Defaults to false.</p> <code>serviceAccountName</code>  string  (Optional) <p>Name of a ServiceAccount for the runner Pod to provision Terraform resources. Default to tf-runner.</p> <code>alwaysCleanupRunnerPod</code>  bool  (Optional) <p>Clean the runner pod up after each reconciliation cycle</p> <code>runnerTerminationGracePeriodSeconds</code>  int64  (Optional) <p>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.</p> <code>refreshBeforeApply</code>  bool  (Optional) <p>RefreshBeforeApply forces refreshing of the state before the apply step.</p> <code>runnerPodTemplate</code>  RunnerPodTemplate  (Optional) <code>enableInventory</code>  bool  (Optional) <p>EnableInventory enables the object to store resource entries as the inventory for external use.</p> <code>tfstate</code>  TFStateSpec  (Optional) <code>targets</code>  []string  (Optional) <p>Targets specify the resource, module or collection of resources to target.</p> <code>parallelism</code>  int32  (Optional) <p>Parallelism limits the number of concurrent operations of Terraform apply step. Zero (0) means using the default value.</p> <code>storeReadablePlan</code>  string  (Optional) <p>StoreReadablePlan enables storing the plan in a readable format.</p> <code>webhooks</code>  []Webhook  (Optional) <code>dependsOn</code>  []github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference  (Optional) <code>enterprise</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <p>Enterprise is the enterprise configuration placeholder.</p> <code>planOnly</code>  bool  (Optional) <p>PlanOnly specifies if the reconciliation should or should not stop at plan phase.</p> <code>breakTheGlass</code>  bool  (Optional) <p>BreakTheGlass specifies if the reconciliation should stop and allow interactive shell in case of emergency.</p> <code>branchPlanner</code>  BranchPlanner  (Optional) <p>BranchPlanner configuration.</p> <code>remediation</code>  Remediation  (Optional) <p>Remediation specifies what the controller should do when reconciliation fails. The default is to not perform any action.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.TerraformStatus","title":"TerraformStatus","text":"<p> (Appears on: Terraform) </p> <p>TerraformStatus defines the observed state of Terraform</p> Field Description <code>ReconcileRequestStatus</code>  github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus  <p> (Members of <code>ReconcileRequestStatus</code> are embedded into this type.) </p> <code>observedGeneration</code>  int64  (Optional) <p>ObservedGeneration is the last reconciled generation.</p> <code>conditions</code>  []Kubernetes meta/v1.Condition  (Optional) <code>lastAppliedRevision</code>  string  (Optional) <p>The last successfully applied revision. The revision format for Git sources is /. <code>lastAttemptedRevision</code>  string  (Optional) <p>LastAttemptedRevision is the revision of the last reconciliation attempt.</p> <code>lastPlannedRevision</code>  string  (Optional) <p>LastPlannedRevision is the revision used by the last planning process. The result could be either no plan change or a new plan generated.</p> <code>lastPlanAt</code>  Kubernetes meta/v1.Time  (Optional) <p>LastPlanAt is the time when the last terraform plan was performed</p> <code>lastDriftDetectedAt</code>  Kubernetes meta/v1.Time  (Optional) <p>LastDriftDetectedAt is the time when the last drift was detected</p> <code>lastAppliedByDriftDetectionAt</code>  Kubernetes meta/v1.Time  (Optional) <p>LastAppliedByDriftDetectionAt is the time when the last drift was detected and terraform apply was performed as a result</p> <code>availableOutputs</code>  []string  (Optional) <code>plan</code>  PlanStatus  (Optional) <code>inventory</code>  ResourceInventory  (Optional) <p>Inventory contains the list of Terraform resource object references that have been successfully applied.</p> <code>lock</code>  LockStatus  (Optional) <code>reconciliationFailures</code>  int64  (Optional) <p>ReconciliationFailures is the number of reconciliation failures since the last success or update.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Variable","title":"Variable","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>name</code>  string  <p>Name is the name of the variable</p> <code>value</code>  Kubernetes pkg/apis/apiextensions/v1.JSON  (Optional) <code>valueFrom</code>  Kubernetes core/v1.EnvVarSource  (Optional)"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.VarsReference","title":"VarsReference","text":"<p> (Appears on: TerraformSpec) </p> <p>VarsReference contain a reference of a Secret or a ConfigMap to generate variables for Terraform resources based on its data, selectively by varsKey.</p> Field Description <code>kind</code>  string  <p>Kind of the values referent, valid values are (\u2018Secret\u2019, \u2018ConfigMap\u2019).</p> <code>name</code>  string  <p>Name of the values referent. Should reside in the same namespace as the referring resource.</p> <code>varsKeys</code>  []string  (Optional) <p>VarsKeys is the data key at which a specific value can be found. Defaults to all keys.</p> <code>optional</code>  bool  (Optional) <p>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.</p>"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.Webhook","title":"Webhook","text":"<p> (Appears on: TerraformSpec) </p> Field Description <code>stage</code>  string  <code>enabled</code>  bool  (Optional) <code>url</code>  string  <code>payloadType</code>  string  (Optional) <code>errorMessageTemplate</code>  string  (Optional) <code>testExpression</code>  string"},{"location":"References/terraform/#infra.contrib.fluxcd.io/v1alpha2.WriteOutputsToSecretSpec","title":"WriteOutputsToSecretSpec","text":"<p> (Appears on: TerraformSpec) </p> <p>WriteOutputsToSecretSpec defines where to store outputs, and which outputs to be stored.</p> Field Description <code>name</code>  string  <p>Name is the name of the Secret to be written</p> <code>labels</code>  map[string]string  (Optional) <p>Labels to add to the outputted secret</p> <code>annotations</code>  map[string]string  (Optional) <p>Annotations to add to the outputted secret</p> <code>outputs</code>  []string  (Optional) <p>Outputs contain the selected names of outputs to be written to the secret. Empty array means writing all outputs, which is default.</p> <p>This page was automatically generated with <code>gen-crd-api-reference-docs</code></p>"},{"location":"adr/0000-template/","title":"0. Title","text":"<ul> <li>Status: [proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005] </li> <li>Date: 2020-10-29 [YYY-MM-DD - date of the decision] </li> <li>Authors: [list of GitHub handles for the authors]</li> <li>Deciders: [list of GitHub handles for those that made the decision]  </li> </ul>"},{"location":"adr/0000-template/#context","title":"Context","text":""},{"location":"adr/0000-template/#decision","title":"Decision","text":""},{"location":"adr/0000-template/#consequences","title":"Consequences","text":""},{"location":"adr/0000-use-adrs-for-decisions/","title":"1. Use ADRs to record decisions","text":"<ul> <li>Status: proposed</li> <li>Date: 2023-06-20</li> <li>Authors: @yitsushi</li> <li>Deciders: @yitsushi @chanwit @yiannistri</li> </ul>"},{"location":"adr/0000-use-adrs-for-decisions/#context","title":"Context","text":"<p>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.</p>"},{"location":"adr/0000-use-adrs-for-decisions/#decision","title":"Decision","text":"<p>The project will use Architectural Decision Records (ADR) to record decisions that are made outside of a proposal.</p> <p>A template has been created based on prior work:</p> <ul> <li>https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions</li> <li>https://adr.github.io/madr/</li> </ul>"},{"location":"adr/0000-use-adrs-for-decisions/#consequences","title":"Consequences","text":"<p>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.</p>"},{"location":"adr/0001-pr-polling-workflow/","title":"1. Pull Request Polling","text":"<ul> <li>Status: proposed</li> <li>Date: 2023-06-20 </li> <li>Authors: @yitsushi</li> <li>Deciders: @yitsushi @chanwit @yiannistri</li> </ul>"},{"location":"adr/0001-pr-polling-workflow/#context","title":"Context","text":"<p>To detect pull request changes, we can use webhooks or polling using GitHub's API.</p>"},{"location":"adr/0001-pr-polling-workflow/#decision","title":"Decision","text":"<p>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.</p> <p>The Branch-Based Planner has two components:</p> <ol> <li>Polling Server: Detect Pull Request changes and manage Teraform resource    state.</li> <li>Informer: Make a comment when new plan output is available.</li> </ol>"},{"location":"adr/0001-pr-polling-workflow/#consequences","title":"Consequences","text":"<p>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.</p>"},{"location":"adr/0002-deny-cross-ns-by-default/","title":"2. Deny cross-namespace refs by default","text":"<ul> <li>Status: [ proposed | rejected | accepted | deprecated ]</li> <li>Date: 2023-07-18</li> <li>Authors: @squaremo</li> <li>Deciders: [list of GitHub handles for those that made the decision]</li> </ul>"},{"location":"adr/0002-deny-cross-ns-by-default/#context","title":"Context","text":"<p>Like Flux, the tf-controller API has a handful of places where it accepts cross-namespace references.</p> <ul> <li><code>Terraform.spec.sourceRef</code> -- refers to the Flux source object with    the Terraform program</li> <li><code>Terraform.spec.dependsOn[]</code> -- refers to other objects that must    be ready before this object can be run</li> <li><code>.data.resources[]</code> -- in the config struct used by the branch    planner</li> </ul> <p>In general in Kubernetes, references to objects in other namespaces are frowned upon, because</p> <ul> <li>they break namespace isolation assurances; and,</li> <li>they encourage the proliferation of permissions.</li> </ul> <p>Both of these effects make a system less secure.</p> <p>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.</p>"},{"location":"adr/0002-deny-cross-ns-by-default/#decision","title":"Decision","text":"<p>Deny cross-namespace references by default, but allow them to be enabled with a flag.</p> <p>So that the default value means the right thing, the flag name must be <code>enable-cross-namespace-refs</code>, and the default <code>false</code>. To avoid confusion when people try to use the Flux version of this flag <code>--disable-cross-namespace-refs</code>, it should be supported too, but only respected if supplied.</p>"},{"location":"adr/0002-deny-cross-ns-by-default/#consequences","title":"Consequences","text":"<p>The changed default will break deployments that rely on cross-namespace refs, but they are easily fixed with the flag.</p> <p>New deployments will be more secure, by default.</p>"},{"location":"adr/0003-workspace-blob-caching/","title":"3. Workspace BLOB Caching","text":"<ul> <li>Status: [ proposed | rejected | accepted | deprecated ]</li> <li>Date: 2023-09-20 </li> <li>Authors: @chanwit</li> <li>Deciders: TBD </li> </ul>"},{"location":"adr/0003-workspace-blob-caching/#context","title":"Context","text":"<p>The TF-Controller currently faces challenges related to the deletion of Terraform resources. These problems span across three categories:</p> <ol> <li>Single object deletion,</li> <li>Resources with dependencies deletion, and</li> <li>Namespace deletion.</li> </ol> <p>These problems must be fixed in the above order as (2) and (3) require single object deletion to be resolved first.</p> <p>Deleting a single TF object can sometimes be obstructed because it's tied to other resources like Source objects, Secrets, and ConfigMaps. If we try to remove it without deleting these resources, the TF object gets stuck in an inconsistent state, making it harder for users to manage their infrastructure smoothly. Therefore, the TF-Controller is being enhanced to address this problem more efficiently, using the contents of generated Workspace BLOBs. Each BLOB contains all necessary information from the associated Source, Secrets, and ConfigMaps to ensure that TF-Controller finalization procedures can delete objects correctly.</p> <p>Currently, the TF-Controller downloads a Source BLOB and pushes it to a tf-runner. The tf-runner processes this BLOB to create a Workspace file system. It generates a backend configuration file, variable files, and other necessary files for the Workspace file system, using data from associated Secrets and ConfigMaps. This newly created Workspace file system is then compressed, sent back to the TF-Controller, and stored as a Workspace BLOB in the controller's storage. A caching mechanism for these BLOBs is essential to fixing the single TF object deletion process.</p>"},{"location":"adr/0003-workspace-blob-caching/#decision","title":"Decision","text":"<ol> <li>BLOB Creation and Storage</li> <li>A gRPC function named <code>CreateWorkspaceBlob</code> will be invoked by the TF-Controller       to tell tf-runner to compress the Workspace file system into a tar.gz BLOB, which is then retrieved back to the controller.</li> <li>The caching mechanism will be executed right before the Terraform Initialization step, ensuring that the latest and most relevant data is used.</li> <li>Each Workspace Blob will be cached on the TF-Controller's local disk, using the UUID of the Terraform object as the filename,<code>${uuid}.tar.gz</code>.</li> <li>To reduce the risk of unauthorized access to the cache entries, and cache collisions, the cache file will be deleted after the finalization process is complete.</li> <li>Persistence </li> <li>The persistence mechanism used by the Source Controller will be adopted for the TF-Controller's persistence volume.</li> <li>BLOB Encryption</li> <li>The encryption and decryption of the BLOBs will be tasked to the runner, with the controller solely responsible for storing encrypted BLOBs.</li> <li>Each namespace will require a service account, preferably named \"tf-runner\".</li> <li>The token of this service account, which is natively supported by Kubernetes, will serve as the most appropriate encryption key because it's stored in a Secret, access to which can be controlled by RBAC. Storing it in a Secret also allows the key to be rotated.</li> <li>Security Measures (Based on STRIDE Analysis)</li> <li>Spoofing: Implement Kubernetes RBAC for access restrictions and use mutual authentication for gRPC communications.</li> <li>Tampering: Use checksums for integrity verification and 0600 permissions to write-protect local disk storage.</li> <li>Repudiation: Ensure strong logging and auditing mechanisms for tracking activities.</li> <li>Information Disclosure: Utilize robust encryption algorithms, rotate encryption keys periodically, and secure service account tokens.</li> <li>Denial of Service: Monitor storage space and automate cleanup processes.</li> <li>Elevation of Privilege: Minimize permissions associated with service account tokens.</li> <li>First MVP &amp; Future Planning</li> <li>For the initial MVP, the default pod local volume will be used.</li> <li>Since a controller restart will erase the BLOB cache, consideration for using persistent volumes should be made for subsequent versions.</li> </ol>"},{"location":"adr/0003-workspace-blob-caching/#consequence","title":"Consequence","text":"<ol> <li>With the implementation of this architecture:</li> <li>Single object deletions will succeed in circumstances in which they previously got stuck.</li> <li>Security measures will ensure the safety of the new Workspace BLOB storage mechanics, minimizing potential risks.</li> <li>Using the default pod local volume might limit storage capabilities and risk data loss upon controller restart. This warrants the need for considering persistent volumes in future versions.</li> <li>Encryption and security measures will demand regular maintenance and monitoring, especially concerning key rotations and integrity checks.</li> </ol>"},{"location":"branch_planner/","title":"Branch Planner Overview","text":"<p>The GitOps methodology streamlines infrastructure provisioning and management, using Git as the source of truth. The Branch Planner, a component of TF-Controller, aims to take this a step further by allowing developers and operations teams to plan Terraform configurations on a branch that's separate from the <code>main</code> branch. This makes it easier to review and understand the potential impact of your changes before you run <code>terraform apply</code>.</p> <p>The Branch Planner's most important feature is its seamless integration with the PR (Pull Request) user interface. When enabled through Helm values, it watches repositories that contain Terraform resources at regular intervals\u2014checking their referenced Source, and polling for Pull Requests using GitHub's API and the provided token. When changes are proposed on a new branch, Branch Planner runs a plan in the cluster and displays the results directly as comments on your PR. Once you're satisfied with the results, you can merge your branch into the <code>main</code> branch to trigger the TF-Controller to reconcile the updated code.</p> <p></p>"},{"location":"branch_planner/#replan-commands","title":"Replan commands","text":"<p>The Branch Planner also allows users to manually trigger the replan process. By simply commenting <code>!replan</code> under the PR, the Branch Planner will be instructed to generate a new plan and post it under the PR as a new comment.</p> <p>Now that you know what Branch Planner can do for you, follow the guide to get started.</p>"},{"location":"branch_planner/branch-planner-getting-started/","title":"Getting Started With Branch Planner","text":""},{"location":"branch_planner/branch-planner-getting-started/#prerequisites","title":"Prerequisites","text":"<ol> <li>Flux is installed on the cluster.</li> <li>A GitHub API token. For public repositories, it's sufficient to enable <code>Public Repositories</code> without any additional permissions. For private repositories, you need the following permissions:</li> <li><code>Pull requests</code> with Read-Write access. This is required to check Pull Request   changes, list comments, and create or update comments.</li> <li><code>Metadata</code> with Read-only access. This is automatically marked as \"mandatory\"   because of the permissions listed above.</li> <li>General knowledge about TF-Controller (see docs).</li> </ol>"},{"location":"branch_planner/branch-planner-getting-started/#quick-start","title":"Quick Start","text":"<p>This section describes how to install Branch Planner using a HelmRelease object in the <code>flux-system</code> namespace with minimum configuration on a KinD cluster.</p> <ol> <li> <p>Create a KinD cluster. <pre><code>kind create cluster\n</code></pre></p> </li> <li> <p>Install Flux. Make sure you have the latest version of Flux (v2 GA).</p> </li> </ol> <pre><code>flux install\n</code></pre> <ol> <li>Create a secret that contains a GitHub API token. If you do not use the <code>gh</code> CLI, copy and paste the token from GitHub's website.</li> </ol> <pre><code>export GITHUB_TOKEN=$(gh auth token)\n\nkubectl create secret generic branch-planner-token \\\n    --namespace=flux-system \\\n    --from-literal=\"token=${GITHUB_TOKEN}\"\n</code></pre> <ol> <li>Install Branch Planner from a HelmRelease provided by the TF-Controller repository. Use TF-Controller v0.16.0-rc.2 or later.</li> </ol> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/fa4b3b85d316340d897fda4fed757265ba2cd30e/docs/branch_planner/release.yaml\n</code></pre> <ol> <li>Create a Terraform object with a Source pointing to a repository. Your repository must contain a Terraform file\u2014for example, <code>main.tf</code>. Check out this demo for an example.</li> </ol> <pre><code>export GITHUB_USER=&lt;your user&gt;\nexport GITHUB_REPO=&lt;your repo&gt;\n\ncat &lt;&lt;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\n</code></pre> <ol> <li>Now you can create a pull request on your GitHub repo. The Branch Planner will create a new Terraform object with the plan-only mode enabled and will generate a new plan for you. It will post the plan as a new comment in the pull request.</li> </ol>"},{"location":"branch_planner/branch-planner-getting-started/#configure-branch-planner","title":"Configure Branch Planner","text":"<p>Branch Planner uses a ConfigMap as configuration. The ConfigMap is optional but useful for fine-tuning Branch Planner.</p>"},{"location":"branch_planner/branch-planner-getting-started/#configuration","title":"Configuration","text":"<p>By default, Branch Planner will look for the <code>branch-planner</code> ConfigMap in the same namespace as where the TF-Controller is installed. That ConfigMap allows users to specify which Terraform resources in a cluster the Brach Planner should monitor.</p> <p>The ConfigMap has two fields:</p> <ol> <li><code>secretName</code>, which contains the API token to access GitHub.</li> <li><code>resources</code>, which defines a list of resources to watch.</li> </ol> <pre><code>---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  namespace: flux-system\n  name: branch-planner\ndata:\n  secretName: branch-planner-token\n  resources: |-\n    - namespace: terraform\n    - namespace: flux-system\n</code></pre>"},{"location":"branch_planner/branch-planner-getting-started/#secret","title":"Secret","text":"<p>Branch Planner uses the referenced Secret with a <code>token</code> field that acquires the API token to fetch pull request information.</p> <pre><code>kubectl create secret generic branch-planner-token \\\n    --namespace=flux-system \\\n    --from-literal=\"token=${GITHUB_TOKEN}\"\n</code></pre>"},{"location":"branch_planner/branch-planner-getting-started/#resources","title":"Resources","text":"<p>If the <code>resources</code> list is empty, nothing will be watched. The resource definition can be exact or namespace-wide.</p> <p>With the following configuration file, the Branch Planner will watch all Terraform objects in the <code>terraform</code> namespace, and the <code>exact-terraform-object</code> Terraform object in <code>default</code> namespace.</p> <pre><code>data:\n  resources:\n    - namespace: default\n      name: exact-terraform-object\n    - namespace: terraform\n</code></pre>"},{"location":"branch_planner/branch-planner-getting-started/#default-configuration","title":"Default Configuration","text":"<p>If no ConfigMap is found, the Branch Planner will not watch any namespaces for Terraform resources and look for a GitHub token in a secret named <code>branch-planner-token</code> in the <code>flux-system</code> namespace. Supplying a secret with a token is a necessary task, otherwise Branch Planner will not be able to interact with the GitHub API.</p>"},{"location":"branch_planner/branch-planner-getting-started/#enable-branch-planner","title":"Enable Branch Planner","text":"<p>To enable branch planner, set the <code>branchPlanner.enabled</code> to <code>true</code> in the Helm values files.</p> <pre><code>---\nbranchPlanner:\n  enabled: true\n</code></pre>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/","title":"Branch planner tfc integration getting started","text":""},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#branch-planner-and-terraform-cloud-integration-getting-started","title":"Branch Planner and Terraform Cloud Integration: Getting Started","text":"<p>With Branch Planner, you can provision the <code>main</code> branch directly on Terraform Cloud. TF-Controller communicates with Terraform Cloud to run the necessary plans and apply your approved code. The state is securely stored on Terraform Cloud.</p> <p>Note: For now, Branch Planner only supports GitHub as the Git provider. We plan to add other Git providers in time.</p>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-by-step-guide","title":"Step-by-step Guide","text":""},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-1-create-a-terraform-cloud-token","title":"Step 1: Create a Terraform Cloud Token","text":"<p>Use the <code>terraform login</code> command to obtain a Terraform Cloud token. Then use the token to create a Kubernetes Secret.</p> <pre><code>kubectl create secret generic \\\n  tfc-cli-config \\\n  --namespace=flux-system \\\n  --from-file=terraform.tfrc=/dev/stdin &lt;&lt; EOF\ncredentials \"app.terraform.io\" {\n  token = \"xxxxxxxxxxxxxx.atlasv1.zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz\"           \n}\nEOF\n</code></pre>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-2-create-a-terraform-cr","title":"Step 2: Create a Terraform CR","text":"<p>Create a Terraform CR to automatically plan and apply Terraform configurations on Terraform Cloud. In this example, the Branch Planner reads the Terraform configurations from a Git repository to plan, apply, and store the state in a Terraform Cloud workspace.</p> <p>The token from Step 1 is specified as the value of <code>spec.cliConfigSecretRef</code> and is used to authenticate with Terraform Cloud.</p> <pre><code>---\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/tf-controller/branch-planner-demo\n  ref:\n    branch: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: branch-planner-tfc\n  namespace: flux-system\nspec:\n  interval: 2m\n  approvePlan: auto\n  cloud:\n    organization: weaveworks\n    workspaces:\n      name: branch-planner-tfc\n  cliConfigSecretRef:\n    name: tfc-cli-config\n    namespace: flux-system\n  vars:\n  - name: subject\n    value: \"world\"\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: branch-planner-demo\n    namespace: flux-system\n</code></pre>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-3-edit-file-create-a-branch-and-open-a-pull-request","title":"Step 3: Edit File, Create a Branch, and Open a Pull Request","text":"<ol> <li> <p>Navigate to Your Repository: Open a web browser and visit your GitHub repository.  For our example, navigate here.</p> </li> <li> <p>Locate the File to Edit: Browse through the repository's file structure and  click on the Terraform configuration file you wish to edit.</p> </li> <li> <p>Edit the File: Click on the pencil icon (edit) located on the top right of the file content. Make your desired changes to the Terraform configurations. For instance, you might change the \"Hello World\" content in the <code>main.tf</code> file.</p> </li> </ol> <p>Once you've made your edits, scroll down to prepare to commit the changes.</p> <ol> <li>Commit the Changes to a New Branch: Instead of committing directly to the <code>main</code> branch,  choose the option to \"Create a new branch\" for this commit and start a pull request. Name the branch something descriptive\u2014for example, <code>change-hello-world-message</code>.</li> </ol> <p>Click on the \"Propose Changes\" button.</p> <ol> <li>Open a Pull Request (PR): After proposing your changes, you'll be led to the \"Open a pull request\" page. Fill in the details of your PR, explaining the changes you made, their purpose, and any other pertinent information.</li> </ol> <p>Click on the \"Create Pull Request\" button.</p> <ol> <li>Review Terraform Plan in PR Comments: Once the PR is created, the Branch Planner will trigger a Terraform plan. After the plan is completed, the results will be posted as a comment on the PR. This enables you and your team to review the expected changes before they're applied.</li> </ol>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#step-4-review-approve-and-merge-the-pull-request","title":"Step 4: Review, Approve and Merge the Pull Request","text":"<ol> <li> <p>Review the Changes:</p> <ul> <li>Navigate to the <code>Pull Requests</code> tab in your GitHub repository.</li> <li>Click on the title of your pull request to see the details.</li> <li>Examine the <code>Files changed</code> section to see the exact modifications made to the Terraform configurations.</li> <li>Check the comments for the Terraform plan output generated by Branch Planner. Ensure the plan matches your expectations.</li> </ul> </li> <li> <p>Iterate on Changes if Necessary:</p> <ul> <li>If you spot any discrepancies or wish to make further adjustments, click on the file in the <code>Files changed</code> section.</li> <li>After making the desired edits, commit the changes to the same branch. This will automatically prompt TF-Controller and Branch Planner to generate a new plan.</li> <li>If, for any reason, the automatic replan doesn't occur or you believe there might be an inconsistency, you can manually trigger a new plan by commenting <code>!replan</code> on the PR. Branch Planner will then process the request and display the new plan results.</li> </ul> </li> <li> <p>Approve the Changes:</p> <ul> <li>If you're content with the changes and the associated Terraform plan, move to the <code>Review changes</code> button on the PR page.</li> <li>Select the <code>Approve</code> option from the dropdown and optionally add any final comments.</li> <li>Click <code>Submit review</code> to finalize your approval.</li> </ul> </li> <li> <p>Merge the Pull Request:</p> <ul> <li>With the changes approved, click on the <code>Merge pull request</code> button.</li> <li>Choose your desired merge strategy from the options provided, such as \"Squash and merge\" or \"Rebase and merge\".</li> <li>Click <code>Confirm merge</code>.</li> <li>Following the merge, TF-Controller will take over. It will send the updated Terraform configuration to Terraform Cloud, where the changes will be planned and then applied. The resulting infrastructure state will be securely stored within your Terraform Cloud workspace.</li> </ul> </li> </ol>"},{"location":"branch_planner/branch-planner-tfc-integration-getting-started/#conclusion","title":"Conclusion","text":"<p>Combining tools like Terraform Cloud, TF-Controller with Branch Planner, and GitHub offers an innovative way for organization to streamline their infrastructure management. Being able to easily review and understand changes in a familiar platform like GitHub ensures clarity. With the immediate feedback provided by Branch Planner, teams can anticipate and discuss potential changes on different branches, before they're implemented. This combination doesn't just make updates safer and more predictable, but it promotes team-wide involvement. Furthermore, the collaboration between TF-Controller and Terraform Cloud guarantees consistency, minimizing errors, and being GitOps. As we navigate an increasingly complex IaC landscape, such simplified, integrated approaches are key to efficient, secure and error-free operations.</p>"},{"location":"how_to/","title":"How to","text":"<ul> <li>How to troubleshoot with Break the Glass mode</li> <li>How to backup and restore a Terraform state</li> <li>How does the interval and retryInterval work?</li> <li>How does the resource deletion work?</li> <li>How to integrate with Flux Receivers and Alerts?</li> <li>How to enable cross-namespace references</li> </ul>"},{"location":"how_to/backup_and_restore_a_Terraform_state/","title":"Backup and restore a Terraform state","text":""},{"location":"how_to/backup_and_restore_a_Terraform_state/#backup-the-tfstate","title":"Backup the tfstate","text":"<p>Assume that we have the <code>my-stack</code> Terraform object with its <code>.spec.workspace</code> set to \"default\".</p> <pre><code>kubectl get terraform\n\nNAME       READY     STATUS         AGE\nmy-stack   Unknown   Initializing   28s\n</code></pre> <p>We can backup its tfstate out of the cluster, like this:</p> <pre><code>WORKSPACE=default\nNAME=my-stack\n\nkubectl get secret tfstate-${WORKSPACE}-${NAME} \\\n  -ojsonpath='{.data.tfstate}' \\\n  | base64 -d | gzip -d &gt; terraform.tfstate\n</code></pre>"},{"location":"how_to/backup_and_restore_a_Terraform_state/#restore-the-tfstate","title":"Restore the tfstate","text":"<p>To restore the tfstate file or import an existing tfstate file to the cluster, we can use the following operation:</p> <pre><code>gzip terraform.tfstate\n\nWORKSPACE=default\nNAME=my-stack\n\nkubectl create secret \\\n  generic tfstate-${WORKSPACE}-${NAME} \\\n  --from-file=tfstate=terraform.tfstate.gz \\\n  --dry-run=client -o=yaml \\\n  | yq e '.metadata.annotations[\"encoding\"]=\"gzip\"' - \\\n  &gt; tfstate-${WORKSPACE}-${NAME}.yaml\n\nkubectl apply -f tfstate-${WORKSPACE}-${NAME}.yaml\n</code></pre>"},{"location":"how_to/build-and-use-a-custom-runnner-image/","title":"Using a custom runner image for TF-Controller","text":"<p>In order to build a custom runner image, you need a Dockerfile that extends the base image and that adds Terraform, plus any additional required tooling. The repository that contains the base images is here. All base image tags follow the following format: <code>${TF_CONTROLLER_VERSION}-base</code></p>"},{"location":"how_to/build-and-use-a-custom-runnner-image/#prerequisites","title":"Prerequisites","text":"<p>You need Docker and Git to build the image.</p>"},{"location":"how_to/build-and-use-a-custom-runnner-image/#build-the-image","title":"Build the image","text":"<ol> <li>Create a <code>Dockerfile</code> that extends the base image and that adds Terraform, plus any additional required tooling. For example:</li> </ol> <pre><code>ARG BASE_IMAGE\nFROM $BASE_IMAGE\n\nARG TARGETARCH\nARG TF_VERSION=1.3.9\n\n# Switch to root to have permissions for operations\nUSER root\n\nADD https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_linux_${TARGETARCH}.zip /terraform_${TF_VERSION}_linux_${TARGETARCH}.zip\nRUN unzip -q /terraform_${TF_VERSION}_linux_${TARGETARCH}.zip -d /usr/local/bin/ &amp;&amp; \\\n    rm /terraform_${TF_VERSION}_linux_${TARGETARCH}.zip &amp;&amp; \\\n    chmod +x /usr/local/bin/terraform\n\n# Switch back to the non-root user after operations\nUSER 65532:65532\n</code></pre> <p>Find the original Dockerfile for the runner here.</p> <ol> <li>Build the image from the directory containing the <code>Dockerfile</code> you created above:</li> </ol> <pre><code>export TF_CONTROLLER_VERSION=v0.16.0-rc.3\nexport TF_VERSION=1.3.9\nexport BASE_IMAGE=ghcr.io/weaveworks/tf-runner:${TF_CONTROLLER_VERSION}-base\nexport TARGETARCH=amd64\nexport REMOTE_REPO=ghcr.io/my-org/custom-runnner\ndocker build \\\n    --build-arg BASE_IMAGE=${BASE_IMAGE} \\\n    --build-arg TARGETARCH=${TARGETARCH} \\\n    --tag my-custom-runner:${TF_CONTROLLER_VERSION} .\ndocker tag my-custom-runner:${TF_CONTROLLER_VERSION} $REMOTE_REPO:${TF_CONTROLLER_VERSION}\ndocker push $REMOTE_REPO:${TF_CONTROLLER_VERSION}\n</code></pre> <p>Replace the relevant values above with the corresponding values in your organisation/implementation.</p> <ol> <li>Update the <code>values.runner.image</code> values in the TF-Controller Helm chart values to point to the new image:</li> </ol> <pre><code>values:\n  runner:\n    image:\n      repository: ghcr.io/my-org/custom-runnner\n      tag: v0.16.0-rc.3\n</code></pre> <ol> <li>Commit and push the changes to Git, and confirm that the HelmRelease has been updated:</li> </ol> <pre><code>kubectl get deployments.apps -n flux-system tf-controller -o jsonpath='{.spec.template.spec.containers[*]}' | jq '.env[] | select(.name == \"RUNNER_POD_IMAGE\")'\n{\n  \"name\": \"RUNNER_POD_IMAGE\",\n  \"value\": \"ghcr.io/my-org/custom-runner:v0.16.0-rc3\"\n}\n</code></pre>"},{"location":"how_to/build-and-use-a-custom-runnner-image/#references","title":"References","text":"<p>A set of GitHub actions in the TF-Controller community repo facilitate a process that's similar to the above, but using GitHub Actions to build and push the image. You can find them here.</p>"},{"location":"how_to/flux_receiver_and_alert/","title":"Integrate with Flux Receivers and Alerts","text":"<p>These docs show how to customize your Flux installation so that Flux API resources like <code>Receivers</code> and <code>Alerts</code> can be used with third-party custom resource definitions such as the <code>Terraform</code> API CRD.</p> <p>You will need to add a patch to the <code>kustomization.yaml</code> in your Flux cluster installation's bootstrap manifests, find it under the <code>flux-system</code> directory.</p>"},{"location":"how_to/flux_receiver_and_alert/#enable-notifications-for-third-party-controllers","title":"Enable notifications for third party controllers","text":"<p>Enable notifications for 3rd party Flux controllers such as tf-controller:</p> <pre><code>apiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nresources:\n  - gotk-components.yaml\n  - gotk-sync.yaml\npatches:\n  - patch: |\n      - op: add\n        path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/-\n        value: Terraform\n      - op: add\n        path: /spec/versions/1/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/-\n        value: Terraform\n    target:\n      kind: CustomResourceDefinition\n      name:  alerts.notification.toolkit.fluxcd.io\n  - patch: |\n      - op: add\n        path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/resources/items/properties/kind/enum/-\n        value: Terraform\n      - op: add\n        path: /spec/versions/1/schema/openAPIV3Schema/properties/spec/properties/resources/items/properties/kind/enum/-\n        value: Terraform\n    target:\n      kind: CustomResourceDefinition\n      name:  receivers.notification.toolkit.fluxcd.io\n  - patch: |\n      - op: add\n        path: /rules/-\n        value:\n          apiGroups: [ 'infra.contrib.fluxcd.io' ]\n          resources: [ '*' ]\n          verbs: [ '*' ]\n    target:\n      kind: ClusterRole\n      name:  crd-controller-flux-system\n</code></pre>"},{"location":"how_to/interval_and_retryInterval/","title":"How does the interval and retryInterval work?","text":""},{"location":"how_to/interval_and_retryInterval/#overview","title":"Overview","text":"<p>This 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.</p>"},{"location":"how_to/interval_and_retryInterval/#requeue-behaviors","title":"Requeue Behaviors","text":"<p>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:</p>"},{"location":"how_to/interval_and_retryInterval/#1-immediate-requeue-not-using-specified-interval-retryinterval","title":"1. Immediate Requeue (Not using specified interval / retryInterval)","text":"<p>In these scenarios, the <code>Reconcile</code> 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:</p> <ul> <li>When there's an error retrieving the Terraform object from the Kubernetes API.</li> <li>After adding the finalizer, if there's an error in patching the Terraform object.</li> <li>If there's a non-access-denied error in retrieving the source object.</li> <li>When the ready condition is unknown or the status of the ready condition isn't unknown, and there's an error in patching the Terraform object.</li> <li>In multiple situations where there's an error in patching the Terraform object's status.</li> <li>If there's an error in creating or looking up the runner.</li> <li>If there's an error while attempting to finalize the Terraform object.</li> </ul>"},{"location":"how_to/interval_and_retryInterval/#2-requeue-after-a-specific-interval-specretryinterval","title":"2. Requeue After a Specific Interval (<code>spec.retryInterval</code>)","text":"<p>In these scenarios, the method specifically asks for a requeue after a certain interval specified by <code>spec.retryInterval</code> (default to 15s).</p> <ul> <li>The Terraform object is being deleted but there are still dependent resources that haven't been deleted.</li> <li>The source object specified by <code>spec.sourceRef</code> is not found.</li> <li>The source object doesn't have an associated artifact.</li> <li>The dependencies do not meet the ready condition.</li> <li>There's an error during the main reconciliation process.</li> <li>Drift is detected during the reconciliation process.</li> </ul>"},{"location":"how_to/interval_and_retryInterval/#3-requeue-after-a-specific-interval-specinterval","title":"3. Requeue After a Specific Interval (<code>spec.interval</code>)","text":"<p>In this scenario, the method specifically asks for a requeue after a successful reconciliation:</p> <p>The interval for the requeue is <code>spec.interval</code>.</p>"},{"location":"how_to/interval_and_retryInterval/#4-no-requeue-wait-for-manual-intervention","title":"4. No Requeue, wait for manual intervention","text":"<p>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:</p> <ul> <li>Access is denied when retrieving the source object.</li> <li>The status of the plan is pending, and it's not set to force or auto-apply.</li> </ul>"},{"location":"how_to/resource_deletion/","title":"Resource Deletion Dependencies in Terraform Controller","text":"<p>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.</p>"},{"location":"how_to/resource_deletion/#source-object","title":"Source Object","text":"<p>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.</p> <p>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).</p> <p>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.</p> <p>If the source object was deleted and the deletion of a Terraform resource is stuck, clearing the <code>finalizers</code> let the system delete the resource skipping the finalizer of the Terraform Controller.</p> <ol> <li>Suspend the <code>kustomization</code>:    <pre><code>flux suspend kustomization tf-stk\n</code></pre></li> <li>Patch the Terraform resource:    <pre><code>kubectl patch terraforms.infra.contrib.fluxcd.io \\\n  -n stk helloworld \\\n  -p '{\"metadata\":{\"finalizers\":null}}' \\\n  --type=merge\n</code></pre></li> </ol> <p>As it skips the finalizer of the Terraform controller, any cleanup the controller would do will be skipped too.</p>"},{"location":"how_to/resource_deletion/#role-bindings","title":"Role Bindings","text":"<p>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.</p> <p>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.</p>"},{"location":"how_to/resource_deletion/#secrets-and-configmaps","title":"Secrets and ConfigMaps","text":"<p>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.</p> <p>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.</p>"},{"location":"how_to/resource_deletion/#troubleshooting","title":"Troubleshooting","text":"<p>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.</p> <p>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.</p>"},{"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":"<p>\"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.</p> <p>~&gt; WARNING: Please note that you cannot use this feature to fix the Terraform resources with <code>v1alpha1</code> version of the Terraform CRD.  It works only with <code>v1alpha2</code> version of the Terraform CRD.</p> <p>~&gt; 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.</p> <p>There are two primary methods of initiating this mode:</p> <ol> <li>Using the <code>tfctl</code> command-line tool.</li> <li>Setting the <code>spec.breakTheGlass</code> field to <code>true</code> in the Terraform object.</li> </ol>"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#using-tfctl-to-break-the-glass","title":"Using <code>tfctl</code> to Break the Glass","text":"<p>In order to use this functionality, it needs to be enabled at the controller level; in order to do that, you can set the following Helm chart value to <code>true</code>:</p> <pre><code>allowBreakTheGlass: true\n</code></pre> <p>After the feature is enabled, to start a one-time troubleshooting session, you can use the <code>tfctl break-glass</code> command. For instance:</p> <pre><code>tfctl break-glass hello-world\n</code></pre> <p>This command initiates a session that allows you to execute any Terraform command to rectify the issues with your Terraform resources. It is noteworthy that this command does not require setting the <code>spec.breakTheGlass</code> field to <code>true</code> in the Terraform object.</p> <p>After resolving the issues, you can simply exit the shell.  GitOps will then continue to reconcile the Terraform object.</p>"},{"location":"how_to/troubleshooting_with_break_the_glass_mode/#break-the-glass-with-specbreaktheglass-field","title":"Break the glass with <code>spec.breakTheGlass</code> field","text":"<p>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.</p> <p>You can enable the 'Break the Glass' feature for every reconciliation by setting the <code>breakTheGlass</code> field to <code>true</code> in the <code>spec</code> of the Terraform object.</p> <p>Here is a sample example:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  breakTheGlass: true\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"how_to/upgrade-tf-controller/","title":"Upgrading TF-Controller","text":"<p>Please follow these steps to upgrade TF-Controller:</p> <ol> <li>Read the latest release changelogs.</li> <li>Check your API versions.</li> <li>To make sure you don't get new state changes, suspend Terraform resources (<code>tfctl suspend --all</code>) to minimize the impact on live systems.</li> <li>Back up Terraform tfstates to avoid losing data. If you're using the default backend with secrets in Kubernetes, use your backup toolset (i.e., Velero) to back up the state data.</li> <li>Upgrade Flux first, following the Flux documentation.</li> <li>Disable auto-approval by either removing the approvePlan value or setting it to \"\".</li> <li>To prevent unintentional resource deletions, set the <code>spec.destroyResourcesOnDeletion</code> flag to <code>false</code> for critical or production systems (the default value is <code>false</code>)</li> <li>If the Flux upgrade goes well, proceed to upgrade the TF-controller via its image tag. Adjust the values in the HelmRelease to match the new version to which you are upgrading.</li> <li>Check the pod logs for the TF-Controller deployment and any runner logs in order to identify potential issues. If you check the <code>warnings</code> in the logs, you can also identify any required API changes. For example: <code>v1alpha1 Terraform is deprecated, upgrade to v1alpha2</code>.</li> <li>Push the changes you made.</li> <li>Resume your Terraform resources\u2014either one-by-one for critical resources, or all of them with <code>tfctl resume --all</code></li> <li>Ensure no changes are planned for deletion. If you changed the value in step 6 from <code>spec.destroyResourcesOnDeletion</code> to <code>false</code>, resources will not be automatically removed.</li> <li>Revert back to auto-approval mode after ensuring stability.</li> <li>Resume any suspended Kustomization objects to restore GitOps automation.</li> <li>Restore <code>spec.destroyResourcesOnDeletion</code>, if this has been disabled for any resources in critical or production systems.</li> </ol> <p>TF-Controller supports v1alpha1 for backward compatibility. This means that you need v1alpha2 for newer (as of September 2023) features such as: - the branch planner - pod sub-domain DNS resolutions - new PodSpec fields like PriorityClass, SecurityContext, and ResourceRequirements (Limits / Requests)</p>"},{"location":"how_to/use-cross-namespace-refs/","title":"Using cross-namespace references","text":"<p>The Terraform CRD in the API for TF-controller includes fields which are references to other objects:</p> Name Purpose .spec.sourceRef Refers to a Flux source .spec.dependsOn[*] Each entry refers to a dependency .spec.cliConfigSecretRef Secret with <code>tf</code> config to use <p>The branch planner configuration can also have cross-namespace references:</p> Name Purpose .secretNamespace Namespace of secret containing a GitHub token .resources[*] Each entry refers to a Terraform object to include in branch planning <p>All of these can refer to an object in a namespace different to that of the Terraform object. However, giving access to objects in other namespaces is generally considered a security risk, so this is disallowed by default. Only references that mention the same namespace, or omit the namespace field, will be accepted. References using a different namespace will cause the controller to stop processing the Terraform object and put it in a non-Ready state.</p> <p>To allow cross-namespace references, use the flag <code>--allow-cross-namespace-refs</code> with the controller and branch-planner. When using the Helm chart to install or update the controller and branch-planner, the value <code>allowCrossNamespaceRefs</code> will allow cross-namespace references for both.</p>"},{"location":"use_tf_controller/","title":"Use TF-controller","text":"<ul> <li>Use TF-controller to provision resources and auto approve</li> <li>Use TF-controller to plan and manually apply Terraform resources</li> <li>Use TF-controller to provision resources and obtain outputs</li> <li>Use TF-controller to detect drifts only without plan or apply</li> <li>Use TF-controller with drift detection disabled</li> <li>Use TF-controller with AWS EKS IRSA</li> <li>Use TF-controller to set variables for Terraform resources</li> <li>Use TF-controller with a custom backend</li> <li>Use TF-controller with an OCI Artifact as Source</li> <li>Use TF-controller to provision Terraform resources that are required health checks</li> <li>Use TF-controller to provision resources and destroy them when the Terraform object gets deleted</li> <li>Use TF-controller to force unlock Terraform states</li> <li>Use TF-controller with Terraform Runners enabled via Env Variables</li> <li>Use TF-controller to provision resources with customized Runner Pods</li> <li>Use TF-controller with Terraform Enterprise</li> <li>Use TF-controller with primitive modules</li> <li>Use TF-controller with GitOps dependency management</li> <li>Use TF-controller with the ready-to-use AWS package</li> <li>User TF-controller with plan-only mode</li> <li>Use TF-controller with external webhooks</li> <li>Use TF-controller with Terraform Runners exposed via hostname/subdomain</li> </ul>"},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/","title":"To detect drifts only without plan or apply","text":""},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/#use-tf-controller-to-detect-drifts-only-without-plan-or-apply","title":"Use TF-controller to detect drifts only without plan or apply","text":"<p>We can set <code>.spec.approvePlan</code> to <code>disable</code> to tell the controller to detect drifts of your Terraform resources only. Doing so will skip the <code>plan</code> and <code>apply</code> stages.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  approvePlan: disable\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/#troubleshooting","title":"Troubleshooting","text":""},{"location":"use_tf_controller/to_detect_drifts_only_without_plan_or_apply/#when-terraform-resource-detects-drift-but-no-plan-is-generated-for-approval","title":"When Terraform resource detects drift, but no plan is generated for approval","text":"<p>In this situation, you may not have <code>spec.approvePlan</code> set to <code>disable</code>. Try setting <code>spec.approvePlan: auto</code> and using <code>tfctl replan</code> to trigger a replan. After the drift disappears, you can set the <code>spec.approvePlan: \"\"</code> to get into the manual mode again.</p>"},{"location":"use_tf_controller/to_force_unlock_Terraform_states/","title":"Use TF-controller to force unlock Terraform states","text":"<p>In some situations, you may need to perform the Terraform force-unlock operation on the tfstate inside the cluster. </p> <p>There are three possible values of <code>.spec.tfstate.forceUnlock</code>, which are <code>yes</code>, <code>no</code>, and <code>auto</code>. The default value is <code>no</code>, which means that you disable this behaviour.</p> <p>The <code>auto</code> force-unlock mode will automatically use the lock identifier produced by the associated state file instead of specified lock identifier.</p> <p>The recommended way is to do manual force unlock. To manually <code>force-unlock</code>, you need to:</p> <ol> <li>set <code>forceUnlock</code> to <code>yes</code>, and</li> <li>specify a lock identifier to unlock a specific locked state,</li> </ol> <p>as the following example:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  tfstate:\n    forceUnlock: \"yes\"\n    lockIdentifier: f2ab685b-f84d-ac0b-a125-378a22877e8d\n</code></pre>"},{"location":"use_tf_controller/to_plan_and_manually_apply_Terraform_resources/","title":"Use TF-controller to plan and manually apply Terraform resources","text":"<p>In this guide, we will walk through the steps of using TF-controller to plan and manually apply Terraform resources.</p> <p>We will start by creating the <code>Terraform</code> object and specifying the necessary fields, including the <code>approvePlan</code> field.</p> <p>We will then create the <code>GitRepository</code> object, which points to the Git repository containing the Terraform configuration.</p> <p>Once these objects are created, we will use kubectl to obtain the <code>approvePlan</code> value and set it in the <code>Terraform</code> object. After making our changes and pushing them to the Git repository, TF-controller will apply the plan and create the real resources.</p>"},{"location":"use_tf_controller/to_plan_and_manually_apply_Terraform_resources/#define-the-terraform-object","title":"Define the Terraform object","text":"<p>Assume that you have a <code>GitRepository</code> object named <code>helloworld</code> pointing to a Git repository, and you want to plan and apply the Terraform resources under <code>./</code> of that Git repo.</p> <p>For the plan &amp; manual approval workflow, please start by either setting <code>.spec.approvePlan</code> to be the blank value, or omitting the field. This will tell TF-controller to use the plan &amp; manual approval workflow, rather than the auto-apply workflow. If you want to use the auto-apply workflow, you will need to set the <code>spec.approvePlan</code> field to \"auto\".</p> <p>In addition to setting the <code>spec.approvePlan</code> field, you will also need to specify the <code>interval</code>, <code>path</code>, and <code>sourceRef</code> fields in the spec field. The <code>interval</code> field determines how often TF-controller will run the Terraform configuration, the <code>path</code> field specifies the location of the configuration files, and the <code>sourceRef</code> field points to the GitRepository object.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: \"\" # or you can omit this field\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_plan_and_manually_apply_Terraform_resources/#view-the-approval-message","title":"View the approval message","text":"<p>Then after a reconciliation loop, the controller will generate a plan, and tell you how to use field <code>.spec.approvePlan</code> to approve the plan. You can run the following command to obtain that message.</p> <pre><code>kubectl -n flux-system get tf/helloworld\n</code></pre> <p>This 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 <code>spec.approvePlan</code> field to the value obtained from the message.</p> <p>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 &amp; manual approval workflow, as it involves generating a plan and requiring manual approval before the changes are applied.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  approvePlan: plan-main-b8e362c206 # first 8 digits of a commit hash is enough\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks/","title":"Use TF-controller to provision Terraform resources that are required health checks","text":"<p>For some Terraform resources, it may be useful to perform health checks on them to verify that they are ready to accept connection before the terraform goes into <code>Ready</code> state:</p> <p>For example, our Terraform file is provisioned and contains the following outputs.</p> <pre><code># main.tf\n\noutput \"rdsAddress\" {\n  value = \"mydb.xyz.us-east-1.rds.amazonaws.com\"\n}\n\noutput \"rdsPort\" {\n  value = \"3306\"\n}\n\noutput \"myappURL\" {\n  value = \"https://example.com/\"\n}\n</code></pre> <p>We can use standard Go template expressions, like <code>${{ .rdsAddress }}</code>, to refer to those output values and use them to verify that the resources are up and running.</p> <p>We support two types of health checks, <code>tcp</code> amd <code>http</code>. The <code>tcp</code> type allows us to verify a TCP connection, while the <code>http</code> type is for verify an HTTP URL. The default timeout of each health check is 20 seconds.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  healthChecks:\n    - name: rds\n      type: tcp\n      address: ${{ .rdsAddress }}:${{ .rdsPort }} \n      timeout: 10s # optional, defaults to 20s\n    - name: myapp\n      type: http\n      url: ${{ .myappURL }}\n      timeout: 5s\n    - name: url_not_from_output\n      type: http\n      url: \"https://example.org\"\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/","title":"Use TF-controller to provision resources and auto approve","text":"<p>To provision resources with TF-controller, you need to create a <code>Terraform</code> object and a Flux source object,  such as a <code>GitRepository</code> or <code>OCIRepository</code> object.</p>"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/#create-a-terraform-object","title":"Create a Terraform object","text":"<p>The <code>Terraform</code> 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.. </p> <p>It defines the Terraform module, the backend configuration, and the GitOps automation mode.</p> <p>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.</p> <p>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.</p>"},{"location":"use_tf_controller/to_provision_resources_and_auto_approve/#gitops-automation-mode","title":"GitOps automation mode","text":"<p>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.</p> <p>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.</p> <p>To specify the GitOps automation mode in a Terraform object, you can set the <code>spec.approvePlan</code> field to the desired value. For example, to use the \"auto-apply\" mode, y ou would set it to <code>spec.approvePlan: auto</code>.</p> <p>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.</p> <p>The following is an example of a <code>Terraform</code> object; we use the \"auto-apply\" mode:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\nspec:\n  path: ./helloworld\n  interval: 10m\n  approvePlan: auto\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n</code></pre> <p>This code is defining a <code>Terraform</code> object in Kubernetes. The <code>apiVersion</code> field specifies the version of the Kubernetes API being used, and the <code>kind</code> field specifies that it is a <code>Terraform</code> object. The <code>metadata</code> block contains information about the object, including its <code>name</code>.</p> <p>The <code>spec</code> field contains the specification for the <code>Terraform</code> object. The <code>path</code> field specifies the path to the Terraform configuration files, in this case a directory named \"helloworld\". The <code>interval</code> field specifies the frequency at which TF-controller should run the Terraform configuration, in this case every 10 minutes. The <code>approvePlan</code> field specifies whether or not to automatically approve the changes proposed by a Terraform plan. In this case, it is set to <code>auto</code>, meaning that changes will be automatically approved.</p> <p>The <code>sourceRef</code> field specifies the Flux source object to be used. In this case, it is a <code>GitRepository</code> object with the name \"helloworld\". This indicates that the Terraform configuration is stored in a Git repository object with the name <code>helloworld</code>.</p>"},{"location":"use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted/","title":"Use TF-controller to provision resources and destroy them when the Terraform object gets deleted","text":"<p>The resources provisioned by a Terraform object are not destroyed by default, and the tfstate of that Terraform object still remains in the cluster.</p> <p>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.</p> <p>However, you may want to destroy provisioned resources when delete the Terraform object in many scenarios. To enable destroy resources on object deletion, set <code>.spec.destroyResourcesOnDeletion</code> to <code>true</code>.</p> <p>~&gt; WARNING: This feature will destroy your resources on the cloud if the Terraform object gets deleted. Please use it with cautions.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  destroyResourcesOnDeletion: true\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/","title":"Use TF-controller to provision resources and obtain outputs","text":"<p>Outputs created by Terraform can be written to a secret using <code>.spec.writeOutputsToSecret</code>.</p>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#write-all-outputs","title":"Write all outputs","text":"<p>We can specify a target secret in <code>.spec.writeOutputsToSecret.name</code>, and the controller will write all outputs to the secret by default.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#write-outputs-selectively","title":"Write outputs selectively","text":"<p>We can choose only a subset of outputs by specify output names we'd like to write in the <code>.spec.writeOutputsToSecret.outputs</code> array.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n    outputs:\n    - hello_world\n    - my_sensitive_data\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#rename-outputs","title":"Rename outputs","text":"<p>Some 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. </p> <p>TF-controller supports mapping output name using the <code>old_name:new_name</code> format.</p> <p>In the following example, we renamed <code>age_key</code> output as <code>age.agekey</code> entry for the <code>helloworld-output</code> Secret's data, so that other components in the GitOps pipeline could consume it.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n    outputs:\n    - age_key:age.agekey\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_and_obtain_outputs/#customize-metadata-of-the-outputted-secret","title":"Customize metadata of the outputted secret","text":"<p>In 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.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: helloworld-output\n    labels:\n      my-label: true\n    annotations:\n      my-annotation: \"very long string\"\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/","title":"Use TF-controller to provision resources with customized Runner Pods","text":""},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/#customize-runner-pods-metadata","title":"Customize Runner Pod's metadata","text":"<p>In 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 <code>aadpodidbinding: myIdentity</code> on the pod is required.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  runnerPodTemplate:\n    metadata:\n      labels:\n        aadpodidbinding: myIdentity\n      annotations:\n        company.com/abc: xyz\n</code></pre>"},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/#customize-runner-pod-image","title":"Customize Runner Pod Image","text":"<p>By default, the Terraform controller uses <code>RUNNER_POD_IMAGE</code> 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.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  runnerPodTemplate:\n    spec:\n      image: registry.io/tf-runner:xyz\n</code></pre> <p>You can use <code>runner.Dockerfile</code> as a basis of customizing runner pod image.</p>"},{"location":"use_tf_controller/to_provision_resources_with_customized_Runner_Pods/#customize-runner-pod-specifications","title":"Customize Runner Pod Specifications","text":"<p>You can also customize various Runner Pod <code>spec</code> fields to control and configure how the Runner Pod runs.  For example, you can configure Runner Pod <code>spec</code> 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 <code>spec</code> fields.</p>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/","title":"Use TF-controller to set variables for Terraform resources","text":"<p>~&gt; BREAKING CHANGE: This is a breaking change of the <code>v1alpha1</code> API.</p> <p>Users who are upgrading from TF-controller &lt;= 0.7.0 require updating <code>varsFrom</code>, from a single object:</p> <pre><code>  varsFrom:\n    kind: ConfigMap\n    name: cluster-config\n</code></pre> <p>to be an array of object, like this:</p> <pre><code>  varsFrom:\n  - kind: ConfigMap\n    name: cluster-config\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#vars-and-varsfrom","title":"<code>vars</code> and <code>varsFrom</code>","text":"<p>You can pass variables to Terraform using the <code>vars</code> and <code>varsFrom</code> fields.</p> <p>Inline variables can be set using <code>vars</code>. The <code>varsFrom</code> field accepts a list of ConfigMaps / Secrets. You may use the <code>varsKeys</code> property of <code>varsFrom</code> to select specific keys from the input or omit this field to select all keys from the input source.</p> <p>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 <code>varsFrom</code>.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  vars:\n  - name: region\n    value: us-east-1\n  - name: env\n    value: dev\n  - name: instanceType\n    value: t3-small\n  varsFrom:\n  - kind: ConfigMap\n    name: cluster-config\n    varsKeys:\n    - nodeCount\n    - instanceType\n  - kind: Secret\n    name: cluster-creds\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#variable-value-as-hcl","title":"Variable value as HCL","text":"<p>The <code>vars</code> field supports HCL string, number, bool, object and list types. For example, the following variable can be populated using the accompanying Terraform spec:</p> <pre><code>variable \"cluster_spec\" {\n  type = object({\n      region     = string\n      env        = string\n      node_count = number\n      public     = bool\n  })\n}\n</code></pre> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  vars:\n  - name: cluster_spec\n    value:\n      region: us-east-1\n      env: dev\n      node_count: 10\n      public: false\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-variables-in-varsfrom","title":"Rename variables in varsFrom","text":"<p>To rename a variable, you can use the varsKeys key within the varsFrom field.  Here's the basic structure:</p> <p><pre><code>spec:\n  varsFrom:\n  - kind: Secret\n    name: &lt;secret_name&gt;\n    varsKeys:\n    - &lt;original_variable_name&gt;:&lt;new_variable_name&gt;\n</code></pre> <code>original_variable_name</code> corresponds to the initial name of the variable in the referenced secret, while <code>new_variable_name</code> represents the alias you want to use within the Terraform code.</p> <p>Consider this example below, where we rename <code>nodeCount</code> to <code>node_count</code>  and <code>instanceType</code> to <code>instance_type</code>:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  varsFrom:\n  - kind: Secret\n    name: cluster-config\n    varsKeys:\n    - nodeCount:node_count\n    - instanceType:instance_type\n</code></pre>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-output-variables","title":"Rename output variables","text":"<p>See Rename outputs for more details.</p>"},{"location":"use_tf_controller/to_set_variables_for_Terraform_resources/#rename-input-secrets","title":"Rename input secrets","text":"<p>See Rename input secrets for more details.</p>"},{"location":"use_tf_controller/with-azure/","title":"With azure","text":""},{"location":"use_tf_controller/with-azure/#use-tf-controller-with-azure","title":"Use TF-Controller with Azure","text":"<p>This content was provided by users @mingmingshiliyu and @maciekdude.</p> <p>Use the OIDC flag and explicitly point to the token. Due to a bug in AzureRM 3.44.x, use version 3.47.x or later.</p> <p>Set env variables on the runner pod:</p> <pre><code>        - name: ARM_USE_OIDC\n          value: \"true\"\n        - name: ARM_OIDC_TOKEN_FILE_PATH\n          value: \"/var/run/secrets/azure/tokens/azure-identity-token\"\n</code></pre> <p>Example yaml:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha1\nkind: Terraform\nmetadata:\n  name: terraformhello\n  namespace: default\nspec:\n  tfstate:\n    forceUnlock: auto\n  backendConfig:\n    customConfiguration: |\n      backend \"azurerm\" {\n        resource_group_name  = \"l\"\n        storage_account_name = \"\"\n        container_name       = \"tfstate\"\n        key                  = \"helloworld.tfstate\"\n        use_oidc             = true\n      }\n  interval: 1m\n  serviceAccountName: service_account_registered_in_aad\n  approvePlan: auto\n  destroy: true\n  path: ./tests/fixture\n  sourceRef:\n    kind: GitRepository\n    name: terraformhello\n    namespace: flux-system\n  runnerPodTemplate:\n    spec:\n      image: azure_cli_runner.xxx\n      env:\n        - name: ARM_USE_OIDC\n          value: \"true\"\n        - name: ARM_SUBSCRIPTION_ID\n          value: \"\"\n        - name: ARM_TENANT_ID\n          value: \"\"\n        - name: ARM_CLIENT_ID\n          value: \"\"\n        - name: ARM_OIDC_TOKEN_FILE_PATH\n          value: \"/var/run/secrets/azure/tokens/azure-identity-token\"\n</code></pre> <p>Import existing resources to a tfstate file stored on a storage account.</p>"},{"location":"use_tf_controller/with-ipv6/","title":"Use TF-Controller with IPv6 addresses.","text":"<p>TF-Controller uses pod IPv4 address to generate the in-cluster hostname to communicate with the runner instance. This logic fails when the runner pod has IPv6 address instead of IPv4.</p> <p>The TF-Controller has a flag to use pod subdomain resolution instead of an IP address, with that enabled the controller will use cluster subdomains, and it works with IPv6 addresses as the resolution is happening at cluster level.</p> <p>To enable this feature, you can set <code>usePodSubdomainResolution</code> to <code>true</code> in the Helm values file:</p> <pre><code>usePodSubdomainResolution: true\n</code></pre>"},{"location":"use_tf_controller/with_AWS_EKS_IRSA/","title":"Use TF-controller with AWS EKS IRSA","text":"<p>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.</p> <p>You can use <code>eksctl</code> to associate an OIDC provider with your EKS cluster, for example:</p> <pre><code>eksctl utils associate-iam-oidc-provider --cluster CLUSTER_NAME --approve\n</code></pre> <p>Then 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 <code>namespace:serviceaccountname</code> will be <code>flux-system:tf-runner</code>. You'll obtain a Role ARN to use in the next step.</p> <p>Finally, annotate the ServiceAccount for the <code>tf-runner</code> with the obtained Role ARN in your cluster:</p> <pre><code>kubectl annotate -n flux-system serviceaccount tf-runner eks.amazonaws.com/role-arn=ROLE_ARN\n</code></pre> <p>If deploying the <code>tf-controller</code> via Helm, this can be accomplished as follows:</p> <pre><code>values:\n  runner:\n    serviceAccount:\n      annotations:\n        eks.amazonaws.com/role-arn: ROLE_ARN\n</code></pre>"},{"location":"use_tf_controller/with_GitOps_dependency_management/","title":"Use TF-controller with GitOps dependency management","text":"<p>TF-controller supports GitOps dependency management. The GitOps dependency management feature is based on the similar technique implemented in the Kustomization controller of Flux.</p> <p>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.</p> <p>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.</p>"},{"location":"use_tf_controller/with_GitOps_dependency_management/#create-a-terraform-object","title":"Create a Terraform object","text":"<p>Similar to the same feature in the Kustomization controller, the dependency management feature is enabled by setting the <code>dependsOn</code> field in the <code>Terraform</code> object. The <code>dependsOn</code> field is a list of <code>Terraform</code> objects.</p> <p>When the dependency is not satisfied, the Terraform object will be in the <code>Unknown</code> state, and it will be retry again every <code>spec.retryInterval</code>. The retry interval is same as the <code>spec.interval</code> by default, and it can be configured separately by setting the <code>spec.retryInterval</code> field.</p> <p>First, create a <code>Terraform</code> object to provision the S3 bucket, name it <code>aws-s3-bucket</code>. The S3 bucket is provisioned by the Terraform module <code>aws_s3_bucket</code> in the OCI image <code>aws-package</code>. It is configured to use the <code>auto-apply</code> mode, and write outputs to the secret <code>aws-s3-bucket-outputs</code>.</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: aws-s3-bucket\n  namespace: flux-system\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  interval: 2m\n  destroyResourcesOnDeletion: true\n  writeOutputsToSecret:\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</code></pre> <p>Second, create a <code>Terraform</code> object to configure ACL for the S3 bucket, name it <code>aws-s3-bucket-acl</code>. The ACL is provisioned by the Terraform module <code>aws_s3_bucket_acl</code>, also from the OCI image <code>aws-package-v4.33.0</code>.</p> <p>In the <code>dependsOn</code> field, specify the <code>Terraform</code> 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 <code>aws-s3-bucket-outputs</code>, by specifying the <code>spec.readInputsFromSecrets</code> field. The <code>spec.readInputsFromSecrets</code> field is a list of Secret objects.  Its <code>name</code> field is the name of the Secret, and its <code>as</code> field is the name of variable that can be used in the <code>spec.values</code> block.</p> <p>For example, the <code>spec.values.bucket</code> field in the <code>aws-s3-bucket-acl</code> Terraform object is set to <code>${{ .aws_s3_bucket.bucket }}</code>.</p> <p>Please note that we use <code>${{</code> and  <code>}}</code> as the delimiters for the variable name, instead of the Helm default ones, <code>{{</code> and <code>}}</code>.</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: aws-s3-bucket-acl\n  namespace: flux-system\nspec:\n  path: aws_s3_bucket_acl\n  values:\n    acl: private\n    bucket: ${{ .aws_s3_bucket.bucket }}\n  sourceRef:\n    kind: OCIRepository\n    name: aws-package\n  approvePlan: auto\n  interval: 3m\n  dependsOn:\n  - name: aws-s3-bucket\n  readInputsFromSecrets:\n  - name: aws-s3-bucket-outputs\n    as: aws_s3_bucket\n  runnerPodTemplate:\n    spec:\n      envFrom:\n      - secretRef:\n          name: aws-credentials\n</code></pre>"},{"location":"use_tf_controller/with_GitOps_dependency_management/#avoid-kustomization-controllers-variable-substitution","title":"Avoid Kustomization controller's variable substitution","text":"<p>The Kustomization controller will substitute variables in the <code>Terraform</code> object, which will cause conflicts with the variable substitution in the GitOps dependency management feature. To avoid this, we need to add the <code>kustomize.toolkit.fluxcd.io/substitute: disabled</code> annotation to the <code>Terraform</code> object.</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: aws-s3-bucket-acl\n  namespace: flux-system\n  annotations:\n    kustomize.toolkit.fluxcd.io/substitute: disabled\nspec:\n  path: aws_s3_bucket_acl\n  values:\n    acl: private\n    bucket: ${{ .aws_s3_bucket.bucket }}\n  sourceRef:\n    kind: OCIRepository\n    name: aws-package\n  approvePlan: auto\n  interval: 3m\n  dependsOn:\n  - name: aws-s3-bucket\n  readInputsFromSecrets:\n  - name: aws-s3-bucket-outputs\n    as: aws_s3_bucket\n  runnerPodTemplate:\n    spec:\n      envFrom:\n      - secretRef:\n          name: aws-credentials\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/","title":"Use TF-controller with Terraform Enterprise","text":""},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-enterprise-integration","title":"Terraform Enterprise Integration","text":"<p>Starting from v0.9.5, Weave TF-controller officially supports integration to Terraform Cloud (TFC) and  Terraform Enterprise (TFE). Here are the steps to set up TF-controller for your TFE instance.</p> <p></p>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-login","title":"Terraform Login","text":"<p>First, you need to obtain an API token from your TFE. You can use <code>terraform login</code> command to do so.</p> <pre><code>terraform login tfe.dev.example.com\n</code></pre> <p>Then you can find your API token inside <code>$HOME/.terraform.d/credentials.tfrc.json</code>. Content of the file will look like this:</p> <pre><code>{\n  \"credentials\": {\n    \"tfe.dev.example.com\": {\n      \"token\": \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n    }\n  }\n}\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#prepare-an-tfrc-file","title":"Prepare an TFRC file","text":"<p>TF-controller accepts an TFRC file in the HCL format. So you have to prepare <code>terraform.tfrc</code> file using contents from above. <pre><code>credentials \"tfe.dev.example.com\" {\n  token = \"mXXXXXXXXX.atlasv1.ixXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n}\n</code></pre></p>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#create-a-secret","title":"Create a Secret","text":"<p>We will now create a Kubernetes Secret from your<code>terraform.tfrc</code> file,  name it <code>tfe-cli-config</code> and put it inside the <code>flux-system</code> namespace.</p> <pre><code>kubectl create secret generic \\\n  tfe-cli-config \\\n  --namespace=flux-system \\\n  --from-file=terraform.tfrc=./terraform.tfrc\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-object","title":"Terraform Object","text":"<p>In your Terraform object, you'll have to 1. disable the backend by setting <code>spec.backendConfig.disable: true</code>, and 2. point <code>spec.cliConfigSecretRef:</code> to the Secret created in the previous step, like this:</p> <pre><code>---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: tfe-demo\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  interval: 2m\n  path: ./terraform/tfe-demo\n  backendConfig:\n    disable: true\n  cliConfigSecretRef:\n    name: tfe-cli-config\n    namespace: flux-system\n  vars:\n  - name: subject\n    value: World\n  sourceRef:\n    kind: GitRepository\n    name: flux-system\n    namespace: flux-system\n  writeOutputsToSecret:\n    name: tfe-helloworld-output\n    outputs:\n    - greeting\n</code></pre>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-module","title":"Terraform Module","text":"<p>Don't forget that you need to tell your Terraform model to use your enterprise instance as well. Here's an example, <pre><code>terraform {\n  required_version = \"&gt;= 1.1.0\"\n  cloud {\n    hostname = \"tfe.dev.example.com\"\n    organization = \"weaveworks\"\n\n    workspaces {\n      name = \"dev\"\n    }\n  }\n}\n\nvariable \"subject\" {\n   type = string\n   default = \"World\"\n   description = \"Subject to hello\"\n}\n\noutput \"greeting\" {\n  value = \"Hello ${var.subject} from Terraform Enterprise\"\n}\n</code></pre></p>"},{"location":"use_tf_controller/with_Terraform_Enterprise/#terraform-cloud","title":"Terraform Cloud","text":"<p>For connecting to Terraform Cloud, please replace your hostname to <code>app.terraform.io</code>.</p>"},{"location":"use_tf_controller/with_a_custom_backend/","title":"Use TF-controller with a custom backend","text":"<p>By default, <code>tf-controller</code> will use the Kubernetes backend to store the Terraform state file (tfstate) in cluster.</p> <p>The tfstate is stored in a secret named: <code>tfstate-${workspace}-${secretSuffix}</code>. The default <code>suffix</code> will be the name of the Terraform resource, however you may override this setting using <code>.spec.backendConfig.secretSuffix</code>. The default <code>workspace</code> name is \"default\", you can also override the workspace by setting <code>.spec.workspace</code> to another value.</p> <p>If you wish to use a custom backend, you can configure it by defining the <code>.spec.backendConfig.customConfiguration</code> with one of the backends such as GCS or S3, for example:</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  backendConfig:\n    customConfiguration: |\n      backend \"s3\" {\n        bucket                      = \"s3-terraform-state1\"\n        key                         = \"dev/terraform.tfstate\"\n        region                      = \"us-east-1\"\n        endpoint                    = \"http://localhost:4566\"\n        skip_credentials_validation = true\n        skip_metadata_api_check     = true\n        force_path_style            = true\n        dynamodb_table              = \"terraformlock\"\n        dynamodb_endpoint           = \"http://localhost:4566\"\n        encrypt                     = true\n      }\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n  runnerPodTemplate:\n    spec:\n      image: registry.io/tf-runner:xyz\n</code></pre>"},{"location":"use_tf_controller/with_an_OCI_Artifact_as_Source/","title":"Use TF-controller with an OCI Artifact as Source","text":"<p>To use OCI artifacts as the source of Terraform objects, you need Flux 2 version v0.32.0 or higher.</p> <p>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:</p> <pre><code>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)\"\n\nflux tag artifact oci://ghcr.io/tf-controller/helloworld:$(git rev-parse --short HEAD) \\\n    --tag main\n</code></pre> <p>Then you define a source (<code>OCIRepository</code>), and use it as the <code>sourceRef</code> of your Terraform object.</p> <pre><code>---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\n  name: helloworld-oci\nspec:\n  interval: 1m\n  url: oci://ghcr.io/tf-controller/helloworld\n  ref:\n    tag: main\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld-tf-oci\nspec:\n  path: ./\n  approvePlan: auto\n  interval: 1m\n  sourceRef:\n    kind: OCIRepository\n    name: helloworld-oci\n  writeOutputsToSecret:\n    name: helloworld-outputs\n</code></pre>"},{"location":"use_tf_controller/with_drift_detection_disabled/","title":"Use TF-controller with drift detection disabled","text":"<p>Drift detection is enabled by default. You can set <code>.spec.disableDriftDetection: true</code> to disable it.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld\n  namespace: flux-system\nspec:\n  approvePlan: auto\n  disableDriftDetection: true\n  interval: 1m\n  path: ./\n  sourceRef:\n    kind: GitRepository\n    name: helloworld\n    namespace: flux-system\n</code></pre>"},{"location":"use_tf_controller/with_external_webhooks/","title":"Use TF-Controller with an External Webhooks","text":"<p>The TF-Controller provides a way to integrate with webhooks to further validate Terraform plans and manage the Terraform execution process.  With the webhook feature, you can implement custom policy checks, validations, and other logic to determine if the Terraform process should proceed.</p>"},{"location":"use_tf_controller/with_external_webhooks/#setting-up-the-webhook","title":"Setting up the Webhook","text":"<ol> <li>Webhook URL: Specify the URL of your webhook, ensuring it points to a valid HTTPS endpoint.</li> <li>Expected Return: The webhook should return a valid JSON object. For instance: <pre><code>{\"passed\": true}\n</code></pre></li> <li>Accepted True Values: The true values can be <code>true</code>, <code>\"true\"</code>, and <code>\"yes\"</code>.</li> <li>Accepted False Values: The false values can be <code>flse</code>, <code>\"false\"</code>, and <code>\"no\"</code>.</li> </ol> <p>Below is a breakdown of the relevant parts of the configuration:</p> <ol> <li><code>webhooks:</code> This is the section where you specify all webhook related configurations.</li> <li><code>stage:</code> Define at which stage the webhook will be triggered. Currenly, we support only the <code>post-planning</code> stage.</li> <li><code>url:</code> The URL pointing to your webhook endpoint.</li> <li><code>testExpression:</code> This expression is used to evaluate the response from the webhook. If it evaluates to true, the controller proceeds with the operation. In the example, the expression checks for the passed value from the webhook's JSON response.</li> <li><code>errorMessageTemplate:</code> If testExpression evaluates to false, this template is used to extract the error message from the webhook's JSON response. This message will be displayed to the user.</li> </ol>"},{"location":"use_tf_controller/with_external_webhooks/#configuration-example","title":"Configuration Example","text":"<p>Here's a configuration example on how to use the webhook feature to integrate with Weave Policy Engine. <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: helloworld-tf\nspec:\n  path: ./terraform\n  approvePlan: \"auto\"\n  interval: 1m\n  storeReadablePlan: human\n  sourceRef:\n    kind: GitRepository\n    name: helloworld-tf\n  webhooks:\n  - stage: post-planning\n    url: https://policy-agent.policy-system.svc/terraform/admission\n    testExpression: \"${{ .passed }}\"\n    errorMessageTemplate: \"Violation: ${{ (index (index .violations 0).occurrences 0).message }}\"\n  writeOutputsToSecret:\n    name: helloworld-outputs\n</code></pre></p> <p>Important Considerations:</p> <ul> <li>Ensure that your webhook endpoint is secure, as the TF-Controller will be sending potentially sensitive Terraform plan data to it.</li> <li>Test your webhook implementation thoroughly before deploying to production, as any issues could interrupt or halt your Terraform process.</li> </ul> <p>With the webhook feature, you can create a more robust and flexible GitOps Terraform pipeline that respects custom organizational policies and other requirements.</p>"},{"location":"use_tf_controller/with_plan_only_mode/","title":"Use TF-controller with a plan-only mode","text":"<p>This 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 <code>terraform plan</code> only.</p> <p>If <code>planOnly</code> is set to <code>true</code>, the controller will skip the apply part and runs only <code>terraform plan</code> and saves the output.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\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\n</code></pre>"},{"location":"use_tf_controller/with_primitive_modules/","title":"Use TF-controller with primitive modules","text":"<p>This document describes how to use the Weave TF-controller with a primitive module. It requires TF-controller v0.13+ to run the example.</p>"},{"location":"use_tf_controller/with_primitive_modules/#what-is-a-primitive-module","title":"What is a primitive module?","text":"<p>It's a Terraform module that contains only a single resource.</p> <ul> <li>A Terraform primitive module must contains the \"values\" variable.</li> <li>The \"values\" variable must be an object with fields of optional types.</li> <li>The module must be placed under a directory, which is named after the resource.</li> <li>The directory can optionally contain other files, for example the .terraform.lock.hcl.</li> <li>We call a set of primitive modules bundled into an OCI image, a package.</li> </ul>"},{"location":"use_tf_controller/with_primitive_modules/#hello-world-primitive-module","title":"Hello World Primitive Module","text":"<p>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 <code>aws_hello_world</code>, and the image is tagged as <code>ghcr.io/tf-controller/hello-primitive-modules/v4.32.0:v1</code>.</p> <p>We'll use the following Terraform object definition to provision the resource.</p> <p>First, we need to create a Terraform object with the <code>spec.sourceRef.kind</code> field  set to <code>OCIRepository</code> and the <code>spec.sourceRef.name</code> field set to the name of the OCIRepository object.</p> <p>Second, we need to set the <code>spec.path</code> field to the name of the resource, in this case <code>aws_hello_world</code>.</p> <p>Third, we need to set the <code>spec.values</code> 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.</p> <p>Finally, we need to set the <code>spec.approvePlan</code> field to <code>auto</code> to automatically approve the plan.</p> <pre><code>---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: OCIRepository\nmetadata:\n  name: hello-package-v4.32.0\n  namespace: flux-system\nspec:\n  interval: 30s\n  url: oci://ghcr.io/tf-controller/hello-primitive-modules/v4.32.0\n  ref:\n    tag: v1\n---\napiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: hello-world\n  namespace: flux-system\nspec:\n  path: aws_hello_world\n  values:\n    greeting: Hi\n    subject: my world\n  sourceRef:\n    kind: OCIRepository\n    name: hello-package-v4.32.0\n  interval: 1h0m\n  approvePlan: auto\n</code></pre>"},{"location":"use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/","title":"Use TF-controller with Terraform Runners exposed via hostname/subdomain","text":"<p>TF-controller uses the Controller/Runner architecture. The Controller acts as a client, and talks to each Runner's Pod via gRPC over port 30000.</p> <p>TF-controller must thus be able to reliably connect to each Runner's pod regardless of the cluster network topology.</p>"},{"location":"use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/#the-default-runner-dns-resolution","title":"The Default Runner DNS resolution","text":"<p>By default, TF-controller fetches the Runner's pod IP address after it is instantiated (e.g. <code>1.2.3.4</code>).</p> <p>It then transforms the IP address into its <code>IP-based pod DNS A record</code> (e.g. <code>1.2.3.4.&lt;namespace&gt;.pod.&lt;cluster-domain&gt;</code>) which is used to connect to the Runner pod using gRPC protocol.</p> <p>In standard Kubernetes cluster deployment, <code>IP-based pod DNS resolution</code> is usually provided by Coredns and especially the <code>pods</code> option of the Kubernetes plugin.</p> <pre><code>cluster.local {\n    kubernetes {\n        pods verified\n    }\n}\n</code></pre> <p>[!IMPORTANT] The gRPC communication between TF-controller and Runner's pod is secured with mTLS. TF-controller generates a valid wildcard TLS certificate for <code>*.&lt;namespace&gt;.pod.&lt;cluster-domain&gt;</code> hosts on the Runner's namespace. The Runner's pod present this certificate during TLS handshake with TF-controller. </p>"},{"location":"use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/#hostnamesubdomain-runner-dns-resolution","title":"Hostname/Subdomain Runner DNS resolution","text":"<p>The default configuration described above works for standard Kubernetes deployments. It does not work however when the cluster DNS provider do not support <code>IP-based pod DNS resolution</code>. This is the case for <code>GCP Cloud DNS</code> for example.</p> <p>For such setup, you can switch the DNS resolution mode to Hostname/Subdomain. Enabling this option will :</p> <ul> <li>Create a <code>Headless service</code> named <code>tf-runner</code> in each allowed namespace</li> </ul> <p>```yaml hl_lines=\"4-5,8-10\" apiVersion: v1 kind: Service metadata:   name: tf-runner   namespace: hello-world spec:   clusterIP: None   ports:   - name: grpc     port: 30000   selector:     app.kubernetes.io/created-by: tf-controller     app.kubernetes.io/name: tf-runner <pre><code>- Set Runner's pod spec with `hostname: &lt;terraform_object_name&gt;` and `subdomain: tf-runner`\n\n```yaml hl_lines=\"12-13\"\napiVersion: v1\nkind: Pod\n  labels:\n    app.kubernetes.io/created-by: tf-controller\n    app.kubernetes.io/instance: tf-runner-3ac83e0f\n    app.kubernetes.io/name: tf-runner\n    infra.contrib.fluxcd.io/terraform: hello-world\n    tf.weave.works/tls-secret-name: terraform-runner.tls-1693866794\n  name: helloworld-tf-runner\n  namespace: hello-world\nspec:\n  hostname: helloworld\n  subdomain: tf-runner\n  containers:\n  - args:\n    - --grpc-port\n    - \"30000\"\n    - --tls-secret-name\n    - terraform-runner.tls-1693866794\n    - --grpc-max-message-size\n    - \"4\"\n    image: ghcr.io/weaveworks/tf-runner:v0.16.0-rc.2\n    name: tf-runner\n    ports:\n    - containerPort: 30000\n      name: grpc\n    resources:\n      limits:\n        cpu: 500m\n        ephemeral-storage: 1Gi\n        memory: 2Gi\n    securityContext:\n      allowPrivilegeEscalation: false\n      capabilities:\n        drop:\n        - ALL\n      readOnlyRootFilesystem: true\n      runAsNonRoot: true\n      runAsUser: 65532\n      seccompProfile:\n        type: RuntimeDefault\n  preemptionPolicy: PreemptLowerPriority\n  priority: 0\n  schedulerName: gke.io/optimize-utilization-scheduler\n  securityContext:\n    seccompProfile:\n      type: RuntimeDefault\n  serviceAccountName: tf-runner\n</code></pre></p> <p>The Runner's pod can then be targeted by TF-controller using <code>&lt;terraform_object_name&gt;.tf-runner.&lt;namespace&gt;.svc.&lt;cluster-domain&gt; (helloworld.tf-runner.hello-world.svc.cluster.local)</code> as per Kubernetes specification instead of <code>IP-based pod DNS resolution</code>.</p> <p>The switch is performed by setting the following Helm value <code>usePodSubdomainResolution: true</code> or running directly TF-controller with the option <code>--use-pod-subdomain-resolution=true</code></p> <p>[!IMPORTANT] The gRPC communication between TF-controller and Runner's pod is secured with mTLS. TF-controller generates a valid wildcard TLS certificate for <code>*.&lt;namespace&gt;.pod.&lt;cluster-domain&gt;</code> and <code>*.tf-runner.&lt;namespace&gt;.svc.&lt;cluster-domain&gt;</code> hosts on the Runner's namespace. The Runner's pod present this certificate during TLS handshake with TF-controller. </p>"},{"location":"use_tf_controller/with_tf_runner_logging/","title":"Use TF-controller with Terraform Runners enabled via Env Variables","text":"<p>A Terraform Runner uses two environment variables, <code>DISABLE_TF_LOGS</code> and <code>ENABLE_SENSITIVE_TF_LOGS</code>, to control the logging behavior of the Terraform execution.</p> <p>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.</p> <ul> <li>The <code>DISABLE_TF_LOGS</code> variable, when set to \"1\", will disable all Terraform output logs to stdout and stderr.</li> <li>The <code>ENABLE_SENSITIVE_TF_LOGS</code> 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 <code>ENABLE_SENSITIVE_TF_LOGS</code> to take effect, the <code>DISABLE_TF_LOGS</code> variable must also be set to \"1\".</li> </ul>"},{"location":"use_tf_controller/with_tf_runner_logging/#the-default-logging-behavior","title":"The Default Logging Behavior","text":"<ul> <li>By default, the logging level for the <code>tf-runner</code> is configured at the <code>info</code> level.</li> <li>The <code>DISABLE_TF_LOGS</code> variable is not activated as part of the default settings.</li> <li>The <code>ENABLE_SENSITIVE_TF_LOGS</code> variable remains inactive in the default configuration.</li> <li>Calls to <code>ShowPlan</code> and <code>ShowPlanRaw</code> on the runner are not logged by default.</li> <li>For <code>Plan</code> calls made on the runner, error messages are sanitized as a part of the default configuration.</li> </ul> <p>For more information on configuring the Terraform Runner and its environment variables, please consult the documentation on customizing runners within the Weave TF-controller.</p>"},{"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":"<p>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.</p>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#what-is-a-package","title":"What is a package?","text":"<p>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.</p> <p>We will provide a set of ready-to-use packages for the most popular cloud providers. Currently, we ship the package for AWS only.</p>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#aws-package","title":"AWS Package","text":"<p>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 <code>awsPackage.install: false</code> in your Helm chart values.</p> <p>If you run <code>flux get sources oci</code> you should see the AWS package installed in your cluster listed as <code>aws-package</code>.</p> <pre><code>flux get sources oci\nNAME          REVISION                    SUSPENDED   READY   MESSAGE                                                                                                         \naws-package   v4.38.0-v1alpha11/6033f3b   False       True    stored artifact for digest 'v4.38.0-v1alpha11/6033f3b'\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#a-step-by-step-tutorial","title":"A step-by-step tutorial","text":"<p>This section describes how to use the AWS package to provision an S3 bucket with ACL using the TF-controller.</p>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#create-a-kind-local-cluster","title":"Create a KinD local cluster","text":"<p>If you don't have a Kubernetes cluster, you can create a KinD cluster with the following command:</p> <pre><code>kind create cluster\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#install-flux","title":"Install Flux","text":"<p>After you have a Kubernetes cluster, you can install Flux with the following command:</p> <pre><code>flux install\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#install-tf-controller","title":"Install TF-controller","text":"<p>Then, you can install the TF-controller with the following command:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#setup-aws-credentials","title":"Setup AWS credentials","text":"<p>To 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.</p> <pre><code>```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\n</code></pre> <p>To apply the secret, run the following command:</p> <pre><code>kubectl apply -f aws-credentials.yaml\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#setup-aws-bucket-and-acl","title":"Setup AWS Bucket and ACL","text":"<p>Now, 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.</p> <pre><code>```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\n  writeOutputsToSecret:\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 }}\n  sourceRef:\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\n  runnerPodTemplate:\n    spec:\n      envFrom:\n      - secretRef:\n          name: aws-credentials\n</code></pre>"},{"location":"use_tf_controller/with_the_ready_to_use_AWS_package/#rename-input-secrets","title":"Rename input secrets","text":"<p>The <code>spec.readInputsFromSecrets</code> 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 <code>spec.values</code> field.</p> <p>To rename a secret, you need to use the <code>as</code> key in the <code>spec.readInputsFromSecrets</code> field. The <code>name</code> key corresponds to the original name of the secret,  while the <code>as</code> key represents the new name that you want to use to reference the secret.</p> <p>In the example below, we can reference the bucket value  from our <code>aws_s3_bucket</code> secret using ${{ .aws_s3_bucket.bucket }} instead of using the original secret name, which is <code>aws-s3-bucket-outputs</code>.</p> <pre><code>apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\n  name: example-bucket-acl\n  namespace: flux-system\nspec:\n  # ...\n  readInputsFromSecrets:\n  - name: aws-s3-bucket-outputs\n    as: aws_s3_bucket\n  values:\n    acl: private\n    bucket: ${{ .aws_s3_bucket.bucket }}\n  # ...\n</code></pre>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index d03c23c2331e5115078ce25775d96340d9c0a5c3..7e27b60a1ab4f104106c7497ff0ac2630fa4d4a1 100644
GIT binary patch
delta 12
Tcmb=gXOr*d;9x#5k*yK{7S98c

delta 12
Tcmb=gXOr*d;MlTxB3mT@8W03F

diff --git a/tfctl/index.html b/tfctl/index.html
index 3387eab6..b622def2 100644
--- a/tfctl/index.html
+++ b/tfctl/index.html
@@ -346,7 +346,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../branch_planner/index.md" class="md-nav__link">
+      <a href="../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/index.html b/use_tf_controller/index.html
index 9bf25b5e..25614749 100644
--- a/use_tf_controller/index.html
+++ b/use_tf_controller/index.html
@@ -12,7 +12,7 @@
         <link rel="prev" href="../getting_started/">
       
       
-        <link rel="next" href="../how_to/">
+        <link rel="next" href="../branch_planner/">
       
       
       <link rel="icon" href="../assets/images/favicon.png">
@@ -358,7 +358,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../branch_planner/index.md" class="md-nav__link">
+      <a href="../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_detect_drifts_only_without_plan_or_apply/index.html b/use_tf_controller/to_detect_drifts_only_without_plan_or_apply/index.html
index 80c13037..bb1031cc 100644
--- a/use_tf_controller/to_detect_drifts_only_without_plan_or_apply/index.html
+++ b/use_tf_controller/to_detect_drifts_only_without_plan_or_apply/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_force_unlock_Terraform_states/index.html b/use_tf_controller/to_force_unlock_Terraform_states/index.html
index 285a92c2..bd3c827b 100644
--- a/use_tf_controller/to_force_unlock_Terraform_states/index.html
+++ b/use_tf_controller/to_force_unlock_Terraform_states/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_plan_and_manually_apply_Terraform_resources/index.html b/use_tf_controller/to_plan_and_manually_apply_Terraform_resources/index.html
index 61d66251..f2767c62 100644
--- a/use_tf_controller/to_plan_and_manually_apply_Terraform_resources/index.html
+++ b/use_tf_controller/to_plan_and_manually_apply_Terraform_resources/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks/index.html b/use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks/index.html
index 9c2a9b90..b906b743 100644
--- a/use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks/index.html
+++ b/use_tf_controller/to_provision_Terraform_resources_that_are_required_health_checks/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_provision_resources_and_auto_approve/index.html b/use_tf_controller/to_provision_resources_and_auto_approve/index.html
index 51a027ee..b82b0044 100644
--- a/use_tf_controller/to_provision_resources_and_auto_approve/index.html
+++ b/use_tf_controller/to_provision_resources_and_auto_approve/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted/index.html b/use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted/index.html
index 7739a179..0f602fa5 100644
--- a/use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted/index.html
+++ b/use_tf_controller/to_provision_resources_and_destroy_them_when_the_Terraform_object_gets_deleted/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_provision_resources_and_obtain_outputs/index.html b/use_tf_controller/to_provision_resources_and_obtain_outputs/index.html
index 73bbc8b3..19f091dc 100644
--- a/use_tf_controller/to_provision_resources_and_obtain_outputs/index.html
+++ b/use_tf_controller/to_provision_resources_and_obtain_outputs/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_provision_resources_with_customized_Runner_Pods/index.html b/use_tf_controller/to_provision_resources_with_customized_Runner_Pods/index.html
index 66e3a02c..50ff74fe 100644
--- a/use_tf_controller/to_provision_resources_with_customized_Runner_Pods/index.html
+++ b/use_tf_controller/to_provision_resources_with_customized_Runner_Pods/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/to_set_variables_for_Terraform_resources/index.html b/use_tf_controller/to_set_variables_for_Terraform_resources/index.html
index d0ec16fd..3f00a2b6 100644
--- a/use_tf_controller/to_set_variables_for_Terraform_resources/index.html
+++ b/use_tf_controller/to_set_variables_for_Terraform_resources/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with-azure/index.html b/use_tf_controller/with-azure/index.html
index fcd4ee55..9b41ef4f 100644
--- a/use_tf_controller/with-azure/index.html
+++ b/use_tf_controller/with-azure/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with-ipv6/index.html b/use_tf_controller/with-ipv6/index.html
index 47b1fd93..ec5f421e 100644
--- a/use_tf_controller/with-ipv6/index.html
+++ b/use_tf_controller/with-ipv6/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_AWS_EKS_IRSA/index.html b/use_tf_controller/with_AWS_EKS_IRSA/index.html
index 15f9de98..86afbd52 100644
--- a/use_tf_controller/with_AWS_EKS_IRSA/index.html
+++ b/use_tf_controller/with_AWS_EKS_IRSA/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_GitOps_dependency_management/index.html b/use_tf_controller/with_GitOps_dependency_management/index.html
index 3a5f2b12..ca3f1754 100644
--- a/use_tf_controller/with_GitOps_dependency_management/index.html
+++ b/use_tf_controller/with_GitOps_dependency_management/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_Terraform_Enterprise/index.html b/use_tf_controller/with_Terraform_Enterprise/index.html
index 493c8563..f4ff0f9c 100644
--- a/use_tf_controller/with_Terraform_Enterprise/index.html
+++ b/use_tf_controller/with_Terraform_Enterprise/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_a_custom_backend/index.html b/use_tf_controller/with_a_custom_backend/index.html
index ea232192..d120a401 100644
--- a/use_tf_controller/with_a_custom_backend/index.html
+++ b/use_tf_controller/with_a_custom_backend/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_an_OCI_Artifact_as_Source/index.html b/use_tf_controller/with_an_OCI_Artifact_as_Source/index.html
index db577bf8..fee9adb4 100644
--- a/use_tf_controller/with_an_OCI_Artifact_as_Source/index.html
+++ b/use_tf_controller/with_an_OCI_Artifact_as_Source/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_drift_detection_disabled/index.html b/use_tf_controller/with_drift_detection_disabled/index.html
index 06df41b8..8dc8ecdf 100644
--- a/use_tf_controller/with_drift_detection_disabled/index.html
+++ b/use_tf_controller/with_drift_detection_disabled/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_external_webhooks/index.html b/use_tf_controller/with_external_webhooks/index.html
index a8fd2527..9a50ef0e 100644
--- a/use_tf_controller/with_external_webhooks/index.html
+++ b/use_tf_controller/with_external_webhooks/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_plan_only_mode/index.html b/use_tf_controller/with_plan_only_mode/index.html
index 1501bec5..40e34b18 100644
--- a/use_tf_controller/with_plan_only_mode/index.html
+++ b/use_tf_controller/with_plan_only_mode/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -525,7 +525,7 @@
 
 
 <h1 id="use-tf-controller-with-a-plan-only-mode">Use TF-controller with a plan-only mode</h1>
-<p>This plan-only mode is designed to be used in conjunction with the <a href="../branch_planner/index.md">Branch Planner</a>.
+<p>This plan-only mode is designed to be used in conjunction with the <a href="../../branch_planner/">Branch Planner</a>.
 But you can also use it in a circumstance where you want to run <code>terraform plan</code> only.</p>
 <p>If <code>planOnly</code> is set to <code>true</code>, the controller will skip the apply part and runs
 only <code>terraform plan</code> and saves the output.</p>
diff --git a/use_tf_controller/with_primitive_modules/index.html b/use_tf_controller/with_primitive_modules/index.html
index 87db9017..1c056401 100644
--- a/use_tf_controller/with_primitive_modules/index.html
+++ b/use_tf_controller/with_primitive_modules/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/index.html b/use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/index.html
index a65c43ef..3f232ba1 100644
--- a/use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/index.html
+++ b/use_tf_controller/with_tf_runner_exposed_using_hostname_subdomain/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_tf_runner_logging/index.html b/use_tf_controller/with_tf_runner_logging/index.html
index 0ede992c..0ac84548 100644
--- a/use_tf_controller/with_tf_runner_logging/index.html
+++ b/use_tf_controller/with_tf_runner_logging/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
diff --git a/use_tf_controller/with_the_ready_to_use_AWS_package/index.html b/use_tf_controller/with_the_ready_to_use_AWS_package/index.html
index 585ec32a..dee40f08 100644
--- a/use_tf_controller/with_the_ready_to_use_AWS_package/index.html
+++ b/use_tf_controller/with_the_ready_to_use_AWS_package/index.html
@@ -344,7 +344,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../branch_planner/index.md" class="md-nav__link">
+      <a href="../../branch_planner/" class="md-nav__link">
         
   
   <span class="md-ellipsis">