feat(tf): Add support for Cloudflare R2 as a TF backend

Author: stuartellis

README.md

@@ -49,8 +49,8 @@ uvx copier copy git+https://github.com/stuartellis/tf-tasks my-project
 # Go to the working directory for the project
 cd my-project
 
-# Ask tenv to detect and install the correct version of Terraform for the project
-tenv terraform install
+# Ask tenv to detect and install the correct version of OpenTofu for the project
+tenv opentofu install
 
 # Create a configuration and a root module for the project
 TFT_CONTEXT=dev task tft:context:new
@@ -201,23 +201,59 @@ The `context.json` file is the configuration file for the context. It specifies
       "tfstate_dir": "dev",
       "region": "eu-west-2",
       "role_arn": "arn:aws:iam::789000123456:role/my-tf-state-role"
-    },
+    }
+  }
+}
+```
+
+The `backends.s3` section specifies the settings for a TF backend that uses S3 for storage. This uses the [S3 native locking feature](https://opentofu.org/docs/language/settings/backends/s3/) in current versions of OpenTofu and Terraform. It does not use DynamoDB. The tooling will use this backend by default.
+
+To use Amazon S3 with DynamoDB for locking, specify an `s3ddb` backend:
+
+```json
+{
+  "metadata": {
+    "description": "Cloud development environment",
+    "environment": "dev"
+  },
+  "backends": {
     "s3ddb": {
-      "tfstate_bucket": "",
-      "tfstate_ddb_table": "",
-      "tfstate_dir": "",
-      "region": "",
-      "role_arn": ""
+      "tfstate_bucket": "789000123456-tf-state-dev-eu-west-2",
+      "tfstate_ddb_table": "789000123456-tf-lock-dev-eu-west-2",
+      "tfstate_dir": "dev",
+      "region": "eu-west-2",
+      "role_arn": "arn:aws:iam::789000123456:role/my-tf-state-role"
     }
   }
 }
 ```
 
-The `backends.s3` section specifies the settings for a TF backend that uses S3 for storage. This uses the [S3 native locking feature](https://opentofu.org/docs/language/settings/backends/s3/) in current versions of Terraform and OpenTofu. It does not use DynamoDB. The tooling will use this backend by default.
+> The tooling automatically enables encryption for S3 backends.
+
+This tooling also supports [Cloudflare R2](https://developers.cloudflare.com/r2/) for remote state storage. To use Cloudflare R2, specify the backend as `r2` in the `context.json` file:
+
+```json
+{
+  "metadata": {
+    "description": "Cloud development environment",
+    "environment": "dev"
+  },
+  "backends": {
+      "r2": {
+        "tfstate_bucket": "my-weur-tf-state-dev",
+        "tfstate_dir": "dev",
+        "region": "auto",
+        "s3_api_endpoint": "https://YOUR-ACCOUNT-ID.r2.cloudflarestorage.com"
+      },
+  }
+}
+```
+
+> Always set the region as `auto` for R2.
 
-The `backends.s3ddb` section specifies the settings for a legacy TF backend that uses S3 for storage and DynamoDB for locking. Only use this type of backend if you need to use an older version of Terraform or OpenTofu.
+Cloudflare R2 implements the S3 API, so you use the same `backend "s3"` block in your TF module with R2 as you would with Amazon S3. 
 
-> The tooling automatically enables encryption for both types of S3 backend.
+This also means that you need to specify an Access Key ID and a Secret Access Key for TF to connect to the R2 bucket. Each API token for R2 has an Access Key ID and a Secret Access Key for compatibility with S3, but other types of Cloudflare API tokens do not. The Cloudflare documentation explains [how to get S3 credentials for an R2 API token](https://developers.cloudflare.com/r2/api/tokens/). Set these S3 credentials as environment variables: `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY`.
 
 ### Setting the tfvars for a Context
 
@@ -400,7 +436,7 @@ Set these variables to override the defaults:
 | tft:units     | List the units.                                                                            |
 | tft:validate  | _terraform validate_ for a unit\*                                                          |
 
-\*: These tasks require that you first [initialise](https://opentofu.org/docs/cli/commands/init/) the unit.
+\*: These tasks require that you first [initialize](https://opentofu.org/docs/cli/commands/init/) the unit.
 
 ### The `tft:context` Tasks
 
@@ -424,6 +460,7 @@ Set these variables to override the defaults:
 | -------------- | ------------------------------------------------------------------------ |
 | tft:init       | _terraform init_ for a unit. An alias for `tft:init:s3`.                 |
 | tft:init:local | _terraform init_ for a unit, with local state.                           |
+| tft:init:r2    | _terraform init_ for a unit, with Cloudflare R2 remote state.            |
 | tft:init:s3    | _terraform init_ for a unit, with S3 remote state and native S3 locking. |
 | tft:init:s3ddb | _terraform init_ for a unit, with S3 remote state and DynamoDB locking.  |
 
@@ -437,7 +474,7 @@ Similarly, there are no restrictions on how you run tasks on multiple units. You
 
 ### Migrating to Terraform
 
-By default, this tooling currently uses OpenTofu. Set `TFT_CLI_EXE` as an environment variable to specify the path to the tool that you wish to use. To use [OpenTofu](https://opentofu.org/), set `TFT_CLI_EXE` with the value `terraform`:
+By default, this tooling currently uses OpenTofu. Set `TFT_CLI_EXE` as an environment variable to specify the path to the tool that you wish to use. To use [Terraform](https://developer.hashicorp.com/terraform), set `TFT_CLI_EXE` with the value `terraform`:
 
 ```shell
 export TFT_CLI_EXE=terraform
@@ -448,12 +485,12 @@ TFT_CONTEXT=dev TFT_UNIT=my-app tft:init
 To specify which version of Terraform to use, create a `.terraform-version` file. This file should contain the version of Terraform and nothing else, like this:
 
 ```shell
-1.12.0
+1.15.3
 ```
 
 The `tenv` tool reads this file when installing or running Terraform.
 
-> Remember that if you switch between Terraform and OpenTofu, you will need to initialize your unit again, and when you run `apply` it will migrate the TF state. The OpenTofu Website provides [migration guides](https://opentofu.org/docs/intro/migration/), which includes information about code changes that you may need to make.
+> Remember that if you switch between Terraform and OpenTofu, the state may not be compatible. You will need to initialize your unit again, and when you run `apply` it will attempt to migrate the TF state.
 
 ## Contributing
 

template/tasks/tft/Taskfile.yaml.jinja

@@ -5,7 +5,7 @@
 #
 # Maintained by Copier: DO NOT EDIT THIS FILE
 #
-# Terraform and OpenTofu tasks for the Task runner.
+# OpenTofu and Terraform tasks for the Task runner.
 #
 # https://github.com/stuartellis/tf-tasks
 #
@@ -327,15 +327,43 @@ tasks:
   ## TF initialization tasks ##
 
   init:local:
-    desc: Initialise local state for TF unit
+    desc: Initialize local state for TF unit
     deps: [clean]
     cmds:
       - "{{.CURRENT_TFT_CLI_EXE}} {{.TFT_CLI_CHDIR_OPT}} init -input=false {{.CLI_ARGS}}"
     requires:
       vars: [TFT_CONTEXT, TFT_UNIT]
 
+  init:r2:
+    desc: Initialize remote state for TF unit - Cloudflare R2
+    deps: [clean]
+    cmds:
+      - "{{.CURRENT_TFT_CLI_EXE}} {{.TFT_CLI_CHDIR_OPT}} init -input=false {{.TFT_CLI_BACKEND_OPT}} {{.CLI_ARGS}}"
+    requires:
+      vars: [TFT_CONTEXT, TFT_UNIT]
+    vars:
+      TFT_CLI_BACKEND_DOCUMENT:
+        sh: cat {{.TFT_CONTEXTS_DIR}}/{{.TFT_CONTEXT}}/context.json
+      TFT_CLI_BACKEND_CONFIG:
+        ref: "fromJson .TFT_CLI_BACKEND_DOCUMENT"
+      TFT_CLI_BACKEND_R2_OPT: >
+        -backend-config=\"use_lockfile=true\"
+        -backend-config=\"skip_credentials_validation=true\"
+        -backend-config=\"skip_metadata_api_check=true\"
+        -backend-config=\"skip_region_validation=true\"
+        -backend-config=\"skip_requesting_account_id=true\"
+        -backend-config=\"skip_s3_checksum=true\"
+        -backend-config=\"use_path_style=true\"
+        -backend-config=\"region={{.TFT_CLI_BACKEND_CONFIG.backends.r2.region}}\"
+        -backend-config=\"bucket={{.TFT_CLI_BACKEND_CONFIG.backends.r2.tfstate_bucket}}\"
+        -backend-config=\"endpoints={s3=\\\"{{.TFT_CLI_BACKEND_CONFIG.backends.r2.s3_api_endpoint}}\\\"}\"
+        -backend-config=\"workspace_key_prefix=workspaces\"
+        -backend-config=\"key=components/{{.CURRENT_TFT_PRODUCT_NAME}}/{{.TFT_CLI_BACKEND_CONFIG.backends.r2.tfstate_dir}}/{{.TFT_UNIT}}.tfstate\"
+      TFT_CLI_BACKEND_OPT:
+        sh: echo {{if eq .TFT_REMOTE_BACKEND "false"}}{{else}}{{.TFT_CLI_BACKEND_R2_OPT}}{{end}}
+
   init:s3:
-    desc: Initialise remote state for TF unit - S3-compatible with native locking
+    desc: Initialize remote state for TF unit - Amazon S3 with native locking
     aliases:
       - init
     deps: [clean]
@@ -360,7 +388,7 @@ tasks:
         sh: echo {{if eq .TFT_REMOTE_BACKEND "false"}}{{else}}{{.TFT_CLI_BACKEND_S3_OPT}}{{end}}
 
   init:s3ddb:
-    desc: Initialise remote state for TF unit - S3 with DynamoDB locking
+    desc: Initialize remote state for TF unit - Amazon S3 with DynamoDB locking
     deps: [clean]
     cmds:
       - "{{.CURRENT_TFT_CLI_EXE}} {{.TFT_CLI_CHDIR_OPT}} init -input=false {{.TFT_CLI_BACKEND_OPT}} {{.CLI_ARGS}}"

template/tf/contexts/template/context.json

@@ -4,15 +4,14 @@
     "environment": "ENVIRONMENT_NAME"
   },
   "backends": {
-    "s3": {
+    "r2": {
       "tfstate_bucket": "",
       "tfstate_dir": "",
-      "region": "",
-      "role_arn": ""
+      "region": "auto",
+      "s3_api_endpoint": ""
     },
-    "s3ddb": {
+    "s3": {
       "tfstate_bucket": "",
-      "tfstate_ddb_table": "",
       "tfstate_dir": "",
       "region": "",
       "role_arn": ""