.gitlab/README.md.template

@@ -197,6 +197,12 @@ three things:
 
 1. set the `enable_id_tokens` input to `true`.
 2. configure the `.gitlab-tofu:id_tokens` job with your desired `id_tokens` setup.
+    - This `.gitlab-tofu:id_tokens` behind the scenes will be used as the base job for the
+      actual tofu jobs, like `plan`, thus some CI keywords maybe overwritten by it, like
+      `before_script` or `script`. We recommend to focus on `id_tokens` related keywords, specifically:
+      - `id_tokens`
+      - `secrets`
+      - `variables`
 3. (optionally) provide the `.gitlab/ci/setup-id-tokens.sh` script to configure things,
    like assuming IAM roles.
 
@@ -235,6 +241,43 @@ aws sts get-caller-identity
 You might configure the name of the `id_tokens` job and the setup script location
 with the `id_tokens_base_job_name` and `id_tokens_setup_script` inputs, respectively.
 
+#### External integration to pull secrets for tofu (providers)
+
+You can easily integrate with external secret providers,
+like a Vault / OpenBao instance using `id_tokens` in combination with `secrets`.
+
+> [!tip]
+> Also have a look at [Using external secrets in CI](https://docs.gitlab.com/ci/secrets/).
+
+For example, you may configure the `aws` provider with a `AWS_ACCESS_KEY_ID` and
+`AWS_SECRET_ACCESS_KEY` assuming their values are stored in `production/aws/AWS_ACCESS_KEY_ID@ops`
+and `production/aws/AWS_SECRET_ACCESS_KEY@ops` (where `production/aws` is the path to the secret,
+the `AWS_*` are the field names and `ops` is the path where the secrets engine is mounted):
+
+```yaml
+include:
+  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@<VERSION>
+    inputs:
+      opentofu_version: <OPENTOFU_VERSION>
+      enable_id_tokens: true
+
+stages: [validate, build, deploy]
+
+.gitlab-tofu:id_tokens:
+  id_tokens:
+    VAULT_ID_TOKEN:
+      aud: https://vault.example.com
+  secrets:
+    AWS_ACCESS_KEY_ID:
+      vault: production/aws/AWS_ACCESS_KEY_ID@ops
+      token: $VAULT_ID_TOKEN
+      file: false
+    AWS_SECRET_ACCESS_KEY:
+      vault: production/aws/AWS_SECRET_ACCESS_KEY@ops
+      token: $VAULT_ID_TOKEN
+      file: false
+```
+
 ### Access to Terraform Module Registry
 
 Similar to automatically configuring the [GitLab-managed Terraform state backend]

README.md

@@ -199,6 +199,12 @@ three things:
 
 1. set the `enable_id_tokens` input to `true`.
 2. configure the `.gitlab-tofu:id_tokens` job with your desired `id_tokens` setup.
+    - This `.gitlab-tofu:id_tokens` behind the scenes will be used as the base job for the
+      actual tofu jobs, like `plan`, thus some CI keywords maybe overwritten by it, like
+      `before_script` or `script`. We recommend to focus on `id_tokens` related keywords, specifically:
+      - `id_tokens`
+      - `secrets`
+      - `variables`
 3. (optionally) provide the `.gitlab/ci/setup-id-tokens.sh` script to configure things,
    like assuming IAM roles.
 
@@ -237,6 +243,43 @@ aws sts get-caller-identity
 You might configure the name of the `id_tokens` job and the setup script location
 with the `id_tokens_base_job_name` and `id_tokens_setup_script` inputs, respectively.
 
+#### External integration to pull secrets for tofu (providers)
+
+You can easily integrate with external secret providers,
+like a Vault / OpenBao instance using `id_tokens` in combination with `secrets`.
+
+> [!tip]
+> Also have a look at [Using external secrets in CI](https://docs.gitlab.com/ci/secrets/).
+
+For example, you may configure the `aws` provider with a `AWS_ACCESS_KEY_ID` and
+`AWS_SECRET_ACCESS_KEY` assuming their values are stored in `production/aws/AWS_ACCESS_KEY_ID@ops`
+and `production/aws/AWS_SECRET_ACCESS_KEY@ops` (where `production/aws` is the path to the secret,
+the `AWS_*` are the field names and `ops` is the path where the secrets engine is mounted):
+
+```yaml
+include:
+  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@<VERSION>
+    inputs:
+      opentofu_version: <OPENTOFU_VERSION>
+      enable_id_tokens: true
+
+stages: [validate, build, deploy]
+
+.gitlab-tofu:id_tokens:
+  id_tokens:
+    VAULT_ID_TOKEN:
+      aud: https://vault.example.com
+  secrets:
+    AWS_ACCESS_KEY_ID:
+      vault: production/aws/AWS_ACCESS_KEY_ID@ops
+      token: $VAULT_ID_TOKEN
+      file: false
+    AWS_SECRET_ACCESS_KEY:
+      vault: production/aws/AWS_SECRET_ACCESS_KEY@ops
+      token: $VAULT_ID_TOKEN
+      file: false
+```
+
 ### Access to Terraform Module Registry
 
 Similar to automatically configuring the [GitLab-managed Terraform state backend]