1. Create an issue describing the bug or enhancement you want to propose (select the right issue template).
2. Make sure the issue has been reviewed and agreed.
3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) documentation).
3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/user/project/repository/forking_workflow/) documentation).
Don't hesitate to mark your MR as `Draft` as long as you think it's not ready to be reviewed.
When enabled, it deploys the result from upstream build stages to a dedicated and temporary environment.
It is only active for non-production, non-integration branches.
It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/) feature.
It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ci/review_apps/) feature.
It also comes with a _cleanup_ job (accessible either from the _environments_ page, or from the pipeline view).
@@ -99,8 +99,8 @@ You're free to enable whichever or both, and you can also choose your deployment
The Kubernetes template supports 3 ways of login/accessing your Kubernetes cluster(s):
1. Using [GitLab agents with the CI/CD workflow](https://docs.gitlab.com/ee/user/clusters/agent/ci_cd_workflow.html): when enabled, the template automatically retrieves and uses your Kubernetes cluster configuration (`KUBECONFIG` env),
:warning: don't forget to set the `KUBE_CONTEXT` variable (to `path/to/agent/project:agent-name`) as [stated in the documentation](https://docs.gitlab.com/ee/user/clusters/agent/ci_cd_workflow.html#environments-that-use-auto-devops).
1. Using [GitLab agents with the CI/CD workflow](https://docs.gitlab.com/user/clusters/agent/ci_cd_workflow/): when enabled, the template automatically retrieves and uses your Kubernetes cluster configuration (`KUBECONFIG` env),
:warning: don't forget to set the `KUBE_CONTEXT` variable (to `path/to/agent/project:agent-name`) as [stated in the documentation](https://docs.gitlab.com/user/clusters/agent/ci_cd_workflow/#environments-that-use-auto-devops).
2. By defining an explicit `kubeconfig` from env (either file or yaml content),
3. By defining explicit `kubeconfig`**exploded parameters** from env: server url, server certificate authority and user token.
@@ -275,8 +275,8 @@ by using available environment variables:
(ex: `MYPROJECT_REVIEW_FIX_BUG_12` or `MYPROJECT_STAGING`)
*`${k8s_namespace}`: the Kubernetes namespace currently used for deployment/cleanup
*`${hostname}`: the environment hostname, extracted from the current environment url (after late variable expansion - see below)
2. any [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#for-a-project)
2. any [GitLab CI variable](https://docs.gitlab.com/ci/variables/predefined_variables/)
3. any [custom variable](https://docs.gitlab.com/ci/variables/#for-a-project)
(ex: `${SECRET_TOKEN}` that you have set in your project CI/CD variables)
#### Variables substitution mechanism
@@ -311,7 +311,7 @@ resources can use a **variables substitution** mechanism implemented by the temp
The K8S template supports two ways of providing your environments url:
* a **static way**: when the environments url can be determined in advance, probably because you're exposing your routes through a DNS you manage,
* a [**dynamic way**](https://docs.gitlab.com/ee/ci/environments/#set-a-dynamic-environment-url): when the url cannot be known before the
* a [**dynamic way**](https://docs.gitlab.com/ci/environments/#set-a-dynamic-environment-url): when the url cannot be known before the
deployment job is executed.
The **static way** can be implemented simply by setting the appropriate configuration variable(s) depending on the environment (see environments configuration chapters):
@@ -340,7 +340,7 @@ the dynamically generated url. When detected by the template, it will use it as
### Deployment output variables
Each deployment job produces _output variables_ that are propagated to downstream jobs (using [dotenv artifacts](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdotenv)):
Each deployment job produces _output variables_ that are propagated to downstream jobs (using [dotenv artifacts](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv)):
*`$environment_type`: set to the type of environment (`review`, `integration`, `staging` or `production`),
*`$environment_name`: the application name (see below),
@@ -356,12 +356,12 @@ You may also add and propagate your own custom variables, by pushing them to the
Here are some advices about your **secrets** (variables marked with a :lock:):
1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project):
*[**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently
1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ci/variables/#for-a-project):
*[**masked**](https://docs.gitlab.com/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently
displayed in your job logs,
*[**protected**](https://docs.gitlab.com/ee/ci/variables/#protected-cicd-variables) if you want to secure some secrets
*[**protected**](https://docs.gitlab.com/ci/variables/#protected-cicd-variables) if you want to secure some secrets
you don't want everyone in the project to have access to (for instance production secrets).
2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable),
2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ci/variables/#mask-a-cicd-variable),
simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`:
it will then be possible to mask it and the template will automatically decode it prior to using it.
3. Don't forget to escape special characters (ex: `$` -> `$$`).
@@ -373,9 +373,9 @@ The Kubernetes template uses some global configuration used throughout all jobs.
| Input / Variable | Description | Default value |
| `kubectl-image` / `K8S_KUBECTL_IMAGE` | the Docker image used to run Kubernetes `kubectl` commands <br/>:warning: **set the version required by your Kubernetes server** | `registry.hub.docker.com/bitnami/kubectl:latest`<br/>[](https://to-be-continuous.gitlab.io/doc/secu/trivy-K8S_KUBECTL_IMAGE) |
| `KUBE_CONTEXT` | Defines the context to be used in `KUBECONFIG`. When using [GitLab agents with the CI/CD workflow](https://docs.gitlab.com/ee/user/clusters/agent/ci_cd_workflow.html), the value should be like `path/to/agent/project:agent-name`. To use different agents per environment, define an [environment-scoped CI/CD variable](https://docs.gitlab.com/ee/ci/environments/index.html#limit-the-environment-scope-of-a-cicd-variable) for each agent. | _none_ |
| `KUBE_CONTEXT` | Defines the context to be used in `KUBECONFIG`. When using [GitLab agents with the CI/CD workflow](https://docs.gitlab.com/user/clusters/agent/ci_cd_workflow/), the value should be like `path/to/agent/project:agent-name`. To use different agents per environment, define an [environment-scoped CI/CD variable](https://docs.gitlab.com/ci/environments/#limit-the-environment-scope-of-a-cicd-variable) for each agent. | _none_ |
| :lock: `K8S_DEFAULT_KUBE_CONFIG`| The default kubeconfig to use (either content or file variable) | **required if not using exploded kubeconfig parameters** |
| `url` / `K8S_URL` | the Kubernetes API url | **required if using exploded kubeconfig parameters** |
| :lock: `K8S_CA_CERT` | the default Kubernetes server certificate authority | **optional if using exploded kubeconfig parameters** |
@@ -501,7 +501,7 @@ In order to be able to communicate with the Vault server, the variant requires t
| :lock: `VAULT_ROLE_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) RoleID | _none_ |
| :lock: `VAULT_SECRET_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) SecretID | _none_ |
By default, the variant will authentifacte using a [JWT ID token](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html). To use [AppRole](https://www.vaultproject.io/docs/auth/approle) instead the `VAULT_ROLE_ID` and `VAULT_SECRET_ID` should be defined as secret project variables.
By default, the variant will authentifacte using a [JWT ID token](https://docs.gitlab.com/ci/secrets/id_token_authentication/). To use [AppRole](https://www.vaultproject.io/docs/auth/approle) instead the `VAULT_ROLE_ID` and `VAULT_SECRET_ID` should be defined as secret project variables.
#### Usage
@@ -560,7 +560,7 @@ This [blog post about OIDC impersonation through Workload Identify Federation][g
| `gcp-oidc-aud` / `GCP_OIDC_AUD` | The `aud` claim for the JWT token | `$CI_SERVER_URL` |
| `gcp-oidc-provider` / `GCP_OIDC_PROVIDER` | Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) | _none_ |
| `gcp-oidc-provider` / `GCP_OIDC_PROVIDER` | Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) | _none_ |
| `gcp-oidc-account` / `GCP_OIDC_ACCOUNT` | Default Service Account to which impersonate with OpenID Connect authentication | _none_ |
| `gcp-review-oidc-provider` / `GCP_REVIEW_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `review` environment _(only define to override default)_ | _none_ |
| `gcp-review-oidc-provider` / `GCP_REVIEW_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `review` environment _(only define to override default)_ | _none_ |
| `gcp-review-oidc-account` / `GCP_REVIEW_OIDC_ACCOUNT` | Service Account to which impersonate with OpenID Connect authentication on `review` environment _(only define to override default)_ | _none_ |
| `gcp-integ-oidc-provider` / `GCP_INTEG_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `integration` environment _(only define to override default)_ | _none_ |
| `gcp-integ-oidc-provider` / `GCP_INTEG_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `integration` environment _(only define to override default)_ | _none_ |
| `gcp-integ-oidc-account` / `GCP_INTEG_OIDC_ACCOUNT` | Service Account to which impersonate with OpenID Connect authentication on `integration` environment _(only define to override default)_ | _none_ |
| `gcp-staging-oidc-provider` / `GCP_STAGING_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `staging` environment _(only define to override default)_ | _none_ |
| `gcp-staging-oidc-provider` / `GCP_STAGING_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `staging` environment _(only define to override default)_ | _none_ |
| `gcp-staging-oidc-account` / `GCP_STAGING_OIDC_ACCOUNT` | Service Account to which impersonate with OpenID Connect authentication on `staging` environment _(only define to override default)_ | _none_ |
| `gcp-prod-oidc-provider` / `GCP_PROD_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `production` environment _(only define to override default)_ | _none_ |
| `gcp-prod-oidc-provider` / `GCP_PROD_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `production` environment _(only define to override default)_ | _none_ |
| `gcp-prod-oidc-account` / `GCP_PROD_OIDC_ACCOUNT` | Service Account to which impersonate with OpenID Connect authentication on `production` environment _(only define to override default)_ | _none_ |
| `kubectl-image` / `K8S_KUBECTL_IMAGE` | The Docker image used to run Kubernetes `kubectl` commands on [GKE](https://cloud.google.com/kubernetes-engine/docs) | `gcr.io/google.com/cloudsdktool/cloud-sdk:latest` |
@@ -609,7 +609,7 @@ This variant use the OIDC and [AWS STS](https://docs.aws.amazon.com/fr_fr/STS/la
- [Create an OpenID Connect (OIDC) identity provider in IAM
| `aws-oidc-aud` / `AWS_OIDC_AUD` | The `aud` claim for the JWT token | `$CI_SERVER_URL` |
| `aws-oidc-role-arn` / `AWS_OIDC_ROLE_ARN` | Default IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) | _none_ |
| `aws-review-oidc-role-arn` / `AWS_REVIEW_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `review` env _(only define to override default)_ | _none_ |
| `aws-integ-oidc-role-arn` / `AWS_INTEG_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `integration` env _(only define to override default)_ | _none_ |
| `aws-staging-oidc-role-arn` / `AWS_STAGING_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `staging` env _(only define to override default)_ | _none_ |
| `aws-prod-oidc-role-arn` / `AWS_PROD_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `production` env _(only define to override default)_ | _none_ |
| `aws-oidc-role-arn` / `AWS_OIDC_ROLE_ARN` | Default IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) | _none_ |
| `aws-review-oidc-role-arn` / `AWS_REVIEW_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `review` env _(only define to override default)_ | _none_ |
| `aws-integ-oidc-role-arn` / `AWS_INTEG_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `integration` env _(only define to override default)_ | _none_ |
| `aws-staging-oidc-role-arn` / `AWS_STAGING_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `staging` env _(only define to override default)_ | _none_ |
| `aws-prod-oidc-role-arn` / `AWS_PROD_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `production` env _(only define to override default)_ | _none_ |
| `kubectl-image` / `K8S_KUBECTL_IMAGE` | The Docker image used to run Kubernetes `kubectl` commands on [AWS] | `docker.io/alpine/k8s:1.32.1` |
"description":"Dynamic review environments for your topic branches (see GitLab [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/))",
"description":"Dynamic review environments for your topic branches (see GitLab [Review Apps](https://docs.gitlab.com/ci/review_apps/))",
"variables":[
{
"name":"K8S_REVIEW_SPACE",
@@ -318,7 +318,7 @@
"variables":[
{
"name":"GCP_OIDC_AUD",
"description":"The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ee/ci/cloud_services/aws/))_",
"description":"The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ci/cloud_services/aws/))_",
"default":"$CI_SERVER_URL",
"advanced":true
},
@@ -328,7 +328,7 @@
},
{
"name":"GCP_OIDC_PROVIDER",
"description":"Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/)"
"description":"Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/)"
},
{
"name":"GCP_REVIEW_OIDC_ACCOUNT",
@@ -337,7 +337,7 @@
},
{
"name":"GCP_REVIEW_OIDC_PROVIDER",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `review` environment",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `review` environment",
"advanced":true
},
{
@@ -347,7 +347,7 @@
},
{
"name":"GCP_INTEG_OIDC_PROVIDER",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `integration` environment",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `integration` environment",
"advanced":true
},
{
@@ -357,7 +357,7 @@
},
{
"name":"GCP_STAGING_OIDC_PROVIDER",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `staging` environment",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `staging` environment",
"advanced":true
},
{
@@ -367,7 +367,7 @@
},
{
"name":"GCP_PROD_OIDC_PROVIDER",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `production` environment",
"description":"Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `production` environment",
"advanced":true
},
{
@@ -385,7 +385,7 @@
"variables":[
{
"name":"AWS_OIDC_AUD",
"description":"The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ee/ci/cloud_services/aws/))_",
"description":"The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ci/cloud_services/aws/))_",
