summaryrefslogtreecommitdiff
path: root/doc/topics
diff options
context:
space:
mode:
Diffstat (limited to 'doc/topics')
-rw-r--r--doc/topics/autodevops/customize.md16
-rw-r--r--doc/topics/autodevops/index.md75
-rw-r--r--doc/topics/autodevops/quick_start_guide.md20
-rw-r--r--doc/topics/autodevops/requirements.md20
-rw-r--r--doc/topics/autodevops/stages.md64
-rw-r--r--doc/topics/autodevops/upgrading_chart.md72
-rw-r--r--doc/topics/autodevops/upgrading_postgresql.md15
-rw-r--r--doc/topics/git/index.md3
-rw-r--r--doc/topics/git/lfs/index.md3
-rw-r--r--doc/topics/git/lfs/migrate_to_git_lfs.md2
-rw-r--r--doc/topics/git/partial_clone.md5
-rw-r--r--doc/topics/gitlab_flow.md4
-rw-r--r--doc/topics/web_application_firewall/index.md11
-rw-r--r--doc/topics/web_application_firewall/quick_start_guide.md16
14 files changed, 245 insertions, 81 deletions
diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md
index 253d5e56463..2d6da4d322b 100644
--- a/doc/topics/autodevops/customize.md
+++ b/doc/topics/autodevops/customize.md
@@ -41,11 +41,16 @@ If your goal is to use only a single custom buildpack, you should provide the pr
## Custom `Dockerfile`
+> Support for `DOCKERFILE_PATH` was [added in GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35662)
+
If your project has a `Dockerfile` in the root of the project repository, Auto DevOps
builds a Docker image based on the Dockerfile, rather than using buildpacks.
This can be much faster and result in smaller images, especially if your
Dockerfile is based on [Alpine](https://hub.docker.com/_/alpine/).
+If you set the `DOCKERFILE_PATH` CI variable, Auto Build looks for a Dockerfile there
+instead.
+
## Passing arguments to `docker build`
Arguments can be passed to the `docker build` command using the
@@ -213,7 +218,7 @@ include:
See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs.
-CAUTION: **Deprecation**
+CAUTION: **Deprecation:**
Auto DevOps templates using the [`only`](../../ci/yaml/README.md#onlyexcept-basic) or
[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax will switch
to the [`rules`](../../ci/yaml/README.md#rules) syntax, starting in
@@ -238,7 +243,7 @@ postgres://user:password@postgres-host:postgres-port/postgres-database
### Upgrading PostgresSQL
-CAUTION: **Deprecation**
+CAUTION: **Deprecation:**
The variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned
PostgreSQL was changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499).
To keep using the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to
@@ -306,11 +311,13 @@ applications.
| `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. |
| `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From GitLab 11.11, used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. |
| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm will output debug logs. |
+| `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. [More details](upgrading_chart.md#ignore-warning-and-continue-deploying) |
| `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. |
| `BUILDPACK_URL` | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). |
| `CANARY_ENABLED` | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). |
| `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. |
| `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. |
+| `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) |
| `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. |
| `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. |
| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra arguments in `helm` commands when deploying the application. Note that using quotes won't prevent word splitting. |
@@ -358,7 +365,8 @@ The following table lists variables used to disable jobs.
| `DAST_DISABLED` | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job won't be created. |
| `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job won't be created. |
| `LICENSE_MANAGEMENT_DISABLED` | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job won't be created. |
-| `PERFORMANCE_DISABLED` | From GitLab 11.0, used to disable the `performance` job. If the variable is present, the job won't be created. |
+| `PERFORMANCE_DISABLED` | From GitLab 11.0, used to disable the browser `performance` job. If the variable is present, the job won't be created. |
+| `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2, used to disable the `load_performance` job. If the variable is present, the job won't be created. |
| `REVIEW_DISABLED` | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs won't be created. |
| `SAST_DISABLED` | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job won't be created. |
| `TEST_DISABLED` | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job won't be created. |
@@ -445,7 +453,7 @@ QA testing:
environment:
name: qa
script:
- - deploy foo
+ - deploy foo
```
The track `foo` being referenced must also be defined in the application's Helm chart, like:
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 767ea5ee7b7..01e61095fe2 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -104,16 +104,20 @@ knowledge of the following:
- [GitLab Runner](https://docs.gitlab.com/runner/)
- [Prometheus](https://prometheus.io/docs/introduction/overview/)
-Auto DevOps provides great defaults for all the stages; you can, however,
+Auto DevOps provides great defaults for all the stages and makes use of [CI templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates); you can, however,
[customize](customize.md) almost everything to your needs.
For an overview on the creation of Auto DevOps, read more
[in this blog post](https://about.gitlab.com/blog/2017/06/29/whats-next-for-gitlab-ci/).
-NOTE: **Note**
+NOTE: **Note:**
Kubernetes clusters can [be used without](../../user/project/clusters/index.md)
Auto DevOps.
+## Kubernetes requirements
+
+See [Auto DevOps requirements for Kubernetes](requirements.md#auto-devops-requirements-for-kubernetes).
+
## Auto DevOps base domain
The Auto DevOps base domain is required to use
@@ -163,6 +167,10 @@ set the Auto DevOps base domain to `1.2.3.4.nip.io`.
After completing setup, all requests hit the load balancer, which routes requests
to the Kubernetes pods running your application.
+### AWS ECS
+
+See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requirements-for-amazon-ecs).
+
## Enabling/Disabling Auto DevOps
When first using Auto DevOps, review the [requirements](#requirements) to ensure
@@ -185,7 +193,7 @@ If enabling, check that your project does not have a `.gitlab-ci.yml`, or if one
and choose the [deployment strategy](#deployment-strategy).
1. Click **Save changes** for the changes to take effect.
-After enabling the feature, an Auto DevOps pipeline is triggered on the default branch.
+After enabling the feature, an Auto DevOps pipeline is triggered on the `master` branch.
### At the group level
@@ -240,11 +248,11 @@ TIP: **Tip:**
Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
to minimize downtime and risk.
-## Using multiple Kubernetes clusters **(PREMIUM)**
+## Using multiple Kubernetes clusters
When using Auto DevOps, you can deploy different environments to
different Kubernetes clusters, due to the 1:1 connection
-[existing between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters-premium).
+[existing between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters).
The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
used by Auto DevOps currently defines 3 environment names:
@@ -271,8 +279,8 @@ To add a different cluster for each environment:
1. Navigate to your project's **{cloud-gear}** **Operations > Kubernetes**.
1. Create the Kubernetes clusters with their respective environment scope, as
described from the table above.
-1. After creating the clusters, navigate to each cluster and install Helm Tiller
- and Ingress. Wait for the Ingress IP address to be assigned.
+1. After creating the clusters, navigate to each cluster and install
+ Ingress. Wait for the Ingress IP address to be assigned.
1. Make sure you've [configured your DNS](#auto-devops-base-domain) with the
specified Auto DevOps domains.
1. Navigate to each cluster's page, through **{cloud-gear}** **Operations > Kubernetes**,
@@ -293,9 +301,9 @@ No documented way of using private container registry with Auto DevOps exists.
We strongly advise using GitLab Container Registry with Auto DevOps to
simplify configuration and prevent any unforeseen issues.
-### Installing Helm behind a proxy
+### Install applications behind a proxy
-GitLab does not support installing [Helm as a GitLab-managed App](../../user/clusters/applications.md#helm) when
+GitLab's Helm integration does not support installing applications when
behind a proxy. Users who want to do so must inject their proxy settings
into the installation pods at runtime, such as by using a
[`PodPreset`](https://kubernetes.io/docs/concepts/workloads/pods/podpreset/):
@@ -358,6 +366,55 @@ Auto Deploy will fail if GitLab can't create a Kubernetes namespace and
service account for your project. For help debugging this issue, see
[Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting).
+### Detected an existing PostgreSQL database
+
+After upgrading to GitLab 13.0, you may encounter this message when deploying
+with Auto DevOps:
+
+```plaintext
+Detected an existing PostgreSQL database installed on the
+deprecated channel 1, but the current channel is set to 2. The default
+channel changed to 2 in of GitLab 13.0.
+[...]
+```
+
+Auto DevOps, by default, installs an in-cluster PostgreSQL database alongside
+your application. The default installation method changed in GitLab 13.0, and
+upgrading existing databases requires user involvement. The two installation
+methods are:
+
+- **channel 1 (deprecated):** Pulls in the database as a dependency of the associated
+ Helm chart. Only supports Kubernetes versions up to version 1.15.
+- **channel 2 (current):** Installs the database as an independent Helm chart. Required
+ for using the in-cluster database feature with Kubernetes versions 1.16 and greater.
+
+If you receive this error, you can do one of the following actions:
+
+- You can *safely* ignore the warning and continue using the channel 1 PostgreSQL
+ database by setting `AUTO_DEVOPS_POSTGRES_CHANNEL` to `1` and redeploying.
+
+- You can delete the channel 1 PostgreSQL database and install a fresh channel 2
+ database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and
+ redeploying.
+
+ DANGER: **Danger:**
+ Deleting the channel 1 PostgreSQL database permanently deletes the existing
+ channel 1 database and all its data. See
+ [Upgrading PostgreSQL](upgrading_postgresql.md)
+ for more information on backing up and upgrading your database.
+
+- If you are not using the in-cluster database, you can set
+ `POSTGRES_ENABLED` to `false` and re-deploy. This option is especially relevant to
+ users of *custom charts without the in-chart PostgreSQL dependency*.
+ Database auto-detection is based on the `postgresql.enabled` Helm value for
+ your release. This value is set based on the `POSTGRES_ENABLED` CI variable
+ and persisted by Helm, regardless of whether or not your chart uses the
+ variable.
+
+DANGER: **Danger:**
+Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing
+channel 1 database for your environment.
+
## Development guides
[Development guide for Auto DevOps](../../development/auto_devops.md)
diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md
index ec5191dd4ac..4f8074f047e 100644
--- a/doc/topics/autodevops/quick_start_guide.md
+++ b/doc/topics/autodevops/quick_start_guide.md
@@ -98,24 +98,10 @@ status on your [GCP dashboard](https://console.cloud.google.com/kubernetes).
Next, you will install some applications on your cluster that are needed
to take full advantage of Auto DevOps.
-## Install the package manager
-
-After creating your Kubernetes cluster, GitLab's Kubernetes integration provides
-[pre-defined applications](../../user/project/clusters/index.md#installing-applications)
-for you to install. To install them, you must next install Helm Tiller, the
-Kubernetes package manager for Kubernetes, to enable the installation of other applications.
-
-Next to **Helm Tiller**, click **Install**.
-
-![Cluster applications](img/guide_cluster_apps_v12_3.png)
-
-After installation completes, the page reloads, and you can install other
-applications.
-
## Install Ingress and Prometheus
-After installing **Helm Tiller**, you can install other applications that rely on it,
-including Ingress and Prometheus, which we will install in this quick start guide:
+After your cluster is running, you can install your first applications.
+In this guide, we will install Ingress and Prometheus:
- Ingress - Provides load balancing, SSL termination, and name-based virtual hosting,
using NGINX behind the scenes.
@@ -305,7 +291,7 @@ all within GitLab. Despite its automatic nature, Auto DevOps can also be configu
and customized to fit your workflow. Here are some helpful resources for further reading:
1. [Auto DevOps](index.md)
-1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters-premium) **(PREMIUM)**
+1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters)
1. [Incremental rollout to production](customize.md#incremental-rollout-to-production-premium) **(PREMIUM)**
1. [Disable jobs you don't need with environment variables](customize.md#environment-variables)
1. [Use a static IP for your cluster](../../user/clusters/applications.md#using-a-static-ip)
diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md
index b09a571fd16..33db94be97e 100644
--- a/doc/topics/autodevops/requirements.md
+++ b/doc/topics/autodevops/requirements.md
@@ -103,22 +103,26 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208132) in GitLab 13.0.
-You can choose to target [Amazon Elastic Container Service (ECS)](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes.
+You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes.
-To get started on Auto DevOps to Amazon ECS, you'll have to add a specific Environment
+To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment
Variable. To do so, follow these steps:
1. In your project, go to **Settings > CI / CD** and expand the **Variables**
section.
1. Specify which AWS platform to target during the Auto DevOps deployment
- by adding the `AUTO_DEVOPS_PLATFORM_TARGET` variable.
+ by adding the `AUTO_DEVOPS_PLATFORM_TARGET` variable with one of the following values:
+ - `FARGATE` if the service you're targeting must be of launch type FARGATE.
+ - `ECS` if you're not enforcing any launch type check when deploying to ECS.
-1. Give this variable the value `ECS` before saving it.
-
-When you trigger a pipeline, if Auto DevOps is enabled and if you've correctly
+When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly
[entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs),
-your application will be deployed to Amazon ECS.
+your application will be deployed to AWS ECS.
+
+NOTE: **Note:**
+[GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS.
+You must manually configure your application (such as Ingress or Help) on AWS ECS.
NOTE: **Note:**
If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project,
@@ -130,5 +134,5 @@ defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/git
However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate)
it on its own. This template is designed to be used with Auto DevOps only. It may change
unexpectedly causing your pipeline to fail if included on its own. Also, the job
-names within this template may also change. Don't override these jobs' names in your
+names within this template may also change. Do not override these jobs' names in your
own pipeline, as the override will stop working when the name changes.
diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md
index 0c7c4919431..bf1594130f4 100644
--- a/doc/topics/autodevops/stages.md
+++ b/doc/topics/autodevops/stages.md
@@ -72,7 +72,8 @@ Heroku buildpacks, with the following caveats:
- The `/bin/herokuish` command is not present in the resulting image, and prefixing
commands with `/bin/herokuish procfile exec` is no longer required (nor possible).
-NOTE: **Note**: Auto Test still uses Herokuish, as test suite detection is not
+NOTE: **Note:**
+Auto Test still uses Herokuish, as test suite detection is not
yet part of the Cloud Native Buildpack specification. For more information, see
[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689).
@@ -294,7 +295,8 @@ You can disable DAST:
> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.4.
-Auto Browser Performance Testing measures the performance of a web page with the
+Auto [Browser Performance Testing](../../user/project/merge_requests/browser_performance_testing.md)
+measures the browser performance of a web page with the
[Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/),
creates a JSON report including the overall performance score for each page, and
uploads the report as an artifact. By default, it tests the root page of your Review and
@@ -307,9 +309,26 @@ file named `.gitlab-urls.txt` in the root directory, one file per line. For exam
/direction
```
-Any performance differences between the source and target branches are also
+Any browser performance differences between the source and target branches are also
[shown in the merge request widget](../../user/project/merge_requests/browser_performance_testing.md).
+## Auto Load Performance Testing **(PREMIUM)**
+
+> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
+
+Auto [Load Performance Testing](../../user/project/merge_requests/load_performance_testing.md)
+measures the server performance of an application with the
+[k6 container](https://hub.docker.com/r/loadimpact/k6/),
+creates a JSON report including several key result metrics, and
+uploads the report as an artifact.
+
+Some initial setup is required. A [k6](https://k6.io/) test needs to be
+written that's tailored to your specific application. The test also needs to be
+configured so it can pick up the environment's dynamic URL via an environment variable.
+
+Any load performance test result differences between the source and target branches are also
+[shown in the merge request widget](../../user/project/merge_requests/load_performance_testing.md).
+
## Auto Deploy
This is an optional step, since many projects don't have a Kubernetes cluster
@@ -372,7 +391,7 @@ as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`.
> - Support for deploying a PostgreSQL version that supports Kubernetes 1.16+ was [introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/49) in GitLab 12.9.
> - Supported out of the box for new deployments as of GitLab 13.0.
-CAUTION: **Deprecation**
+CAUTION: **Deprecation:**
The default value for the `deploymentApiVersion` setting was changed from
`extensions/v1beta` to `apps/v1` in [GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/issues/47).
@@ -398,7 +417,8 @@ To use Auto Deploy on a Kubernetes 1.16+ cluster:
1. If you are deploying your application for the first time and are using
GitLab 12.9 or 12.10, set `AUTO_DEVOPS_POSTGRES_CHANNEL` to `2`.
-DANGER: **Danger:** On GitLab 12.9 and 12.10, opting into
+DANGER: **Danger:**
+On GitLab 12.9 and 12.10, opting into
`AUTO_DEVOPS_POSTGRES_CHANNEL` version `2` deletes the version `1` PostgreSQL
database. Follow the [guide to upgrading PostgreSQL](upgrading_postgresql.md)
to back up and restore your database before opting into version `2` (On
@@ -437,6 +457,10 @@ Herokuish, and you must prefix commands run in these images with
`/bin/herokuish procfile exec` to replicate the environment where your application
will run.
+### Upgrade auto-deploy-app Chart
+
+You can upgrade auto-deploy-app chart by following the [upgrade guide](upgrading_chart.md).
+
### Workers
Some web applications must run extra deployments for "worker processes". For
@@ -469,16 +493,16 @@ workers:
sidekiq:
replicaCount: 1
command:
- - /bin/herokuish
- - procfile
- - exec
- - sidekiq
+ - /bin/herokuish
+ - procfile
+ - exec
+ - sidekiq
preStopCommand:
- - /bin/herokuish
- - procfile
- - exec
- - sidekiqctl
- - quiet
+ - /bin/herokuish
+ - procfile
+ - exec
+ - sidekiqctl
+ - quiet
terminationGracePeriodSeconds: 60
```
@@ -524,12 +548,12 @@ networkPolicy:
matchLabels:
app.gitlab.com/env: staging
ingress:
- - from:
- - podSelector:
- matchLabels: {}
- - namespaceSelector:
- matchLabels:
- app.gitlab.com/managed_by: gitlab
+ - from:
+ - podSelector:
+ matchLabels: {}
+ - namespaceSelector:
+ matchLabels:
+ app.gitlab.com/managed_by: gitlab
```
For more information on installing Network Policies, see
diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md
new file mode 100644
index 00000000000..e4dacdfcf5b
--- /dev/null
+++ b/doc/topics/autodevops/upgrading_chart.md
@@ -0,0 +1,72 @@
+# Upgrading auto-deploy-app chart for Auto DevOps
+
+Auto DevOps provides the auto-deploy-app chart for deploying your application to the
+Kubernetes cluster with Helm/Tiller. Major version changes of this chart could have
+a significantly different resource architecture, and may not be backwards compatible.
+
+This guide provides instructions on how to upgrade your deployments to use the latest
+chart and resource architecture.
+
+## Compatibility
+
+The following table lists the version compatibility between GitLab and [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) (with the [auto-deploy-app chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app)).
+
+| GitLab version | auto-deploy-image version | Notes |
+|------------------|---------------------------|--------------------------------------------|
+| v10.0 and higher | v0.1.0 and higher | v0 and v1 charts are backwards compatible. |
+
+## Upgrade Guide
+
+The Auto DevOps project must use the unmodified chart managed by GitLab.
+[Customized charts](customize.md#custom-helm-chart) are unsupported.
+
+### v1 chart
+
+The v1 chart is backward compatible with the v0 chart, so no configuration changes are needed.
+
+## Troubleshooting
+
+### Major version mismatch warning
+
+If deploying a chart that has a major version that is different from the previous one,
+the new chart might not be correctly deployed. This could be due to an architectural
+change. If that happens, the deployment job fails with a message similar to:
+
+```plaintext
+*************************************************************************************
+ [WARNING]
+Detected a major version difference between the the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0).
+A new major version might not be backward compatible with the current release (production). The deployment could fail or be stuck in an unrecoverable status.
+...
+```
+
+To clear this error message and resume deployments, you must do one of the following:
+
+- Manually [upgrade the chart version](#upgrade-guide).
+- [Use a specific chart version](#use-a-specific-chart-version).
+
+#### Use a specific chart version
+
+To use a specific chart version, you must specify a corresponding version of [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image).
+Do this by [customizing the image in your `.gitlab-ci.yml`](customize.md#customizing-gitlab-ciyml).
+
+For example, create the following `.gitlab-ci.yml` file in the project. It configures Auto DevOps
+to use [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) version `v0.17.0`
+for deployment jobs. It will download the chart from [chart repository](https://charts.gitlab.io/):
+
+```yaml
+include:
+ - template: Auto-DevOps.gitlab-ci.yml
+
+.auto-deploy:
+ image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v0.17.0"
+```
+
+### Ignore warning and continue deploying
+
+If you are certain that the new chart version is safe to be deployed,
+you can add the `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` [environment variable](customize.md#build-and-deployment)
+to force the deployment to continue, where `<N>` is the major version.
+
+For example, if you want to deploy the v2.0.0 chart on a deployment that previously
+used the v0.17.0 chart, add `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V2`.
diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md
index 893f7ba7cde..2ebe362280f 100644
--- a/doc/topics/autodevops/upgrading_postgresql.md
+++ b/doc/topics/autodevops/upgrading_postgresql.md
@@ -26,8 +26,12 @@ involves:
This varies based on Kubernetes providers.
1. Prepare for downtime. The steps below include taking the application offline
so that the in-cluster database does not get modified after the database dump is created.
+1. Ensure you have not set `POSTGRES_ENABLED` to `false`, as this setting deletes
+ any existing channel 1 database. For more information, see
+ [Detected an existing PostgreSQL database](index.md#detected-an-existing-postgresql-database).
-TIP: **Tip:** If you have configured Auto DevOps to have staging,
+TIP: **Tip:**
+If you have configured Auto DevOps to have staging,
consider trying out the backup and restore steps on staging first, or
trying this out on a review app.
@@ -158,12 +162,13 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain
## Install new PostgreSQL
-CAUTION: **Caution:** Using the newer version of PostgreSQL will delete
+CAUTION: **Caution:**
+Using the newer version of PostgreSQL will delete
the older 0.7.1 PostgreSQL. To prevent the underlying data from being
-deleted, you can choose to retain the [persistent
-volume](#retain-persistent-volumes).
+deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes).
-TIP: **Tip:** You can also
+TIP: **Tip:**
+You can also
[scope](../../ci/environments/index.md#scoping-environments-with-specs) the
`AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and
`POSTGRES_VERSION` variables to specific environments, e.g. `staging`.
diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md
index 2e36fea14bf..89da3dfdbd0 100644
--- a/doc/topics/git/index.md
+++ b/doc/topics/git/index.md
@@ -26,8 +26,9 @@ The following resources will help you get started with Git:
- [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics)
- [Git on the Server - GitLab](https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab)
- [How to install Git](how_to_install_git/index.md)
+- [Git terminology](../../gitlab-basics/start-using-git.md#git-terminology)
- [Start using Git on the command line](../../gitlab-basics/start-using-git.md)
-- [Command line file editing basic commands](../../gitlab-basics/command-line-commands.md)
+- [Edit files through the command line](../../gitlab-basics/command-line-commands.md)
- [GitLab Git Cheat Sheet (download)](https://about.gitlab.com/images/press/git-cheat-sheet.pdf)
- Commits:
- [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit)
diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md
index 706d3c3eddf..1e2f45fd67b 100644
--- a/doc/topics/git/lfs/index.md
+++ b/doc/topics/git/lfs/index.md
@@ -89,6 +89,9 @@ that are on the remote repository, such as for a branch from origin:
git lfs fetch origin master
```
+Make sure your files aren't listed in `.gitignore`, otherwise, they will be ignored by Git thus will not
+be pushed to the remote repository.
+
### Migrate an existing repo to Git LFS
Read the documentation on how to [migrate an existing Git repository with Git LFS](migrate_to_git_lfs.md).
diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md
index a64639a9238..3e287c0816d 100644
--- a/doc/topics/git/lfs/migrate_to_git_lfs.md
+++ b/doc/topics/git/lfs/migrate_to_git_lfs.md
@@ -21,7 +21,7 @@ and lastly create LFS tracking rules to prevent new binary files
from being added.
This tutorial was inspired by the guide
-[Use BFG to migrate a repository to Git LFS](https://confluence.atlassian.com/bitbucket/use-bfg-to-migrate-a-repo-to-git-lfs-834233484.html).
+[Use BFG to migrate a repository to Git LFS](https://support.atlassian.com/bitbucket-cloud/docs/use-bfg-to-migrate-a-repo-to-git-lfs/).
For more information on Git LFS, see the [references](#references)
below.
diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md
index 7462406cad3..de25c8a3283 100644
--- a/doc/topics/git/partial_clone.md
+++ b/doc/topics/git/partial_clone.md
@@ -84,7 +84,7 @@ Updating files: 100% (28/28), done.
$ cd www-gitlab-com
-$ git sparse-checkout init --cone
+$ git sparse-checkout init --clone
$ git sparse-checkout add data
remote: Enumerating objects: 301, done.
@@ -113,9 +113,6 @@ file to specify which files should be included when cloning and fetching.
For more details, see the Git documentation for
[`rev-list-options`](https://gitlab.com/gitlab-org/git/-/blob/9fadedd637b312089337d73c3ed8447e9f0aa775/Documentation/rev-list-options.txt#L735-780).
-With the `uploadpack.allowFilter` and `uploadpack.allowAnySHA1InWant` options
-enabled on the Git server:
-
1. **Create a filter spec.** For example, consider a monolithic repository with
many applications, each in a different subdirectory in the root. Create a file
`shiny-app/.filterspec` using the GitLab web interface:
diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md
index 6382ac0957a..04c942ab532 100644
--- a/doc/topics/gitlab_flow.md
+++ b/doc/topics/gitlab_flow.md
@@ -176,9 +176,9 @@ The name of a branch might be dictated by organizational standards.
When you are done or want to discuss the code, open a merge request.
A merge request is an online place to discuss the change and review the code.
-If you open the merge request but do not assign it to anyone, it is a "Work In Progress" merge request.
+If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/work_in_progress_merge_requests.md).
These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet.
-Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready.
+Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to prevent it from being merged before it's ready.
When you think the code is ready, assign the merge request to a reviewer.
The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch.
diff --git a/doc/topics/web_application_firewall/index.md b/doc/topics/web_application_firewall/index.md
index 57043bf73b3..5ce7c0779bb 100644
--- a/doc/topics/web_application_firewall/index.md
+++ b/doc/topics/web_application_firewall/index.md
@@ -1,3 +1,10 @@
+---
+stage: Defend
+group: Container Security
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+
# Web Application Firewall - ModSecurity
A web application firewall (or WAF) filters, monitors, and blocks HTTP traffic to
@@ -18,7 +25,7 @@ applications which have an Ingress.
The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) by default. The OWASP CRS will detect and log a wide range of common attacks.
-NOTE: **Note**
+NOTE: **Note:**
The WAF is deployed in "Detection-only mode" by default and will only log attack
attempts.
@@ -53,7 +60,7 @@ If you are using a self-managed instance of GitLab, you need to configure the
[Google OAuth2 OmniAuth Provider](../../integration/google.md) before
you can configure a cluster on GKE. Once this is set up, you can follow the steps on the [quick start guide](quick_start_guide.md) to get started.
-NOTE: **Note**
+NOTE: **Note:**
This guide shows how the WAF can be deployed using Auto DevOps. The WAF
is available by default to all applications no matter how they are deployed,
as long as they are using Ingress.
diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md
index ec6702bb457..9e69bc7e7c7 100644
--- a/doc/topics/web_application_firewall/quick_start_guide.md
+++ b/doc/topics/web_application_firewall/quick_start_guide.md
@@ -1,3 +1,9 @@
+---
+stage: Defend
+group: Container Security
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
# Getting started with the Web Application Firewall
This is a step-by-step guide that will help you use GitLab's [Web Application Firewall](index.md) after
@@ -11,7 +17,7 @@ These instructions will also work for a self-managed GitLab instance. However, y
need to ensure your own [Runners are configured](../../ci/runners/README.md) and
[Google OAuth is enabled](../../integration/google.md).
-**Note**: GitLab's Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#Ingress),
+**Note**: GitLab's Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress),
so it will be available to your applications no matter how you deploy them to Kubernetes.
## Configuring your Google account
@@ -86,7 +92,7 @@ status on your [GCP dashboard](https://console.cloud.google.com/kubernetes).
The next step is to install some applications on your cluster that are needed
to take full advantage of Auto DevOps.
-## Installing Helm and Ingress
+## Install Ingress
GitLab's Kubernetes integration comes with some
[pre-defined applications](../../user/project/clusters/index.md#installing-applications)
@@ -94,12 +100,6 @@ for you to install.
![Cluster applications](../autodevops/img/guide_cluster_apps_v12_3.png)
-The first one to install is Helm Tiller, a package manager for Kubernetes, which
-is needed in order to install the rest of the applications. Go ahead and click
-its **Install** button.
-Once it is installed, the other applications that rely on it will each have their
-**Install** buttons enabled.
-
For this guide, we need to install Ingress. Ingress provides load balancing,
SSL termination, and name-based virtual hosting, using NGINX behind
the scenes. Make sure to switch the toogle to the enabled position before installing.
View Lorry Controller Status