Tracks and builds Docker images.
Note: docker registry must be v2.
-
repository
: Required. The name of the repository, e.g.concourse/docker-image-resource
.Note: When configuring a private registry using a non-root CA, you must include the port (e.g. :443 or :5000) even though the docker CLI does not require it.
-
tag
: Optional. The tag to track. Defaults tolatest
. -
username
: Optional. The username to authenticate with when pushing. -
password
: Optional. The password to use when authenticating. -
aws_access_key_id
: Optional. AWS access key to use for acquiring ECR credentials. -
aws_secret_access_key
: Optional. AWS secret key to use for acquiring ECR credentials. -
aws_session_token
: Optional. AWS session token (assumed role) to use for acquiring ECR credentials. -
insecure_registries
: Optional. An array of CIDRs orhost:port
addresses to whitelist for insecure access (eitherhttp
or unverifiedhttps
). This option overrides any entries inca_certs
with the same address. -
registry_mirror
: Optional. A URL pointing to a docker registry mirror service. -
ca_certs
: Optional. An array of objects with the following format:ca_certs: - domain: example.com:443 cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- - domain: 10.244.6.2:443 cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
Each entry specifies the x509 CA certificate for the trusted docker registry residing at the specified domain. This is used to validate the certificate of the docker registry when the registry's certificate is signed by a custom authority (or itself).
The domain should match the first component of
repository
, including the port. If the registry specified inrepository
does not use a custom cert, addingca_certs
will break the check script. This option is overridden by entries ininsecure_registries
with the same address or a matching CIDR. -
client_certs
: Optional. An array of objects with the following format:client_certs: - domain: example.com cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- key: | -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY----- - domain: 10.244.6.2 cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- key: | -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
Each entry specifies the x509 certificate and key to use for authenticating against the docker registry residing at the specified domain. The domain should match the first component of
repository
. -
max_concurrent_downloads
: Optional. Maximum concurrent downloads.Limits the number of concurrent download threads.
-
max_concurrent_uploads
: Optional. Maximum concurrent uploads.Limits the number of concurrent upload threads.
The current image digest is fetched from the registry for the given tag of the repository.
Pulls down the repository image by the requested digest.
The following files will be placed in the destination:
/image
: Ifsave
istrue
, thedocker save
d image will be provided here./repository
: The name of the repository that was fetched./tag
: The tag of the repository that was fetched./image-id
: The fetched image ID./digest
: The fetched image digest./rootfs.tar
: Ifrootfs
istrue
, the contents of the image will be provided here./metadata.json
: Collects custom metadata. Contains the containerenv
variables and runninguser
./docker_inspect.json
: Output of thedocker inspect
onimage_id
. Useful if collectingLABEL
metadata from your image.
save
: Optional. Place adocker save
d image in the destination.rootfs
: Optional. Place a.tar
file of the image in the destination.skip_download
: Optional. Skipdocker pull
of image. Artifacts based on the image will not be present.
As with all concourse resources, to modify params of the implicit get
step after each put
step you may also set these parameters under a put
get_params
. For example:
put: foo
params: {...}
get_params: {skip_download: true}
Push a Docker image to the source's repository and tag. The resulting version is the image's digest.
-
additional_tags
: Optional. Path to a file containing a whitespace-separated list of tags. The Docker build will additionally be pushed with those tags. -
build
: Optional. The path of a directory containing aDockerfile
to build. -
build_args
: Optional. A map of Docker build-time variables. These will be available as environment variables during the Docker build.While not stored in the image layers, they are stored in image metadata and so it is recommend to avoid using these to pass secrets into the build context. In multi-stage builds
ARG
s in earlier stages will not be copied to the later stages, or in the metadata of the final stage.The build metadata environment variables provided by Concourse will be expanded in the values (the syntax is
$SOME_ENVVAR
or${SOME_ENVVAR}
).Example:
build_args: DO_THING: true HOW_MANY_THINGS: 2 EMAIL: [email protected] CI_BUILD_ID: concourse-$BUILD_ID
-
build_args_file
: Optional. Path to a JSON file containing Docker build-time variables.Example file contents:
{ "EMAIL": "[email protected]", "HOW_MANY_THINGS": 1, "DO_THING": false }
-
cache
: Optional. Defaultfalse
. When thebuild
parameter is set, first pullimage:tag
from the Docker registry (so as to use cached intermediate images when building). This will cause the resource to fail if it is set totrue
and the image does not exist yet. -
cache_from
: Optional. An array of images to consider as cache, in order to reuse build steps from a previous build. The array elements are paths to directories generated by aget
step withsave: true
. This has a similar aim ofcache
, but it loads the images from disk instead of pulling them from the network, so that Concourse resource caching can be used. It also allows more than one image to be specified, which is useful for multi-stage Dockerfiles. If you want to cache an image used in aFROM
step, you should put it inload_bases
instead. -
cache_tag
: Optional. Defaulttag
. The specific tag to pull before building whencache
parameter is set. Instead of pulling the same tag that's going to be built, this allows picking a different tag likelatest
or the previous version. This will cause the resource to fail if it is set to a tag that does not exist yet. -
dockerfile
: Optional. The path of theDockerfile
in the directory if it's not at the root of the directory. -
import_file
: Optional. A path to a file todocker import
and then push. -
labels
: Optional. A map of labels that will be added to the image.Example:
labels: commit: b4d4823 version: 1.0.3
-
labels_file
: Optional. Path to a JSON file containing the image labels.Example file contents:
{ "commit": "b4d4823", "version": "1.0.3" }
-
load
: Optional. The path of a directory containing an image that was fetched using this same resource type withsave: true
. -
load_base
: Optional. A path to a directory containing an image todocker load
before runningdocker build
. The directory must haveimage
,image-id
,repository
, andtag
present, i.e. the tree produced by/in
. -
load_bases
: Optional. Same asload_base
, but takes an array to load multiple images. -
load_file
: Optional. A path to a file todocker load
and then push. Requiresload_repository
. -
load_repository
: Optional. The repository of the image loaded fromload_file
. -
load_tag
: Optional. Defaultlatest
. The tag of image loaded fromload_file
-
pull_repository
: Optional. DEPRECATED. Useget
andload
instead. A path to a repository to pull down, and then push to this resource. -
pull_tag
: Optional. DEPRECATED. Useget
andload
instead. Defaultlatest
. The tag of the repository to pull down viapull_repository
. -
tag
: DEPRECATED - Usetag_file
instead -
tag_file
: Optional. The value should be a path to a file containing the name of the tag. -
tag_as_latest
: Optional. Defaultfalse
. If true, the pushed image will be tagged aslatest
in addition to whatever other tag was specified. -
tag_prefix
: Optional. If specified, the tag read from the file will be prepended with this string. This is useful for addingv
in front of version numbers. -
target_name
: Optional. Specify the name of the target build stage. Only supported for multi-stage Docker builds
resources:
- name: git-resource
type: git
source: # ...
- name: git-resource-image
type: docker-image
source:
repository: concourse/git-resource
username: username
password: password
- name: git-resource-rootfs
type: s3
source: # ...
jobs:
- name: build-rootfs
plan:
- get: git-resource
- put: git-resource-image
params: {build: git-resource}
get_params: {rootfs: true}
- put: git-resource-rootfs
params: {file: git-resource-image/rootfs.tar}
- golang is required - version 1.9.x is tested; earlier versions may also work.
- docker is required - version 17.06.x is tested; earlier versions may also work.
The tests have been embedded with the Dockerfile
; ensuring that the testing
environment is consistent across any docker
enabled platform. When the docker
image builds, the test are run inside the docker container, on failure they
will stop the build.
Run the tests with the following commands for both alpine
and ubuntu
images:
docker build -t docker-image-resource -f dockerfiles/alpine/Dockerfile .
docker build -t docker-image-resource -f dockerfiles/ubuntu/Dockerfile .
To use the newly built image, push it to a docker registry that's accessible to Concourse and configure your pipeline to use it:
resource_types:
- name: docker-image-resource
type: docker-image
privileged: true
source:
repository: example.com:5000/docker-image-resource
tag: latest
resources:
- name: some-image
type: docker-image-resource
...
Please make all pull requests to the master
branch and ensure tests pass
locally.