From 244ed23cb7797a278d953ab0bab5e106b1c575cf Mon Sep 17 00:00:00 2001
From: Timo Furrer <tuxtimo@gmail.com>
Date: Fri, 11 Apr 2025 16:27:13 +0200
Subject: [PATCH] Document example with external secrets integration

Changelog: added
---
 .gitlab/README.md.template | 43 ++++++++++++++++++++++++++++++++++++++
 README.md                  | 43 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/.gitlab/README.md.template b/.gitlab/README.md.template
index 3f6124b..3a3ec03 100644
--- a/.gitlab/README.md.template
+++ b/.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]
diff --git a/README.md b/README.md
index 3154bb8..b181325 100644
--- a/README.md
+++ b/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]
-- 
GitLab