Docker

Description

This plugin enables you to build and publish Docker images in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-docker

Registry: https://hub.docker.com/r/target/vela-docker

Usage

NOTE:
Users should refrain from using latest as the tag for the Docker image.
It is recommended to use a semantically versioned tag instead.

Samples of building and publishing an image:

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
    parameters:
      registry: index.docker.io
      tags: [ index.docker.io/octocat/hello-world:latest ]

NOTE: The two above samples are functionally equivalent.

Sample of building an image without publishing:

steps:
  - name: publish hello world
    image: target/vela-docker:latest
    pull: always
    parameters:
+     dry_run: true
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]

Sample of building and publishing an image with custom tags:

steps:
  - name: publish hello world
    image: target/vela-docker:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: octocat/hello-world
-     tags: [ latest ]
+     tags: 
+       - latest
+       - octocat/hello-world:1
+       - index.docker.io/octocat/hello-world:foobar

Sample of building and publishing an image with build arguments:

steps:
  - name: publish hello world
    image: target/vela-docker:latest
    pull: always
    parameters:
+     build_args:
+       - FOO=bar
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]

Sample of building and publishing an image with image caching:

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
    parameters:
+     cache_from: index.docker.io/octocat/hello-world
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]

Sample of building and publishing with custom daemon settings:

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
    parameters:
+     daemon: 
+       registry_mirrors: mirror.index.docker.io
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]

Secrets

NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.

Internal

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
+   secrets: [ docker_username, docker_password ]
    parameters:
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]
-     username: octocat
-     password: superSecretPassword

This example will add the secrets to the publish_hello-world step as environment variables:
DOCKER_USERNAME=<value>
DOCKER_PASSWORD=<value>

External

The plugin accepts the following files for authentication:

Parameter	Volume Configuration
`password`	`/vela/parameters/docker/password`, `/vela/secrets/docker/password`
`username`	`/vela/parameters/docker/username`, `/vela/secrets/docker/username`

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]
-     username: octocat
-     password: superSecretPassword

This example will read the secret values in the volume stored at /vela/secrets/

Parameters

NOTE:
The plugin supports reading all parameters via environment variables or files.
Any values set from a file take precedence over values set from the environment.
By default build kit is on; it can be turned off by setting DOCKER_BUILDKIT=0 in the environment.
The key.key syntax signifies a new yaml object within the definition.

The following parameters are used to configure the image:

Name	Description	Required	Default	Environment Variables
`add_hosts`	set a custom host-to-IP mapping - format (host:ip)	`false`	N/A	`PARAMETER_ADD_HOSTS` `DOCKER_ADD_HOSTS`
`build_args`	set variables to pass to the image at build-time	`false`	N/A	`PARAMETER_BUILD_ARGS` `DOCKER_BUILD_ARGS`
`cache_from`	set of images to consider as cache sources	`false`	N/A	`PARAMETER_CACHE_FROM` `DOCKER_CACHE_FROM`
`cgroup_parent`	set a parent cgroup for the container	`false`	N/A	`PARAMETER_CGROUP_PARENT` `DOCKER_CGROUP_PARENT`
`compress`	enable compressing the build context using gzip	`false`	`false`	`PARAMETER_COMPRESS` `DOCKER_COMPRESS`
`context`	set of files and/or directory to build the image from	`true`	`.`	`PARAMETER_CONTEXT` `DOCKER_CONTEXT`
`cpu`	set the cpu parameter, see cpu settings below	`false`	N/A	`PARAMETER_CPU` `DOCKER_CPU`
`daemon`	set the daemon parameter, see daemon settings below	`false`	N/A	`PARAMETER_DAEMON` `DOCKER_DAEMON`
`disable_content_trust`	enable skipping verification of the image	`false`	`true`	`PARAMETER_DISABLE_CONTENT_TRUST` `DOCKER_DISABLE_CONTENT_TRUST`
`dry_run`	enable building the image without publishing	`false`	`false`	`PARAMETER_DRY_RUN` `DOCKER_DRY_RUN`
`file`	set the name of the Dockerfile	`false`	N/A	`PARAMETER_FILE` `DOCKER_FILE`
`force_rm`	enable always removing the intermediate containers after a successful build	`false`	`false`	`PARAMETER_FORCE_RM` `DOCKER_FORCE_RM`
`image_id_file`	set the file to write the image ID to	`false`	N/A	`PARAMETER_IMAGE_ID_FILE` `DOCKER_IMAGE_ID_FILE`
`isolation`	set container isolation technology	`false`	N/A	`PARAMETER_ISOLATION` `DOCKER_ISOLATION`
`labels`	set metadata for an image	`false`	N/A	`PARAMETER_LABELS` `DOCKER_LABELS`
`log_level`	set the log level for the plugin	`true`	`info`	`PARAMETER_LOG_LEVEL` `DOCKER_LOG_LEVEL`
`memory`	set memory limit	`false`	N/A	`PARAMETER_MEMORY` `DOCKER_MEMORY`
`memory_swaps`	set the swap limit equal to memory plus swap: ‘-1’ to enable unlimited swap	`false`	N/A	`PARAMETER_MEMORY_SWAPS` `DOCKER_MEMORY_SWAPS`
`network`	set the networking mode for the RUN instructions during build	`false`	N/A	`PARAMETER_NETWORK` `DOCKER_NETWORK`
`no_cache`	disable caching when building the image	`false`	`false`	`PARAMETER_NO_CACHE` `DOCKER_NO_CACHE`
`output`	set the output destination - format (type=local,dest=path)	`false`	N/A	`PARAMETER_OUTPUTS` `DOCKER_OUTPUTS`
`password`	set password for communication with the registry	`true`	N/A	`PARAMETER_PASSWORD` `DOCKER_PASSWORD`
`platform`	set a platform if server is multi-platform capable	`false`	N/A	`PARAMETER_PLATFORM` `DOCKER_PLATFORM`
`progress`	set type of progress output - options (auto\|plain\|tty)	`false`	N/A	`PARAMETER_PROGRESS` `DOCKER_PROGRESS`
`pull`	enable always attempting to pull a newer version of the image	`false`	`false`	`PARAMETER_PULL` `DOCKER_PULL`
`quiet`	enable suppressing the build output and print image ID on success	`false`	`false`	`PARAMETER_QUIET` `DOCKER_QUIET`
`registry`	set Docker registry address to communicate with	`true`	`index.docker.io`	`PARAMETER_REGISTRY` `DOCKER_REGISTRY`
`remove`	enable removing the intermediate containers after a successful build	`false`	`true`	`PARAMETER_REMOVE` `DOCKER_REMOVE`
`repo`	set Docker repository for the image	`false`	N/A	`PARAMETER_REPO` `DOCKER_REPO`
`secret`	set secret file to expose to the build (only if BuildKit enabled) - format (id=mysecret,src=/local/secret)	`false`	N/A	`PARAMETER_SECRETS` `DOCKER_SECRETS`
`security_opts`	set options for security	`false`	N/A	`PARAMETER_SECURITY_OPTS` `DOCKER_SECURITY_OPTS`
`shm_sizes`	set the size of /dev/shm	`false`	N/A	`PARAMETER_SHM_SIZES` `DOCKER_SHM_SIZES`
`squash`	enable squashing newly built layers into a single new layer	`false`	`false`	`PARAMETER_SQUASH` `DOCKER_SQUASH`
`ssh_components`	set SSH agent socket or keys to expose to the build (only if BuildKit enabled) - format (default\|[=\|[,]])	`false`	N/A	`PARAMETER_SSH_COMPONENTS` `DOCKER_SSH_COMPONENTS`
`stream`	enable stream attaching to the server to negotiate build context	`false`	`false`	`PARAMETER_STREAM` `DOCKER_STREAM`
`tags`	set the tags for the Docker image - format (name:tag)	`true`	N/A	`PARAMETER_TAGS` `DOCKER_TAGS`
`target`	set the target build stage to build	`false`	N/A	`PARAMETER_TARGET` `DOCKER_TARGET`
`ulimits`	set options for ulimits	`false`	N/A	`PARAMETER_ULIMITS` `DOCKER_ULIMITS`
`username`	set user name for communication with the registry	`true`	N/A	`PARAMETER_USERNAME` `DOCKER_USERNAME`

CPU

The following settings are used to configure the cpu parameter:

Name	Description	Required	Default
`period`	set limit on the CPU CFS (Completely Fair Scheduler) period	`false`	N/A
`quota`	set limit on the CPU CFS (Completely Fair Scheduler) quota	`false`	N/A
`shares`	set CPU shares (relative weight)	`false`	N/A
`set_cpus`	set CPUs in which to allow execution (0-3, 0,1)	`false`	N/A
`set_mems`	set MEMs in which to allow execution (0-3, 0,1)	`false`	N/A

Daemon

The following settings are used to configure the daemon parameter:

Name	Description	Required	Default
`bip`	set a network bridge IP	`false`	N/A
`dns`	set the DNS settings, see dns settings below	`false`	N/A
`experimental`	enable experimental features	`false`	N/A
`insecure_registries`	set the insecure Docker registries	`false`	N/A
`ipv6`	enable IPv6 networking	`false`	N/A
`mtu`	set the network MTU for the contain	`false`	N/A
`registry_mirrors`	set the Docker registry mirrors	`false`	N/A
`storage`	set the storage settings, see storage settings below	`false`	N/A

DNS

The following settings are used to configure the dns daemon setting:

Name	Description	Required	Default
`servers`	set the DNS nameservers	`false`	N/A
`searches`	set the DNS search domains	`false`	N/A

Storage

The following settings are used to configure the storage daemon setting:

Name	Description	Required	Default
`driver`	set the storage driver for the daemon	`false`	N/A
`opts`	set the storage options for the daemon	`false`	N/A

Template

COMING SOON!

Troubleshooting

You can start troubleshooting this plugin by tuning the level of logs being displayed:

steps:
  - name: publish_hello-world
    image: target/vela-docker:latest
    pull: always
    parameters:
      registry: index.docker.io
      repo: octocat/hello-world
      tags: [ latest ]
+     log_level: trace

Below are a list of common problems and how to solve them:

Last modified March 8, 2022: feat(openssh): Add SSH & SCP documentation (#287) (fe29de8f)