Add latest changes from gitlab-org/gitlab@master

2 files changed, 23 insertions, 48 deletions

diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
index a5289ca0a4d..f45c60bdd1f 100644
--- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
+++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
@@ -29,7 +29,7 @@ You must replace the `vault.example.com` URL below with the URL of your Vault se
 
 ## How it works
 
-Each job has JSON Web Token (JWT) provided as CI/CD variable named `CI_JOB_JWT`. This JWT can be used to authenticate with Vault using the [JWT Auth](https://developer.hashicorp.com/vault/docs/auth/jwt#jwt-authentication) method.
+ID tokens are JSON Web Tokens (JWTs) used for OIDC authentication with third-party services. If a job has at least one ID token defined, the `secrets` keyword automatically uses that token to authenticate with Vault.
 
 The following fields are included in the JWT:
 
@@ -256,61 +256,36 @@ $ vault write auth/jwt/config \
 
 For the full list of available configuration options, see Vault's [API documentation](https://developer.hashicorp.com/vault/api-docs/auth/jwt#configure).
 
-The following job, when run for the default branch, is able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
+In GitLab, create the following [CI/CD variables](../../variables/index.md#for-a-project) to provide details about your Vault server:
 
-```yaml
-read_secrets:
-  image: vault:latest
-  script:
-    # Check job's ref name
-    - echo $CI_COMMIT_REF_NAME
-    # and is this ref protected
-    - echo $CI_COMMIT_REF_PROTECTED
-    # Vault's address can be provided here or as CI/CD variable
-    - export VAULT_ADDR=http://vault.example.com:8200
-    # Authenticate and get token. Token expiry time and other properties can be configured
-    # when configuring JWT Auth - https://developer.hashicorp.com/vault/api-docs/auth/jwt#parameters-1
-    - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-staging jwt=$CI_JOB_JWT)"
-    # Now use the VAULT_TOKEN to read the secret and store it in an environment variable
-    - export PASSWORD="$(vault kv get -field=password secret/myproject/staging/db)"
-    # Use the secret
-    - echo $PASSWORD
-    # This will fail because the role myproject-staging can not read secrets from secret/myproject/production/*
-    - export PASSWORD="$(vault kv get -field=password secret/myproject/production/db)"
-```
+- `VAULT_SERVER_URL` - The URL of your Vault server, for example `https://vault.example.com:8200`.
+- `VAULT_AUTH_ROLE` - Optional. The role to use when attempting to authenticate. If no role is specified, Vault uses the [default role](https://developer.hashicorp.com/vault/api-docs/auth/jwt#default_role) specified when the authentication method was configured.
+- `VAULT_AUTH_PATH` - Optional. The path where the authentication method is mounted. Default is `jwt`.
+- `VAULT_NAMESPACE` - Optional. The [Vault Enterprise namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) to use for reading secrets and authentication. If no namespace is specified, Vault uses the root (`/`) namespace. The setting is ignored by Vault Open Source.
 
-NOTE:
-If you're using a Vault instance provided by HashiCorp Cloud Platform,
-you need to export the `VAULT_NAMESPACE` variable. Its default value is `admin`.
-
-![read secrets staging example](img/vault-read-secrets-staging.png)
-
-The following job is able to authenticate using the `myproject-production` role and read secrets under `/secret/myproject/production/`:
+The following job, when run for the default branch, can read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
 
 ```yaml
-read_secrets:
-  image: vault:latest
+job_with_secrets:
+  id_tokens:
+    VAULT_ID_TOKEN:
+      aud: https://example.vault.com
+  secrets:
+    STAGING_DB_PASSWORD:
+      vault: secret/myproject/staging/db/password@secrets # authenticates using $VAULT_ID_TOKEN
   script:
-    # Check job's ref name
-    - echo $CI_COMMIT_REF_NAME
-    # and is this ref protected
-    - echo $CI_COMMIT_REF_PROTECTED
-    # Vault's address can be provided here or as CI/CD variable
-    - export VAULT_ADDR=http://vault.example.com:8200
-    # Authenticate and get token. Token expiry time and other properties can be configured
-    # when configuring JWT Auth - https://developer.hashicorp.com/vault/api-docs/auth/jwt#parameters-1
-    - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-production jwt=$CI_JOB_JWT)"
-    # Now use the VAULT_TOKEN to read the secret and store it in environment variable
-    - export PASSWORD="$(vault kv get -field=password secret/myproject/production/db)"
-    # Use the secret
-    - echo $PASSWORD
+    - access-staging-db.sh --token $STAGING_DB_PASSWORD
 ```
 
-![read secrets production example](img/vault-read-secrets-production.png)
+In this example:
+
+- `@secrets` - The vault name, where your Secrets Engines are enabled.
+- `secret/myproject/staging/db` - The path location of the secret in Vault.
+- `password` The field to be fetched within the referenced secret.
 
 ### Limit token access to Vault secrets
 
-You can control `CI_JOB_JWT` access to Vault secrets by using Vault protections
+You can control ID token access to Vault secrets by using Vault protections
 and GitLab features. For example, restrict the token by:
 
 - Using Vault [bound claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims)
diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md
index 07019a2776f..2cfda1116fe 100644
--- a/doc/ci/yaml/yaml_optimization.md
+++ b/doc/ci/yaml/yaml_optimization.md
@@ -65,7 +65,7 @@ test2:
 
 `&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the
 given hash into the current one," and `*` includes the named anchor
-(`job_configuration` again). The expanded version of this example is:
+(`job_configuration` again). The [expanded](../pipeline_editor/index.md#view-full-configuration) version of this example is:
 
 ```yaml
 .job_template:
@@ -123,7 +123,7 @@ test:mysql:
   services: *mysql_configuration
 ```
 
-The expanded version is:
+The [expanded](../pipeline_editor/index.md#view-full-configuration) version is:
 
 ```yaml
 .job_template: