Supports checking, fetching, and pushing of images to Docker registries.
This resource is intended as a replacement for the Docker Image resource. Here are the key differences:
-
This resource is implemented in pure Go and does not use the Docker daemon or CLI. This makes it safer (no need for
privileged: true
), more efficient, and less error-prone (now that we're using Go APIs and not parsingdocker
CLI output). -
This resource has stronger test coverage.
-
This resource does not and will never support building - only registry image pushing/pulling. Building should instead be done with something like the
oci-build
task (or anything that can produce OCI image tarballs). -
A goal of this resource is to stay as focused and simple as possible. The Docker Image resource grew way too large and complicated. There are simply too many ways to build and publish Docker images. It will be easier to support many smaller resources + tasks rather than one huge interface.
-
repository
: Required. The name of the repository, e.g.alpine
. If using ecr you only need the repository name, not the full URI e.g.alpine
not012345678910.dkr.ecr.us-east-1.amazonaws.com/alpine
-
tag
: Optional. Defaultlatest
. The name of the tag to monitor and publish to. -
username
andpassword
: Optional. A username and password to use when authenticating to the registry. Must be specified for private repos or when usingput
. -
aws_access_key_id
: Optional. Default""
. The access key ID to use for authenticating with ECR. -
aws_secret_access_key
: Optional. Default""
. The secret access key to use for authenticating with ECR. -
aws_session_token
: Optional. Default""
. The session token to use for authenticating with STS credentials with ECR. -
aws_region
: Optional. Default""
. The region to use for accessing ECR. This is required if you are using ECR. This region will help determine the full repository URL you are accessing (e.g.,012345678910.dkr.ecr.us-east-1.amazonaws.com
) -
aws_role_arn
: Optional. Default""
. If set, then this role will be assumed before authenticating to ECR. -
debug
: Optional. Defaultfalse
. If set, progress bars will be disabled and debugging output will be printed instead. -
registry_mirror
: Optional.host
: Required. A hostname pointing to a Docker registry mirror service. Note that this is only used if no registry hostname prefix is specified in therepository
. If therepository
contains a registry hostname prefix -- such asmy-registry.com/foo/bar
-- theregistry_mirror
is ignored and the explicitly declared registry in therepository
value is used.username
andpassword
: Optional. A username and password to use when authenticating to the mirror.
-
content_trust
: Optional. Configuration about content trust.server
: Optional. URL for the notary server. (equal toDOCKER_CONTENT_TRUST_SERVER
)repository_key_id
: Required. Target key's ID used to sign the trusted collection, could be retrieved bynotary key list
repository_key
: Required. Target key used to sign the trusted collection.repository_passphrase
: Required. The passphrase of the signing/target key. (equal toDOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE
)tls_key
: Optional. Default""
TLS key for the notary server.tls_cert
: Optional. Default""
TLS certificate for the notary server.
Configure Docker Content Trust for use with the Docker Hub and Notary service by specifying the above source parameters as follows:
repository_key
should be set to the contents of the DCT key file located in your ~/.docker/trust/private directory.repository_key_id
should be set to the full key itself, which is also the filename of the key file mentioned above, without the .key extension.
Consider the following resource:
resources:
- name: trusted-image
type: registry-image
source:
repository: docker.io/foo/bar
username: ((registry_user))
password: ((registry_pass))
content_trust:
repository_key_id: ((registry_key_id))
repository_key: ((registry_key))
repository_passphrase: ((registry_passphrase))
Specify the values for these variables as shown in the following static variable file, or preferrably in a configured credential manager:
registry_user: jertel
registry_pass: my_docker_hub_token
registry_passphrase: my_dct_key_passphrase
registry_key_id: 1452a842871e529ffc2be29a012618e1b2a0e6984a89e92e34b5a0fc21a04cd
registry_key: |
-----BEGIN ENCRYPTED PRIVATE KEY-----
role: jertel
MIhsj2sd41fwaa...
-----END ENCRYPTED PRIVATE KEY-----
NOTE This configuration only applies to the out
action. check
& in
aren't impacted. Hence, it would be possible to check
or use in
to get unsigned images.
Reports the current digest that the registry has for the tag configured in
source
.
Fetches an image at a digest.
format
: Optional. Defaultrootfs
. The format to fetch as.skip_download
: Optional. Defaultfalse
. Skip downloading the image. Useful only to trigger a job without using the object.
The resource will produce the following files:
./digest
: A file containing the image's digest, e.g.sha256:...
../tag
: A file containing the tag fromsource
, e.g.latest
.
The remaining files depend on the configuration value for format
:
The rootfs
format will fetch and unpack the image for use by Concourse task
and resource type images.
This the default for the sake of brevity in pipelines and task configs.
In this format, the resource will produce the following files:
./rootfs/...
: the unpacked rootfs produced by the image../metadata.json
: the runtime information to propagate to Concourse.
The oci
format will fetch the image and write it to disk in OCI format. This
is analogous to running docker save
.
In this format, the resource will produce the following files:
./image.tar
: the OCI image tarball, suitable for passing todocker load
.
Uploads an image to the registry under the tag configured in source
.
If additional_tags
param is defined then the uploaded image will also be
tagged with each one of the values specified in that file.
The currently encouraged way to build these images is by using the
oci-build-task
.
image
: Required. The path to the OCI image tarball to upload. Expanded withfilepath.Glob
.additional_tags
: Optional. The path to a file with whitespace-separated list of tag values to tag the image with (in addition to the tag configured insource
).
Images used as image resources in tasks are called anonymous resources. Anonymous resources can specify a version, which is the image digest. For example:
image_resource:
type: docker-image
source:
repository: golang
version:
digest: 'sha256:5f640aeb8b78e9876546a9d06b928d2ad0c6e51900bcba10ff4e12dc57f6f265'
This is useful when the registry image does not have tags, or when the tags are going to be re-used.
- golang is required - version 1.11.x or above is required for go mod to work
- docker is required - version 17.06.x is tested; earlier versions may also work.
- go mod is used for dependency management of the golang packages.
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 registry-image-resource -f dockerfiles/alpine/Dockerfile .
docker build -t registry-image-resource -f dockerfiles/ubuntu/Dockerfile .
The integration requires 2 docker repos, one private and one public. The docker build
step requires setting --build-args
so the integration will run.
Run the tests with the following command:
docker build . -t registry-image-resource -f dockerfiles/alpine/Dockerfile \
--build-arg DOCKER_PRIVATE_USERNAME="some-username" \
--build-arg DOCKER_PRIVATE_PASSWORD="some-password" \
--build-arg DOCKER_PRIVATE_REPO="some/repo" \
--build-arg DOCKER_PUSH_USERNAME="some-username" \
--build-arg DOCKER_PUSH_PASSWORD="some-password" \
--build-arg DOCKER_PUSH_REPO="some/repo"
docker build . -t registry-image-resource -f dockerfiles/ubuntu/Dockerfile \
--build-arg DOCKER_PRIVATE_USERNAME="some-username" \
--build-arg DOCKER_PRIVATE_PASSWORD="some-password" \
--build-arg DOCKER_PRIVATE_REPO="some/repo" \
--build-arg DOCKER_PUSH_USERNAME="some-username" \
--build-arg DOCKER_PUSH_PASSWORD="some-password" \
--build-arg DOCKER_PUSH_REPO="some/repo"
Please make all pull requests to the master
branch and ensure tests pass
locally.