Merge branch 'use-cloud-native-buildpacks-by-default' into 'master'

Use Cloud Native Buildpacks by default in Auto Build

See merge request gitlab-org/gitlab!63351

doc/topics/autodevops/customize.md

@@ -16,15 +16,25 @@ staging and canary deployments,
 
 ## Custom buildpacks
 
-If the automatic buildpack detection fails for your project, or if you want to
-use a custom buildpack, you can override the buildpack using a project CI/CD variable
-or a `.buildpacks` file in your project:
+If the automatic buildpack detection fails for your project, or if you
+need more control over your build, you can customize the buildpacks
+used for the build.
 
-- **Project variable** - Create a project variable `BUILDPACK_URL` with the URL
-  of the buildpack to use.
-- **`.buildpacks` file** - Add a file in your project's repository called `.buildpacks`,
-  and add the URL of the buildpack to use on a line in the file. If you want to
-  use multiple buildpacks, enter one buildpack per line.
+### Custom buildpacks with Cloud Native Buildpacks
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165) in GitLab 12.10.
+
+Specify either:
+
+- The CI/CD variable `BUILDPACK_URL` according to [`pack`'s specifications](https://buildpacks.io/docs/app-developer-guide/specific-buildpacks/).
+- A [`project.toml` project descriptor](https://buildpacks.io/docs/app-developer-guide/using-project-descriptor/) with the buildpacks you would like to include.
+
+### Custom buildpacks with Herokuish
+
+Specify either:
+
+- The CI/CD variable `BUILDPACK_URL`.
+- A `.buildpacks` file at the root of your project, containing one buildpack URL per line.
 
 The buildpack URL can point to either a Git repository URL or a tarball URL.
 For Git repositories, you can point to a specific Git reference (such as
@@ -347,8 +357,8 @@ applications.
 | `ADDITIONAL_HOSTS`                      | Fully qualified domain names specified as a comma-separated list that are added to the Ingress hosts. |
 | `<ENVIRONMENT>_ADDITIONAL_HOSTS`        | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the Ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. |
 | `AUTO_DEVOPS_ATOMIC_RELEASE`            | As of GitLab 13.0, Auto DevOps uses [`--atomic`](https://v2.helm.sh/docs/helm/#options-43) for Helm deployments by default. Set this variable to `false` to disable the use of `--atomic` |
-| `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED`   | When set to a non-empty value and no `Dockerfile` is present, Auto Build builds your application using Cloud Native Buildpacks instead of Herokuish. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). |
-| `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`   | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). |
+| `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED`   | Set to `false` to use Herokuish instead of Cloud Native Buildpacks with Auto Build. [More details](stages.md#auto-build-using-cloud-native-buildpacks). |
+| `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`   | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks). |
 | `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS`    | Extra arguments to be passed to the `docker build` command. Note that using quotes doesn't prevent word splitting. [More details](#passing-arguments-to-docker-build). |
 | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI/CD variable names](#forward-cicd-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). |
 | `AUTO_DEVOPS_CHART`                     | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). |
@@ -358,7 +368,7 @@ applications.
 | `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 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. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). |
+| `BUILDPACK_URL`                         | Buildpack's full URL. [Must point to a URL supported by Pack or Herokuish](#custom-buildpacks). |
 | `CANARY_ENABLED`                        | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). |
 | `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. |

doc/topics/autodevops/stages.md

@@ -33,15 +33,24 @@ your own `Dockerfile`, you must either:
 - Override the default values by
   [customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart).
 
-### Auto Build using Heroku buildpacks
+### Auto Build using Cloud Native Buildpacks
+
+> - Introduced in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165).
+> - Auto Build using Cloud Native Buildpacks by default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63351) in GitLab 14.0.
 
 Auto Build builds an application using a project's `Dockerfile` if present. If no
-`Dockerfile` is present, it uses [Herokuish](https://github.com/gliderlabs/herokuish)
-and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks)
-to detect and build the application into a Docker image.
+`Dockerfile` is present, Auto Build builds your application using
+[Cloud Native Buildpacks](https://buildpacks.io) to detect and build the
+application into a Docker image. The feature uses the
+[`pack` command](https://github.com/buildpacks/pack).
+The default [builder](https://buildpacks.io/docs/concepts/components/builder/)
+is `heroku/buildpacks:18` but a different builder can be selected using
+the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`.
 
 Each buildpack requires your project's repository to contain certain files for
-Auto Build to build your application successfully. For example, your application's
+Auto Build to build your application successfully. The structure is
+specific to the builder and buildpacks you have selected.
+For example, when using the Heroku's builder (the default), your application's
 root directory must contain the appropriate file for your application's
 language:
 
@@ -52,39 +61,38 @@ For the requirements of other languages and frameworks, read the
 [Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks).
 
 NOTE:
-If Auto Build fails despite the project meeting the buildpack requirements, set
-a project CI/CD variable `TRACE=true` to enable verbose logging, which may help you
-troubleshoot.
+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).
 
-### Auto Build using Cloud Native Buildpacks (beta)
+### Auto Build using Herokuish
 
-> Introduced in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165).
+> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63351) with Cloud Native Buildpacks in GitLab 14.0.
 
-Auto Build supports building your application using [Cloud Native Buildpacks](https://buildpacks.io)
-through the [`pack` command](https://github.com/buildpacks/pack). To use Cloud Native Buildpacks,
-set the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` to a non-empty
-value. The default builder is `heroku/buildpacks:18` but a different builder
-can be selected using the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`.
+Prior to GitLab 14.0, [Herokuish](https://github.com/gliderlabs/herokuish) was
+the default build method for projects without a `Dockerfile`. Herokuish can
+still be used by setting the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED`
+to `false`.
 
-Cloud Native Buildpacks (CNBs) are an evolution of Heroku buildpacks, and
-GitLab expects them to eventually supersede Herokuish-based builds within Auto DevOps. For more
-information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212692).
+NOTE:
+If Auto Build fails despite the project meeting the buildpack requirements, set
+a project CI/CD variable `TRACE=true` to enable verbose logging, which may help you
+troubleshoot.
+
+### Moving from Herokuish to Cloud Native Buildpacks
 
 Builds using Cloud Native Buildpacks support the same options as builds using
-Heroku buildpacks, with the following caveats:
+Herokuish, with the following caveats:
 
 - The buildpack must be a Cloud Native Buildpack. A Heroku buildpack can be
   converted to a Cloud Native Buildpack using Heroku's
   [`cnb-shim`](https://github.com/heroku/cnb-shim).
-- `BUILDPACK_URL` must be in a form
+- `BUILDPACK_URL` must be in a format
   [supported by `pack`](https://buildpacks.io/docs/app-developer-guide/specific-buildpacks/).
-- The `/bin/herokuish` command is not present in the resulting image, and prefixing
+- The `/bin/herokuish` command is not present in the built image, and prefixing
   commands with `/bin/herokuish procfile exec` is no longer required (nor possible).
-
-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).
+  Instead, custom commands should be prefixed with `/cnb/lifecycle/launcher`
+  to receive the correct execution environment.
 
 ## Auto Test
 
@@ -461,15 +469,16 @@ If present, `DB_MIGRATE` is run as a shell command within an application pod as
 a Helm pre-upgrade hook.
 
 For example, in a Rails application in an image built with
-[Herokuish](https://github.com/gliderlabs/herokuish):
+[Cloud Native Buildpacks](#auto-build-using-cloud-native-buildpacks):
 
-- `DB_INITIALIZE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:setup`
-- `DB_MIGRATE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:migrate`
+- `DB_INITIALIZE` can be set to `RAILS_ENV=production /cnb/lifecycle/launcher bin/rails db:setup`
+- `DB_MIGRATE` can be set to `RAILS_ENV=production /cnb/lifecycle/launcher bin/rails db:migrate`
 
 Unless your repository contains a `Dockerfile`, your image is built with
-Herokuish, and you must prefix commands run in these images with
-`/bin/herokuish procfile exec` (for Herokuish) or `/cnb/lifecycle/launcher`
-(for Cloud Native Buildpacks) to replicate the environment where your
+Cloud Native Buildpacks, and you must prefix commands run in these images with
+`/cnb/lifecycle/launcher`, (or `/bin/herokuish procfile exec` when
+using [Herokuish](#auto-build-using-herokuish))
+to replicate the environment where your
 application runs.
 
 ### Upgrade auto-deploy-app Chart
@@ -508,14 +517,10 @@ workers:
   sidekiq:
     replicaCount: 1
     command:
-      - /bin/herokuish
-      - procfile
-      - exec
+      - /cnb/lifecycle/launcher
       - sidekiq
     preStopCommand:
-      - /bin/herokuish
-      - procfile
-      - exec
+      - /cnb/lifecycle/launcher
       - sidekiqctl
       - quiet
     terminationGracePeriodSeconds: 60

lib/gitlab/ci/templates/Jobs/Build.gitlab-ci.yml

 build:
   stage: build
-  image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-build-image:v0.6.0"
+  image: 'registry.gitlab.com/gitlab-org/cluster-integration/auto-build-image:v1.0.0'
   variables:
-    DOCKER_TLS_CERTDIR: ""
+    DOCKER_TLS_CERTDIR: ''
   services:
-    - name: "docker:20.10.6-dind"
+    - name: 'docker:20.10.6-dind'
       command: ['--tls=false', '--host=tcp://0.0.0.0:2375']
   script:
     - |