palantir/gradle-docker
Fork: 163 Star: 724 (更新于 1970-01-01 00:00:00)
license: Apache-2.0
Language: Groovy .
a Gradle plugin for orchestrating docker builds and pushes.
最后发布版本: 0.35.0 ( 2023-04-03 16:51:41)
Docker Gradle Plugin
Disclaimer: This Repo is now Defunct
- This repo is on life support only - although we will keep it working, no new features are accepted;
- It is no longer used internally at Palantir.
Docker Plugin
This repository provides three Gradle plugins for working with Docker containers:
-
com.palantir.docker
: add basic tasks for building and pushing docker images based on a simple configuration block that specifies the container name, the Dockerfile, task dependencies, and any additional file resources required for the Docker build. -
com.palantir.docker-compose
: adds a task for populating placeholders in a docker-compose template file with image versions resolved from dependencies. -
com.palantir.docker-run
: adds tasks for starting, stopping, statusing and cleaning up a named container based on a specified image
Apply the plugin using standard gradle convention:
plugins {
id 'com.palantir.docker' version '<version>'
}
Set the container name, and then optionally specify a Dockerfile, any task dependencies and file resources required for the Docker build. This plugin will automatically include outputs of task dependencies in the Docker build context.
Docker Configuration Parameters
-
name
the name to use for this container, may include a tag -
tags
(deprecated) (optional) an argument list of tags to create; any tag inname
will be stripped before applying a specific tag; defaults to the empty set -
tag
(optional) a tag to create with a specified task name -
dockerfile
(optional) the dockerfile to use for building the image; defaults toproject.file('Dockerfile')
and must be a file object -
files
(optional) an argument list of files to be included in the Docker build context, evaluated perProject#files
. For example,files tasks.distTar.outputs
adds the TAR/TGZ file produced by thedistTar
tasks, andfiles tasks.distTar.outputs, 'my-file.txt'
adds the archive in addition to filemy-file.txt
from the project root directory. The specified files are collected in a Gradle CopySpec which may be copiedinto
the Docker build context directory. The underlying CopySpec may also be used to copy entire directories into the build context. The following example adds the aforementioned archive and text file to the CopySpec, uses the CopySpec to add all filesfrom
src/myDir
into the CopySpec, then finally executes the copy into the directorymyDir
in docker build context.
docker {
files tasks.distTar.outputs, 'my-file.txt'
copySpec.from("src/myDir").into("myDir")
}
The final structure will be:
build/
docker/
myDir/
my-file.txt
// contents of task.distTar.outputs
// files from src/myDir
-
buildArgs
(optional) an argument map of string to string which will set --build-arg arguments to the docker build command; defaults to empty, which results in no --build-arg parameters -
labels
(optional) a map of string to string which will set --label arguments to the docker build command; defaults to empty, which results in no labels applied. -
pull
(optional) a boolean argument which defines whether Docker should attempt to pull a newer version of the base image before building; defaults tofalse
-
noCache
(optional) a boolean argument which defines whether Docker build should add the option --no-cache, so that it rebuilds the whole image from scratch; defaults tofalse
-
buildx
(optional) a boolean argument which defines whether Docker build should use buildx for cross platform builds; defaults tofalse
-
platform
(optional) a list of strings argument which defines which platforms buildx should target; defaults to empty -
builder
(optional) a string argument which defines which builder buildx should use; defaults tonull
-
load
(optional) a boolean argument which defines whether Docker buildx builder should add --load flag, loading the image into the local repository; defaults tofalse
-
push
(optional) a boolean argument which defines whether Docker buildx builder should add --push flag, pushing the image into the remote registry; defaults tofalse
To build a docker container, run the docker
task. To push that container to a
docker repository, run the dockerPush
task.
Tag and Push tasks for each tag will be generated for each provided tag
and tags
entry.
Examples
Simplest configuration:
docker {
name 'hub.docker.com/username/my-app:version'
}
Canonical configuration for building a Docker image from a distribution archive:
// Assumes that Gradle "distribution" plugin is applied
docker {
name 'hub.docker.com/username/my-app:version'
files tasks.distTar.outputs // adds resulting *.tgz to the build context
}
Configuration specifying all parameters:
docker {
name 'hub.docker.com/username/my-app:version'
tags 'latest' // deprecated, use 'tag'
tag 'myRegistry', 'my.registry.com/username/my-app:version'
dockerfile file('Dockerfile')
files tasks.distTar.outputs, 'file1.txt', 'file2.txt'
buildArgs([BUILD_VERSION: 'version'])
labels(['key': 'value'])
pull true
noCache true
}
Managing Docker image dependencies
The com.palantir.docker
and com.palantir.docker-compose
plugins provide
functionality to declare and resolve version-aware dependencies between docker
images. The primary use-case is to generate docker-compose.yml
files whose
image versions are mutually compatible and up-to-date in cases where multiple
images depend on the existence of the same Dockerized service.
Specifying and publishing dependencies on Docker images
The docker
plugin adds a docker
Gradle component and a docker
Gradle
configuration that can be used to specify and publish dependencies on other
Docker containers.
Example
plugins {
id 'maven-publish'
id 'com.palantir.docker'
}
...
dependencies {
docker 'foogroup:barmodule:0.1.2'
docker project(":someSubProject")
}
publishing {
publications {
dockerPublication(MavenPublication) {
from components.docker
artifactId project.name + "-docker"
}
}
}
The above configuration adds a Maven publication that specifies dependencies on
barmodule
and the someSubProject
Gradle sub project. The resulting POM file
has two dependency
entries, one for each dependency. Each project can declare
its dependencies on other docker images and publish an artifact advertising
those dependencies.
Generating docker-compose.yml files from dependencies
The com.palantir.docker-compose
plugin uses the transitive dependencies of the
docker
configuration to populate a docker-compose.yml.template
file with the
image versions specified by this project and all its transitive dependencies.
The plugin uses standard Maven/Ivy machanism for declaring and resolving
dependencies.
The generateDockerCompose
task generates a docker-compose.yml
file from a
user-defined template by replacing each version variable by the concrete version
declared by the transitive dependencies of the docker configuration. The task
performs two operations: First, it generates a mapping group:name --> version
from the dependencies of the docker
configuration (see above). Second, it
replaces all occurrences of version variables of the form {{group:name}}
in
the docker-compose.yml.template
file by the resolved versions and writes the
resulting file as docker-compose.yml
.
The docker-compose
plugin also provides a dockerComposeUp
task that starts
the docker images specified in the dockerComposeFile
in detached mode.
You can also use the dockerComposeDown
task to stop the containers.
Example
Assume a docker-compose.yml.template
as follows:
myservice:
image: 'repository/myservice:latest'
otherservice:
image: 'repository/otherservice:{{othergroup:otherservice}}'
build.gradle
declares a dependency on a docker image published as
'othergroup:otherservice' in version 0.1.2:
plugins {
id 'com.palantir.docker-compose'
}
dependencies {
docker 'othergroup:otherservice:0.1.2'
}
The generateDockerCompose
task creates a docker-compose.yml
as follows:
myservice:
image: 'repository/myservice:latest'
otherservice:
image: 'repository/otherservice:0.1.2'
The generateDockerCompose
task fails if the template file contains variables
that cannot get resolved using the provided docker
dependencies. Version
conflicts between transitive dependencies of the same artifact are handled with
the standard Gradle semantics: each artifact is resolved to the highest declared
version.
Configuring file locations
The template and generated file locations are customizable through the
dockerCompose
extension:
dockerCompose {
template 'my-template.yml'
dockerComposeFile 'my-docker-compose.yml'
}
Docker Run Plugin
Apply the plugin using standard gradle convention:
plugins {
id 'com.palantir.docker-run' version '<version>'
}
Use the dockerRun
configuration block to configure the name, image and optional
command to execute for the dockerRun
tasks:
dockerRun {
name 'my-container'
image 'busybox'
volumes 'hostvolume': '/containervolume'
ports '7080:5000'
daemonize true
env 'MYVAR1': 'MYVALUE1', 'MYVAR2': 'MYVALUE2'
command 'sleep', '100'
arguments '--hostname=custom', '-P'
}
Docker Run Configuration Parameters
-
name
the name to use for this container, may include a tag. -
image
the name of the image to use. -
volumes
optional map of volumes to mount in the container. The key is the path to the host volume, resolved usingproject.file()
. The value is the exposed container volume path. -
ports
optional mappinglocal:container
of local port to container port. -
env
optional map of environment variables to supply to the running container. These must be exposed in the Dockerfile withENV
instructions. -
daemonize
defaults to true to daemonize the container after starting. However if your container runs a command and exits, you can set this to false. -
ignoreExitValue
(optional) to ignore the exit code returned from the execution of the docker command; defaults tofalse
-
clean
(optional) a boolean argument which adds--rm
to thedocker run
command to ensure that containers are cleaned up after running; defaults tofalse
-
command
the command to run. -
arguments
additional arguments to be passed into the docker run command. Please see https://docs.docker.com/engine/reference/run/ for possible values.
Tasks
-
Docker
-
docker
: build a docker image with the specified name and Dockerfile -
dockerTag
: tag the docker image with all specified tags -
dockerTag<tag>
: tag the docker image with<tag>
-
dockerPush
: push the specified image to a docker repository -
dockerPush<tag>
: push the<tag>
docker image to a docker repository -
dockerTagsPush
: push all tagged docker images to a docker repository -
dockerPrepare
: prepare to build a docker image by copying dependent task outputs, referenced files, anddockerfile
into a temporary directory -
dockerClean
: remove temporary directory associated with the docker build -
dockerfileZip
: builds a ZIP file containing the configured Dockerfile
-
-
Docker Compose
-
generateDockerCompose
: Populates a docker-compose file template with image versions declared by dependencies -
dockerComposeUp
: Brings up services defined indockerComposeFile
in detacted state -
dockerComposeDown
: Stops services defined indockerComposeFile
-
-
Docker Run
-
dockerRun
: run the specified image with the specified name -
dockerStop
: stop the running container -
dockerRunStatus
: indicate the run status of the container -
dockerRemoveContainer
: remove the container
-
License
This plugin is made available under the Apache 2.0 License.
Contributing
Contributions to this project must follow the contribution guide.
最近版本更新:(数据更新于 1970-01-01 00:00:00)
2023-04-03 16:51:41 0.35.0
2022-06-24 00:15:37 0.34.0
2022-04-07 17:42:00 0.33.0
2022-01-04 22:00:28 0.32.0
2021-11-23 23:11:44 0.31.0
2021-11-04 04:01:29 0.31.0-rc1
2021-09-29 20:07:52 0.30.0
2021-09-24 20:44:59 0.29.0
2021-08-13 22:18:48 0.28.0
2021-07-16 19:19:28 0.27.0
主题(topics):
docker, gradle, octo-correct-managed
palantir/gradle-docker同语言 Groovy最近更新仓库
2024-10-31 23:28:37 gradle/gradle
2023-07-15 08:08:41 google/protobuf-gradle-plugin
2022-09-09 20:01:49 researchgate/gradle-release
2016-08-25 02:42:24 okjsp/okky
1970-01-01 00:00:00 paraujof/springio
1970-01-01 00:00:00 thilko/gradle-springdoc-plugin