Add latest changes from gitlab-org/gitlab@master

6 files changed, 49 insertions, 18 deletions

diff --git a/doc/ci/components/catalog.md b/doc/ci/components/catalog.md
index 2194e72d56c..36ed7065e1c 100644
--- a/doc/ci/components/catalog.md
+++ b/doc/ci/components/catalog.md
@@ -11,15 +11,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 The CI/CD catalog is a list of [components repositories](index.md#components-repository),
 each containing resources that you can add to your CI/CD pipelines.
 
-## Mark a components repository as a catalog resource
+Each top level namespace has its own catalog, which contains all the releases from
+components repositories hosted under it. You can create components repositories anywhere
+under the desired top level namespace and the released components are available to
+all projects in that namespace.
+
+## Add a components repository to the Catalog
 
 After components are added to a components repository, they can immediately be [used](index.md#use-a-component-in-a-cicd-configuration)
 to build pipelines in other projects.
 
-However, this repository is not discoverable. You must mark this project as a catalog resource
-to allow it to be visible in the CI/CD Catalog so other users can discover it.
+However, the repository is not discoverable. You must set the project as a catalog resource
+for it to be visible in the CI/CD Catalog, then other users can discover it. You should only set a repository as a catalog resource when the components are ready for usage.
 
-To mark a project as a catalog resource:
+To set a project as a catalog resource:
 
 1. On the left sidebar, select **Search or go to** and find your project.
 1. On the left sidebar, select **Settings > General**.
@@ -30,4 +35,15 @@ Ensure the project has a clear [description](../../user/project/settings/index.m
 as the project description is displayed in the component list in the catalog.
 
 NOTE:
-This action is not reversible.
+This action is not reversible, and the
+component is always visible in the Catalog unless the repository is deleted. If a component has a bug or other issue, you can [create a new release](index.md#release-a-component) with an updated version.
+
+After the repository is set as a components repository, it appears in the CI/CD Catalog of the namespace.
+
+## View available components in the CI/CD Catalog
+
+To view the components available to your project from the CI/CD Catalog:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. On the left sidebar, select **Build > Pipeline Editor**.
+1. Select **Browse CI/CD Catalog**.
diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md
index e73436522dc..e0379bf783d 100644
--- a/doc/ci/components/index.md
+++ b/doc/ci/components/index.md
@@ -13,13 +13,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 This feature is an experimental feature and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/9897)
 to track future work. Tell us about your use case by leaving comments in the epic.
 
+A CI/CD component is a reusable single pipeline configuration unit. Use them to compose an entire pipeline configuration or a small part of a larger pipeline.
+
+A component can optionally take [input parameters](../yaml/inputs.md).
+
+CI/CD components are similar to the other kinds of [configuration added with the `include` keyword](../yaml/includes.md), but have several advantages:
+
+- Components can be released and used with a specific version.
+- Multiple components can be combined in the same project and released with a single tag.
+- Components are discoverable in the [CI/CD Catalog](catalog.md).
+
 ## Components repository
 
-A components repository is a GitLab project with a repository that hosts one or more pipeline components.
-A pipeline component is a reusable single pipeline configuration unit. Use them to compose
-an entire pipeline configuration or a small part of a larger pipeline.
+A components repository is a GitLab project with a repository that hosts one or more pipeline components. All components in the project are versioned and released together.
 
-A component can optionally take [input parameters](../yaml/inputs.md).
+If a component requires different versioning from other components, the component should be migrated to its own components repository.
 
 ## Create a components repository
 
@@ -167,7 +175,7 @@ To create a release for a CI/CD component, use either:
   be released after all tests pass in pipelines for new tags.
 - The [UI for creating a release](../../user/project/releases/index.md#create-a-release).
 
-All released versions of the components are displayed in the CI/CD Catalog
+All released versions of the components are displayed in the [CI/CD Catalog](catalog.md)
 page for the given resource, providing users with information about official releases.
 
 Components [can be used](#use-a-component-in-a-cicd-configuration) without being released,
diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
index 647669385d8..5f969472aad 100644
--- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
+++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
@@ -90,7 +90,10 @@ Example JWT payload:
 
 The JWT is encoded by using RS256 and signed with a dedicated private key. The expire time for the token is set to job's timeout, if specified, or 5 minutes if it is not. The key used to sign this token may change without any notice. In such case retrying the job generates new JWT using the current signing key.
 
-You can use this JWT and your instance's JWKS endpoint (`https://gitlab.example.com/-/jwks`) to authenticate with a Vault server that is configured to allow the JWT Authentication method for authentication.
+You can use this JWT for authentication with a Vault server that is configured to allow
+the JWT authentication method. Provide your GitLab instance's base URL
+(for example `https://gitlab.example.com`) to your Vault server as the `oidc_discovery_url`.
+The server can then retrieve the keys for validating the token from your instance.
 
 When configuring roles in Vault, you can use [bound claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims) to match against the JWT claims and restrict which secrets each CI/CD job has access to.
 
@@ -248,11 +251,11 @@ Now, configure the JWT Authentication method:
 
 ```shell
 $ vault write auth/jwt/config \
-    jwks_url="https://gitlab.example.com/-/jwks" \
+    oidc_discovery_url="https://gitlab.example.com" \
     bound_issuer="https://gitlab.example.com"
 ```
 
-[`bound_issuer`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) specifies that only a JWT with the issuer (that is, the `iss` claim) set to `gitlab.example.com` can use this method to authenticate, and that the JWKS endpoint (`https://gitlab.example.com/-/jwks`) should be used to validate the token.
+[`bound_issuer`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) specifies that only a JWT with the issuer (that is, the `iss` claim) set to `gitlab.example.com` can use this method to authenticate, and that the `oidc_discovery_url` (`https://gitlab.example.com`) should be used to validate the token.
 
 For the full list of available configuration options, see Vault's [API documentation](https://developer.hashicorp.com/vault/api-docs/auth/jwt#configure).
 
diff --git a/doc/ci/index.md b/doc/ci/index.md
index 4b93bec9c34..2502a8da8c0 100644
--- a/doc/ci/index.md
+++ b/doc/ci/index.md
@@ -75,6 +75,10 @@ They can be hard-coded in your `.gitlab-ci.yml` file, project settings, or dynam
 
 - [Learn more about CI/CD variables](variables/index.md).
 
+### CI/CD components
+
+A [CI/CD component](components/index.md) is a reusable single pipeline configuration unit. Use them to compose an entire pipeline configuration or a small part of a larger pipeline.
+
 ## Videos
 
 - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab CI/CD demo](https://www.youtube-nocookie.com/embed/ljth1Q5oJoo).
diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md
index a477b73c107..20eae01f45b 100644
--- a/doc/ci/secrets/convert-to-id-tokens.md
+++ b/doc/ci/secrets/convert-to-id-tokens.md
@@ -52,7 +52,7 @@ As part of the transition from `CI_JOB_JWT` to ID tokens, you must update the `b
 
 ```shell
 $ vault write auth/jwt/config \
-    jwks_url="https://gitlab.example.com/-/jwks" \
+    oidc_discovery_url="https://gitlab.example.com" \
     bound_issuer="https://gitlab.example.com"
 ```
 
@@ -72,7 +72,7 @@ You can create multiple authentication paths in Vault, which enable you to trans
 
    ```shell
    $ vault write auth/jwt_v2/config \
-       jwks_url="https://gitlab.example.com/-/jwks" \
+       oidc_discovery_url="https://gitlab.example.com" \
        bound_issuer="https://gitlab.example.com"
    ```
 
@@ -170,7 +170,7 @@ After all roles have been updated with the `bound_claims.iss` claims, you can re
 
 ```shell
 $ vault write auth/jwt/config \
-    jwks_url="https://gitlab.example.com/-/jwks" \
+    oidc_discovery_url="https://gitlab.example.com" \
     bound_issuer=""
 ```
 
diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md
index c184102d948..e663d8d5c14 100644
--- a/doc/ci/secrets/index.md
+++ b/doc/ci/secrets/index.md
@@ -55,14 +55,14 @@ To configure your Vault server:
 
 1. Ensure your Vault server is running on version 1.2.0 or later.
 1. Enable the authentication method by running these commands. They provide your Vault
-   server the [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517) (JWKS) endpoint for your GitLab instance, so Vault
+   server the [OIDC Discovery URL](https://openid.net/specs/openid-connect-discovery-1_0.html) for your GitLab instance, so Vault
    can fetch the public signing key and verify the JSON Web Token (JWT) when authenticating:
 
    ```shell
    $ vault auth enable jwt
 
    $ vault write auth/jwt/config \
-     jwks_url="https://gitlab.example.com/-/jwks" \
+     oidc_discovery_url="https://gitlab.example.com" \
      bound_issuer="gitlab.example.com"
    ```