##// END OF EJS Templates
implab » gradle-container-plugin
RSS
More documentation, TagImage task supports multiple tags, set COMPOSE_PROJECT_NAME to project.group by default
cin -
r14:ab28d6aa054e v1.2.1 default
parent child
Show More
Show file before | Show file after | Hide comments
@@ -0,0 +1,57
1 # Creating bundle from images
2
3 ## NAME
4
5 Save set of images to the single archive.
6
7 ## SYNOPSIS
8
9 ```gradle
10 plugins {
11 // task types and base extension
12 id "org.implab.gradle-container-base"
13 }
14
15 container {
16 cliCmd = "podman"
17 }
18
19 // create configuration
20 configurations {
21 bundleImages {
22 canBeResolved = true
23 canBeConsumed = false
24 }
25 }
26
27 // add dependencies to the project
28 dependencies {
29 bundleImages project(":images:foo"), project(":images:bar")
30 }
31
32 // create task to export bundle
33 task bundle(type: SaveImage) {
34 // add image refs from artifacts
35 imageRefs configurations.bundleImages
36
37 // add image name
38 exportImages.add "nginx:latest"
39 }
40 ```
41
42 ## DESCRIPTION
43
44 To create an archive with images the task of type `SaveImage` can be used. This
45 task has the following properties:
46
47 | Property | Description |
48 |-|-|
49 | `archiveFileName` | The file name of the bundle archive, defaults to `{archiveBaseName}-{archiveVersion}-{archiveClassifier}.{archiveExtension}`.|
50 | `archiveBaseName` | The base name of the archive, defaults to `{project.group}-{project.name}`. |
51 | `archiveVersion` | The archive version, defaults to `{project.version}`. |
52 | `exportImages` | A set of image names to include in the bundle. |
53
54 | Method | Description |
55 |-|-|
56 | `imageRefs(FileCollection)` | Adds a set of files with image refs to add to the bundle. |
57 | `imageRef(File)` | Adds an image name from the file with image reference. |
Show file before | Show file after | Hide comments
@@ -0,0 +1,148
1 # Compose project
2
3 ## NAME
4
5 `org.implab.gradle-container-compose` - docker compose project.
6
7 ## SYNOPSIS
8
9 ```gradle
10 plugins {
11 id "org.implab.gradle-container-compose"
12 }
13
14 dependencies {
15 composeImages project(":images:foo") {
16 ext {
17 // imageName from :images:foo will be written to .env as FOO_IMAGE var
18 composeVar = "FOO_IMAGE"
19 }
20 }
21 }
22
23 writeEnv {
24 // write additional variables to .env
25 env "DEBUG_JAVA" put "yes"
26
27 // set compose name, this variable is set to that value by default
28 env "COMPOSE_PROJECT_NAME" put project.group
29 }
30
31 // base container extension
32 container {
33 cliCmd = "podman"
34 }
35
36 // compose parameters
37 compose {
38 // add compose profiles
39 profiles.add("dev")
40
41 // set compose file name
42 // defaults to compose.yaml
43 composeFileName = "docker-compose.yaml"
44 }
45
46 ```
47
48 ## DESCRIPTION
49
50 This plugin creates a set of conventional tasks to prepare and start compose
51 project. This can be used to create and run sandbox.
52
53 These tasks are:
54
55 * `build` - prepares the context for the compose file, depends on `processResources`
56 and `writeEnv` tasks.
57 * `up` - invokes `compose up -d` in the built context and starts up the project
58 in the background.
59 * `stop` - invokes `compose stop` and stops the projects.
60 * `rm` - invokes `compose rm` and removes containers, by default temporary volumes
61 are removed with containers.
62 * `clean` - cleanups the build directory and removes built context.
63
64 Special configuration `composeImages` should be used to add a dependencies to the
65 images needed by this project. The dependencies must provide a single artifact
66 a json file containing `tag` property. This configuration well be resolved and
67 tag for each dependency will be stored in the environment variable specified with
68 `composeVar` property.
69
70 ```gradle
71 configuration {
72 composeImages file("nginx.json") {
73 ext {
74 composeVar = "NGINX_IMAGE"
75 }
76 }
77 composeImage project(":images:foo") {
78 ext {
79 composeVar = "FOO_IMAGE"
80 }
81 }
82 }
83 ```
84
85 The compose environment variables are written to the `.env` file inside the
86 context directory and will be used by `compose up` command.
87
88 ## Tasks
89
90 ### writeEnv
91
92 `type: WriteEnv, dependsOn: [configurations.composeImages, processResources]`
93
94 Inspects configuration `composeImages`, adds default `COMPOSE_PROJECT_NAME`
95 variable and writes `.env` file to the context directory.
96
97 This task provides a property `environment` of type `MapProperty<String, String>`
98 which can be used to customize the compose environment.
99
100 ```gradle
101 writeEnv {
102 // direct environment property access
103 environment.put("VAR_1", valueOrProvider)
104
105 // syntax sugar to modify environment property
106 env "VAR_2" put "value" // simple value
107 env "VAR_3" put provider { getSomeValue() } // provider
108
109 // map provider will be merged into the
110 env {
111 VAR_4 = "val1"
112 VAR_5 = getAnotherValue()
113 }
114 }
115 ```
116
117 ### processResources
118
119 `type: Copy`
120
121 Copies resources from the source directory `src/main` into the context directory `build/context`
122
123 ### up
124
125 `type: ComposeUp, dependsOn: [buildTask]`
126
127 Starts the compose project. The project is started in the background.
128
129 ### build
130
131 `type: DefaultTask, dependsOn: [writeEnvTask]`
132
133 This is a meta task used to group the set of tasks related to the build target.
134
135 ### stop
136
137 `type: ComposeStop`
138
139 Stops the current compose project.
140
141 ### rm
142
143 `type: ComposeRm`
144
145 Removes containers created from this compose project.
146
147 `removeValues` - boolean property, if set to true the task will remove all
148 temporary volumes left from containers.
Show file before | Show file after | Hide comments
@@ -3,6 +3,7 package org.implab.gradle.containers;
3 3 import java.io.IOException;
4 4 import java.util.HashMap;
5 5 import java.util.Map;
6 import java.util.Optional;
6 7
7 8 import org.gradle.api.DefaultTask;
8 9 import org.gradle.api.Plugin;
@@ -21,6 +22,8 import org.implab.gradle.containers.task
21 22 public abstract class ComposePlugin implements Plugin<Project>, ProjectMixin {
22 23 public final String COMPOSE_IMAGES_CONFIGURATION = "composeImages";
23 24
25 public final String COMPOSE_PROJECT_NAME = "COMPOSE_PROJECT_NAME";
26
24 27 public final String COMPOSE_EXTENSION = "compose";
25 28
26 29 public final String COMPOSE_UP_TASK = "up";
@@ -75,6 +78,11 public abstract class ComposePlugin impl
75 78 t.dependsOn(processResources, containerImages);
76 79 t.getEnvFile().set(containerExtension.getContextDirectory().file(ENV_FILE_NAME));
77 80
81 var group = project.getGroup();
82 if (group != null && group.toString().length() > 0) {
83 t.getEnvironment().put(COMPOSE_PROJECT_NAME, group.toString());
84 }
85
78 86 t.getEnvironment().putAll(containerImages.map(this::extractComposeEnv));
79 87
80 88 });
Show file before | Show file after | Hide comments
@@ -106,7 +106,7 public abstract class DockerTraits {
106 106 complete(startProcess(builder(args)));
107 107 }
108 108
109 public void saveImage(List<String> images, File output) throws InterruptedException, IOException {
109 public void saveImage(Set<String> images, File output) throws InterruptedException, IOException {
110 110 if (output.exists())
111 111 output.delete();
112 112
Show file before | Show file after | Hide comments
@@ -8,9 +8,9 import java.util.Optional;
8 8 import org.gradle.api.file.DirectoryProperty;
9 9 import org.gradle.api.file.FileCollection;
10 10 import org.gradle.api.file.RegularFile;
11 import org.gradle.api.provider.ListProperty;
12 11 import org.gradle.api.provider.Property;
13 12 import org.gradle.api.provider.Provider;
13 import org.gradle.api.provider.SetProperty;
14 14 import org.gradle.api.tasks.Input;
15 15 import org.gradle.api.tasks.Internal;
16 16 import org.gradle.api.tasks.OutputFile;
@@ -21,7 +21,7 import org.implab.gradle.containers.cli.
21 21 public abstract class SaveImage extends DockerCliTask {
22 22
23 23 @Input
24 public abstract ListProperty<String> getExportImages();
24 public abstract SetProperty<String> getExportImages();
25 25
26 26 @OutputFile
27 27 public Provider<RegularFile> getArchiveFile() {
Show file before | Show file after | Hide comments
@@ -1,7 +1,11
1 1 package org.implab.gradle.containers.tasks;
2 2
3 3 import java.io.IOException;
4 import java.util.HashSet;
5 import java.util.Set;
6
4 7 import org.gradle.api.provider.Property;
8 import org.gradle.api.provider.SetProperty;
5 9 import org.gradle.api.tasks.Input;
6 10 import org.gradle.api.tasks.TaskAction;
7 11
@@ -10,12 +14,33 public abstract class TagImage extends D
10 14 public abstract Property<String> getSrcImage();
11 15
12 16 @Input
17 public abstract SetProperty<String> getTags();
18
19 @Input
20 @Deprecated
13 21 public abstract Property<String> getDestImage();
14 22
23 private Set<String> getImageTags() {
24 var tags = new HashSet<>(getTags().get());
25 tags.add(getDestImage().get());
26 return tags;
27 }
28
29 public TagImage() {
30 this.setOnlyIf("No tags were specified", self -> getImageTags().size() > 0);
31 }
32
15 33 @TaskAction
16 34 public void run() throws InterruptedException, IOException {
17 docker().tagImage(
18 getSrcImage().get(),
19 getDestImage().get());
35 var tags = getImageTags();
36 var src = getSrcImage().get();
37
38 if (tags.size() == 0)
39 getLogger().info("No tags were specified");
40
41 for (var tag : tags) {
42 getLogger().info("Tag: {}", tag);
43 docker().tagImage(src, tag);
20 44 }
21 45 }
46 }
Show file before | Show file after | Hide comments
@@ -5,7 +5,7
5 5 ```gradle
6 6
7 7 plugins {
8 id 'org.implab.gradle-container' version '1.1'
8 id 'org.implab.gradle-container'
9 9 }
10 10
11 11 container {
@@ -44,58 +44,168 task printVersion {
44 44 ## Description
45 45
46 46 This plugin is a simple wrapper around docker CLI. All the image
47 building process is deligated to the `Dockerfile` which will run
48 in the prepeared build context.
47 building process is delegated to the `Dockerfile` which will run
48 in the prepared build context.
49 49
50 ### Project structure
50 ## Project structure
51 51
52 * `build/`
52 * `build/` - this folder will be created during build, it can be useful while
53 solving Dockerfile problems
53 54 * `context/` - the build context where `docker build` command will run.
54 55 * `imageid` - the file storing the id of the image has been built.
55 56 * `image-name-1.2.3.tgz` - the exported image if `saveImage` has been executed.
56 57 * `src`
57 58 * `main` - the source files which will be copied to the build context.
58 59
59 ## Properties
60 ## Global properties
61
62 There are several global properties recognized by this plugin in the project.
63 These properties affect images naming and publication and they are useful in
64 multi-project environment.
60 65
61 66 `imagesAuthority` - the registry where the image should be published.
62 67 for example `docker.io`
63 68
64 69 `imagesGroup` - the path to the image in the repository.
65 70
71 `containerCli` - the command line cli, this property corresponds to
72 `container.cliCmd` in the project.
73
74 Properties defined in the project takes precedence over global properties.
75
76 ## Image names
77
78 ```gradle
79 plugins {
80 id "org.implab.gradle-container"
81 }
82
83 container {
84 // image authority, the repository for your images
85 // defaults to global imagesAuthority property or none
86 imageAuthority = "my.registry.org"
87
88 // the image path
89 // defaults to global imagesGroup property or none
90 imageGroup = "my/project"
91
92 // the name of the image
93 // defaults to project.name
94 imageLocalName = "foo"
95 }
96
97 // provider for imageName, returns ImageName object
98 // ImageName consists of "{imageAuthority}/{imageGroup}/{imageLocalName}"
99 def imageNameProvider = container.imageName
100 ```
101
66 102 ## Tasks
67 103
104 Some tasks support passing additional options as additional command line
105 parameters. These task has the property `options` and some additional methods.
106
107 | Property | Description |
108 |--|--|
109 | `options` | A list of additional arguments passed to `docker build` command. |
110
111 | Method | Description |
112 |---|---|
113 | `option(String)` | Adds option to `options`. |
114 | `option(Closure)` | Converts the parameter to provider and adds it to `options`. |
115 | `option(Callable)` | Converts the parameter to provider and adds it to `options`. |
116 | `options(String...)` | Adds specified options to `options`. |
117 | `options(Closure)`| Converts the parameter to provider and adds it to `options`. |
118 | `options(Callable)`| Converts the parameter to provider and adds it to `options` |
119
68 120 ### buildImage
69 121
122 `type: BuildImage`
123
70 124 The task builds the image. Wrapper around the `docker build` command.
71 125
126 | Property | Description |
127 |---|---|
128 | `contextDirectory` | A Dockerfile context directory. Set to `container.context`. |
129 | `buildArgs` | A dictionary with environment variables which are set during build. |
130 | `buildTarget` | A target image for the multi-stage builds. Defaults to none. |
131 | `imageName` | A name (tag) for the resulting image. |
132 | `imageIdFIle` | Output file name where image ref will be written. |
133
134 This task also supports additional command line options.
135
72 136 ### saveImage
73 137
138 `type: SaveImage`
139
74 140 The task exports image as the .tar archive.
75 141
142 | Property | Description |
143 |-|-|
144 | `archiveFileName` | The file name of the bundle archive, defaults to `{archiveBaseName}-{archiveVersion}-{archiveClassifier}.{archiveExtension}`.|
145 | `archiveBaseName` | The base name of the archive, defaults to `{project.group}-{project.name}`. |
146 | `archiveVersion` | The archive version, defaults to `{project.version}`. |
147 | `exportImages` | A set of image names to include in the bundle. |
148
149 | Method | Description |
150 |-|-|
151 | `imageRefs(FileCollection)` | Adds a set of files with image refs to add to the bundle. |
152 | `imageRef(File)` | Adds an image name from the file with image reference. |
153
76 154 ### pushImage
77 155
78 The task pushes the image to the remote repository.
156 The task pushes the image to the remote repository (imageAuthority).
157
158 [Since v1.2] This task also supports additional command line options. You can use them to
159 push all tags for the image.
160
161 ```gradle
162 pushImage {
163 option "--all-tags"
164 }
165 ```
79 166
80 167 ### processResources
81 168
82 The copy task, it prepares the build context. Use it to customize
169 The copy task, it prepares the build context. Use this task to customize
83 170 the build context.
84 171
85 172 ### tagImage
86 173
174 `type: TagImage`
175
87 176 since: 1.1
88 177
89 178 ```gradle
90 179 task tagLatest(type: TagImage) {
180 pushImage.dependsOn it
181
91 182 srcImage = container.imageName
92 destImage = container.imageName.map { it.tag("latest") }
183
184 tags.add(container.imageName.map { it.tag("latest") })
93 185 }
94 186
95 187 ```
96 188
189 | Property | Description |
190 |-|-|
191 | `srcImage` | The source image name to add tag to. |
192 | `tags` | The set of tags to add to the image. |
193
194 ## See also
195
196 * Creating [compose](compose.md) project
197 * Creating [bundle](bundle.md) project
198
97 199 ## Changes
98 200
201 ### 1.2
202
203 Added `org.implab.gradle-container-base`, `org.implab.gradle-container-compose`
204 plugins.
205
206 * `org.implab.gradle-container-base` registers base extension and task types.
207 * `org.implab.gradle-container-compose` registers conventional tasks.
208
99 209 ### 1.1
100 210
101 211 Warning! This version isn't fully backward compatible with 1.0 version.
General Comments 0
You need to be logged in to leave comments. Login now