diff options
Diffstat (limited to 'doc/ci/secrets/index.md')
-rw-r--r-- | doc/ci/secrets/index.md | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md new file mode 100644 index 00000000000..6d561fe00a3 --- /dev/null +++ b/doc/ci/secrets/index.md @@ -0,0 +1,157 @@ +--- +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: concepts, howto +--- + +# Using external secrets in CI + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218746) in GitLab 13.4 and GitLab Runner 13.4. + +Secrets represent sensitive information your CI job needs to complete work. This +sensitive information can be items like API tokens, database credentials, or private keys. +Secrets are sourced from your secrets provider. + +Unlike CI variables, which are always presented to a job, secrets must be explicitly +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 +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 +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). + +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 +subscription levels, supports writing secrets to and deleting secrets from Vault, +and multiple secrets engines. + +## Configure your Vault server + +To configure your Vault server: + +1. Enable the authentication method by running these commands. They provide your Vault + server the [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) (JWKS) endpoint 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" \ + bound_issuer="gitlab.example.com" + ``` + +1. Configure policies on your Vault server to grant or forbid access to certain + paths and operations. This example grants read access to the set of secrets + required by your production environment: + + ```shell + vault policy write myproject-production - <<EOF + # Read-only permission on 'ops/data/production/*' path + + path "ops/data/production/*" { + capabilities = [ "read" ] + } + EOF + ``` + +1. Configure roles on your Vault server, restricting roles to a project or namespace, + as described in [Configure Vault server roles](#configure-vault-server-roles) on this page. +1. [Create the following CI variables](../variables/README.md#custom-environment-variables) + to provide details about your Vault server: + - `VAULT_SERVER_URL` - The URL of your Vault server, such as `https://vault.example.com:8200`. + Required. + - `VAULT_AUTH_ROLE` - (Optional) The role to use when attempting to authenticate. + If no role is specified, Vault uses the [default role](https://www.vaultproject.io/api/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`. + + NOTE: **Note:** + Support for [providing these values in the user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/218677) + is planned but not yet implemented. + +## Use Vault secrets in a CI job **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4 and GitLab Runner 13.4. + +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` +``` + +In this example: + +- `production/db` - The secret. +- `password` The field. +- `ops` - The path where the secrets engine is mounted. + +After GitLab fetches the secret from Vault, the value is saved in a temporary file. +The path to this file is stored in environment variable named `DATABASE_PASSWORD`, +similar to [CI variables of type `file`](../variables/README.md#custom-environment-variables-of-type-file). + +For more information about the supported syntax, read the +[`.gitlab-ci.yml` reference](../yaml/README.md#secretsvault). + +## Configure Vault server roles + +When a CI job attempts to authenticate, it specifies a role. You can use roles to group +different policies together. If authentication is successful, these policies are +attached to the resulting Vault token. + +[Bound claims](https://www.vaultproject.io/docs/auth/jwt#bound-claims) are predefined +values that are matched to the JWT's claims. With bounded claims, you can restrict access +to specific GitLab users, specific projects, or even jobs running for specific Git +references. You can have as many bounded claims you need, but they must *all* match +for authentication to be successful. + +Combining bounded claims with GitLab features like [user roles](../../user/permissions.md) +and [protected branches](../../user/project/protected_branches.md), you can tailor +these rules to fit your specific use case. In this example, authentication is allowed +only for jobs running for protected tags with names matching the pattern used for +production releases: + +```shell +$ vault write auth/jwt/role/myproject-production - <<EOF +{ + "role_type": "jwt", + "policies": ["myproject-production"], + "token_explicit_max_ttl": 60, + "user_claim": "user_email", + "bound_claims_type": "glob", + "bound_claims": { + "project_id": "42", + "ref_protected": "true", + "ref_type": "tag", + "ref": "auto-deploy-*" + } +} +EOF +``` + +CAUTION: **Caution:** +Always restrict your roles to a project or namespace by using one of the provided +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 +[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 +[Vault's documentation on creating roles](https://www.vaultproject.io/api/auth/jwt#create-role) +for the JSON web token method. |