Table of Contents

• Overview
• Usage
  • Required CI Variables
  • Optional CI Variables
  • Docker Image Naming
  • Docker Image Tags
• Kubernetes Support
  • Required CI Variables for Kubernetes Support
  • Kubernetes Manifests

Overview

Image for use in your project's Gitlab CI config with image:.

Builds your Docker image and deploys to Docker Registry.

Usage

In your .gitlab-ci.yml:

image: docker-build:latest

build:
  stage: build
  script:
  - build

deploy:
  only:
  - master OR tags
  stage: deploy
  script:
  - deploy

Required CI Variables

Example:

REGISTRY=internal.registry.svc.cluster.local
DOCKER_AUTH_CONFIG='{ "auths": { "internal.registry.svc.cluster.local": { "auth": "YW5vbnltb3VzOmFub255bW91cw==" }} }'

if you also want to publish to Docker Hub you need to add credentials for both docker.io and index.docker.io (it's the same password for both) as the push process needs to talk to both:

REGISTRY=index.docker.io
DOCKER_AUTH_CONFIG='{ "auths": { "docker.io": { "auth": "YW5vbnltb3VzOmFub255bW91cw==" }, "index.docker.io": { "auth": "YW5vbnltb3VzOmFub255bW91cw==" }} }'

How to generate the above "auth" value:

echo -n 'anonymous:anonymous' | base64

Although it is unlkely that either your username or your password will actually be the string anonymous.

Optional CI Variables

Using artefact to store docker image between builds

If you want your docker image to be built once per commit, and then re-used on next stages, your can treat it as an artifact and re-used on next job. This has few benefits:

• You can download the artefact and inspect it if troubleshooting is needed
• If the build process takes long time, this makes it happen once in pipeline
• You can inspect/test the image in CI without pushing it externally in separate jobs, possibly in parallel

There are also some costs:

• Image import/export process takes some additional time
• Images are stored in Gitlab artifact store, so limiting age of them is crucial

Example:

image: docker-build:latest

variables:
    DOCKER_IMAGE_ARTIFACT: docker-image.tar

build:
  stage: build
  script:
  - build
  artifacts:
    paths:
    - docker-image.tar
    expire_in: 8 hours

deploy:
  only:
  - master
  - tags
  stage: deploy
  script:
  - deploy
  dependencies:
  - build

Docker Image Naming

• The default naming strategy is:

https://my-gitlab-url/my-group(s)/project_name -> ${REGISTRY}/my-group(s)/project_name

• The path to the image (my-group(s) in this example) can be overriden with the CI variable GROUP
• The name of the image (project_name in this example) can be overriden with the CI variable IMAGE_NAME, and/or optionally IMAGE_NAME_EXTRA

For example, this config snippet would produce an image named something-else:

...
  variables:
    IMAGE_NAME: 'something-else'

  script:
  - build
...

Docker Image Tags

Up to 3 tags are created:

• current git SHA checksum
• latest
• git tag (if a tag matches current git SHA)

Kubernetes Support

The docker-build image includes the ability to deploy your image to your kubernetes cluster. You do this by including Kubernetes manifests in a project subfolder /manifests.

Just include the script command deploy-k8s in one of your script sections (after the image has been deployed to your registry, preferably).

Required CI Variables for Kubernetes Support

Kubernetes Manifests

The deploy-k8s command will look for files in the /manifests project subfolder that end either .yaml or .yaml.jinja2.

Jinja2 template files can contain the replacement token {{IMAGE}} which will be replaced by the best available image tag (Preferring a symbolic tag from a git tag, but falling back to the commit SHA), which should process into YAML valid for passing to the Kubernetes API. These, and any plain YAML files will be passed to the Kubernetes API in the same way as if they had been passed to kubectl apply.