README.md

# Table of Contents

* [Overview](#overview)
* [Usage](#usage)
  * [Required CI Variables](#required-ci-variables)
  * [Optional CI Variables](#optional-ci-variables)
  * [Docker Image Naming](#docker-image-naming)
  * [Docker Image Tags](#docker-image-tags)
* [Kubernetes Support](#kubernetes-support)
  * [Required CI Variables for Kubernetes Support](#required-ci-variables-for-kubernetes-support)
  * [Kubernetes Manifests](#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

| **Variable Name** | **Description** |
|---|---|
| DOCKER_AUTH_CONFIG | Docker auth config file contents (~/.docker/config.json). **Keep this private!** |
| REGISTRY | Docker registry to push to |

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

| **Variable Name** | **Description** |
|---|---|
| DOCKER_BUILD_ARGS | Add arbitrary arguments to `docker build` as a JSON object e.g. `{'FOO': 'bar'}` would supply --build-arg=FOO=bar |
| DOCKERFILE | Set path to Dockerfile (Default: 'Dockerfile') |
| CONTEXT | Set path to docker build context (Default: '.') |
| GROUP | Override the default image publish path. (Default: the value of CI_PROJECT_NAMESPACE) |
| IMAGE_NAME | Override the default image name from CI_PROJECT_NAME to something else. (Default: the value of CI_PROJECT_NAME) |
| IMAGE_NAME_EXTRA | Modify the image name to be `<image-name>-<image-name-extra>`. (Default: None) |
| VERSION_FILE_PATH | If set, full docker image name will be saved under given path. |
| DOCKER_IMAGE_ARTIFACT | The docker image can be passed between stages as a gitlab artifact. This variable allows you to change the name of the file created. (Default: `<image-name>-<image-name-extra>.tar`) |
| NOTEST | Do not try pulling the image to verify that the publish worked (Some registries take time to make the image available) |

## 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

| **Variable Name** | **Description** |
|---|---|
| KUBE_CONFIG | Contents of a suitable `~/.kube/config` file to provide access to your kubernetes cluster. Must include all certificates etc required for access. **Keep this private!** |

## 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`.