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