diff --git a/README.md b/README.md index 2a2078e2c2f9d81935c9cab8a485355e656d091e..5a1715b5db0ea97d9231499d73dcdae47313849a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This project implements a GitLab CI/CD template to build, test and secure your container images out of a `Dockerfile`. -It supports [kaniko](https://github.com/GoogleContainerTools/kaniko), [Buildah](https://buildah.io/) or [Docker](https://www.docker.com/) as build tools. +It supports [kaniko](https://github.com/chainguard-dev/kaniko), [Buildah](https://buildah.io/) or [Docker](https://www.docker.com/) as build tools. ## Usage @@ -44,13 +44,18 @@ The template supports following ways of building container images: 1. The former **Docker-in-Docker (DinD)** technique, that was widely used for years because of no other alternative, but that is now commonly recognized to have **significant security issues** ([read this post](https://jpetazzo.github.io/2015/09/03/do-not-use-docker-in-docker-for-ci/) for more info), -2. Or using [kaniko](https://github.com/GoogleContainerTools/kaniko), an open-source, daemonless tool from Google for building Docker - images, and that solves Docker-in-Docker security issues (and also speeds-up build times). -3. Or using [buildah](https://buildah.io/), an open-source, daemonless tool backed by RedHat for building Docker +2. Or using [kaniko](https://github.com/chainguard-dev/kaniko), an open-source, daemonless tool from Google for building Docker + images, and that solved Docker-in-Docker security issues but that is now [unmaintained](https://github.com/GoogleContainerTools/kaniko/issues/3348), +3. Or using [Buildah](https://buildah.io/), an open-source, daemonless tool backed by RedHat for building Docker images, and that solves Docker-in-Docker security issues (and also speeds-up build times), can also be configured to run rootless or support platform emulation. -By default, the template uses the [kaniko](https://docs.gitlab.com/ci/docker/using_kaniko/) way, but you may -select an alternate build tool by using the `DOCKER_BUILD_TOOL` variable (see below). +By default, the template uses [Buildah](https://buildah.io/), but you may select an alternate build tool by setting the `build-tool` input / `DOCKER_BUILD_TOOL` variable (see below). + +> [!important] Version 8 switches the default Docker build tool to Buildah +> +> Because [Kaniko is no longer maintained](https://github.com/GoogleContainerTools/kaniko/issues/3348), [Buildah](https://buildah.io/) is now the default. +> +> This change may introduce breaking changes to your pipelines. :warning: If you choose to use 'Docker-in-Docker' option considering the associated security risks, make sure your runner has required privileges to run Docker-in-Docker ([see GitLab doc](https://docs.gitlab.com/ci/docker/using_docker_build/#use-docker-in-docker-workflow-with-docker-executor)). @@ -62,7 +67,7 @@ The Docker template uses some global configuration used throughout all jobs. | Input / Variable | Description | Default value | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `build-tool` / `DOCKER_BUILD_TOOL` | The build tool to use for building container image, possible values are `kaniko`, `buildah`, `dind` or `external` | `kaniko` | +| `build-tool` / `DOCKER_BUILD_TOOL` | The build tool to use for building container image, possible values are `kaniko`, `buildah`, `dind` or `external` | `buildah` | | `kaniko-image` / `DOCKER_KANIKO_IMAGE` | The image used to run `kaniko` - _for kaniko build only_ | `gcr.io/kaniko-project/executor:debug` (use `debug` images for GitLab)
[![Trivy Badge](https://to-be-continuous.gitlab.io/doc/secu/trivy-badge-DOCKER_KANIKO_IMAGE.svg)](https://to-be-continuous.gitlab.io/doc/secu/trivy-DOCKER_KANIKO_IMAGE)| | `buildah-image` / `DOCKER_BUILDAH_IMAGE` | The image used to run `buildah` - _for buildah build only_ | `quay.io/containers/buildah:latest`
[![Trivy Badge](https://to-be-continuous.gitlab.io/doc/secu/trivy-badge-DOCKER_BUILDAH_IMAGE.svg)](https://to-be-continuous.gitlab.io/doc/secu/trivy-DOCKER_BUILDAH_IMAGE)| | `image` / `DOCKER_IMAGE` | The Docker image used to run the docker client (see [full list](https://hub.docker.com/r/library/docker/)) - _for Docker-in-Docker build only_ | `docker.io/library/docker:latest`
[![Trivy Badge](https://to-be-continuous.gitlab.io/doc/secu/trivy-badge-DOCKER_IMAGE.svg)](https://to-be-continuous.gitlab.io/doc/secu/trivy-DOCKER_IMAGE) | @@ -250,8 +255,6 @@ The signing process can be configured with the following variables: | :lock: `cosign-private-key` / `DOCKER_COSIGN_PRIVATE_KEY` | Private key used for signing the Docker image and the attestation | _none_ | | :lock: `cosign-password` / `COSIGN_PASSWORD` | Password of the private key | _none_ | - - ## Multi Dockerfile support This template supports building multiple Docker images from a single Git repository. @@ -423,16 +426,16 @@ If you have defined one of those labels in the Dockerfile, the final value will :warning: this job requires that your runner has required privileges to run [Docker-in-Docker](https://docs.gitlab.com/ci/docker/using_docker_build/#use-docker-in-docker-workflow-with-docker-executor). If it is not the case this job will not be run. -This job performs a [Health Check](https://docs.docker.com/engine/reference/builder/#healthcheck) on your built image. +This job performs a [HealthCheck](https://docs.docker.com/reference/dockerfile/#healthcheck) on your built image. It is bound to the `package-test` stage, and uses the following variables: -| Input / Variable | Description | Default value | -| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -| `healthcheck-disabled` / `DOCKER_HEALTHCHECK_DISABLED` | Set to `true` to disable health check | _(none: enabled by default)_ | -| `healthcheck-timeout` / `DOCKER_HEALTHCHECK_TIMEOUT` | When testing a Docker Health (test stage), how long (in seconds) wait for the [HealthCheck status](https://docs.docker.com/engine/reference/builder/#healthcheck) | `60` | -| `healthcheck-options` / `DOCKER_HEALTHCHECK_OPTIONS` | Docker options for health check such as port mapping, environment... | _(none)_ | -| `healthcheck-container-args` / `DOCKER_HEALTHCHECK_CONTAINER_ARGS` | Set arguments sent to the running container for health check | _(none)_ | +| Input / Variable | Description | Default value | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| `healthcheck-disabled` / `DOCKER_HEALTHCHECK_DISABLED` | Set to `true` to disable health check | _(none: enabled by default)_ | +| `healthcheck-timeout` / `DOCKER_HEALTHCHECK_TIMEOUT` | When testing a Docker Health (test stage), how long (in seconds) wait for the [HealthCheck status](https://docs.docker.com/reference/dockerfile/#healthcheck) | `60` | +| `healthcheck-options` / `DOCKER_HEALTHCHECK_OPTIONS` | Docker options for health check such as port mapping, environment... | _(none)_ | +| `healthcheck-container-args` / `DOCKER_HEALTHCHECK_CONTAINER_ARGS` | Set arguments sent to the running container for health check | _(none)_ | In case your Docker image is not intended to run as a service and only contains a _client tool_ (like curl, Ansible, ...) you can test it by overriding the Health Check Job. See [this example](#overriding-docker-healthcheck). diff --git a/kicker.json b/kicker.json index b8071b4d765394feba9462aaff9f2d83d39bff4d..3b67d341d7abf0f573f1b8ef36c6ed4ac7ab4269 100644 --- a/kicker.json +++ b/kicker.json @@ -9,9 +9,9 @@ { "name": "DOCKER_BUILD_TOOL", "type": "enum", - "values": ["kaniko", "buildah", "dind", "external"], + "values": ["buildah", "dind", "kaniko", "external"], "description": "The build tool to use for building container image", - "default": "kaniko" + "default": "buildah" }, { "name": "DOCKER_KANIKO_IMAGE", diff --git a/templates/gitlab-ci-docker.yml b/templates/gitlab-ci-docker.yml index 919ab239b2195560d9433a13da0f0125f8f79aea..d6b76c37dc86fd74e9b106835f13350eab2ed88d 100644 --- a/templates/gitlab-ci-docker.yml +++ b/templates/gitlab-ci-docker.yml @@ -18,11 +18,11 @@ spec: build-tool: description: The build tool to use for building container image options: - - kaniko - buildah - dind + - kaniko - external - default: kaniko + default: buildah kaniko-image: description: |- The image used to run kaniko @@ -312,7 +312,6 @@ variables: # don't use CI_PROJECT_TITLE, kaniko doesn't support space in argument right now (https://github.com/GoogleContainerTools/kaniko/issues/1231) DOCKER_METADATA: $[[ inputs.metadata ]] - # default to kaniko, possible options : kaniko|buildah|dind DOCKER_BUILD_TOOL: $[[ inputs.build-tool ]] DOCKER_CONTEXT_PATH: $[[ inputs.context-path ]]