Merge branch 'encryption-support' into 'main'

Document state and plan encryption support

See merge request components/opentofu!197

.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:

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: