DOCS.md

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|<id>[=<socket>|<key>[,<key>]])	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: