Add latest changes from gitlab-org/gitlab@master

1 files changed, 25 insertions, 10 deletions

diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md
index ba12508beeb..14f771431e5 100644
--- a/doc/ci/secrets/index.md
+++ b/doc/ci/secrets/index.md
@@ -23,10 +23,16 @@ GitLab has selected [Vault by HashiCorp](https://www.vaultproject.io) as the
 first supported provider, and [KV-V2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2)
 as the first supported secrets engine.
 
-GitLab authenticates using Vault's
+By default, GitLab authenticates using Vault's
 [JSON Web Token (JWT) authentication method](https://developer.hashicorp.com/vault/docs/auth/jwt#jwt-authentication), using
-the [JSON Web Token](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) (`CI_JOB_JWT`)
-introduced in GitLab 12.10.
+the [JSON Web Token](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) (`CI_JOB_JWT`).
+
+[ID tokens](../yaml/index.md#id_tokens) is the preferred secure way to authenticate with Vault,
+because ID tokens are defined per-job. GitLab can also authenticate with Vault by using the `CI_JOB_JWT`,
+but that token is provided to every job, which can be a security risk.
+
+The [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md)
+tutorial has more details about authenticating with ID tokens.
 
 You must [configure your Vault server](#configure-your-vault-server) before you
 can use [use Vault secrets in a CI job](#use-vault-secrets-in-a-ci-job).
@@ -106,9 +112,14 @@ After [configuring your Vault server](#configure-your-vault-server), you can use
 the secrets stored in Vault by defining them with the `vault` keyword:
 
 ```yaml
-secrets:
-  DATABASE_PASSWORD:
-    vault: production/db/password@ops  # translates to secret `ops/data/production/db`, field `password`
+job_using_vault:
+  id_tokens:
+    VAULT_ID_TOKEN:
+      aud: https://gitlab.com
+  secrets:
+    DATABASE_PASSWORD:
+      vault: production/db/password@ops  # translates to secret `ops/data/production/db`, field `password`
+      token: $VAULT_ID_TOKEN
 ```
 
 In this example:
@@ -125,9 +136,13 @@ To overwrite the default behavior, set the `file` option explicitly:
 
 ```yaml
 secrets:
+  id_tokens:
+    VAULT_ID_TOKEN:
+      aud: https://gitlab.com
   DATABASE_PASSWORD:
     vault: production/db/password@ops
     file: false
+    token: $VAULT_ID_TOKEN
 ```
 
 In this example, the secret value is put directly in the `DATABASE_PASSWORD` variable
@@ -177,8 +192,8 @@ Always restrict your roles to a project or namespace by using one of the provide
 claims like `project_id` or `namespace_id`. Without these restrictions, any JWT
 generated by this GitLab instance may be allowed to authenticate using this role.
 
-For a full list of `CI_JOB_JWT` claims, read the
-[How it works](../examples/authenticating-with-hashicorp-vault/index.md#how-it-works) section of the
+For a full list of ID token JWT claims, read the
+[How It Works](../examples/authenticating-with-hashicorp-vault/index.md#how-it-works) section of the
 [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial.
 
 You can also specify some attributes for the resulting Vault tokens, such as time-to-live,
@@ -188,7 +203,7 @@ for the JSON web token method.
 
 ## Using a self-signed Vault server
 
-When the Vault server is using a self-signed certificate, you will see the following error in the job logs:
+When the Vault server is using a self-signed certificate, you see the following error in the job logs:
 
 ```plaintext
 ERROR: Job failed (system failure): resolving secrets: initializing Vault service: preparing authenticated client: checking Vault server health: Get https://vault.example.com:8000/v1/sys/health?drsecondarycode=299&performancestandbycode=299&sealedcode=299&standbycode=299&uninitcode=299: x509: certificate signed by unknown authority
@@ -197,7 +212,7 @@ ERROR: Job failed (system failure): resolving secrets: initializing Vault servic
 You have two options to solve this error:
 
 - Add the self-signed certificate to the GitLab Runner server's CA store.
-  If you deployed GitLab Runner using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), you will have to create your own GitLab Runner image.
+  If you deployed GitLab Runner using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), you have to create your own GitLab Runner image.
 - Use the `VAULT_CACERT` environment variable to configure GitLab Runner to trust the certificate:
   - If you are using systemd to manage GitLab Runner, see [how to add an environment variable for GitLab Runner](https://docs.gitlab.com/runner/configuration/init.html#setting-custom-environment-variables).
   - If you deployed GitLab Runner using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html):