docker plugin

docker - stage files from Docker images

Usage:

# Specify the docker source kind
kind: docker

# Specify the registry endpoint, defaults to Docker Hub (optional)
registry-url: https://registry.hub.docker.com

# Image path
image: library/alpine

# Alternatively, you can specify a full url, the registry endpoint
# is assumed to be at the root of the domain
# url: https://registry.hub.docker.com/library/alpine

# Image tag to follow (optional)
track: latest

# Specify the digest of the exact image to use (required)
ref: 6c9f6f68a131ec6381da82f2bff978083ed7f4f7991d931bfa767b7965ebc94b

# Some images are built for multiple platforms. When tracking a tag, we
# will choose which image to use based on these settings. Default values
# are chosen based on the output of `uname -m` and `uname -s`, but you
# can override them.
#
# architecture: arm64
# os: linux
#
# **Since**: 2.0.1

# Specify the version to be reported as the *guess_version* when reporting
# SourceInfo
#
# Since: 2.5
#
version: 1.2

Note that Docker images may contain device nodes. BuildStream elements cannot contain device nodes so those will be dropped. Any regular files in the /dev directory will also be dropped.

See built-in functionality doumentation for details on common configuration options for sources.

Reporting SourceInfo

The docker source reports the URL of the docker registry as the url.

Further, the docker source reports the SourceInfoMedium.OCI_IMAGE medium and the SourceVersionType.OCI_DIGEST version_type, for which it reports the content digest of the docker image as the version.

Additionally, the docker source reports the docker image name through the image-name key of the extra_data.

As such, after removing the scheme from the URL (i.e. remove https://) the same docker image can be obtained by calling:

docker pull <url-without-scheme>/<image-name>@<version>

Since the docker source does not have any way to guess what tag is associated to the digest, or what release version that would mean; the docker source exposes the version configuration attribute to allow explicit specification of the guess_version.