From ca2687c20ee0a1936d2781e26df3a9d0da27e128 Mon Sep 17 00:00:00 2001
From: Timo Furrer <tfurrer@gitlab.com>
Date: Thu, 14 Nov 2024 18:10:00 +0100
Subject: [PATCH] Document state and plan encryption support

Changelog: added
---
 .gitlab/README.md.template | 90 ++++++++++++++++++++++++++++++++++++++
 README.md                  | 90 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 180 insertions(+)

diff --git a/.gitlab/README.md.template b/.gitlab/README.md.template
index e77bcf4..bf69880 100644
--- a/.gitlab/README.md.template
+++ b/.gitlab/README.md.template
@@ -326,6 +326,96 @@ or `TF_CLI_ARGS_init` (handled by OpenTofu directly) to `-lockfile=readonly`
 to prevent any changes to the lockfile during the pipeline job and with
 that ensuring that OpenTofu really uses the locked dependencies.
 
+#### State and Plan Encryption
+
+We recommend that you configure the OpenTofu
+[State and Plan Encryption](https://opentofu.org/docs/language/state/encryption).
+
+You can easily do this by following the guide on the page linked above.
+
+Here is an example:
+
+**Tofu config at `<root-dir>/encryption.tf`**:
+
+```hcl
+variable "passphrase" {
+  sensitive   = true
+  description = "Passphrase to encrypt and decrypt state and plan"
+}
+
+terraform {
+  encryption {
+    key_provider "pbkdf2" "this" {
+      passphrase = var.passphrase
+    }
+
+    method "aes_gcm" "this" {
+      keys = key_provider.pbkdf2.this
+    }
+
+    state {
+      method = method.aes_gcm.this
+    }
+
+    plan {
+      method = method.aes_gcm.this
+    }
+  }
+}
+```
+
+Then you only not to configure a passphrase as CI/CD variable with the name
+`TF_VAR_passphrase`.
+
+Everything else will work out of the box.
+
+In case you want to migrate from an unencrypted state and plan you can
+temporarily configure your encryption block with `fallback`s, like so:
+
+```hcl
+variable "passphrase" {
+  sensitive   = true
+  description = "Passphrase to ecnrypt and decrypt state and plan"
+}
+
+terraform {
+  encryption {
+    method "unencrypted" "migrate" {}
+
+    key_provider "pbkdf2" "this" {
+      passphrase = var.passphrase
+    }
+
+    method "aes_gcm" "this" {
+      keys = key_provider.pbkdf2.this
+    }
+
+    state {
+      method = method.aes_gcm.this
+
+      fallback {
+        method = method.unencrypted.migrate
+      }
+    }
+
+    plan {
+      method = method.aes_gcm.this
+
+      fallback {
+        method = method.unencrypted.migrate
+      }
+    }
+  }
+}
+```
+
+Then you can run the pipeline one time to migrate and then remove the
+`unencrypted` `method` and the `fallback` blocks.
+
+> **Call for Action**:
+> If you have a good proposal on how to make state and plan encryption
+> easier with this component then let us know in an issue!
+
 ### Examples
 
 Here are some example repositories to demonstrate how this component maybe used:
diff --git a/README.md b/README.md
index f45c9e4..f19502b 100644
--- a/README.md
+++ b/README.md
@@ -401,6 +401,96 @@ or `TF_CLI_ARGS_init` (handled by OpenTofu directly) to `-lockfile=readonly`
 to prevent any changes to the lockfile during the pipeline job and with
 that ensuring that OpenTofu really uses the locked dependencies.
 
+#### State and Plan Encryption
+
+We recommend that you configure the OpenTofu
+[State and Plan Encryption](https://opentofu.org/docs/language/state/encryption).
+
+You can easily do this by following the guide on the page linked above.
+
+Here is an example:
+
+**Tofu config at `<root-dir>/encryption.tf`**:
+
+```hcl
+variable "passphrase" {
+  sensitive   = true
+  description = "Passphrase to encrypt and decrypt state and plan"
+}
+
+terraform {
+  encryption {
+    key_provider "pbkdf2" "this" {
+      passphrase = var.passphrase
+    }
+
+    method "aes_gcm" "this" {
+      keys = key_provider.pbkdf2.this
+    }
+
+    state {
+      method = method.aes_gcm.this
+    }
+
+    plan {
+      method = method.aes_gcm.this
+    }
+  }
+}
+```
+
+Then you only not to configure a passphrase as CI/CD variable with the name
+`TF_VAR_passphrase`.
+
+Everything else will work out of the box.
+
+In case you want to migrate from an unencrypted state and plan you can
+temporarily configure your encryption block with `fallback`s, like so:
+
+```hcl
+variable "passphrase" {
+  sensitive   = true
+  description = "Passphrase to ecnrypt and decrypt state and plan"
+}
+
+terraform {
+  encryption {
+    method "unencrypted" "migrate" {}
+
+    key_provider "pbkdf2" "this" {
+      passphrase = var.passphrase
+    }
+
+    method "aes_gcm" "this" {
+      keys = key_provider.pbkdf2.this
+    }
+
+    state {
+      method = method.aes_gcm.this
+
+      fallback {
+        method = method.unencrypted.migrate
+      }
+    }
+
+    plan {
+      method = method.aes_gcm.this
+
+      fallback {
+        method = method.unencrypted.migrate
+      }
+    }
+  }
+}
+```
+
+Then you can run the pipeline one time to migrate and then remove the
+`unencrypted` `method` and the `fallback` blocks.
+
+> **Call for Action**:
+> If you have a good proposal on how to make state and plan encryption
+> easier with this component then let us know in an issue!
+
 ### Examples
 
 Here are some example repositories to demonstrate how this component maybe used:
-- 
GitLab