Add latest changes from gitlab-org/gitlab@master

1 files changed, 19 insertions, 6 deletions

diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md
index 6d561fe00a3..09aeebcc7cc 100644
--- a/doc/ci/secrets/index.md
+++ b/doc/ci/secrets/index.md
@@ -17,23 +17,36 @@ Unlike CI variables, which are always presented to a job, secrets must be explic
 required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/README.md#secrets)
 for more information about the syntax.
 
-GitLab has selected [Vault by Hashicorp](https://www.vaultproject.io) as the
+GitLab has selected [Vault by HashiCorp](https://www.vaultproject.io) as the
 first supported provider, and [KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2)
 as the first supported secrets engine.
 
 GitLab authenticates using Vault's
-[JWT Auth method](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication), using
+[JSON Web Token (JWT) authentication method](https://www.vaultproject.io/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.
 
 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).
 
+The flow for using GitLab with HashiCorp Vault
+is summarized by this diagram:
+
+![Flow between GitLab and HashiCorp](../img/gitlab_vault_workflow_v13_4.png "How GitLab CI_JOB_JWT works with HashiCorp Vault")
+
+1. Configure your vault and secrets.
+1. Generate your JWT and provide it to your CI job.
+1. Runner contacts HashiCorp Vault and authenticates using the JWT.
+1. HashiCorp Vault verifies the JWT.
+1. HashiCorp Vault checks the bounded claims and attaches policies.
+1. HashiCorp Vault returns the token.
+1. Runner reads secrets from the HashiCoupr Vault.
+
 NOTE: **Note:**
-Read the [Authenticating and Reading Secrets With Hashicorp Vault](../examples/authenticating-with-hashicorp-vault/index.md)
-tutorial for a version of this feature that is available to all
+Read the [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md)
+tutorial for a version of this feature. It's available to all
 subscription levels, supports writing secrets to and deleting secrets from Vault,
-and multiple secrets engines.
+and supports multiple secrets engines.
 
 ## Configure your Vault server
 
@@ -149,7 +162,7 @@ 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
-[Authenticating and Reading Secrets With Hashicorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial.
+[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,
 IP address range, and number of uses. The full list of options is available in