diff options
Diffstat (limited to 'doc/user')
24 files changed, 281 insertions, 103 deletions
diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index bf1de09739d..0fb96462623 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -315,6 +315,7 @@ but commented out to help encourage others to add to it in the future. --> |incident_issues|counts|monitor|Issues created by the alert bot| |alert_bot_incident_issues|counts|monitor|Issues created by the alert bot| |incident_labeled_issues|counts|monitor|Issues with the incident label| +|issues_created_gitlab_alerts|counts|monitor|issues created from alerts by non-alert bot users| |ldap_group_links|counts|| |ldap_keys|counts|| |ldap_users|counts|| diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index ebd89d9a017..f18897d5a15 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -37,17 +37,16 @@ The results are sorted by the severity of the vulnerability: ## Requirements -To run a Dependency Scanning job, by default, you need GitLab Runner with the -[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or -[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) -executor running in privileged mode. If you're using the shared Runners on GitLab.com, -this is enabled by default. +To run Dependency Scanning jobs, by default, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +If you're using the shared Runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** If you use your own Runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. -Privileged mode is not necessary if you've [disabled Docker in Docker for Dependency Scanning](#disabling-docker-in-docker-for-dependency-scanning) +Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for Dependency Scanning](#enabling-docker-in-docker). ## Supported languages and package managers @@ -86,7 +85,7 @@ include: - template: Dependency-Scanning.gitlab-ci.yml ``` -The included template will create a `dependency_scanning` job in your CI/CD +The included template will create Dependency Scanning jobs in your CI/CD pipeline and scan your project's source code for possible vulnerabilities. The results will be saved as a [Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) @@ -110,23 +109,24 @@ variables: Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -### Overriding the Dependency Scanning template +### Overriding Dependency Scanning jobs CAUTION: **Deprecation:** Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. -If you want to override the job definition, such as changing properties like -`variables` or `dependencies`, you must declare a `dependency_scanning` job -after the template inclusion, and specify any additional keys under it. For example: +To override a job definition (for example, to change properties like `variables` or `dependencies`), +declare a new job with the same name as the one to override. Place this new job after the template +inclusion and specify any additional keys under it. For example, this disables `DS_REMEDIATE` for +the `gemnasium` analyzer: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml -dependency_scanning: +gemnasium-dependency_scanning: variables: - CI_DEBUG_TRACE: "true" + DS_REMEDIATE: "false" ``` ### Available variables @@ -143,13 +143,13 @@ The following variables allow configuration of global dependency scanning settin | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `DS_ANALYZER_IMAGE_PREFIX` | **DEPRECATED:** Use `SECURE_ANALYZERS_PREFIX` instead. | | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#disabling-docker-in-docker-for-dependency-scanning).| +| `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. | #### Configuring Docker-in-Docker orchestrator -The following variables configure the Docker-in-Docker orchestrator. +The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker). | Environment variable | Default | Description | | --------------------------------------- | ----------- | ----------- | @@ -193,34 +193,26 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -### Disabling Docker in Docker for Dependency Scanning +### Enabling Docker-in-Docker > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12487) in GitLab Ultimate 12.5. -You can avoid the need for Docker in Docker by running the individual analyzers. -This does not require running the executor in privileged mode. For example: +If needed, you can enable Docker-in-Docker to restore the Dependency Scanning behavior that existed +prior to GitLab 13.0. Follow these steps to do so: -```yaml -include: - - template: Dependency-Scanning.gitlab-ci.yml +1. Configure GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). +1. Set the `DS_DISABLE_DIND` variable to `false`: -variables: - DS_DISABLE_DIND: "true" -``` + ```yaml + include: + - template: Dependency-Scanning.gitlab-ci.yml -This will create individual `<analyzer-name>-dependency_scanning` jobs for each analyzer that runs in your CI/CD pipeline. + variables: + DS_DISABLE_DIND: "false" + ``` -By removing Docker-in-Docker (DIND), GitLab relies on [Linguist](https://github.com/github/linguist) -to start relevant analyzers depending on the detected repository language(s) instead of the -[orchestrator](https://gitlab.com/gitlab-org/security-products/dependency-scanning/). However, there -are some differences in the way repository languages are detected between DIND and non-DIND. You can -observe these differences by checking both Linguist and the common library. For instance, Linguist -looks for `*.java` files to spin up the [gemnasium-maven](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) -image, while orchestrator only looks for the existence of `pom.xml` or `build.gradle`. GitLab uses -Linguist to detect new file types in the default branch. This means that when introducing files or -dependencies for a new language or package manager, the corresponding scans won't be triggered in -the merge request, and will only run on the default branch once the merge request is merged. This will be addressed by -[#211702](https://gitlab.com/gitlab-org/gitlab/-/issues/211702). +This creates a single `dependency_scanning` job in your CI/CD pipeline instead of multiple +`<analyzer-name>-dependency_scanning` jobs. ## Interacting with the vulnerabilities @@ -428,7 +420,7 @@ jobs to run successfully. For more information, see [Offline environments](../of Here are the requirements for using Dependency Scanning in an offline environment: -- [Disable Docker-In-Docker](#disabling-docker-in-docker-for-dependency-scanning). +- Keep Docker-In-Docker disabled (default). - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of Dependency Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/) @@ -477,7 +469,6 @@ include: - template: Dependency-Scanning.gitlab-ci.yml variables: - DS_DISABLE_DIND: "true" DS_ANALYZER_IMAGE_PREFIX: "docker-registry.example.com/analyzers" ``` @@ -613,7 +604,7 @@ ERROR: Could not find dependencies: <dependency-name>. You may need to run npm i ### Error response from daemon: error processing tar file: docker-tar: relocation error -This error occurs when the Docker version used to run the SAST job is `19.03.0`. +This error occurs when the Docker version that runs the Dependency Scanning job is `19.03.00`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in [this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails"). diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 279c31565ef..a86da0ef16f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -452,6 +452,6 @@ involve pinning to the previous template versions, for example: ``` Additionally, we provide a dedicated project containing the versioned legacy templates. -This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md).. +This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index a23867ac87a..69db0fe9d03 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -145,10 +145,10 @@ CAUTION: **Deprecation:** Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. -If you want to override a job definition (for example, change properties like -`variables` or `dependencies`), you need to declare a job with the same name as the SAST job to override, after the -template inclusion and specify any additional keys under it. -For example, this enables `FAIL_NEVER` for the `spotbugs` analyzer: +To override a job definition, (for example, change properties like `variables` or `dependencies`), +declare a job with the same name as the SAST job to override. Place this new job after the template +inclusion and specify any additional keys under it. For example, this enables `FAIL_NEVER` for the +`spotbugs` analyzer: ```yaml include: @@ -176,19 +176,22 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m ### Enabling Docker-in-Docker -If needed, you can restore the behavior of SAST prior to %13.0 by enabling back Docker-in-Docker. -You need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode), and the variable `SAST_DISABLE_DIND` set to `false`: +If needed, you can enable Docker-in-Docker to restore the SAST behavior that existed prior to GitLab +13.0. Follow these steps to do so: -```yaml -include: - - template: SAST.gitlab-ci.yml +1. Configure GitLab Runner with Docker-inDocker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). +1. Set the variable `SAST_DISABLE_DIND` set to `false`: -variables: - SAST_DISABLE_DIND: "false" -``` + ```yaml + include: + - template: SAST.gitlab-ci.yml + + variables: + SAST_DISABLE_DIND: "false" + ``` -This will create a single `sast` job in your CI/CD pipeline -instead of multiple `<analyzer-name>-sast` jobs. +This creates a single `sast` job in your CI/CD pipeline instead of multiple `<analyzer-name>-sast` +jobs. #### Enabling Kubesec analyzer @@ -545,7 +548,7 @@ security reports without requiring internet access. ### Error response from daemon: error processing tar file: docker-tar: relocation error -This error occurs when the Docker version used to run the SAST job is `19.03.0`. +This error occurs when the Docker version that runs the SAST job is `19.03.0`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in [this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails"). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 902f8cd2b5b..7bd148edd15 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -21,7 +21,7 @@ The Web Application Firewall section provides metrics for the NGINX Ingress controller and ModSecurity firewall. This section has the following prerequisites: -- Project has to have at least one [environment](../../../ci/environments.md). +- Project has to have at least one [environment](../../../ci/environments/index.md). - [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity) has to be enabled. - [Elastic Stack](../../clusters/applications.md#web-application-firewall-modsecurity) has to be installed. @@ -48,7 +48,7 @@ The **Container Network Policy** section provides packet flow metrics for your application's Kubernetes namespace. This section has the following prerequisites: -- Your project contains at least one [environment](../../../ci/environments.md) +- Your project contains at least one [environment](../../../ci/environments/index.md) - You've [installed Cilium](../../clusters/applications.md#install-cilium-using-gitlab-cicd) - You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration) diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 5ebd4306df0..be3c9ee3e6d 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -10,7 +10,7 @@ GitLab provides **GitLab Managed Apps**, a one-click install for various applica be added directly to your configured cluster. These applications are needed for [Review Apps](../../ci/review_apps/index.md) -and [deployments](../../ci/environments.md) when using [Auto DevOps](../../topics/autodevops/index.md). +and [deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index ba96eef1e01..a2adf238dda 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13392) for group-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14809) for instance-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. -Cluster environments provide a consolidated view of which CI [environments](../../ci/environments.md) are +Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/index.md) are deployed to the Kubernetes cluster and it: - Shows the project and the relevant environment related to the deployment. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 35fff638849..5e6ff980c8b 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -103,7 +103,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with -[environments](../../../ci/environments.md) similar to how the +[environments](../../../ci/environments/index.md) similar to how the [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. @@ -157,7 +157,7 @@ The result is: ## Cluster environments **(PREMIUM)** -For a consolidated view of which CI [environments](../../../ci/environments.md) +For a consolidated view of which CI [environments](../../../ci/environments/index.md) are deployed to the Kubernetes cluster, see the documentation for [cluster environments](../../clusters/environments.md). diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index b8f9f043e38..d53acaf502a 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -31,6 +31,7 @@ To learn what you can do with an epic, see [Manage epics](manage_epics.md). Poss - [Reopen a closed epic](manage_epics.md#reopen-a-closed-epic) - [Go to an epic from an issue](manage_epics.md#go-to-an-epic-from-an-issue) - [Search for an epic from epics list page](manage_epics.md#search-for-an-epic-from-epics-list-page) +- [Make an epic confidential](manage_epics.md#make-an-epic-confidential) - [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) - [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics-ultimate) diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 8e2a47bb1af..b94def57c76 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -17,7 +17,8 @@ selected group. From your group page: 1. Go to **Epics**. 1. Click **New epic**. -1. Enter a descriptive title and click **Create epic**. +1. Enter a descriptive title. +1. Click **Create epic**. You will be taken to the new epic where can edit the following details: @@ -29,8 +30,7 @@ You will be taken to the new epic where can edit the following details: An epic's page contains the following tabs: -- **Epics and Issues**: epics and issues added to this epic. Child epics and their issues appear in - a tree view. +- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view. - Click the <kbd>></kbd> beside a parent epic to reveal the child epics and issues. - Hover over the total counts to see a breakdown of open and closed items. - **Roadmap**: a roadmap view of child epics which have start and due dates. @@ -121,6 +121,36 @@ The sort option and order is saved and used wherever you browse epics, including  +## Make an epic confidential + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> - It's deployed behind a feature flag, disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-confidential-epics-premium-only). **(PREMIUM ONLY)** + +When you're creating an epic, you can make it confidential by selecting the **Make this epic +confidential** checkbox. + +### Enable Confidential Epics **(PREMIUM ONLY)** + +The Confidential Epics feature is under development and not ready for production use. It's deployed behind a +feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:confidential_epics) +``` + +To disable it: + +```ruby +Feature.disable(:confidential_epics) +``` + ## Manage issues assigned to an epic ### Add an issue to an epic diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 7b5ba14a5ae..495bfdeed6e 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -12,7 +12,7 @@ projects. ## Cluster precedence -GitLab will try [to match](../../../ci/environments.md#scoping-environments-with-specs) clusters in +GitLab will try [to match](../../../ci/environments/index.md#scoping-environments-with-specs) clusters in the following order: - Project-level clusters. @@ -20,11 +20,11 @@ the following order: - Instance-level clusters. To be selected, the cluster must be enabled and -match the [environment selector](../../../ci/environments.md#scoping-environments-with-specs). +match the [environment selector](../../../ci/environments/index.md#scoping-environments-with-specs). ## Cluster environments **(PREMIUM)** -For a consolidated view of which CI [environments](../../../ci/environments.md) +For a consolidated view of which CI [environments](../../../ci/environments/index.md) are deployed to the Kubernetes cluster, see the documentation for [cluster environments](../../clusters/environments.md). diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 304806723f5..132a64d99a3 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -18,13 +18,15 @@ The Packages feature allows GitLab to act as a repository for the following: ## Enable the Package Registry for your project -If you cannot find the **{package}** **Packages & Registries > Package Registry** entry under your -project's sidebar, it is not enabled in your GitLab instance. Ask your -administrator to enable GitLab Package Registry following the [administration -documentation](../../administration/packages/index.md). +If you cannot find the **{package}** **Packages & Registries > Package +Registry** entry under your project's sidebar, ensure that: -Once enabled for your GitLab instance, to enable Package Registry for your -project: +1. The GitLab Package Registry has been enabled by your administrator (following + [this documentation](../../administration/packages/index.md)); and +1. The Package Registry has been enabled for your project. + +Once an administrator has enabled the GitLab Package Registry for your GitLab +instance, to enable Package Registry for your project: 1. Go to your project's **Settings > General** page. 1. Expand the **Visibility, project features, permissions** section and enable the diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 639bf7e447d..ddf6dd42ba6 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -57,7 +57,7 @@ Some GitLab features may support versions outside the range provided here. ### Deploy Boards **(PREMIUM)** GitLab's Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments.md) running on Kubernetes, +status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -102,8 +102,8 @@ Kubernetes clusters can be used without Auto DevOps. > Introduced in GitLab 8.15. -When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments.md#web-terminals) -support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in +When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) +support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new shell session within your existing containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any deployments, replica sets, and @@ -205,7 +205,7 @@ you can either: ### Setting the environment scope **(PREMIUM)** When adding more than one Kubernetes cluster to your project, you need to differentiate -them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the +them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their @@ -321,7 +321,7 @@ of the form `<project_name>-<project_id>-<environment>` (see [Deployment variables](#deployment-variables)). For **non**-GitLab-managed clusters, the namespace can be customized using -[`environment:kubernetes:namespace`](../../../ci/environments.md#configuring-kubernetes-deployments) +[`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) in `.gitlab-ci.yml`. NOTE: **Note:** When using a [GitLab-managed cluster](#gitlab-managed-clusters), the @@ -349,7 +349,7 @@ Reasons for failure include: - The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching - [`environment:name`](../../../ci/environments.md#defining-environments). If your job has no + [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no `environment:name` set, it will not be passed the Kubernetes credentials. NOTE: **NOTE:** diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8d4f8c3eb62..8f7bb844e37 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -3,7 +3,7 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. GitLab's Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../ci/environments.md) running on [Kubernetes](https://kubernetes.io), displaying the status +status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -57,9 +57,9 @@ specific environment, there are a lot of use cases. To name a few: ## Enabling Deploy Boards -To display the Deploy Boards for a specific [environment](../../ci/environments.md) you should: +To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: -1. Have [defined an environment](../../ci/environments.md#defining-environments) with a deploy stage. +1. Have [defined an environment](../../ci/environments/index.md#defining-environments) with a deploy stage. 1. Have a Kubernetes cluster up and running. @@ -113,7 +113,7 @@ metadata: name: "APPLICATION_NAME" annotations: app.gitlab.com/app: ${CI_PROJECT_PATH_SLUG} - app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} + app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} spec: replicas: 1 selector: @@ -146,5 +146,5 @@ version of your application. - [GitLab Autodeploy](../../topics/autodevops/stages.md#auto-deploy) - [GitLab CI/CD environment variables](../../ci/variables/README.md) -- [Environments and deployments](../../ci/environments.md) +- [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png b/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png Binary files differnew file mode 100644 index 00000000000..2f0309ce664 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png diff --git a/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png b/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png Binary files differnew file mode 100644 index 00000000000..59dc9ccfd30 --- /dev/null +++ b/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 2ef29caa118..6c40e5b9696 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -72,6 +72,25 @@ It enables you to search as you type through all environments and select the one  +##### Select a dashboard + +The **dashboard** dropdown box above the dashboard displays the list of all dashboards available for the project. +It enables you to search as you type through all dashboards and select the one you're looking for. + + + +##### Mark a dashboard as favorite + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214582) in GitLab 13.0. + +When viewing a dashboard, click the empty **Star dashboard** **{star-o}** button to mark a +dashboard as a favorite. Starred dashboards display a solid star **{star}** button, +and appear at the top of the dashboard select list. + +To remove dashboard from the favorites list, click the solid **Unstar Dashboard** **{star}** button. + + + #### About managed Prometheus deployments Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). @@ -145,7 +164,7 @@ one of them will be used: [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). - If you have managed Prometheus applications installed on multiple Kubernetes clusters at the **same** level, the Prometheus application of a cluster with a - matching [environment scope](../../../ci/environments.md#scoping-environments-with-specs) is used. + matching [environment scope](../../../ci/environments/index.md#scoping-environments-with-specs) is used. ## Monitoring CI/CD Environments @@ -154,7 +173,7 @@ environment which has had a successful deployment. GitLab will automatically scan the Prometheus server for metrics from known servers like Kubernetes and NGINX, and attempt to identify individual environments. The supported metrics and scan process is detailed in our [Prometheus Metrics Library documentation](prometheus_library/index.md). -You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). +You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments/index.md#monitoring-environments). ### Adding custom metrics @@ -180,6 +199,8 @@ Multiple metrics can be displayed on the same chart if the fields **Name**, **Ty #### Query Variables +##### Predefined variables + GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are: - `ci_environment_slug` @@ -192,6 +213,12 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) NOTE: **Note:** Variables for Prometheus queries must be lowercase. +##### User-defined variables + +[Variables can be defined](#templating-templating-properties) in a custom dashboard YAML file. + +##### Using variables + Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7). Support for the `"%{ci_environment_slug}"` format was @@ -303,19 +330,29 @@ If you select another branch, this branch should be merged to your **default** b Dashboards have several components: +- Templating variables. - Panel groups, which consist of panels. - Panels, which support one or more metrics. The following tables outline the details of expected properties. -**Dashboard properties:** +##### **Dashboard (top-level) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | | `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | | `panel_groups` | array | yes | The panel groups which should be on the dashboard. | +| `templating` | Hash | no | Top level key under which templating related options can be added. | -**Panel group (`panel_groups`) properties:** +##### **Templating (`templating`) properties** + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `variables` | Hash | no | Variables can be defined here. | + +Read the documentation on [templating](#templating-variables-for-metrics-dashboards). + +##### **Panel group (`panel_groups`) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | @@ -323,7 +360,7 @@ The following tables outline the details of expected properties. | `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `panels` | array | required | The panels which should be in the panel group. | -**Panel (`panels`) properties:** +##### **Panel (`panels`) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | @@ -335,7 +372,7 @@ The following tables outline the details of expected properties. | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | -**Axis (`panels[].y_axis`) properties:** +##### **Axis (`panels[].y_axis`) properties** | Property | Type | Required | Description | | ----------- | ------ | ----------------------------- | -------------------------------------------------------------------- | @@ -343,7 +380,7 @@ The following tables outline the details of expected properties. | `format` | string | no, defaults to `engineering` | Unit format used. See the [full list of units](prometheus_units.md). | | `precision` | number | no, defaults to `2` | Number of decimal places to display in the number. | | -**Metrics (`metrics`) properties:** +##### **Metrics (`metrics`) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | @@ -652,6 +689,106 @@ Note the following properties:  +### Templating variables for metrics dashboards + +Templating variables can be used to make your metrics dashboard more versatile. + +#### Templating variable types + +`templating` is a top-level key in the +[dashboard YAML](#dashboard-top-level-properties). +Define your variables in the `variables` key, under `templating`. The value of +the `variables` key should be a hash, and each key under `variables` +defines a templating variable on the dashboard. + +A variable can be used in a Prometheus query in the same dashboard using the syntax +described [here](#using-variables). + +##### `text` variable type + +CAUTION: **Warning:** +This variable type is an _alpha_ feature, and is subject to change at any time +without prior notice! + +For each `text` variable defined in the dashboard YAML, there will be a free text +box on the dashboard UI, allowing you to enter a value for each variable. + +The `text` variable type supports a simple and a full syntax. + +###### Simple syntax + +This example creates a variable called `variable1`, with a default value +of `default value`: + +```yaml +templating: + variables: + variable1: 'default value' # `text` type variable with `default value` as its default. +``` + +###### Full syntax + +This example creates a variable called `variable1`, with a default value of `default`. +The label for the text box on the UI will be the value of the `label` key: + +```yaml +templating: + variables: + variable1: # The variable name that can be used in queries. + label: 'Variable 1' # (Optional) label that will appear in the UI for this text box. + type: text + options: + default_value: 'default' # (Optional) default value. +``` + +##### `custom` variable type + +CAUTION: **Warning:** +This variable type is an _alpha_ feature, and is subject to change at any time +without prior notice! + +Each `custom` variable defined in the dashboard YAML creates a dropdown +selector on the dashboard UI, allowing you to select a value for each variable. + +The `custom` variable type supports a simple and a full syntax. + +###### Simple syntax + +This example creates a variable called `variable1`, with a default value of `value1`. +The dashboard UI will display a dropdown with `value1`, `value2` and `value3` +as the choices. + +```yaml +templating: + variables: + variable1: ['value1', 'value2', 'value3'] +``` + +###### Full syntax + +This example creates a variable called `variable1`, with a default value of `var1_option_2`. +The label for the text box on the UI will be the value of the `label` key. +The dashboard UI will display a dropdown with `Option 1` and `Option 2` +as the choices. + +If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`. +Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`: + +```yaml +templating: + variables: + variable1: # The variable name that can be used in queries. + label: 'Variable 1' # (Optional) label that will appear in the UI for this dropdown. + type: custom + options: + values: + - value: 'value option 1' # The value that will replace the variable in queries. + text: 'Option 1' # (Optional) Text that will appear in the UI dropdown. + - value: 'value_option_2' + text: 'Option 2' + default: true # (Optional) This option should be the default value of this variable. +``` + ### View and edit the source file of a custom dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. @@ -764,7 +901,7 @@ receivers: ... ``` -In order for GitLab to associate your alerts with an [environment](../../../ci/environments.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. +In order for GitLab to associate your alerts with an [environment](../../../ci/environments/index.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. ### Taking action on incidents **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 7efc0346e5b..fdcb1049ef7 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -111,7 +111,7 @@ you will be able to see: - Both pre and post-merge pipelines and the environment information if any. - Which deployments are in progress. -If there's an [environment](../../../ci/environments.md) and the application is +If there's an [environment](../../../ci/environments/index.md) and the application is successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index b003edc6d2a..2dcf72aaf01 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -64,3 +64,16 @@ Standard alert statuses include `triggered`, `acknowledged`, and `resolved`: - **Triggered**: No one has begun investigation. - **Acknowledged**: Someone is actively investigating the problem. - **Resolved**: No further work is required. + +## Alert Management details + +NOTE: **Note:** +You will need at least Developer [permissions](../../permissions.md) to view Alert Management details. + +Navigate to the Alert Management detail view by visiting the [Alert Management list](#alert-management-list) and selecting an Alert from the list. + + + +### Update an Alert's status + +The Alert Management detail view allows users to update the Alert Status. See [Alert Management statuses](#alert-management-statuses) for more details. diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 8a8dd4781b6..ec35a4dfdce 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -73,22 +73,22 @@ For example, you may not want to enable a feature flag on production until your first confirmed that the feature is working correctly on testing environments. To handle these situations, you can enable a feature flag on a particular environment -with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs). +with [Environment specs](../../../ci/environments/index.md#scoping-environments-with-specs). You can define multiple specs per flag so that you can control your feature flag more granularly. To define specs for each environment: 1. Navigate to your project's **Operations > Feature Flags**. 1. Click on the **New Feature Flag** button or edit an existing flag. -1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments. -1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs) and type the environment name. +1. Set the status of the default [spec](../../../ci/environments/index.md#scoping-environments-with-specs) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments. +1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments/index.md#scoping-environments-with-specs) and type the environment name. 1. Set the status and rollout strategy of the additional spec. This status and rollout strategy combination takes precedence over the default spec since we always use the most specific match available. 1. Click **Create feature flag** or **Update feature flag**.  NOTE: **NOTE** -We'd highly recommend you to use the [Environment](../../../ci/environments.md) +We'd highly recommend you to use the [Environment](../../../ci/environments/index.md) feature in order to quickly assess which flag is enabled per environment. ## Feature flag behavior change in 13.0 @@ -122,7 +122,7 @@ make a strategy apply to a specific environment spec: 1. Click the **Add Environment** button. 1. Create a new - [spec](../../../ci/environments.md#scoping-environments-with-specs). + [spec](../../../ci/environments/index.md#scoping-environments-with-specs). To apply the strategy to multiple environment specs, repeat these steps. diff --git a/doc/user/project/operations/img/alert_detail_v13_0.png b/doc/user/project/operations/img/alert_detail_v13_0.png Binary files differnew file mode 100644 index 00000000000..7da09407cd5 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_v13_0.png diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index df7ce61525e..954f88fe4f2 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -4,7 +4,7 @@ GitLab provides a variety of tools to help operate and maintain your applications: - Collect [Prometheus metrics](../integrations/prometheus_library/index.md). -- Deploy to different [environments](../../../ci/environments.md). +- Deploy to different [environments](../../../ci/environments/index.md). - Connect your project to a [Kubernetes cluster](../clusters/index.md). - Manage your infrastructure with [Infrastructure as Code](../../infrastructure/index.md) approaches. - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index 620d9d70e4d..8e1117de4c7 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -13,7 +13,7 @@ You can add a button to the Monitoring dashboard linking directly to your existi  1. There should now be a button on your - [Monitoring dashboard](../../../ci/environments.md#monitoring-environments) which + [Monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) which will open the URL you entered in the above step.  diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 3a923ff32a8..ac10071e578 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -23,19 +23,19 @@ Press `t` to launch the File search function when in **Issues**, Start typing what you are searching for and watch the magic happen. With the up/down arrows, you go up and down the results, with `Esc` you close the search -and go back to **Files**. +and go back to **Files** ## How it works The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. -It implements a fuzzy search with highlight, and tries to provide intuitive +It implements a fuzzy search with the highlight and tries to provide intuitive results by recognizing patterns that people use while searching. For example, consider the [GitLab FOSS repository](https://gitlab.com/gitlab-org/gitlab-foss/tree/master) and that we want to open the `app/controllers/admin/deploy_keys_controller.rb` file. -Using fuzzy search, we start by typing letters that get us closer to the file. +Using a fuzzy search, we start by typing letters that get us closer to the file. **Tip:** To narrow down your search, include `/` in your search terms. |
