Docker

Updated 2 years ago by Admin

The Docker plugin can be used to build and publish images to the Docker registry using Docker-in-Docker. The following pipeline configuration uses the Docker plugin to build and publish Docker images.

  • Example configuration builds and publishes an image using a Dockerfile in the root of your git repository. The docker context also defaults to the root of your git repository.
    1  kind: pipeline
    2  name: default
    3
    4  steps:
    5   - name: docker  
    6    image: plugins/docker
    7    settings:
    8      username: kevinbacon
    9      password: pa55word
    10     repo: foo/bar
    11     tags:
    12     - latest
  • Example configuration using multiple tags:
    1  steps:
    2  - name: docker  
    3    image: plugins/docker
    4    settings:
    5     username: kevinbacon
    6     password: pa55word
    7     repo: foo/bar
    8     tags:
    9       - latest
    10      - '1.0.1'
    11      - '1.0
  • Example configuration uses a .tags file, a comma-separate list of tags, to dynamically configure tags. The plugin automatically loads this file if it exists.
    1  steps:
    2  - name: build
    3    image: golang
    4    commands:
    5      - go build
    6      - go test
    7      - echo -n "5.2.6,5.2.4" > .tags
    8
    9  - name: docker  
    10   image: plugins/docker
    11    settings:
    12    username: kevinbacon
    13    password: pa55word
    14    repo: foo/bar
  • Example configuration using build arguments:
    1  steps:
    2  - name: docker  
    3    image: plugins/docker
    4    settings:
    5     username: kevinbacon
    6     password: pa55word
    7     repo: foo/bar
    8    build_args:
    9      - HTTP_PROXY=http://yourproxy.com
  • Example configuration passing secrets as build arguments:
    1  steps:
    2   - name: build-image
    3     image: plugins/docker
    4     environment:
    5       TOKEN:
    6         from_secret: one_of_the_tokens
    7     settings:
    8       username: kevinbacon
    9       password: pa55word
    10      repo: foo/bar
    11      build_args_from_env:
    12        - TOKEN
  • Example configuration using alternate Dockerfile:
    1 steps:
    2 - name: docker  
    3   image: plugins/docker
    4   settings:
    5     username: kevinbacon
    6     password: pa55word
    7     repo: foo/bar
    8     dockerfile: path/to/Dockerfile
  • Example configuration using a custom registry:
    1 steps:
    2 - name: docker  
    3   image: plugins/docker
    4   settings:
    5     username: kevinbacon
    6     password: pa55word
    7     repo: index.company.com/foo/bar
    8     registry: index.company.com

Secrets

It is considered best practice to source sensitive configuration parameters from secrets. The following example demonstrates how you can source the username and password from secrets:

1 kind: pipeline
2 name: default
3 
4 steps:
5 - name: docker  
6   image: plugins/docker
7   settings:
8     username:
9       from_secret: docker_username
10    password:
11      from_secret: docker_password
12    repo: foo/bar
13    tags:
14    - latest

Autotag

The Docker plugin can be configured to automatically tag your images. When this feature is enabled and the event type is tag, the plugin will automatically tag the image using the standard major, minor, release convention. For example:

  • v1.0.0 produces docker tags 1, 1.0, 1.0.0
  • v1.0.0-rc.1 produces docker tags 1.0.0-rc.1

When the event type is push and the target branch is your default branch (e.g. master) the plugin will automatically tag the image as latest. All other event types and branches are ignored.

Example configuration:

1 steps:
2 - name: docker  
3   image: plugins/docker
4   settings:
5     repo: foo/bar
6     auto_tag: true
7     username: kevinbacon
8     password: pa55word

Example configuration with tag suffix:

1 steps:
2 - name: docker  
3   image: plugins/docker
4   settings:
5     repo: foo/bar
6     auto_tag: true
7     auto_tag_suffix: linux-amd64
8     username: kevinbacon
9     password: pa55word

Please note that auto-tagging is intentionally simple and opinionated. We are not accepting pull requests at this time to further customize the logic.

Parameters

  • registry
     authenticates to this registry
  • username
     authenticates with this username
  • password
     authenticates with this password
  • repo
     repository name for the image
  • tags
     repository tag for the image
  • dockerfile
     dockerfile to be used, defaults to Dockerfile
  • dry_run
     boolean if the docker image should be pushed at the end
  • purge
     boolean if cleanup of the docker image should be done at the end
  • context
     the context path to use, defaults to root of the git repo
  • target
     the build target to use, must be defined in the docker file
  • force_tag=false
     replace existing matched image tags
  • insecure=false
     enable insecure communication to this registry
  • mirror
     use a mirror registry instead of pulling images directly from the central Hub
  • bip=false
     use for pass bridge ip
  • custom_dns
     set custom dns servers for the container
  • custom_dns_search
     docker daemon dns search domains
  • storage_driver
     supports aufs, overlay or vfs drivers
  • storage_path
     docker daemon storage path
  • build_args
     pass custom arguments to docker build
  • build_args_from_env
     pass the envvars as custom arguments to docker build
  • auto_tag=false
     generate tag names automatically based on git branch and git tag
  • auto_tag_suffix
     generate tag names with this suffix
  • debug, launch_debug
     launch the docker daemon in verbose debug mode
  • mtu
     docker daemon custom mtu setting
  • ipv6
     docker daemon IPv6 networking
  • experimental
     docker daemon Experimental mode
  • daemon_off
     don’t start the docker daemon
  • cache_from
     images to consider as cache sources
  • squash
     squash the layers at build time
  • pull_image
     force pull base image at build time
  • compress
     compress the build context using gzip
  • custom_labels
     additional k=v labels
  • label_schema
     label-schema labels
  • email
     docker email
  • no_cache
     do not use cached intermediate containers
  • add_host
     additional host:IP mapping

Common Problems

Missing Username or Password

If the registry username or password are missing you will see the below entry in your pipeline logs. The most common root cause for this issue is incorrectly configuration secrets.

Registry credentials or Docker config not provided. Guest mode enabled.

Invalid Username or Password

If the registry username and password are invalid you will see the below entry in your pipeline logs. The most common root cause for this issue is copy / paste problems when creating secrets, such as newlines or special characters being accidentally copied with the secret string.

level=fatal msg="Error authenticating: exit status 1"

Insecure Registry

If the registry is self-hosted and if the registry uses plain http or self-signed certificates, the docker client will be unable to establish a secure connection to the registry. This will cause the docker login to fail with the following error:

level=fatal msg="Error authenticating: exit status 1"

This can be solved with the following plugin configuration:

1 steps:
2 - name: docker  
3   image: plugins/docker
4   settings:
5     repo: foo/bar
6     username: kevinbacon
7     password: pa55word
8     insecure: true

How did we do?