diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-18 21:09:07 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-18 21:09:07 +0300 |
commit | 6b8d671de726534a03c18e025a586e1bc9c04a4f (patch) | |
tree | f6a9168160b0d435641a1767b2e68487ec75ae46 /doc | |
parent | 163a7046ac76eb4109184e82ce0af911633e6626 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
20 files changed, 418 insertions, 79 deletions
diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 87be9d500fb..26c83ab6034 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -619,7 +619,7 @@ provided by `gitlab-ctl`. Consider the following example, where you first build the image: -```bash +```shell # This builds a image with content of sha256:111111 docker build -t my.registry.com/my.group/my.project:latest . docker push my.registry.com/my.group/my.project:latest @@ -627,7 +627,7 @@ docker push my.registry.com/my.group/my.project:latest Now, you do overwrite `:latest` with a new version: -```bash +```shell # This builds a image with content of sha256:222222 docker build -t my.registry.com/my.group/my.project:latest . docker push my.registry.com/my.group/my.project:latest @@ -774,7 +774,7 @@ once a week. Create a file under `/etc/cron.d/registry-garbage-collect`: -```bash +```shell SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 4c72634d4ff..37fffcdce22 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -88,11 +88,10 @@ pattern (`*~`). The hooks are searched and executed in this order: -1. `gitlab-shell/hooks` directory as known to Gitaly. -1. `<project>.git/hooks/<hook_name>` - executed by `git` itself, this is symlinked to `gitlab-shell/hooks/<hook_name>`. +1. Built-in GitLab server hooks (not user-customizable). 1. `<project>.git/custom_hooks/<hook_name>` - per-project hook (this was kept as the already existing behavior). 1. `<project>.git/custom_hooks/<hook_name>.d/*` - per-project hooks. -1. `<project>.git/hooks/<hook_name>.d/*` OR `<custom_hooks_dir>/<hook_name.d>/*` - global hooks: all executable files (except editor backup files). +1. `<custom_hooks_dir>/<hook_name>.d/*` - global hooks: all executable files (except editor backup files). The hooks of the same type are executed in order and execution stops on the first script exiting with a non-zero value. diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 48d415c6bdf..4ffce11aed0 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md @@ -74,7 +74,7 @@ and they will assist you with any issues you are having. - How to get cronjobs configured on a cluster - ```bash + ```shell kubectl get cronjobs ``` diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 7d4e62a8ff5..852a5ae6e71 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -17,7 +17,7 @@ Currently, these levels are recognized: Gets a list of protected environments from a project: -```bash +```shell GET /projects/:id/protected_environments ``` @@ -25,7 +25,7 @@ GET /projects/:id/protected_environments | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -```bash +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/' ``` @@ -51,7 +51,7 @@ Example response: Gets a single protected environment: -```bash +```shell GET /projects/:id/protected_environments/:name ``` @@ -60,7 +60,7 @@ GET /projects/:id/protected_environments/:name | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the protected environment | -```bash +```shell curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/production' ``` @@ -84,11 +84,11 @@ Example response: Protects a single environment: -```bash +```shell POST /projects/:id/protected_environments ``` -```bash +```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments?name=staging&deploy_access_levels%5B%5D%5Buser_id%5D=1' ``` @@ -122,11 +122,11 @@ Example response: Unprotects the given protected environment: -```bash +```shell DELETE /projects/:id/protected_environments/:name ``` -```bash +```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/staging' ``` diff --git a/doc/ci/README.md b/doc/ci/README.md index f25a0ade42a..5206807cf7a 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -50,6 +50,7 @@ To get started with GitLab CI/CD, we recommend you read through the following documents: - [How GitLab CI/CD works](introduction/index.md#how-gitlab-cicd-works). +- [Fundamental pipeline architectures](pipelines/pipeline_architectures.md). - [GitLab CI/CD basic workflow](introduction/index.md#basic-cicd-workflow). - [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started_part_four.md). diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 621b679de73..08419685388 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -397,7 +397,7 @@ Before the new extended Docker configuration options, you would need to create your own image based on the `super/sql:latest` image, add the default command, and then use it in job's configuration, like: -```Dockerfile +```dockerfile # my-super-sql:latest image's Dockerfile FROM super/sql:latest diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index f59401c6f87..848808f65ea 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -63,7 +63,7 @@ Next, we'll create a small subset of tests that exemplify most of the states I e this `Weapon` class to go through. To get started, create a folder called `lib/tests` and add the following code to a new file `weaponTests.ts`: -```ts +```typescript import { expect } from 'chai'; import { Weapon, BulletFactory } from '../lib/weapon'; @@ -114,7 +114,7 @@ describe('Weapon', () => { To build and run these tests using gulp, let's also add the following gulp functions to the existing `gulpfile.js` file: -```ts +```typescript gulp.task('build-test', function () { return gulp.src('src/tests/**/*.ts', { read: false }) .pipe(tap(function (file) { @@ -140,7 +140,7 @@ to trigger the weapon. In the `src/lib` folder create a `weapon.ts` file. We'll to it: `Weapon` and `BulletFactory` which will encapsulate Phaser's **sprite** and **group** objects, and the logic specific to our game. -```ts +```typescript export class Weapon { private isTriggered: boolean = false; private currentTimer: number = 0; @@ -210,7 +210,7 @@ export class BulletFactory { Lastly, we'll redo our entry point, `game.ts`, to tie together both `Player` and `Weapon` objects as well as add them to the update loop. Here is what the updated `game.ts` file looks like: -```ts +```typescript import { Player } from "./player"; import { Weapon, BulletFactory } from "./weapon"; diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md new file mode 100644 index 00000000000..0e6745a59eb --- /dev/null +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -0,0 +1,269 @@ +--- +type: reference +--- + +# Pipeline Architecture + +Pipelines are the fundamental building blocks for CI/CD in GitLab. This page documents +some of the important concepts related to them. + +There are three main ways to structure your pipelines, each with their +own advantages. These methods can be mixed and matched if needed: + +- [Basic](#basic-pipelines): Good for straightforward projects where all the configuration is in one easy to find place. +- [Directed Acylic Graph](#directed-acyclic-graph-pipelines): Good for large, complex projects that need efficient execution. +- [Child/Parent Pipelines](#child--parent-pipelines): Good for monorepos and projects with lots of independently defined components. + +For more details about +any of the keywords used below, check out our [CI YAML reference](../yaml/) for details. + +## Basic Pipelines + +This is the simplest pipeline in GitLab. It will run everything in the build stage concurrently, +and once all of those finish, it will run everything in the test stage the same way, and so on. +It's not the most efficient, and if you have lots of steps it can grow quite complex, but it's +easier to maintain: + +```mermaid +graph LR + subgraph deploy stage + deploy --> deploy_a + deploy --> deploy_b + end + subgraph test stage + test --> test_a + test --> test_b + end + subgraph build stage + build --> build_a + build --> build_b + end + build_a -.-> test + build_b -.-> test + test_a -.-> deploy + test_b -.-> deploy +``` + +Example basic `/.gitlab-ci.yml` pipeline configuration matching the diagram: + +```yaml +stages: + - build + - test + - deploy + +image: alpine + +build_a: + stage: build + script: + - echo "This job builds something." + +build_b: + stage: build + script: + - echo "This job builds something else." + +test_a: + stage: test + script: + - echo "This job tests something. It will only run when all jobs in the" + - echo "build stage are complete." + +test_b: + stage: test + script: + - echo "This job tests something else. It will only run when all jobs in the" + - echo "build stage are complete too. It will start at about the same time as test_a." + +deploy_a: + stage: deploy + script: + - echo "This job deploys something. It will only run when all jobs in the" + - echo "test stage complete." + +deploy_b: + stage: deploy + script: + - echo "This job deploys something else. It will only run when all jobs in the" + - echo "test stage complete. It will start at about the same time as deploy_a." +``` + +## Directed Acyclic Graph Pipelines + +If efficiency is important to you and you want everything to run as quickly as possible, +you can use [Directed Acylic Graphs (DAG)](../directed_acyclic_graph/index.md). Use the +[`needs` keyword](../yaml/README.md#needs) to define dependency relationships between +your jobs. When GitLab knows the relationships between your jobs, it can run everything +as fast as possible, and even skips into subsequent stages when possible. + +In the example below, if `build_a` and `test_a` are much faster than `build_b` and +`test_b`, GitLab will start `deploy_a` even if `build_b` is still running. + +```mermaid +graph LR + subgraph Pipeline using DAG + build_a --> test_a --> deploy_a + build_b --> test_b --> deploy_b + end +``` + +Example DAG `/.gitlab-ci.yml` configuration matching the diagram: + +```yaml +stages: + - build + - test + - deploy + +image: alpine + +build_a: + stage: build + script: + - echo "This job builds something quickly." + +build_b: + stage: build + script: + - echo "This job builds something else slowly." + +test_a: + stage: test + needs: build_a + script: + - echo "This test job will start as soon as build_a finishes." + - echo "It will not wait for build_b, or other jobs in the build stage, to finish." + +test_b: + stage: test + needs: build_b + script: + - echo "This test job will start as soon as build_b finishes." + - echo "It will not wait for other jobs in the build stage to finish." + +deploy_a: + stage: deploy + needs: test_a + script: + - echo "Since build_a and test_a run quickly, this deploy job can run much earlier." + - echo "It does not need to wait for build_b or test_b." + +deploy_b: + stage: deploy + needs: test_b + script: + - echo "Since build_b and test_b run slowly, this deploy job will run much later." +``` + +## Child / Parent Pipelines + +In the examples above, it's clear we've got two types of things that could be built independently. +This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via +the [`trigger` keyword](../yaml/README.md#trigger). It will separate out the configuration +into multiple files, keeping things very simple. You can also combine this with: + +- The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only + when there are changes to that area. +- The [`include` keyword](../yaml/README.md#include): Bring in common behaviors, ensuring + you are not repeating yourself. +- [DAG pipelines](#directed-acyclic-graph-pipelines) inside of child pipelines, achieving the benefits of both. + +```mermaid +graph LR + subgraph Parent pipeline + trigger_a -.-> build_a + trigger_b -.-> build_b + subgraph child pipeline B + build_b --> test_b --> deploy_b + end + + subgraph child pipeline A + build_a --> test_a --> deploy_a + end + end +``` + +Example `/.gitlab-ci.yml` configuration for the parent pipeline matching the diagram: + +```yaml +stages: + - triggers + +trigger_a: + stage: triggers + trigger: + include: a/.gitlab-ci.yml + rules: + - changes: + - a/* + +trigger_b: + stage: triggers + trigger: + include: b/.gitlab-ci.yml + rules: + - changes: + - b/* +``` + +Example child `a` pipeline configuration, located in `/a/.gitlab-ci.yml`, making +use of the DAG `needs:` keyword: + +```yaml +stages: + - build + - test + - deploy + +image: alpine + +build_a: + stage: build + script: + - echo "This job builds something." + +test_a: + stage: test + needs: build_a + script: + - echo "This job tests something." + +deploy_a: + stage: deploy + needs: test_a + script: + - echo "This job deploys something." +``` + +Example child `b` pipeline configuration, located in `/b/.gitlab-ci.yml`, making +use of the DAG `needs:` keyword: + +```yaml +stages: + - build + - test + - deploy + +image: alpine + +build_b: + stage: build + script: + - echo "This job builds something else." + +test_b: + stage: test + needs: build_b + script: + - echo "This job tests something else." + +deploy_b: + stage: deploy + needs: test_b + script: + - echo "This job deploys something else." +``` + +It's also possible to set jobs to run before or after triggering child pipelines, +for example if you have common setup steps or a unified deployment at the end. diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 6de3eaf8831..83b3ec44314 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -17,6 +17,11 @@ NOTE: **Note:** Coming over to GitLab from Jenkins? Check out our [reference](../jenkins/index.md) for converting your pre-existing pipelines over to our format. +NOTE: **Note:** +There are a few different [basic pipeline architectures](../pipelines/pipeline_architectures.md) +that you can consider for use in your project. You may want to familiarize +yourself with these prior to getting started. + GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI [pipeline](../pipelines.md), you must: diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index a137f10949f..235f237ba94 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -17,12 +17,12 @@ First, in your `.gitlab-ci.yml` add: ```yaml services: - - postgres:latest + - postgres:12.2-alpine variables: POSTGRES_DB: nice_marmot POSTGRES_USER: runner - POSTGRES_PASSWORD: "" + POSTGRES_PASSWORD: "runner-password" ``` NOTE: **Note:** @@ -37,7 +37,7 @@ And then configure your application to use the database, for example: ```yaml Host: postgres User: runner -Password: +Password: runner-password Database: nice_marmot ``` diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md index c1d58c1bd4b..a71e2b3c792 100644 --- a/doc/development/code_comments.md +++ b/doc/development/code_comments.md @@ -7,7 +7,7 @@ check if a comment is still relevant and what needs to be done to address it. Examples: -```rb +```ruby # Deprecated scope until code_owner column has been migrated to rule_type. # To be removed with https://gitlab.com/gitlab-org/gitlab/issues/11834. scope :code_owner, -> { where(code_owner: true).or(where(rule_type: :code_owner)) } diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md index 64385a2ea79..79ed465b121 100644 --- a/doc/development/creating_enums.md +++ b/doc/development/creating_enums.md @@ -8,7 +8,7 @@ To use this type, add `limit: 2` to the migration that creates the column. Example: -```rb +```ruby def change add_column :ci_job_artifacts, :file_format, :integer, limit: 2 end diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index e2f84e1200e..de7a437a1d6 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -783,33 +783,64 @@ nicely on different mobile devices. - When providing a shell command and its output, prefix the shell command with `$` and leave a blank line between the command and the output. - When providing a command without output, don't prefix the shell command with `$`. +- If you need to include triple backticks inside a code block, use four backticks + for the codeblock fences instead of three. - For regular code blocks, always use a highlighting class corresponding to the language for better readability. Examples: - ~~~md + ````markdown ```ruby Ruby code ``` - ```js + ```javascript JavaScript code ``` - ```md + ```markdown [Markdown code example](example.md) ``` - ```text + ```plaintext Code or text for which no specific highlighting class is available. ``` - ~~~ - -- To display raw Markdown instead of rendered Markdown, you can use triple backticks - with `md`, like the `Markdown code` example above, unless you want to include triple - backticks in the code block as well. In that case, use triple tildes (`~~~`) instead. -- [Syntax highlighting for code blocks](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) - is available for many languages. Use `shell` instead of `bash` or `sh` for shell output. -- For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks). + ```` + +Syntax highlighting is required for code blocks added to the GitLab documentation. +Refer to the table below for the most common language classes, or check the +[complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) +of language classes available. + +| Preferred language tags | Language aliases and notes | +|-------------------------|------------------------------------------------------------------------------| +| `asciidoc` | | +| `dockerfile` | Alias: `docker`. | +| `elixir` | | +| `erb` | | +| `golang` | Alias: `go`. | +| `graphql` | | +| `haml` | | +| `html` | | +| `ini` | For some simple config files that are not in TOML format. | +| `javascript` | Alias `js`. | +| `json` | | +| `markdown` | Alias: `md`. | +| `mermaid` | | +| `nginx` | | +| `perl` | | +| `php` | | +| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. | +| `prometheus` | Prometheus configuration examples. | +| `python` | | +| `ruby` | Alias: `rb`. | +| `shell` | Aliases: `bash` or `sh`. | +| `sql` | | +| `toml` | Runner configuration examples, and other toml formatted configuration files. | +| `typescript` | Alias: `ts`. | +| `xml` | | +| `yaml` | Alias: `yml`. | + +For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks). ## GitLab SVG icons diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 32017a284d5..b275a265cc6 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -240,13 +240,13 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag. 1. Create a package scoped flag name: - ```go + ```golang var findAllTagsFeatureFlag = "go-find-all-tags" ``` 1. Create a switch in the code using the `featureflag` package: - ```go + ```golang if featureflag.IsEnabled(ctx, findAllTagsFeatureFlag) { // go implementation } else { @@ -256,7 +256,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag. 1. Create Prometheus metrics: - ```go + ```golang var findAllTagsRequests = prometheus.NewCounterVec( prometheus.CounterOpts{ Name: "gitaly_find_all_tags_requests_total", @@ -280,7 +280,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag. 1. Set headers in tests: - ```go + ```golang import ( "google.golang.org/grpc/metadata" diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 73a1dd8ad8a..ae215026f56 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -195,7 +195,7 @@ When comparing expected and actual values in tests, use and others to improve readability when comparing structs, errors, large portions of text, or JSON documents: -```go +```golang type TestData struct { // ... } diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index dcd822705f9..aa210f3550f 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -918,12 +918,12 @@ instead of the default `ruby:latest`: 1. Set `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` to `--build-arg=RUBY_VERSION=alpine`. 1. Add the following to a custom `Dockerfile`: - ```docker - ARG RUBY_VERSION=latest - FROM ruby:$RUBY_VERSION + ```dockerfile + ARG RUBY_VERSION=latest + FROM ruby:$RUBY_VERSION - # ... put your stuff here - ``` + # ... put your stuff here + ``` NOTE: **Note:** Passing in complex values (newlines and spaces, for example) will likely @@ -955,14 +955,14 @@ In projects: 1. Activate the experimental `Dockerfile` syntax by adding the following to the top of the file: - ```docker + ```dockerfile # syntax = docker/dockerfile:experimental ``` 1. To make secrets available in any `RUN $COMMAND` in the `Dockerfile`, mount the secret file and source it prior to running `$COMMAND`: - ```docker + ```dockerfile RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND ``` diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md index e3cf0bcd498..96c2da4e963 100644 --- a/doc/topics/web_application_firewall/quick_start_guide.md +++ b/doc/topics/web_application_firewall/quick_start_guide.md @@ -80,11 +80,11 @@ under which this application will be deployed. ![Google auth](../autodevops/img/guide_google_auth_v12_3.png) 1. The last step is to provide the cluster details. - 1. Give it a name, leave the environment scope as is, and choose the GCP project under which the cluster - will be created (per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you). - 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the cluster will be created. - 1. Enter the number of nodes you want it to have. - 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). + 1. Give it a name, leave the environment scope as is, and choose the GCP project under which the cluster + will be created (per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you). + 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the cluster will be created. + 1. Enter the number of nodes you want it to have. + 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). ![GitLab GKE cluster details](../autodevops/img/guide_gitlab_gke_details_v12_3.png) @@ -180,40 +180,40 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the 1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. - This is done by running the following commands: + This is done by running the following commands: - ```bash - $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' - ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running + ```shell + $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' + ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running - $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;' - modsecurity on; - ``` + $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;' + modsecurity on; + ``` 1. Verify the Rails application has been installed properly. - ```bash - $ kubectl get ns - auto-devv-2-16730183-production Active + ```shell + $ kubectl get ns + auto-devv-2-16730183-production Active - $ kubectl get pods -n auto-devv-2-16730183-production - NAME READY STATUS RESTARTS - production-5778cfcfcd-nqjcm 1/1 Running 0 - production-postgres-6449f8cc98-r7xgg 1/1 Running 0 - ``` + $ kubectl get pods -n auto-devv-2-16730183-production + NAME READY STATUS RESTARTS + production-5778cfcfcd-nqjcm 1/1 Running 0 + production-postgres-6449f8cc98-r7xgg 1/1 Running 0 + ``` 1. To make sure the Rails application is responding, send a request to it by running: - ```bash - $ kubectl get ing -n auto-devv-2-16730183-production - NAME HOSTS PORTS - production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 + ```shell + $ kubectl get ing -n auto-devv-2-16730183-production + NAME HOSTS PORTS + production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 - $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io | grep 'Rails!' --after 2 --before 2 - <body> - <p>You're on Rails!</p> - </body> - ``` + $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io | grep 'Rails!' --after 2 --before 2 + <body> + <p>You're on Rails!</p> + </body> + ``` Now that we have confirmed our system is properly setup, we can go ahead and test the WAF with OWASP CRS! @@ -223,7 +223,7 @@ the WAF with OWASP CRS! Now let's send a potentially malicious request, as if we were a scanner, checking for vulnerabilities within our application and examine the modsecurity logs: -```bash +```shell $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 <body> <p>You're on Rails!</p> diff --git a/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png b/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png Binary files differnew file mode 100644 index 00000000000..467deb86881 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png diff --git a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png Binary files differnew file mode 100644 index 00000000000..8899852ed04 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index e703f15b4d3..2f6c77c8217 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -55,6 +55,17 @@ will help you to quickly create a deployment: 1. Navigate to your project's **CI/CD > Pipelines** page, and run a pipeline on any branch. 1. When the pipeline has run successfully, graphs will be available on the **Operations > Metrics** page. +![Monitoring Dashboard](img/prometheus_monitoring_dashboard_v12_8.png) + +#### Using the Metrics Dashboard + +##### Select an environment + +The **Environment** dropdown box above the dashboard displays the list of all [environments](#monitoring-cicd-environments). +It enables you to search as you type through all environments and select the one you're looking for. + +![Monitoring Dashboard Environments](img/prometheus_dashboard_environments_v12_8.png) + #### 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/). @@ -428,6 +439,29 @@ Note the following properties: ![single stat panel type](img/prometheus_dashboard_single_stat_panel_type.png) +###### Percentile based results + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201946) in GitLab 12.8. + +Query results sometimes need to be represented as a percentage value out of 100. You can use the `max_value` property at the root of the panel definition: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - title: "Single Stat" + type: "single-stat" + max_value: 100 + metrics: + - id: 10 + query: 'max(go_memstats_alloc_bytes{job="prometheus"})' + unit: '%' + label: "Total" +``` + +For example, if you have a query value of `53.6`, adding `%` as the unit results in a single stat value of `53.6%`, but if the maximum expected value of the query is `120`, the value would be `44.6%`. Adding the `max_value` causes the correct percentage value to display. + ##### Heatmaps > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5. |