diff options
Diffstat (limited to 'doc/topics')
19 files changed, 484 insertions, 327 deletions
diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 8f48b1fc57a..72f688a0ed5 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -208,6 +208,10 @@ If you need to specifically remove a part of the file, you can also copy and pas [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) into your project and edit it as needed. +## Use multiple Kubernetes clusters + +See [Multiple Kubernetes clusters for Auto DevOps](multiple_clusters_auto_devops.md). + ## Customizing the Kubernetes namespace > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. @@ -338,7 +342,7 @@ You must define environment-scoped CI/CD variables for `POSTGRES_ENABLED` and `DATABASE_URL` in your project's CI/CD settings: 1. Disable the built-in PostgreSQL installation for the required environments using - environment-scoped [CI/CD variables](../../ci/environments/index.md#scoping-environments-with-specs). + environment-scoped [CI/CD variables](../../ci/environments/index.md#scope-environments-with-specs). For this use case, it's likely that only `production` must be added to this list. The built-in PostgreSQL setup for Review Apps and staging is sufficient. @@ -379,6 +383,7 @@ applications. | `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From GitLab 11.11, used to set the name of the Helm repository. Defaults to `gitlab`. | | `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_CHART_REPOSITORY_PASS_CREDENTIALS` | From GitLab 14.2, set to a non-empty value to enable forwarding of the Helm repository credentials to the chart server when the chart artifacts are on a different host than repository. | | `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm outputs 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. For more information, see [Ignore warnings and continue deploying](upgrading_auto_deploy_dependencies.md#ignore-warnings-and-continue-deploying). | | `BUILDPACK_URL` | Buildpack's full URL. [Must point to a URL supported by Pack or Herokuish](#custom-buildpacks). | @@ -587,7 +592,7 @@ service: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/160) in GitLab 10.8. NOTE: -You can also set this inside your [project's settings](index.md#deployment-strategy). +You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). The normal behavior of Auto DevOps is to use continuous deployment, pushing automatically to the `production` environment every time a new pipeline is run @@ -616,7 +621,7 @@ If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8. NOTE: -You can also set this inside your [project's settings](index.md#deployment-strategy). +You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). When you're ready to deploy a new version of your app to production, you may want to use an incremental rollout to replace just a few pods with the latest code to @@ -673,7 +678,7 @@ removed in the future. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7545) in GitLab 11.4. NOTE: -You can also set this inside your [project's settings](index.md#deployment-strategy). +You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). This configuration is based on [incremental rollout to production](#incremental-rollout-to-production). diff --git a/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png b/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png Binary files differdeleted file mode 100644 index 9be414434c7..00000000000 --- a/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png +++ /dev/null diff --git a/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png b/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png Binary files differdeleted file mode 100644 index 9b51b5cfdd8..00000000000 --- a/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png +++ /dev/null diff --git a/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png b/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png Binary files differdeleted file mode 100644 index 2f3f8259316..00000000000 --- a/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png +++ /dev/null diff --git a/doc/topics/autodevops/img/guide_google_auth_v12_3.png b/doc/topics/autodevops/img/guide_google_auth_v12_3.png Binary files differdeleted file mode 100644 index b97b2be9f15..00000000000 --- a/doc/topics/autodevops/img/guide_google_auth_v12_3.png +++ /dev/null diff --git a/doc/topics/autodevops/img/guide_google_signin_v12_3.png b/doc/topics/autodevops/img/guide_google_signin_v12_3.png Binary files differdeleted file mode 100644 index 58bcc5e67b6..00000000000 --- a/doc/topics/autodevops/img/guide_google_signin_v12_3.png +++ /dev/null diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index beb5f6a58f6..f4936e9162d 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -6,320 +6,269 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Auto DevOps **(FREE)** -> - Introduced in GitLab 11.0 for general availability. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38366) in GitLab 11.0. -GitLab Auto DevOps helps to reduce the complexity of software delivery by -setting up pipelines and integrations for you. Auto DevOps configures -GitLab CI/CD pipelines including security auditing and vulnerability -testing. +GitLab Auto DevOps is a collection of pre-configured features and integrations +that work together to support your software delivery process. -Using Auto DevOps, you can: +Auto DevOps features and integrations: -- Detect the language of your code. -- Automatically build, test, and measure code quality. -- Scan for potential vulnerabilities, security flaws, and licensing issues. -- Monitor in real-time. +- Detect your code's language. +- Build and test your application. +- Measure code quality. +- Scan for vulnerabilities and security flaws. +- Check for licensing issues. +- Monitor in real time. - Deploy your application. -The functionality of Auto DevOps is based on default CI/CD templates that -auto-discover your source code. These templates enable GitLab to provide -consistency across your projects, seamless management of processes, and faster -creation of new projects. Leveraging [CI/CD best practices](../../ci/pipelines/pipeline_efficiency.md) -and tools, Auto DevOps lets you push your code, with GitLab doing the rest, -improving your productivity and efficiency. - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an introduction to Auto DevOps, watch [AutoDevOps in GitLab 11.0](https://youtu.be/0Tc0YYBxqi4) or see this [overview](https://about.gitlab.com/stages-devops-lifecycle/auto-devops/). +For an introduction to Auto DevOps, watch [Auto DevOps in GitLab 11.0](https://youtu.be/0Tc0YYBxqi4). -For requirements, read [Requirements for Auto DevOps](requirements.md) for more information. +## Auto DevOps features -For GitLab contributors, see the [Auto DevOps development guide](../../development/auto_devops.md). +Based on the DevOps [stages](stages.md), use Auto DevOps to: -## Enable or disable Auto DevOps +**Build your app:** -Auto DevOps is enabled by default for all projects in self-managed instances -(as of [GitLab 11.3](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729)), -but not for GitLab SaaS instances. +- [Auto Build](stages.md#auto-build) +- [Auto Dependency Scanning](stages.md#auto-dependency-scanning) -When first using Auto DevOps, review the [requirements](requirements.md) to -ensure all the necessary components to make full use of Auto DevOps are -available. First-time users should follow the [quick start guide](quick_start_guide.md). +**Test your app:** -Depending on your instance type, you can enable or disable Auto DevOps at the -following levels: +- [Auto Test](stages.md#auto-test) +- [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing) +- [Auto Code Intelligence](stages.md#auto-code-intelligence) +- [Auto Code Quality](stages.md#auto-code-quality) +- [Auto Container Scanning](stages.md#auto-container-scanning) +- [Auto License Compliance](stages.md#auto-license-compliance) -| Instance type | [Project](#at-the-project-level) | [Group](#at-the-group-level) | [Instance](#at-the-instance-level) (Admin Area) | -|---------------------|------------------------|------------------------|------------------------| -| GitLab SaaS | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | -| GitLab self-managed | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +**Deploy your app:** -When you enable Auto DevOps for your instance, it attempts to run on all -pipelines in each project. The Auto DevOps setting automatically disables itself for individual -projects on their first pipeline failure. An instance administrator can enable -or disable this default in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). +- [Auto Review Apps](stages.md#auto-review-apps) +- [Auto Deploy](stages.md#auto-deploy) -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26655) in GitLab 12.7, -Auto DevOps runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) -exists. +**Monitor your app:** -If a [CI/CD configuration file](../../ci/yaml/index.md) is present in the -project, it remains unchanged and Auto DevOps doesn't affect it. +- [Auto Monitoring](stages.md#auto-monitoring) -### At the project level +**Secure your app:** -When you enable Auto DevOps for a project, ensure that your project does not have a `.gitlab-ci.yml` present. If it exists, remove it before enabling Auto DevOps. +- [Auto Dynamic Application Security Testing (DAST)](stages.md#auto-dast) +- [Auto Static Application Security Testing (SAST)](stages.md#auto-sast) +- [Auto Secret Detection](stages.md#auto-secret-detection) -To enable it: +### How it works -1. Go to your project's **Settings > CI/CD > Auto DevOps**. -1. Select the **Default to Auto DevOps pipeline** checkbox to enable it. -1. (Optional, but recommended) When enabling, you can add in the - [base domain](#auto-devops-base-domain) Auto DevOps uses to - [deploy your application](stages.md#auto-deploy), - and choose the [deployment strategy](#deployment-strategy). -1. Click **Save changes** for the changes to take effect. +Auto DevOps detects your code language and uses [CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates) +to create and run default pipelines. All you need to kick it off is to +[enable](#enable-or-disable-auto-devops) it. -After enabling the feature, an Auto DevOps pipeline is triggered on the default branch. +Auto DevOps starts by building and testing your application. Then, based on your +[predefined deployment configuration](requirements.md), +creates the necessary jobs to deploy your apps to staging +and/or production. It also sets up [Review Apps](stages.md#auto-review-apps) +so that you can preview your changes in a per-branch basis. -### At the group level +Note that you don't need to set up the deployment upfront. Auto DevOps +still builds and tests your application. You can define the deployment later. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52447) in GitLab 11.10. +Auto DevOps avoids the hassle of having to create entire pipelines manually. +Keep it simple and facilitate an iterative approach: ship your app first, +then explore the [customizations](customize.md) later. +You can also [manage Auto DevOps with APIs](customize.md#extend-auto-devops-with-the-api). -Only administrators and group owners can enable or disable Auto DevOps at the group level. +Some of the benefits of using Auto DevOps as part of your workflow are: -When you enable Auto DevOps at group level, the subgroups and projects in that group inherit the configuration. Auto DevOps -can be specifically enabled or disabled individually for projects and subgroups. +- Consistency: always start from default templates. +- Simplicity: create your pipeline with the default settings first, iterate later. +- Productivity: deploy multiple apps in a short period of time. +- Efficiency: get things done fast. -To enable or disable Auto DevOps at the group level: +### Comparison to application platforms and PaaS -1. Go to your group's **Settings > CI/CD > Auto DevOps** page. -1. Select the **Default to Auto DevOps pipeline** checkbox to enable it. -1. Click **Save changes** for the changes to take effect. +Auto DevOps provides features often included in an application +platform or in a Platform as a Service (PaaS). -### At the instance level **(FREE SELF)** +Inspired by [Heroku](https://www.heroku.com/), Auto DevOps goes beyond it +in multiple ways: -Even when disabled at the instance level, group owners and project maintainers -can still enable Auto DevOps at the group and project level, respectively. +- Auto DevOps works with any Kubernetes cluster. +- There is no additional cost. +- You can use a cluster hosted by yourself or on any public cloud. +- Auto DevOps offers an incremental graduation path. If you need to [customize](customize.md), start by changing the templates and evolve from there. -1. As an administrator, on the top bar, select **Menu >** **{admin}** **Admin**. -1. Go to **Settings > CI/CD > Continuous Integration and Deployment**. -1. Select **Default to Auto DevOps pipeline for all projects** to enable it. -1. (Optional) You can set up the Auto DevOps [base domain](#auto-devops-base-domain), - for Auto Deploy and Auto Review Apps to use. -1. Click **Save changes** for the changes to take effect. +## Get started with Auto DevOps -### Deployment strategy +To get started, you only need to [enable Auto DevOps](#enable-or-disable-auto-devops). +This is enough to run an Auto DevOps pipeline to build and +test your application. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. +If you want to build, test, and deploy your app: -You can change the deployment strategy used by Auto DevOps by visiting your -project's **Settings > CI/CD > Auto DevOps**. The following options -are available: +1. See the [requirements for deployment](requirements.md). +1. [Enable Auto DevOps](#enable-or-disable-auto-devops). +1. Follow the [quick start guide](#quick-start). -- **Continuous deployment to production**: Enables [Auto Deploy](stages.md#auto-deploy) - with the default branch directly deployed to production. -- **Continuous deployment to production using timed incremental rollout**: Sets the - [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable - to `timed`. Production deployments execute with a 5 minute delay between - each increment in rollout. -- **Automatic deployment to staging, manual deployment to production**: Sets the - [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) variables - to `1` and `manual`. This means: +As Auto DevOps relies on many components, be familiar with: - - The default branch is directly deployed to staging. - - Manual actions are provided for incremental rollout to production. +- [Continuous methodologies](../../ci/introduction/index.md) +- [Docker](https://docs.docker.com) +- [GitLab Runner](https://docs.gitlab.com/runner/) -NOTE: -Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique -to minimize downtime and risk. +When deploying to a Kubernetes cluster make sure you're also familiar with: -## Quick start +- [Kubernetes](https://kubernetes.io/docs/home/) +- [Helm](https://helm.sh/docs/) +- [Prometheus](https://prometheus.io/docs/introduction/overview/) -For GitLab.com users, see the [quick start guide](quick_start_guide.md) -for setting up Auto DevOps deploying to a Kubernetes cluster on Google Kubernetes -Engine (GKE). +### Enable or disable Auto DevOps -If you use a self-managed instance of GitLab, you must configure the -[Google OAuth 2.0 OmniAuth Provider](../../integration/google.md) before -configuring a cluster on GKE. After configuring the provider, you can follow -the steps in the [quick start guide](quick_start_guide.md) to get started. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3, Auto DevOps is enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26655) GitLab 12.7, Auto DevOps runs pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists. -In [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/208132) and later, it is -possible to leverage Auto DevOps to deploy to [AWS ECS](requirements.md#auto-devops-requirements-for-amazon-ecs). +Depending on your instance type, you can enable or disable Auto DevOps at the +following levels: -## Comparison to application platforms and PaaS +| Instance type | [Project](#at-the-project-level) | [Group](#at-the-group-level) | [Instance](#at-the-instance-level) (Admin Area) | +|---------------------|------------------------|------------------------|------------------------| +| GitLab SaaS | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| GitLab self-managed | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -Auto DevOps provides features often included in an application -platform or a Platform as a Service (PaaS). It takes inspiration from the -innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it -in multiple ways: +Before enabling Auto DevOps, consider [preparing it for deployment](requirements.md). If you don't, Auto DevOps can build and test your app, +but cannot deploy it. -- Auto DevOps works with any Kubernetes cluster; you're not limited to running - on infrastructure managed by GitLab. (Note that many features also work without Kubernetes). -- There is no additional cost (no markup on the infrastructure costs), and you - can use a Kubernetes cluster you host or Containers as a Service on any - public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). -- Auto DevOps has more features including security testing, performance testing, - and code quality testing. -- Auto DevOps offers an incremental graduation path. If you need advanced customizations, - you can start modifying the templates without starting over on a - completely different platform. Review the [customizing](customize.md) documentation for more information. +#### At the project level -## Features +To use Auto DevOps for individual projects, you can enable it in a +project-by-project basis. If you intend to use it for more projects, +you can enable it for a [group](#at-the-group-level) or an +[instance](#at-the-instance-level). This can save you the time of +enabling it one by one. -NOTE: -Depending on your target platform, some features might not be available to you. +Only project Maintainers can enable or disable Auto DevOps at the project level. -Comprised of a set of [stages](stages.md), Auto DevOps brings these best practices to your -project automatically: +Before enabling Auto DevOps, ensure that your project does not have a +`.gitlab-ci.yml` present. If present, your CI/CD configuration takes +precedence over the Auto DevOps pipeline. -- [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing) -- [Auto Build](stages.md#auto-build) -- [Auto Code Intelligence](stages.md#auto-code-intelligence) -- [Auto Code Quality](stages.md#auto-code-quality) -- [Auto Container Scanning](stages.md#auto-container-scanning) -- [Auto DAST (Dynamic Application Security Testing)](stages.md#auto-dast) -- [Auto Dependency Scanning](stages.md#auto-dependency-scanning) -- [Auto Deploy](stages.md#auto-deploy) -- [Auto License Compliance](stages.md#auto-license-compliance) -- [Auto Monitoring](stages.md#auto-monitoring) -- [Auto Review Apps](stages.md#auto-review-apps) -- [Auto SAST (Static Application Security Testing)](stages.md#auto-sast) -- [Auto Secret Detection](stages.md#auto-secret-detection) -- [Auto Test](stages.md#auto-test) +To enable Auto DevOps for a project: -As Auto DevOps relies on many different components, you should have a basic -knowledge of the following: +1. Go to your project's **Settings > CI/CD > Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline**. +1. (Recommended) Add the [base domain](requirements.md#auto-devops-base-domain). +1. (Recommended) Choose the [deployment strategy](requirements.md#auto-devops-deployment-strategy). +1. Select **Save changes**. -- [Kubernetes](https://kubernetes.io/docs/home/) -- [Helm](https://helm.sh/docs/) -- [Docker](https://docs.docker.com) -- [GitLab Runner](https://docs.gitlab.com/runner/) -- [Prometheus](https://prometheus.io/docs/introduction/overview/) +GitLab triggers the Auto DevOps pipeline on the default branch. -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, and -[manage Auto DevOps with GitLab APIs](customize.md#extend-auto-devops-with-the-api). +To disable it, follow the same process and deselect **Default to Auto +DevOps pipeline**. -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/). +#### At the group level -NOTE: -Kubernetes clusters can [be used without](../../user/project/clusters/index.md) -Auto DevOps. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52447) in GitLab 11.10. -## Kubernetes requirements +When you enable Auto DevOps at group level, the subgroups and projects in that +group inherit the configuration. This saves you time by batch-enabling it +rather than enabling individually for each subgroup or project. -See [Auto DevOps requirements for Kubernetes](requirements.md#auto-devops-requirements-for-kubernetes). +When enabled for a group, you can still disable Auto DevOps +for the subgroups and projects where you don't want to use it. -## Auto DevOps base domain +Only GitLab administrators and group owners can enable or disable Auto DevOps +at the group level. -The Auto DevOps base domain is required to use -[Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and -[Auto Monitoring](stages.md#auto-monitoring). You can define the base domain in -any of the following places: +To enable Auto DevOps for a group: -- Either under the cluster's settings, whether for an instance, - [projects](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) or - [groups](../../user/group/clusters/index.md#base-domain) -- Or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN` -- Or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN` -- Or as an instance-wide fallback in **Menu >** **{admin}** **Admin >** - **Settings > CI/CD** under the **Continuous Integration and Delivery** section. +1. Go to your group's **Settings > CI/CD > Auto DevOps**. +1. Select **Default to Auto DevOps pipeline**. +1. Select **Save changes**. -The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence -as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). -If this variable isn't set and the cluster setting is left blank, the instance-wide domain is used if set for your instance. +After enabling Auto DevOps at the group level, you can trigger the +Auto DevOps pipeline for any project that belongs to that group. To do so: -Auto DevOps requires a wildcard DNS A record matching the base domain(s). For -a base domain of `example.com`, you'd need a DNS entry like: +1. Go to the project's homepage. +1. Make sure the project doesn't contain a `.gitlab-ci.yml` file. +1. From the project's sidebar, go to **CI/CD > Pipelines**. +1. Select **Run pipeline** to trigger the Auto DevOps pipeline. -```plaintext -*.example.com 3600 A 1.2.3.4 -``` +To disable Auto DevOps on the group level, follow the same process and +deselect **Default to Auto DevOps pipeline**. -In this case, the deployed applications are served from `example.com`, and `1.2.3.4` -is the IP address of your load balancer; generally NGINX ([see requirements](requirements.md)). -Setting up the DNS record is beyond the scope of this document; check with your -DNS provider for information. +#### At the instance level **(FREE SELF)** -Alternatively, you can use free public services like [nip.io](https://nip.io) -which provide automatic wildcard DNS without any configuration. For [nip.io](https://nip.io), -set the Auto DevOps base domain to `1.2.3.4.nip.io`. +By enabling Auto DevOps in the instance level, all projects created in that +instance become enabled. This is convenient when you want to run Auto DevOps by +default for all projects. You can still disable Auto DevOps individually for +the groups and projects where you don't want to run it. -After completing setup, all requests hit the load balancer, which routes requests -to the Kubernetes pods running your application. +Only GitLab administrators can enable or disable Auto DevOps in the instance +level. -### AWS ECS +Even when disabled for an instance, group owners and project maintainers +can still enable Auto DevOps at the group and project levels. -See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requirements-for-amazon-ecs). +To enable Auto DevOps for your instance: -## Use multiple Kubernetes clusters +1. From the top bar, select **Menu >** **{admin}** **Admin**. +1. Go to **Settings > CI/CD > Continuous Integration and Deployment**. +1. Select **Default to Auto DevOps pipeline**. +1. (Optional) Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain). +1. Select **Save changes**. -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/multiple_kubernetes_clusters.md). +When enabled, it attempts to run Auto DevOps pipelines in every project. If the +pipeline fails in a particular project, it disables itself. +GitLab administrators can change this in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). -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 defines 3 environment names: +If a [CI/CD configuration file](../../ci/yaml/index.md) is present, +it remains unchanged and Auto DevOps doesn't affect it. -- `review/` (every environment starting with `review/`) -- `staging` -- `production` +To disable Auto DevOps in the instance level, follow the same process +and deselect the **Default to Auto DevOps pipeline** checkbox. -Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so -except for the environment scope, they must have a different deployment domain. -You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above -[based on the environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). +### Quick start -The following table is an example of how to configure the three different clusters: +To guide your through the process of setting up Auto DevOps to deploy to a Kubernetes cluster on +Google Kubernetes Engine (GKE), see the [quick start guide](quick_start_guide.md). -| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes | -|--------------|---------------------------|-------------------------------------------|----------------------------|---| -| review | `review/*` | `review.example.com` | `review/*` | The review cluster which runs all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, used by every environment name starting with `review/`. | -| staging | `staging` | `staging.example.com` | `staging` | (Optional) The staging cluster which runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). | -| production | `production` | `example.com` | `production` | The production cluster which runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). | +You can also follow the quick start for the general steps, but deploy to +[AWS ECS](requirements.md#auto-devops-requirements-for-amazon-ecs) instead. -To add a different cluster for each environment: +If you're a self-managed user, before deploying to GKE, a GitLab administrator needs to: -1. Navigate to your project's **Infrastructure > Kubernetes clusters**. -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 - Ingress](quick_start_guide.md#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 **Infrastructure > Kubernetes clusters**, - and add the domain based on its Ingress IP address. +1. Configure the [Google OAuth 2.0 OmniAuth Provider](../../integration/google.md). +1. Configure a cluster on GKE. -After completing configuration, test your setup by creating a merge request. -Verify whether your application deployed as a Review App in the Kubernetes -cluster with the `review/*` environment scope. Similarly, you can check the -other environments. +## Upgrade Auto DevOps dependencies when updating GitLab -[Cluster environment scope isn't respected](https://gitlab.com/gitlab-org/gitlab/-/issues/20351) -when checking for active Kubernetes clusters. For multi-cluster setup to work with Auto DevOps, -create a fallback cluster with **Cluster environment scope** set to `*`. A new cluster isn't -required. You can use any of the clusters already added. +When updating GitLab, you may need to upgrade Auto DevOps dependencies to +match your new GitLab version: -## Limitations +- [Upgrading Auto DevOps resources](upgrading_auto_deploy_dependencies.md): + - Auto DevOps template. + - Auto Deploy template. + - Auto Deploy image. + - Helm. + - Kubernetes. + - Environment variables. +- [Upgrading PostgreSQL](upgrading_postgresql.md). -The following restrictions apply. +## Limitations ### Private registry support -No documented way of using private container registry with Auto DevOps exists. -We strongly advise using GitLab Container Registry with Auto DevOps to +We cannot guarantee that you can use a private container registry with Auto DevOps. + +We strongly advise you to use GitLab Container Registry with Auto DevOps to simplify configuration and prevent any unforeseen issues. ### Install applications behind a proxy The GitLab integration with Helm 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://v1-19.docs.kubernetes.io/docs/concepts/workloads/pods/podpreset/): +behind a proxy. + +To do so, inject proxy settings into the installation pods at runtime. +For example, you can use a [`PodPreset`](https://v1-19.docs.kubernetes.io/docs/concepts/workloads/pods/podpreset/): ```yaml apiVersion: settings.k8s.io/v1alpha1 @@ -335,23 +284,6 @@ spec: value: "PUT_YOUR_HTTPS_PROXY_HERE" ``` -## Upgrade Auto DevOps dependencies when updating GitLab - -When updating GitLab, you may need to upgrade Auto DevOps dependencies to -match your new GitLab version: - -- [Upgrading Auto DevOps resources](upgrading_auto_deploy_dependencies.md): - - Auto DevOps template. - - Auto Deploy template. - - Auto Deploy image. - - Helm. - - Kubernetes. - - Environment variables. -- [Upgrading PostgreSQL](upgrading_postgresql.md). - ## Troubleshooting See [troubleshooting Auto DevOps](troubleshooting.md). - -<!-- DO NOT ADD TROUBLESHOOTING INFO HERE --> -<!-- Troubleshooting information has moved to troubleshooting.md --> diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md new file mode 100644 index 00000000000..2191ab9ee8b --- /dev/null +++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md @@ -0,0 +1,53 @@ +--- +stage: Configure +group: Configure +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/#assignments +--- + +# Multiple Kubernetes clusters for Auto DevOps **(FREE)** + +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/multiple_kubernetes_clusters.md). + +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 defines 3 environment names: + +- `review/` (every environment starting with `review/`) +- `staging` +- `production` + +Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so +except for the environment scope, they must have a different deployment domain. +You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above +[based on the environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). + +The following table is an example of how to configure the three different clusters: + +| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes | +|--------------|---------------------------|-------------------------------------------|----------------------------|---| +| review | `review/*` | `review.example.com` | `review/*` | The review cluster which runs all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, used by every environment name starting with `review/`. | +| staging | `staging` | `staging.example.com` | `staging` | (Optional) The staging cluster which runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). | +| production | `production` | `example.com` | `production` | The production cluster which runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). | + +To add a different cluster for each environment: + +1. Navigate to your project's **Infrastructure > Kubernetes clusters**. +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 + Ingress](quick_start_guide.md#install-ingress). Wait for the Ingress IP address to be assigned. +1. Make sure you've [configured your DNS](requirements.md#auto-devops-base-domain) with the + specified Auto DevOps domains. +1. Navigate to each cluster's page, through **Infrastructure > Kubernetes clusters**, + and add the domain based on its Ingress IP address. + +After completing configuration, test your setup by creating a merge request. +Verify whether your application deployed as a Review App in the Kubernetes +cluster with the `review/*` environment scope. Similarly, check the +other environments. + +[Cluster environment scope isn't respected](https://gitlab.com/gitlab-org/gitlab/-/issues/20351) +when checking for active Kubernetes clusters. For multi-cluster setup to work with Auto DevOps, +create a fallback cluster with **Cluster environment scope** set to `*`. A new cluster isn't +required. You can use any of the clusters already added. diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md new file mode 100644 index 00000000000..830aff11824 --- /dev/null +++ b/doc/topics/autodevops/prepare_deployment.md @@ -0,0 +1,71 @@ +--- +stage: Configure +group: Configure +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/#assignments +--- + +# Prepare Auto DevOps for deployment **(FREE)** + +If you enable Auto DevOps without setting the base domain and deployment +strategy, GitLab can't deploy your application directly. Therefore, we +recommend that you prepare them before enabling Auto DevOps. + +## Deployment strategy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. + +When using Auto DevOps to deploy your applications, choose the +[continuous deployment strategy](../../ci/introduction/index.md) +that works best for your needs: + +| Deployment strategy | Setup | Methodology | +|--|--|--| +| **Continuous deployment to production** | Enables [Auto Deploy](stages.md#auto-deploy) with the default branch continuously deployed to production. | Continuous deployment to production.| +| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. | +| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. | + +You can choose the deployment method when enabling Auto DevOps or later: + +1. In GitLab, go to your project's **Settings > CI/CD > Auto DevOps**. +1. Choose the deployment strategy. +1. Select **Save changes**. + +NOTE: +Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique +to minimize downtime and risk. + +## Auto DevOps base domain + +The Auto DevOps base domain is required to use +[Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and +[Auto Monitoring](stages.md#auto-monitoring). + +To define the base domain, either: + +- In the project, group, or instance level: go to your cluster settings and add it there. +- In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`. +- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there. + +The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence +as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). + +If you don't specify the base domain in your projects and groups, Auto DevOps uses the instance-wide **Auto DevOps domain**. + +Auto DevOps requires a wildcard DNS A record matching the base domain(s). For +a base domain of `example.com`, you'd need a DNS entry like: + +```plaintext +*.example.com 3600 A 1.2.3.4 +``` + +In this case, the deployed applications are served from `example.com`, and `1.2.3.4` +is the IP address of your load balancer, generally NGINX ([see requirements](requirements.md)). +Setting up the DNS record is beyond the scope of this document; check with your +DNS provider for information. + +Alternatively, you can use free public services like [nip.io](https://nip.io) +which provide automatic wildcard DNS without any configuration. For [nip.io](https://nip.io), +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. diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 196f6dec7e7..2cf5a5befd7 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -4,19 +4,30 @@ group: Configure 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/#assignments --- -# Getting started with Auto DevOps **(FREE)** +# Tutorial: Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)** This step-by-step guide helps you use [Auto DevOps](index.md) to -deploy a project hosted on GitLab.com to Google Kubernetes Engine. +In this tutorial, we'll help you to get started with [Auto DevOps](index.md) +through an example of how to deploy an application to Google Kubernetes Engine (GKE). You are using the GitLab native Kubernetes integration, so you don't need to create a Kubernetes cluster manually using the Google Cloud Platform console. -You are creating and deploying a simple application that you create from a GitLab template. +You are creating and deploying an application that you create from a GitLab template. -These instructions also work for a self-managed GitLab instance; -ensure your own [runners are configured](../../ci/runners/index.md) and +These instructions also work for self-managed GitLab instances. +Ensure your own [runners are configured](../../ci/runners/index.md) and [Google OAuth is enabled](../../integration/google.md). +To deploy a project to Google Kubernetes Engine, follow the steps below: + +1. [Configure your Google account](#configure-your-google-account) +1. [Create a new project from a template](#create-a-new-project-from-a-template) +1. [Create a Kubernetes cluster from GitLab](#create-a-kubernetes-cluster-from-gitlab) +1. [Install Ingress](#install-ingress) +1. [Configure your base domain](#configure-your-base-domain) +1. [Enable Auto DevOps](#enable-auto-devops-optional) +1. [Deploy the application](#deploy-the-application) + ## Configure your Google account Before creating and connecting your Kubernetes cluster to your GitLab project, @@ -38,12 +49,12 @@ and apply for credit. ## Create a new project from a template -We are using a GitLab project template to get started. As the name suggests, +Use a GitLab project template to get started. As the name suggests, those projects provide a bare-bones application built on some well-known frameworks. -1. In GitLab, click the plus icon (**{plus-square}**) at the top of the navigation bar, and select - **New project**. -1. Go to the **Create from template** tab, where you can choose among a Ruby on +1. On the top bar in GitLab, select the plus icon (**{plus-square}**), and select + **New project/repository**. +1. Go to the **Create from template** tab, where you can choose a Ruby on Rails, Spring, or NodeJS Express project. For this tutorial, use the Ruby on Rails template. @@ -55,23 +66,21 @@ those projects provide a bare-bones application built on some well-known framewo  -1. Click **Create project**. +1. Select **Create project**. Now that you've created a project, create the Kubernetes cluster to deploy this project to. -## Create a Kubernetes cluster from within GitLab +## Create a Kubernetes cluster from GitLab -1. On your project's landing page, click **Add Kubernetes cluster** - (note that this option is also available when you navigate to - **Infrastructure > Kubernetes clusters**). +1. On your project's landing page, select the button **Add Kubernetes cluster**.  -1. On the **Add a Kubernetes cluster integration** page, click the **Create new cluster** tab, - then click **Google GKE**. +1. On the **Add a Kubernetes cluster integration** page, select the **Create new cluster** tab, + then select **Google GKE**. -1. Connect with your Google account, and click **Allow** to allow access to your +1. Connect with your Google account, and select **Allow** to allow access to your Google account. (This authorization request is only displayed the first time you connect GitLab with your Google account.) @@ -97,7 +106,7 @@ to deploy this project to. - **GitLab-managed cluster** - Select this checkbox to [allow GitLab to manage namespace and service accounts](../../user/project/clusters/index.md#gitlab-managed-clusters) for this cluster. -1. Click **Create Kubernetes cluster**. +1. Select **Create Kubernetes cluster**. After a couple of minutes, the cluster is created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). @@ -105,14 +114,14 @@ status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). ## Install Ingress After your cluster is running, you must install NGINX Ingress Controller as a -load balancer, to route traffic from the internet to your application. Because -you've created a Google GKE cluster in this guide, you can install NGINX Ingress Controller +load balancer, to route traffic from the internet to your application. +Install the NGINX Ingress Controller through the GitLab [Cluster management project template](../../user/clusters/management_project_template.md), or manually with Google Cloud Shell: -1. Go to your cluster's details page, and click the **Advanced Settings** tab. -1. Click the link to Google Kubernetes Engine to visit the cluster on Google Cloud Console. -1. On the GKE cluster page, select **Connect**, then click **Run in Cloud Shell**. +1. Go to your cluster's details page, and select the **Advanced Settings** tab. +1. Select the link to Google Kubernetes Engine to visit the cluster on Google Cloud Console. +1. On the GKE cluster page, select **Connect**, then select **Run in Cloud Shell**. 1. After the Cloud Shell starts, run these commands to install NGINX Ingress Controller: ```shell @@ -127,7 +136,7 @@ or manually with Google Cloud Shell: ## Configure your base domain -Follow these steps to configure the Base Domain where your apps will be accessible. +Follow these steps to configure the base domain where you access your apps. 1. A few minutes after you install NGINX, the load balancer obtains an IP address, and you can get the external IP address with the following command: @@ -141,8 +150,8 @@ Follow these steps to configure the Base Domain where your apps will be accessib Copy this IP address, as you need it in the next step. 1. Go back to the cluster page on GitLab, and go to the **Details** tab. - - Add your **Base domain**. For this guide, use the domain `<IP address>.nip.io`. - - Click **Save changes**. + - Add your **Base domain**. For this example, use the domain `<IP address>.nip.io`. + - Select **Save changes**.  @@ -152,11 +161,11 @@ While Auto DevOps is enabled by default, Auto DevOps can be disabled at both the instance level (for self-managed instances) and the group level. Complete these steps to enable Auto DevOps if it's disabled: -1. Navigate to **Settings > CI/CD > Auto DevOps**, and click **Expand**. +1. Go to **Settings > CI/CD > Auto DevOps**, and select **Expand**. 1. Select **Default to Auto DevOps pipeline** to display more options. -1. In **Deployment strategy**, select your desired [continuous deployment strategy](index.md#deployment-strategy) +1. In **Deployment strategy**, select your desired [continuous deployment strategy](requirements.md#auto-devops-deployment-strategy) to deploy the application to production after the pipeline successfully runs on the default branch. -1. Click **Save changes**. +1. Select **Save changes**.  @@ -169,7 +178,7 @@ In the next section, we explain what each job does in the pipeline. When your pipeline runs, what is it doing? -To view the jobs in the pipeline, click the pipeline's status badge. The +To view the jobs in the pipeline, select the pipeline's status badge. The **{status_running}** icon displays when pipeline jobs are running, and updates without refreshing the page to **{status_success}** (for success) or **{status_failed}** (for failure) when the jobs complete. @@ -233,12 +242,12 @@ you to common environment tasks: - **Re-deploy to environment** (**{repeat}**) - For more information, see [Retrying and rolling back](../../ci/environments/index.md#retry-or-roll-back-a-deployment) - **Stop environment** (**{stop}**) - For more information, see - [Stopping an environment](../../ci/environments/index.md#stopping-an-environment) + [Stopping an environment](../../ci/environments/index.md#stop-an-environment) GitLab displays the [Deploy Board](../../user/project/deploy_boards.md) below the environment's information, with squares representing pods in your Kubernetes cluster, color-coded to show their status. Hovering over a square on -the deploy board displays the state of the deployment, and clicking the square +the deploy board displays the state of the deployment, and selecting the square takes you to the pod's logs page. NOTE: @@ -251,7 +260,7 @@ in **Settings > CI/CD > Variables**. Following the [GitLab flow](../gitlab_flow.md#working-with-feature-branches), you should next create a feature branch to add content to your application: -1. In your project's repository, navigate to the following file: `app/views/welcome/index.html.erb`. +1. In your project's repository, go to the following file: `app/views/welcome/index.html.erb`. This file should only contain a paragraph: `<p>You're on Rails!</p>`. 1. Open the GitLab [Web IDE](../../user/project/web_ide/index.md) to make the change. 1. Edit the file so it contains: @@ -261,7 +270,7 @@ you should next create a feature branch to add content to your application: ``` 1. Stage the file. Add a commit message, then create a new branch and a merge request - by clicking **Commit**. + by selecting **Commit**.  @@ -272,7 +281,7 @@ a few more that run only on branches other than the default branch.  After a few minutes a test fails, which means a test was -'broken' by your change. Click on the failed `test` job to see more information +'broken' by your change. Select the failed `test` job to see more information about it: ```plaintext @@ -287,18 +296,18 @@ bin/rails test test/controllers/welcome_controller_test.rb:4 To fix the broken test: -1. Return to the **Overview** page for your merge request, and click **Open in Web IDE**. +1. Return to the **Overview** page for your merge request, and select **Open in Web IDE**. 1. In the left-hand directory of files, find the `test/controllers/welcome_controller_test.rb` - file, and click it to open it. + file, and select it to open it. 1. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.` -1. Click **Commit**. -1. In the left-hand column, under **Unstaged changes**, click the checkmark icon +1. Select **Commit**. +1. In the left-hand column, under **Unstaged changes**, select the checkmark icon (**{stage-all}**) to stage the changes. -1. Write a commit message, and click **Commit**. +1. Write a commit message, and select **Commit**. Return to the **Overview** page of your merge request, and you should not only see the test passing, but also the application deployed as a -[review application](stages.md#auto-review-apps). You can visit it by clicking +[review application](stages.md#auto-review-apps). You can visit it by selecting the **View app** **{external-link}** button to see your changes deployed.  @@ -314,7 +323,7 @@ all in GitLab. Despite its automatic nature, Auto DevOps can also be configured 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#use-multiple-kubernetes-clusters) +1. [Multiple Kubernetes clusters](multiple_clusters_auto_devops.md) 1. [Incremental rollout to production](customize.md#incremental-rollout-to-production) **(PREMIUM)** 1. [Disable jobs you don't need with CI/CD variables](customize.md#cicd-variables) 1. [Use your own buildpacks to build your application](customize.md#custom-buildpacks) diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 9c330aede17..535ec18e5b6 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -6,11 +6,85 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Requirements for Auto DevOps **(FREE)** -You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes), -[Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs), -or [Amazon Cloud Compute](#auto-devops-requirements-for-amazon-ecs). -For more information about Auto DevOps, see [the main Auto DevOps page](index.md) -or the [quick start guide](quick_start_guide.md). +Before enabling [Auto DevOps](index.md), we recommend you to prepare it for +deployment. If you don't, you can use it to build and test your apps, and +then configure the deployment later. + +To prepare the deployment: + +1. Define the [deployment strategy](#auto-devops-deployment-strategy). +1. Prepare the [base domain](#auto-devops-base-domain). +1. Define where you want to deploy it to: + + 1. [Kubernetes](#auto-devops-requirements-for-kubernetes). + 1. [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs). + 1. [Amazon EC2](#auto-devops-requirements-for-amazon-ec2). + 1. [Bare metal](#auto-devops-requirements-for-bare-metal). + +When done: + +1. [Enable Auto DevOps](index.md#enable-or-disable-auto-devops). +1. See the [quick start](quick_start_guide.md) process. + +## Auto DevOps deployment strategy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. + +When using Auto DevOps to deploy your applications, choose the +[continuous deployment strategy](../../ci/introduction/index.md) +that works best for your needs: + +| Deployment strategy | Setup | Methodology | +|--|--|--| +| **Continuous deployment to production** | Enables [Auto Deploy](stages.md#auto-deploy) with the default branch continuously deployed to production. | Continuous deployment to production.| +| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. | +| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. | + +You can choose the deployment method when enabling Auto DevOps or later: + +1. In GitLab, go to your project's **Settings > CI/CD > Auto DevOps**. +1. Choose the deployment strategy. +1. Select **Save changes**. + +NOTE: +Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique +to minimize downtime and risk. + +## Auto DevOps base domain + +The Auto DevOps base domain is required to use +[Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and +[Auto Monitoring](stages.md#auto-monitoring). + +To define the base domain, either: + +- In the project, group, or instance level: go to your cluster settings and add it there. +- In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`. +- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there. + +The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence +as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). + +If you don't specify the base domain in your projects and groups, Auto DevOps uses the instance-wide **Auto DevOps domain**. + +Auto DevOps requires a wildcard DNS A record matching the base domain(s). For +a base domain of `example.com`, you'd need a DNS entry like: + +```plaintext +*.example.com 3600 A 1.2.3.4 +``` + +In this case, the deployed applications are served from `example.com`, and `1.2.3.4` +is the IP address of your load balancer, generally NGINX ([see requirements](requirements.md)). +Setting up the DNS record is beyond the scope of this document; check with your +DNS provider for information. + +Alternatively, you can use free public services like [nip.io](https://nip.io) +which provide automatic wildcard DNS without any configuration. For [nip.io](https://nip.io), +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. ## Auto DevOps requirements for Kubernetes @@ -49,7 +123,7 @@ To make full use of Auto DevOps with Kubernetes, you need: - **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) - You must [specify the Auto DevOps base domain](index.md#auto-devops-base-domain), + You must [specify the Auto DevOps base domain](#auto-devops-base-domain), which all of your Auto DevOps applications use. This domain must be configured with wildcard DNS. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index f689183d556..3b595cc7ea8 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -107,12 +107,14 @@ Check the [currently supported languages](#currently-supported-languages). Auto Test uses tests you already have in your application. If there are no tests, it's up to you to add them. +<!-- vale gitlab.Spelling = NO --> + NOTE: Not all buildpacks supported by [Auto Build](#auto-build) are supported by Auto Test. Auto Test uses [Herokuish](https://gitlab.com/gitlab-org/gitlab/-/issues/212689), *not* Cloud Native Buildpacks, and only buildpacks that implement the -<!-- vale gitlab.Spelling = NO --> [Testpack API](https://devcenter.heroku.com/articles/testpack-api) are supported. + <!-- vale gitlab.Spelling = YES --> ### Currently supported languages @@ -696,7 +698,7 @@ To use Auto Monitoring: 1. [Enable Auto DevOps](index.md#enable-or-disable-auto-devops), if you haven't done already. 1. Navigate to your project's **{rocket}** **CI/CD > Pipelines** and click **Run pipeline**. 1. After the pipeline finishes successfully, open the - [monitoring dashboard for a deployed environment](../../ci/environments/index.md#monitoring-environments) + [monitoring dashboard for a deployed environment](../../ci/environments/index.md#monitor-environments) to view the metrics of your deployed application. To view the metrics of the whole Kubernetes cluster, navigate to **Operations > Metrics**. diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 4cf699ce25a..e4378ce2d78 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -117,7 +117,7 @@ If your Auto DevOps project has an active environment that was deployed with the 1. Deploy your environment as usual. This deployment uses Helm v3. 1. If the deployment succeeds, you can safely run `<environment-name>:helm-2to3:cleanup`. This deletes all Helm v2 release data from the namespace. -1. Remove the `MIGRATE_HELM_2TO3` CI/CD variable or set it to `false`. You can do this one environment at a time using [environment scopes](../../ci/environments/index.md#scoping-environments-with-specs). +1. Remove the `MIGRATE_HELM_2TO3` CI/CD variable or set it to `false`. You can do this one environment at a time using [environment scopes](../../ci/environments/index.md#scope-environments-with-specs). #### In-Cluster PostgreSQL Channel 2 diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index c03c4171d6d..e526ba55465 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -103,7 +103,7 @@ being modified after the database dump is created. 1. Connect to the pod with: ```shell - kubectl exec -it production-postgres-5db86568d7-qxlxv --namespace "$APP_NAMESPACE" bash + kubectl exec -it production-postgres-5db86568d7-qxlxv --namespace "$APP_NAMESPACE" -- bash ``` 1. Once, connected, create a dump file with the following command. @@ -175,7 +175,7 @@ deleted, you can choose to retain the [persistent volume](#retain-persistent-vol NOTE: You can also -[scope](../../ci/environments/index.md#scoping-environments-with-specs) the +[scope](../../ci/environments/index.md#scope-environments-with-specs) the `AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and `POSTGRES_VERSION` variables to specific environments, e.g. `staging`. @@ -190,7 +190,7 @@ higher*. This is the minimum PostgreSQL version supported by Auto DevOps. See also the list of [tags available](https://hub.docker.com/r/bitnami/postgresql/tags). 1. Set `PRODUCTION_REPLICAS` to `0`. For other environments, use - `REPLICAS` with an [environment scope](../../ci/environments/index.md#scoping-environments-with-specs). + `REPLICAS` with an [environment scope](../../ci/environments/index.md#scope-environments-with-specs). 1. If you have set the `DB_INITIALIZE` or `DB_MIGRATE` variables, either remove the variables, or rename the variables temporarily to `XDB_INITIALIZE` or the `XDB_MIGRATE` to effectively disable them. @@ -221,7 +221,7 @@ higher*. This is the 1. Connect to the pod: ```shell - kubectl exec -it production-postgresql-0 --namespace "$APP_NAMESPACE" bash + kubectl exec -it production-postgresql-0 --namespace "$APP_NAMESPACE" -- bash ``` 1. Once connected to the pod, run the following command to restore the database. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 8844d362c10..0e288f1445e 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -123,6 +123,27 @@ them before continuing the rebase. To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) and [rebasing strategies](https://git-scm.com/book/en/v2/Git-Branching-Rebasing). +#### Rebase from the GitLab UI + +You can rebase your feature branch directly from the merge request through a +[quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics), +if all of these conditions are met: + +- No [merge conflicts](#merge-conflicts) exist for your feature branch. +- You have the **Developer** role for the source project. This role grants you + permission to push to the source branch for the source project. +- If the merge request is in a fork, the fork must allow commits + [from members of the upstream project](../../user/project/merge_requests/allow_collaboration.md). + +To rebase from the UI: + +1. Go to your merge request. +1. Type `/rebase` in a comment. +1. Select **Comment**. + +GitLab schedules a rebase of the feature branch against the default branch and +executes it as soon as possible. + ### Interactive rebase You can use interactive rebase to modify commits. For example, amend a commit @@ -153,18 +174,20 @@ the operation you want to perform in each commit. To do so, you need to edit the commits in your terminal's text editor. For example, if you're using [Vim](https://www.vim.org/) as the text editor in -a macOS's `ZSH` shell, and you want to **squash** all the three commits +a macOS's `ZSH` shell, and you want to `squash` or `fixup` all the three commits (join them into one): -1. Press <!-- vale gitlab.FirstPerson = NO --> <kbd>i</kbd> <!-- vale gitlab.FirstPerson = YES --> +<!-- vale gitlab.FirstPerson = NO --> + +1. Press <kbd>i</kbd> on your keyboard to switch to Vim's editing mode. 1. Navigate with your keyboard arrows to edit the **second** commit keyword - from `pick` to `squash` (or `s`). Do the same to the **third** commit. + from `pick` to `squash` or `fixup` (or `s` or `f`). Do the same to the **third** commit. The first commit should be left **unchanged** (`pick`) as we want to squash the second and third into the first. 1. Press <kbd>Escape</kbd> to leave the editing mode. 1. Type `:wq` to "write" (save) and "quit". -1. Git outputs the commit message so you have a chance to edit it: +1. When squashing, Git outputs the commit message so you have a chance to edit it: - All lines starting with `#` are ignored and not included in the commit message. Everything else is included. - To leave it as it is, type `:wq`. To edit the commit message: switch to the @@ -173,6 +196,8 @@ a macOS's `ZSH` shell, and you want to **squash** all the three commits push your changes normally. If you had pushed these commits already, [force-push](#force-push) instead. +<!-- vale gitlab.FirstPerson = YES --> + Note that the steps for editing through the command line can be slightly different depending on your operating system and the shell you're using. diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 32039548475..0b4fd335455 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -271,7 +271,11 @@ If you are storing LFS files outside of GitLab you can disable LFS on the projec It is possible to host LFS objects externally by setting a custom LFS URL with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`. -You might choose to do this if you are using an appliance like a <!-- vale gitlab.Spelling = NO --> Sonatype Nexus <!-- vale gitlab.Spelling = YES --> to store LFS data. If you choose to use an external LFS store, +<!-- vale gitlab.Spelling = NO --> + +You might choose to do this if you are using an appliance like a Sonatype Nexus to store LFS data. If you choose to use an external LFS store, GitLab can't verify LFS objects. Pushes then fail if you have GitLab LFS support enabled. +<!-- vale gitlab.Spelling = YES --> + To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md), which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). diff --git a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md deleted file mode 100644 index d7fb8a37b9c..00000000000 --- a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2021-07-22' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2021-07-22>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/git/merge_requests.md b/doc/topics/git/merge_requests.md deleted file mode 100644 index d889bc8ffe5..00000000000 --- a/doc/topics/git/merge_requests.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../user/project/merge_requests/index.md' -remove_date: '2021-08-13' ---- - -This document was moved to [another location](../../user/project/merge_requests/index.md). - -<!-- This redirect file can be deleted after <2021-08-13>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/img/gitlab_flow.png b/doc/topics/img/gitlab_flow.png Binary files differindex a6f3c947843..c12405455f9 100644 --- a/doc/topics/img/gitlab_flow.png +++ b/doc/topics/img/gitlab_flow.png |
