Add latest changes from gitlab-org/gitlab@master

3 files changed, 126 insertions, 0 deletions

diff --git a/doc/ci/secrets/gcp_secret_manager.md b/doc/ci/secrets/gcp_secret_manager.md
new file mode 100644
index 00000000000..ad2a2a269eb
--- /dev/null
+++ b/doc/ci/secrets/gcp_secret_manager.md
@@ -0,0 +1,92 @@
+---
+stage: Verify
+group: Pipeline Security
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Use GCP Secret Manager secrets in GitLab CI/CD **(PREMIUM ALL)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11739) in GitLab and GitLab Runner 16.8.
+
+You can use secrets stored in the [Google Cloud (GCP) Secret Manager](https://cloud.google.com/security/products/secret-manager)
+in your GitLab CI/CD pipelines.
+
+The flow for using GitLab with GCP Secret Manager
+is summarized by this diagram:
+
+1. GitLab issues ID token to CI/CD job.
+1. The runner authenticates to GCP using an ID token.
+1. GCP verifies the ID token with GitLab.
+1. GCP issues a short-lived access token.
+1. The runner accesses the secret data using the access token.
+1. GCP checks IAM permission on the access token's principal.
+1. GCP returns the secret data to Runner.
+
+To use GitLab with GCP Secret Manager, you must:
+
+- Have secrets stored in [GCP Secret Manager](https://cloud.google.com/security/products/secret-manager).
+- Configure [GCP Workload Identity Federation](#configure-gcp-iam-workload-identify-federation-wif) to include GitLab as an identity provider.
+- Configure [GCP IAM](#grant-access-to-gcp-iam-principal) permissions to grant access to GCP Secret Manager.
+- Configure [GitLab CI/CD with GCP Secret Manager](#configure-gitlab-cicd-to-use-gcp-secret-manager-secrets).
+
+## Configure GCP IAM Workload Identify Federation (WIF)
+
+GCP IAM WIF must be configured to recognize ID tokens issued by GitLab and assign an appropriate principal to them.
+The principal is used to authorize access to the Secret Manager resources:
+
+1. In GCP Console, go to **IAM & Admin > Workload Identity Federation**.
+1. Select **CREATE POOL** and create a new identity pool with a unique name, for example `gitlab-pool`.
+1. Select **ADD PROVIDER** to add a new OIDC Provider to the Identity Pool with a unique name, for example `gitlab-provider`.
+   1. Set **Issuer (URL)** to the GitLab URL, for example `https://gitlab.com`.
+   1. Select **Default audience**, or select **Allowed audiences** for a custom audience, which is used in the `aud` for the GitLab CI/CD ID token.
+1. Under **Attribute Mapping**, configure provider attributes, which are mappings between the [OIDC claims](id_token_authentication.md#token-payload)
+   (referred to as "assertion") and Google attributes. These mappings can be used to set fine grained access control.
+   For example, to grant a GitLab project access to Secret Manager secrets, select **ADD MAPPING** and create a mapping of
+   `attribute.gitlab_project_id` to `assertion.project_id`.
+
+## Grant access to GCP IAM principal
+
+After setting up WIF, you must grant the WIF principal access to the secrets in Secret Manager.
+
+1. In GCP Console, go to **IAM & Admin > IAM**.
+1. Select **GRANT ACCESS** to grant access to the principal set created through the WIF provider. For example,
+   to grant IAM access to the principal matching the project with ID `123`, add
+   a new principal like: `principalSet://iam.googleapis.com/projects/[PROJECT_NUMBER]/locations/global/workloadIdentityPools/[POOL_ID]/attribute.gitlab_project_id/[PROJECT_ID]`.
+1. Assign the role **Secret Manager Secret Accessor**.
+1. (Optional) Select **IAM condition (Optional)** to add an IAM condition.
+   Under **Condition Builder**, you can add conditions. For example, you could add two `AND` conditions:
+   - First condition:
+     - **Condition type**: `Type`
+     - **Operator**: `is`
+     - **Resource type**: `secretmanager.googleapis.com/SecretVersion`
+   - Second condition:
+     - **Condition type**: `Name`
+     - **Operator**: `Starts with`
+     - **Value**: The pattern of secrets that you want to grant access to.
+
+You can add additional IAM conditions for fine-grained access controls, including
+accessing secrets with names starting with the project name.
+
+## Configure GitLab CI/CD to use GCP Secret Manager secrets
+
+You can use secrets stored in GCP Secret Manager in CI/CD jobs by defining them with the `gcp_secret_manager` keyword:
+
+```yaml
+job_using_gcp_sm:
+  id_tokens:
+    GCP_ID_TOKEN:
+      # `aud` must match the audience defined in the WIF Identity Pool.
+      aud: https://iam.googleapis.com/projects/1234/locations/global/workloadIdentityPools/gitlab-pool/providers/gitlab-provider
+  secrets:
+    DATABASE_PASSWORD:
+      gcp_secret_manager:
+        name: my-project-secret  # This is the name of the secret defined in GCP Secret Manager
+        version: 1               # optional: default to `latest`.
+      token: $GCP_ID_TOKEN
+```
+
+You must also [add these CI/CD variables](../variables/index.md#for-a-project) to provide details about your GCP Secret Manager:
+
+- `GCP_PROJECT_NUMBER`: The GCP [Project Number](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
+- `GCP_WORKLOAD_IDENTITY_FEDERATION_POOL_ID`: The WIF Pool ID (e.g `gitlab-pool`)
+- `GCP_WORKLOAD_IDENTITY_FEDERATION_PROVIDER_ID`: The WIF Provider ID (e.g `gitlab-provider`)
diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md
index e452b26d8a9..96b9709bdef 100644
--- a/doc/ci/secrets/index.md
+++ b/doc/ci/secrets/index.md
@@ -18,6 +18,12 @@ Unlike CI/CD variables, which are always presented to a job, secrets must be exp
 required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/index.md#secrets)
 for more information about the syntax.
 
+GitLab provides support for the following secret management providers:
+
+1. [Vault by HashiCorp](#use-vault-secrets-in-a-ci-job)
+1. [Google Cloud Secret Manager](gcp_secret_manager.md)
+1. [Azure Key Vault](azure_key_vault.md)
+
 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.
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 35b35567d8f..27f6113345f 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -4253,6 +4253,34 @@ job:
       vault: production/db/password@ops  # Translates to secret: `ops/data/production/db`, field: `password`
 ```
 
+#### `secrets:gcp_secret_manager`
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11739) in GitLab 16.8 and GitLab Runner 16.8.
+
+Use `secrets:gcp_secret_manager` to specify secrets provided by [GCP Secret Manager](https://cloud.google.com/security/products/secret-manager).
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**:
+
+- `name`: Name of the secret.
+- `version`: Version of the secret.
+
+**Example of `secrets:gcp_secret_manager`**:
+
+```yaml
+job:
+  secrets:
+    DATABASE_PASSWORD:
+      gcp_secret_manager:
+        name: 'test'
+        version: 2
+```
+
+**Related topics**:
+
+- [Use GCP Secret Manager secrets in GitLab CI/CD](../secrets/gcp_secret_manager.md).
+
 #### `secrets:azure_key_vault`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab 16.3 and GitLab Runner 16.3.