diff --git a/.gitlab/README.md.template b/.gitlab/README.md.template index e77bcf401d67ef99ca8d095e2fc09e54b64cf959..bf69880d3b82f5e606da5d26bcc820f79f9c0a2a 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 f45c9e48822b8351e42c4d4b56083ad953ec84ef..f19502be1bb6dfb3e8fa56ed00aaa061eef8adeb 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: