Building images with kaniko and GitLab CI/CD
Introduced in GitLab 11.2. Requires GitLab Runner 11.2 and above.
kaniko is a tool to build container images from a Dockerfile, inside a container or Kubernetes cluster.
kaniko solves two problems with using the docker-in-docker build method:
- Docker-in-docker requires privileged mode in order to function, which is a significant security concern.
- Docker-in-docker generally incurs a performance penalty and can be quite slow.
Requirements
In order to utilize kaniko with GitLab, a GitLab Runner using one of the following executors is required:
Building a Docker image with kaniko
When building an image with kaniko and GitLab CI/CD, you should be aware of a few important details:
- The kaniko debug image is recommended (
gcr.io/kaniko-project/executor:debug
) because it has a shell, and a shell is required for an image to be used with GitLab CI/CD. - The entrypoint will need to be overridden, otherwise the build script will not run.
- A Docker
config.json
file needs to be created with the authentication information for the desired container registry.
In the following example, kaniko is used to:
- Build a Docker image.
- Then push it to GitLab Container Registry.
The job will run only when a tag is pushed. A config.json
file is created under
/kaniko/.docker
with the needed GitLab Container Registry credentials taken from the
environment variables
GitLab CI/CD provides.
In the last step, kaniko uses the Dockerfile
under the
root directory of the project, builds the Docker image and pushes it to the
project’s Container Registry while tagging it with the Git tag:
build:
stage: build
image:
name: gcr.io/kaniko-project/executor:debug
entrypoint: [""]
script:
- echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
- /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
only:
- tags
Using a registry with a custom certificate
When trying to push to a Docker registry that uses a certificate that is signed by a custom CA, you might get the following error:
$ /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --no-push
INFO[0000] Downloading base image registry.gitlab.example.com/group/docker-image
error building image: getting stage builder for stage 0: Get https://registry.gitlab.example.com/v2/: x509: certificate signed by unknown authority
This can be solved by adding your CA’s certificate to the kaniko certificate store:
before_script:
- echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
- |
echo "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" >> /kaniko/ssl/certs/ca-certificates.crt
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc