Deprecate `TF_STATE_NAME` and introduce `GITLAB_TOFU_STATE_NAME` as replacement

Changelog: changed

.gitlab/README.md.template

@@ -518,6 +518,7 @@ When migrating from the GitLab Terraform CI/CD templates you can use the followi
     - Although the `TF_ROOT` variable is still used and maybe overwritten after the import on individual jobs.
 - Migrate the `TF_STATE_NAME` variable to the `state_name` input.
     - Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
+    - Note that this component deprecated the `TF_STATE_NAME` variable and uses `GITLAB_TOFU_STATE_NAME` instead.
 - Migrate the `TF_AUTO_DEPLOY` variable to custom `rules` inputs.
 - Used other variables -> Use the same variables with this component.
 

README.md

@@ -533,6 +533,7 @@ When migrating from the GitLab Terraform CI/CD templates you can use the followi
     - Although the `TF_ROOT` variable is still used and maybe overwritten after the import on individual jobs.
 - Migrate the `TF_STATE_NAME` variable to the `state_name` input.
     - Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
+    - Note that this component deprecated the `TF_STATE_NAME` variable and uses `GITLAB_TOFU_STATE_NAME` instead.
 - Migrate the `TF_AUTO_DEPLOY` variable to custom `rules` inputs.
 - Used other variables -> Use the same variables with this component.
 

src/gitlab-tofu.sh

@@ -20,6 +20,7 @@
 # GITLAB_TOFU_IMPLICIT_INIT: if set to true will perform an implicit `tofu init` before any command that require it. Defaults to `true`.
 # GITLAB_TOFU_IGNORE_INIT_ERRORS: if set to true will ignore errors in the `tofu init` command.
 # GITLAB_TOFU_INIT_NO_RECONFIGURE: if set to true will not pass `-reconfigure` to the `tofu init` command.
+# GITLAB_TOFU_STATE_NAME: the name of the GitLab-managed Terraform state backend endpoint.
 #
 # Respected OpenTofu Environment Variables:
 # > these are variables that are
@@ -97,6 +98,18 @@ if [ -n "$ZSH_VERSION" ]; then
   unsetopt sh_word_split
 fi
 
+# Deprecations
+# ============
+if [ -n "$TF_STATE_NAME" ]; then
+  echo 'WARNING: you have manually set the deprecated TF_STATE_NAME environment variable. Please use the GITLAB_TOFU_STATE_NAME environment variable instead. The TF_STATE_NAME variable will be removed soon.' >&2
+
+  if [ -n "$GITLAB_TOFU_STATE_NAME" ]; then
+    echo 'WARNING: you have set GITLAB_TOFU_STATE_NAME environment variable in addition to the deprecated TF_STATE_NAME. This causes a conflict and GITLAB_TOFU_STATE_NAME will be used exclusively' >&2
+  else
+    GITLAB_TOFU_STATE_NAME="$TF_STATE_NAME"
+  fi
+fi
+
 JQ_PLAN='
   (
     [.resource_changes[]?.change.actions?] | flatten
@@ -111,11 +124,11 @@ JQ_PLAN='
 state_backend_username="gitlab-ci-token"
 state_backend_password="${CI_JOB_TOKEN}"
 
-# If TF_ADDRESS is unset but TF_STATE_NAME is provided, then default to GitLab backend in current project
-if [ -n "${TF_STATE_NAME}" ] && [ -z "${TF_ADDRESS}" ]; then
-  # auto url-encode TF_STATE_NAME
-  TF_STATE_NAME="$(jq -rn --arg x "${TF_STATE_NAME}" '$x|@uri')"
-  TF_ADDRESS="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}"
+# If TF_ADDRESS is unset but GITLAB_TOFU_STATE_NAME is provided, then default to GitLab backend in current project
+if [ -n "${GITLAB_TOFU_STATE_NAME}" ] && [ -z "${TF_ADDRESS}" ]; then
+  # auto url-encode GITLAB_TOFU_STATE_NAME
+  GITLAB_TOFU_STATE_NAME="$(jq -rn --arg x "${GITLAB_TOFU_STATE_NAME}" '$x|@uri')"
+  TF_ADDRESS="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${GITLAB_TOFU_STATE_NAME}"
 fi
 
 if [ -z "${GITLAB_TOFU_PLAN_NAME}" ]; then

templates/apply.yml

@@ -97,9 +97,9 @@ spec:
 '$[[ inputs.as ]]':
   stage: $[[ inputs.stage ]]
   environment:
-    name: $TF_STATE_NAME
+    name: $GITLAB_TOFU_STATE_NAME
     action: start
-  resource_group: $TF_STATE_NAME
+  resource_group: $GITLAB_TOFU_STATE_NAME
   rules: $[[ inputs.rules ]]
   cache:
     key: "$__CACHE_KEY_HACK"
@@ -110,7 +110,7 @@ spec:
     # FIXME: work around to make slashes work in `cache:key`. see https://gitlab.com/gitlab-org/gitlab/-/issues/439898
     __CACHE_KEY_HACK: "$[[ inputs.root_dir ]]"
     TF_ROOT: $[[ inputs.root_dir ]]
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
     GITLAB_TOFU_APPLY_NO_PLAN: $[[ inputs.no_plan ]]
     GITLAB_TOFU_PLAN_NAME: $[[ inputs.plan_name ]]
     GITLAB_TOFU_VAR_FILE: '$[[ inputs.var_file ]]'

templates/delete-state.yml

@@ -27,10 +27,10 @@ spec:
 
 '$[[ inputs.as ]]':
   stage: $[[ inputs.stage ]]
-  resource_group: $TF_STATE_NAME
+  resource_group: $GITLAB_TOFU_STATE_NAME
   image: curlimages/curl:latest
   variables:
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
   script:
-    - curl --request DELETE -u "gitlab-ci-token:$CI_JOB_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/$TF_STATE_NAME"
+    - curl --request DELETE -u "gitlab-ci-token:$CI_JOB_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/$GITLAB_TOFU_STATE_NAME"
   rules: $[[ inputs.rules ]]

templates/destroy.yml

@@ -97,9 +97,9 @@ spec:
 '$[[ inputs.as ]]':
   stage: $[[ inputs.stage ]]
   environment:
-    name: $TF_STATE_NAME
+    name: $GITLAB_TOFU_STATE_NAME
     action: stop
-  resource_group: $TF_STATE_NAME
+  resource_group: $GITLAB_TOFU_STATE_NAME
   rules: $[[ inputs.rules ]]
   cache:
     key: "$__CACHE_KEY_HACK"
@@ -110,7 +110,7 @@ spec:
     # FIXME: work around to make slashes work in `cache:key`. see https://gitlab.com/gitlab-org/gitlab/-/issues/439898
     __CACHE_KEY_HACK: "$[[ inputs.root_dir ]]"
     TF_ROOT: $[[ inputs.root_dir ]]
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
     GITLAB_TOFU_APPLY_NO_PLAN: $[[ inputs.no_plan ]]
     GITLAB_TOFU_PLAN_NAME: $[[ inputs.plan_name ]]
     GITLAB_TOFU_VAR_FILE: '$[[ inputs.var_file ]]'

templates/graph.yml

@@ -104,7 +104,7 @@ spec:
     # FIXME: work around to make slashes work in `cache:key`. see https://gitlab.com/gitlab-org/gitlab/-/issues/439898
     __CACHE_KEY_HACK: "$[[ inputs.root_dir ]]"
     TF_ROOT: $[[ inputs.root_dir ]]
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
     GITLAB_TOFU_VAR_FILE: '$[[ inputs.var_file ]]'
   image:
     name: '$[[ inputs.image_registry_base ]]/$[[ inputs.image_name ]]:$[[ inputs.version ]]-opentofu$[[ inputs.opentofu_version ]]-$[[ inputs.base_os ]]$[[ inputs.image_digest ]]'

templates/module-release.yml

@@ -23,7 +23,7 @@ spec:
       description: |
         System that this module can be used with.
         e.g. 'local' or 'azurerm'
-    
+
     module_version:
       description: |
         Version of the module that should be published.

templates/plan.yml

@@ -156,7 +156,7 @@ spec:
     # FIXME: work around to make slashes work in `cache:key`. see https://gitlab.com/gitlab-org/gitlab/-/issues/439898
     __CACHE_KEY_HACK: "$[[ inputs.root_dir ]]"
     TF_ROOT: $[[ inputs.root_dir ]]
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
     GITLAB_TOFU_PLAN_NAME: $[[ inputs.plan_name ]]
     GITLAB_TOFU_PLAN_WITH_JSON: true
     GITLAB_TOFU_VAR_FILE: '$[[ inputs.var_file ]]'

templates/test.yml

@@ -107,7 +107,7 @@ spec:
     # FIXME: work around to make slashes work in `cache:key`. see https://gitlab.com/gitlab-org/gitlab/-/issues/439898
     __CACHE_KEY_HACK: "$[[ inputs.root_dir ]]"
     TF_ROOT: $[[ inputs.root_dir ]]
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
     GITLAB_TOFU_VAR_FILE: '$[[ inputs.var_file ]]'
   image:
     name: '$[[ inputs.image_registry_base ]]/$[[ inputs.image_name ]]:$[[ inputs.version ]]-opentofu$[[ inputs.opentofu_version ]]-$[[ inputs.base_os ]]$[[ inputs.image_digest ]]'

templates/validate.yml

@@ -103,7 +103,7 @@ spec:
     # FIXME: work around to make slashes work in `cache:key`. see https://gitlab.com/gitlab-org/gitlab/-/issues/439898
     __CACHE_KEY_HACK: "$[[ inputs.root_dir ]]"
     TF_ROOT: $[[ inputs.root_dir ]]
-    TF_STATE_NAME: $[[ inputs.state_name ]]
+    GITLAB_TOFU_STATE_NAME: $[[ inputs.state_name ]]
     GITLAB_TOFU_IGNORE_INIT_ERRORS: 'true' # Tofu can report errors which might be the reason init failed.
     GITLAB_TOFU_VAR_FILE: '$[[ inputs.var_file ]]'
   image:

tests/integration-tests/Defaults.gitlab-ci.yml

@@ -6,7 +6,7 @@ include:
       base_os: $GITLAB_OPENTOFU_BASE_IMAGE_OS
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       # Required to run everything immediately, instead of manually.
       fmt_rules: [{when: always}]
       validate_rules: [{when: always}]

tests/integration-tests/Destroy.gitlab-ci.yml

@@ -7,7 +7,7 @@ include:
       as: 'setup:apply'
       stage: setup
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       no_plan: true
       # Required to run everything immediately, instead of manually.
       rules: [{when: always}]
@@ -18,7 +18,7 @@ include:
       version: $CI_COMMIT_SHA
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       # Required to run everything immediately, instead of manually.
       fmt_rules: [{when: always}]
       validate_rules: [{when: always}]

tests/integration-tests/FullPipelineTriggerInChildPipeline.gitlab-ci.yml

@@ -6,7 +6,7 @@ include:
       base_os: $GITLAB_OPENTOFU_BASE_IMAGE_OS
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       # Required to run everything immediately, instead of manually.
       fmt_rules: [{when: always}]
       validate_rules: [{when: always}]

tests/integration-tests/JobTemplates.gitlab-ci.yml

@@ -5,7 +5,7 @@ include:
       version: $CI_COMMIT_SHA
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
 
 stages: [validate, build, deploy, cleanup]
 

tests/integration-tests/TestJob.gitlab-ci.yml

@@ -5,7 +5,7 @@ include:
       version: $CI_COMMIT_SHA
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       # Required to run everything immediately, instead of manually.
       rules: [{when: always}]
 

tests/integration-tests/TriggerInChildPipeline.gitlab-ci.yml

@@ -5,8 +5,8 @@ include:
       version: $CI_COMMIT_SHA
       base_os: $GITLAB_OPENTOFU_BASE_IMAGE_OS
       opentofu_version: $OPENTOFU_VERSION
-      root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      root_dir: $TEST_GITLAB_TOFU_ROOT_DIR
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       fmt_rules: [{when: on_success}]
       validate_rules: [{when: on_success}]
       plan_rules: [{when: on_success}]
@@ -19,7 +19,7 @@ include:
   - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/delete-state@$CI_COMMIT_SHA
     inputs:
       stage: cleanup
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       rules: [{when: always}]
 
 stages: [test, cleanup]

tests/integration-tests/ValidatePlanDestroyTriggerInChildPipeline.gitlab-ci.yml

@@ -7,7 +7,7 @@ include:
       as: 'setup:apply'
       stage: setup
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       no_plan: true
       # Required to run everything immediately, instead of manually.
       rules: [{when: always}]
@@ -18,7 +18,7 @@ include:
       version: $CI_COMMIT_SHA
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       # Required to run everything immediately, instead of manually.
       fmt_rules: [{when: always}]
       validate_rules: [{when: always}]

tests/integration-tests/VarFile.gitlab-ci.yml

@@ -6,7 +6,7 @@ include:
       base_os: $GITLAB_OPENTOFU_BASE_IMAGE_OS
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       var_file: varfile.integration-test.tfvars
       # Required to run everything immediately, instead of manually.
       fmt_rules: [{when: always}]

tests/integration-tests/WarningOnNonEmptyPlan.gitlab-ci.yml

@@ -6,13 +6,13 @@ include:
       base_os: $GITLAB_OPENTOFU_BASE_IMAGE_OS
       opentofu_version: $OPENTOFU_VERSION
       root_dir: $TEST_TF_ROOT
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       warning_on_non_empty_plan: true
 
   # For CI Terraform state cleanup
   - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/delete-state@$CI_COMMIT_SHA
     inputs:
-      state_name: $TEST_TF_STATE_NAME
+      state_name: $TEST_GITLAB_TOFU_STATE_NAME
       rules: [{when: always}]
 
 stages: [build, cleanup, verify]