jib-container

Description

Extends the container module type to build the image with Jib. Use this to efficiently build container images for Java services. Check out the jib example to see it in action.
The image is always built locally, directly from the module source directory (see the note on that below), before shipping the container image to the right place. You can set build.tarOnly: true to only build the image as a tarball.
By default (and when not using remote building), the image is pushed to the local Docker daemon, to match the behavior of and stay compatible with normal container modules.
When using remote building with the kubernetes provider, the image is synced to the cluster (where individual layers are cached) and then pushed to the deployment registry from there. This is to make sure any registry auth works seamlessly and exactly like for normal Docker image builds.
Please consult the Jib documentation for how to configure Jib in your Gradle or Maven project.
To provide additional arguments to Gradle/Maven when building, you can set the extraFlags field.
Important note: Unlike many other module types, jib modules are built from the module source directory instead of the build staging directory, because of how Java projects are often laid out across a repository. This means build.dependencies[].copy directives are effectively ignored, and any include/exclude statements and .gardenignore files will not impact the build result. Note that you should still configure includes, excludes and/or a .gardenignore to tell Garden which files to consider as part of the module version hash, to correctly detect whether a new build is required.
Below is the full schema reference. For an introduction to configuring Garden modules, please look at our Configuration guide.
The first section contains the complete YAML schema, and the second section describes each schema key.
jib-container modules also export values that are available in template strings. See the Outputs section below for details.

Complete YAML Schema

The values in the schema below are the default values.
1
# The schema version of this config (currently not used).
2
apiVersion: garden.io/v0
3
​
4
kind: Module
5
​
6
# The type of this module.
7
type:
8
​
9
# The name of this module.
10
name:
11
​
12
# Specify how to build the module. Note that plugins may define additional keys on this object.
13
build:
14
# A list of modules that must be built before this module is built.
15
dependencies:
16
- # Module name to build ahead of this module.
17
name:
18
​
19
# Specify one or more files or directories to copy from the built dependency to this module.
20
copy:
21
- # POSIX-style path or filename of the directory or file(s) to copy to the target.
22
source:
23
​
24
# POSIX-style path or filename to copy the directory or file(s), relative to the build directory.
25
# Defaults to to same as source path.
26
target: ''
27
​
28
# Maximum time in seconds to wait for build to finish.
29
timeout: 1200
30
​
31
# The type of project to build. Defaults to auto-detecting between gradle and maven (based on which
32
# files/directories are found in the module root), but in some cases you may need to specify it.
33
projectType: auto
34
​
35
# The JDK version to use.
36
jdkVersion: 11
37
​
38
# Build the image and push to a local Docker daemon (i.e. use the `jib:dockerBuild` / `jibDockerBuild` target).
39
dockerBuild: false
40
​
41
# Don't load or push the resulting image to a Docker daemon or registry, only build it as a tar file.
42
tarOnly: false
43
​
44
# Specify the image format in the resulting tar file. Only used if `tarOnly: true`.
45
tarFormat: docker
46
​
47
# Specify extra flags to pass to maven/gradle when building the container image.
48
extraFlags:
49
​
50
# A description of the module.
51
description:
52
​
53
# Set this to `true` to disable the module. You can use this with conditional template strings to disable modules
54
# based on, for example, the current environment or other variables (e.g. `disabled: \${environment.name == "prod"}`).
55
# This can be handy when you only need certain modules for specific environments, e.g. only for development.
56
#
57
# Disabling a module means that any services, tasks and tests contained in it will not be deployed or run. It also
58
# means that the module is not built _unless_ it is declared as a build dependency by another enabled module (in which
59
# case building this module is necessary for the dependant to be built).
60
#
61
# If you disable the module, and its services, tasks or tests are referenced as _runtime_ dependencies, Garden will
62
# automatically ignore those dependency declarations. Note however that template strings referencing the module's
63
# service or task outputs (i.e. runtime outputs) will fail to resolve when the module is disabled, so you need to make
64
# sure to provide alternate values for those if you're using them, using conditional expressions.
65
disabled: false
66
​
67
# Specify a list of POSIX-style paths or globs that should be regarded as the source files for this module. Files that
68
# do *not* match these paths or globs are excluded when computing the version of the module, when responding to
69
# filesystem watch events, and when staging builds.
70
#
71
# Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source
72
# tree, which use the same format as `.gitignore` files. See the [Configuration Files
73
# guide](https://docs.garden.io/using-garden/configuration-overview#including-excluding-files-and-directories) for
74
# details.
75
#
76
# Also note that specifying an empty list here means _no sources_ should be included.
77
#
78
# If neither `include` nor `exclude` is set, and the module has a Dockerfile, Garden
79
# will parse the Dockerfile and automatically set `include` to match the files and
80
# folders added to the Docker image (via the `COPY` and `ADD` directives in the Dockerfile).
81
#
82
# If neither `include` nor `exclude` is set, and the module
83
# specifies a remote image, Garden automatically sets `include` to `[]`.
84
include:
85
​
86
# Specify a list of POSIX-style paths or glob patterns that should be excluded from the module. Files that match these
87
# paths or globs are excluded when computing the version of the module, when responding to filesystem watch events,
88
# and when staging builds.
89
#
90
# Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include`
91
# field, the files/patterns specified here are filtered from the files matched by `include`. See the [Configuration
92
# Files guide](https://docs.garden.io/using-garden/configuration-overview#including-excluding-files-and-directories)
93
# for details.
94
#
95
# Unlike the `modules.exclude` field in the project config, the filters here have _no effect_ on which files and
96
# directories are watched for changes. Use the project `modules.exclude` field to affect those, if you have large
97
# directories that should not be watched for changes.
98
exclude:
99
​
100
# A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific
101
# branch or tag, with the format: <git remote url>#<branch|tag>
102
#
103
# Garden will import the repository source code into this module, but read the module's config from the local
104
# garden.yml file.
105
repositoryUrl:
106
​
107
# When false, disables pushing this module to remote registries.
108
allowPublish: true
109
​
110
# A list of files to write to the module directory when resolving this module. This is useful to automatically
111
# generate (and template) any supporting files needed for the module.
112
generateFiles:
113
- # POSIX-style filename to read the source file contents from, relative to the path of the module (or the
114
# ModuleTemplate configuration file if one is being applied).
115
# This file may contain template strings, much like any other field in the configuration.
116
sourcePath:
117
​
118
# POSIX-style filename to write the resolved file contents to, relative to the path of the module source directory
119
# (for remote modules this means the root of the module repository, otherwise the directory of the module
120
# configuration).
121
#
122
# Note that any existing file with the same name will be overwritten. If the path contains one or more
123
# directories, they will be automatically created if missing.
124
targetPath:
125
​
126
# By default, Garden will attempt to resolve any Garden template strings in source files. Set this to false to
127
# skip resolving template strings. Note that this does not apply when setting the `value` field, since that's
128
# resolved earlier when parsing the configuration.
129
resolveTemplates: true
130
​
131
# The desired file contents as a string.
132
value:
133
​
134
# A map of variables scoped to this particular module. These are resolved before any other parts of the module
135
# configuration and take precedence over project-scoped variables. They may reference project-scoped variables, and
136
# generally use any template strings normally allowed when resolving modules.
137
variables:
138
​
139
# Specify a path (relative to the module root) to a file containing variables, that we apply on top of the
140
# module-level `variables` field.
141
#
142
# The format of the files is determined by the configured file's extension:
143
#
144
# * `.env` - Standard "dotenv" format, as defined by [dotenv](https://github.com/motdotla/dotenv#rules).
145
# * `.yaml`/`.yml` - YAML. The file must consist of a YAML document, which must be a map (dictionary). Keys may
146
# contain any value type.
147
# * `.json` - JSON. Must contain a single JSON _object_ (not an array).
148
#
149
# _NOTE: The default varfile format will change to YAML in Garden v0.13, since YAML allows for definition of nested
150
# objects and arrays._
151
#
152
# To use different module-level varfiles in different environments, you can template in the environment name
153
# to the varfile name, e.g. `varfile: "my-module.\$\{environment.name\}.env` (this assumes that the corresponding
154
# varfiles exist).
155
varfile:
156
​
157
# Specify build arguments to use when building the container image.
158
#
159
# Note: Garden will always set a `GARDEN_MODULE_VERSION` argument with the module version at build time.
160
buildArgs: {}
161
​
162
# Specify extra flags to use when building the container image. Note that arguments may not be portable across
163
# implementations.
164
extraFlags:
165
​
166
# Specify the image name for the container. Should be a valid Docker image identifier. If specified and the module
167
# does not contain a Dockerfile, this image will be used to deploy services for this module. If specified and the
168
# module does contain a Dockerfile, this identifier is used when pushing the built image.
169
image:
170
​
171
# Specifies which files or directories to sync to which paths inside the running containers of hot reload-enabled
172
# services when those files or directories are modified. Applies to this module's services, and to services with this
173
# module as their `sourceModule`.
174
hotReload:
175
# Specify one or more source files or directories to automatically sync into the running container.
176
sync:
177
- # POSIX-style path of the directory to sync to the target, relative to the module's top-level directory. Must be
178
# a relative path. Defaults to the module's top-level directory if no value is provided.
179
source: .
180
​
181
# POSIX-style absolute path to sync the directory to inside the container. The root path (i.e. "/") is not
182
# allowed.
183
target:
184
​
185
# An optional command to run inside the container after syncing.
186
postSyncCommand:
187
​
188
# POSIX-style name of Dockerfile, relative to module root.
189
dockerfile:
190
​
191
# A list of services to deploy from this container module.
192
services:
193
- # Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must start with a letter,
194
# and cannot end with a dash), cannot contain consecutive dashes or start with `garden`, or be longer than 63
195
# characters.
196
name:
197
​
198
# The names of any services that this service depends on at runtime, and the names of any tasks that should be
199
# executed before this service is deployed.
200
dependencies: []
201
​
202
# Set this to `true` to disable the service. You can use this with conditional template strings to enable/disable
203
# services based on, for example, the current environment or other variables (e.g. `enabled: \${environment.name
204
# != "prod"}`). This can be handy when you only need certain services for specific environments, e.g. only for
205
# development.
206
#
207
# Disabling a service means that it will not be deployed, and will also be ignored if it is declared as a runtime
208
# dependency for another service, test or task.
209
#
210
# Note however that template strings referencing the service's outputs (i.e. runtime outputs) will fail to resolve
211
# when the service is disabled, so you need to make sure to provide alternate values for those if you're using
212
# them, using conditional expressions.
213
disabled: false
214
​
215
# Annotations to attach to the service _(note: May not be applicable to all providers)_.
216
#
217
# When using the Kubernetes provider, these annotations are applied to both Service and Pod resources. You can
218
# generally specify the annotations intended for both Pods or Services here, and the ones that don't apply on
219
# either side will be ignored (i.e. if you put a Service annotation here, it'll also appear on Pod specs but will
220
# be safely ignored there, and vice versa).
221
annotations: {}
222
​
223
# The command/entrypoint to run the container with when starting the service.
224
command:
225
​
226
# The arguments to run the container with when starting the service.
227
args:
228
​
229
# Whether to run the service as a daemon (to ensure exactly one instance runs per node). May not be supported by
230
# all providers.
231
daemon: false
232
​
233
# Specifies which files or directories to sync to which paths inside the running containers of the service when
234
# it's in dev mode, and overrides for the container command and/or arguments.
235
#
236
# Dev mode is enabled when running the `garden dev` command, and by setting the `--dev` flag on the `garden
237
# deploy` command.
238
#
239
# See the [Code Synchronization guide](https://docs.garden.io/guides/code-synchronization-dev-mode) for more
240
# information.
241
devMode:
242
# Override the default container arguments when in dev mode.
243
args:
244
​
245
# Override the default container command (i.e. entrypoint) when in dev mode.
246
command:
247
​
248
# Specify one or more source files or directories to automatically sync with the running container.
249
sync:
250
- # POSIX-style path of the directory to sync to the target, relative to the module's top-level directory.
251
# Must be a relative path. Defaults to the module's top-level directory if no value is provided.
252
source: .
253
​
254
# POSIX-style absolute path to sync the directory to inside the container. The root path (i.e. "/") is not
255
# allowed.
256
target:
257
​
258
# Specify a list of POSIX-style paths or glob patterns that should be excluded from the sync.
259
#
260
# `.git` directories and `.garden` directories are always ignored.
261
exclude:
262
​
263
# The sync mode to use for the given paths. See the [Dev Mode
264
# guide](https://docs.garden.io/guides/code-synchronization-dev-mode) for details.
265
mode: one-way-safe
266
​
267
# The default permission bits, specified as an octal, to set on files at the sync target. Defaults to 0600
268
# (user read/write). See the [Mutagen
269
# docs](https://mutagen.io/documentation/synchronization/permissions#permissions) for more information.
270
defaultFileMode:
271
​
272
# The default permission bits, specified as an octal, to set on directories at the sync target. Defaults to
273
# 0700 (user read/write). See the [Mutagen
274
# docs](https://mutagen.io/documentation/synchronization/permissions#permissions) for more information.
275
defaultDirectoryMode:
276
​
277
# Set the default owner of files and directories at the target. Specify either an integer ID or a string
278
# name. See the [Mutagen
279
# docs](https://mutagen.io/documentation/synchronization/permissions#owners-and-groups) for more
280
# information.
281
defaultOwner:
282
​
283
# Set the default group on files and directories at the target. Specify either an integer ID or a string
284
# name. See the [Mutagen
285
# docs](https://mutagen.io/documentation/synchronization/permissions#owners-and-groups) for more
286
# information.
287
defaultGroup:
288
​
289
# List of ingress endpoints that the service exposes.
290
ingresses:
291
- # Annotations to attach to the ingress (Note: May not be applicable to all providers)
292
annotations: {}
293
​
294
# The hostname that should route to this service. Defaults to the default hostname configured in the provider
295
# configuration.
296
#
297
# Note that if you're developing locally you may need to add this hostname to your hosts file.
298
hostname:
299
​
300
# The link URL for the ingress to show in the console and on the dashboard. Also used when calling the service
301
# with the `call` command.
302
#
303
# Use this if the actual URL is different from what's specified in the ingress, e.g. because there's a load
304
# balancer in front of the service that rewrites the paths.
305
#
306
# Otherwise Garden will construct the link URL from the ingress spec.
307
linkUrl:
308
​
309
# The path which should be routed to the service.
310
path: /
311
​
312
# The name of the container port where the specified paths should be routed.
313
port:
314
​
315
# Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with
316
# `GARDEN`) and values must be primitives or references to secrets.
317
env: {}
318
​
319
# Specify how the service's health should be checked after deploying.
320
healthCheck:
321
# Set this to check the service's health by making an HTTP request.
322
httpGet:
323
# The path of the service's health check endpoint.
324
path:
325
​
326
# The name of the port where the service's health check endpoint should be available.
327
port:
328
​
329
scheme: HTTP
330
​
331
# Set this to check the service's health by running a command in its container.
332
command:
333
​
334
# Set this to check the service's health by checking if this TCP port is accepting connections.
335
tcpPort:
336
​
337
# The maximum number of seconds to wait until the readiness check counts as failed.
338
readinessTimeoutSeconds: 3
339
​
340
# The maximum number of seconds to wait until the liveness check counts as failed.
341
livenessTimeoutSeconds: 3
342
​
343
# If this module uses the `hotReload` field, the container will be run with this command/entrypoint when the
344
# service is deployed with hot reloading enabled.
345
hotReloadCommand:
346
​
347
# If this module uses the `hotReload` field, the container will be run with these arguments when the service is
348
# deployed with hot reloading enabled.
349
hotReloadArgs:
350
​
351
# The maximum duration (in seconds) to wait for resources to deploy and become healthy.
352
timeout: 300
353
​
354
cpu:
355
# The minimum amount of CPU the service needs to be available for it to be deployed, in millicpus (i.e. 1000 = 1
356
# CPU)
357
min: 10
358
​
359
# The maximum amount of CPU the service can use, in millicpus (i.e. 1000 = 1 CPU)
360
max: 1000
361
​
362
memory:
363
# The minimum amount of RAM the service needs to be available for it to be deployed, in megabytes (i.e. 1024 = 1
364
# GB)
365
min: 90
366
​
367
# The maximum amount of RAM the service can use, in megabytes (i.e. 1024 = 1 GB)
368
max: 90
369
​
370
# List of ports that the service container exposes.
371
ports:
372
- # The name of the port (used when referencing the port elsewhere in the service configuration).
373
name:
374
​
375
# The protocol of the port.
376
protocol: TCP
377
​
378
# The port exposed on the container by the running process. This will also be the default value for
379
# `servicePort`.
380
# This is the port you would expose in your Dockerfile and that your process listens on. This is commonly a
381
# non-priviledged port like 8080 for security reasons.
382
# The service port maps to the container port:
383
# `servicePort:80 -> containerPort:8080 -> process:8080`
384
containerPort:
385
​
386
# Specify a preferred local port to attach to when creating a port-forward to the service port. If this port
387
# is
388
# busy, a warning will be shown and an alternative port chosen.
389
localPort:
390
​
391
# The port exposed on the service. Defaults to `containerPort` if not specified.
392
# This is the port you use when calling a service from another service within the cluster. For example, if
393
# your service name is my-service and the service port is 8090, you would call it with:
394
# http://my-service:8090/some-endpoint.
395
# It is common to use port 80, the default port number, so that you can call the service directly with
396
# http://my-service/some-endpoint.
397
# The service port maps to the container port:
398
# `servicePort:80 -> containerPort:8080 -> process:8080`
399
servicePort:
400
​
401
# Set this to expose the service on the specified port on the host node (may not be supported by all
402
# providers). Set to `true` to have the cluster pick a port automatically, which is most often advisable if
403
# the cluster is shared by multiple users.
404
# This allows you to call the service from the outside by the node's IP address and the port number set in
405
# this field.
406
nodePort:
407
​
408
# The number of instances of the service to deploy. Defaults to 3 for environments configured with `production:
409
# true`, otherwise 1.
410
# Note: This setting may be overridden or ignored in some cases. For example, when running with `daemon: true`,
411
# with hot-reloading enabled, or if the provider doesn't support multiple replicas.
412
replicas:
413
​
414
# List of volumes that should be mounted when deploying the service.
415
#
416
# Note: If neither `hostPath` nor `module` is specified, an empty ephemeral volume is created and mounted when
417
# deploying the container.
418
volumes:
419
- # The name of the allocated volume.
420
name:
421
​
422
# The path where the volume should be mounted in the container.
423
containerPath:
424
​
425
# _NOTE: Usage of hostPath is generally discouraged, since it doesn't work reliably across different platforms
426
# and providers. Some providers may not support it at all._
427
#
428
# A local path or path on the node that's running the container, to mount in the container, relative to the
429
# module source path (or absolute).
430
hostPath:
431
​
432
# The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will
433
# depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim
434
# module](./persistentvolumeclaim.md), for example.
435
#
436
# When a `module` is specified, the referenced module/volume will be automatically configured as a runtime
437
# dependency of this service, as well as a build dependency of this module.
438
#
439
# Note: Make sure to pay attention to the supported `accessModes` of the referenced volume. Unless it supports
440
# the ReadWriteMany access mode, you'll need to make sure it is not configured to be mounted by multiple
441
# services at the same time. Refer to the documentation of the module type in question to learn more.
442
module:
443
​
444
# If true, run the service's main container in privileged mode. Processes in privileged containers are essentially
445
# equivalent to root on the host. Defaults to false.
446
privileged:
447
​
448
# Specify if containers in this module have TTY support enabled (which implies having stdin support enabled).
449
tty: false
450
​
451
# POSIX capabilities to add to the running service's main container.
452
addCapabilities:
453
​
454
# POSIX capabilities to remove from the running service's main container.
455
dropCapabilities:
456
​
457
# A list of tests to run in the module.
458
tests:
459
- # The name of the test.
460
name:
461
​
462
# The names of any services that must be running, and the names of any tasks that must be executed, before the
463
# test is run.
464
dependencies: []
465
​
466
# Set this to `true` to disable the test. You can use this with conditional template strings to
467
# enable/disable tests based on, for example, the current environment or other variables (e.g.
468
# `enabled: \${environment.name != "prod"}`). This is handy when you only want certain tests to run in
469
# specific environments, e.g. only during CI.
470
disabled: false
471
​
472
# Maximum duration (in seconds) of the test run.
473
timeout: null
474
​
475
# The arguments used to run the test inside the container.
476
args:
477
​
478
# Specify artifacts to copy out of the container after the run. The artifacts are stored locally under the
479
# `.garden/artifacts` directory.
480
#
481
# Note: Depending on the provider, this may require the container image to include `sh` `tar`, in order to enable
482
# the file transfer.
483
artifacts:
484
- # A POSIX-style path or glob to copy. Must be an absolute path. May contain wildcards.
485
source:
486
​
487
# A POSIX-style path to copy the artifacts to, relative to the project artifacts directory at
488
# `.garden/artifacts`.
489
target: .
490
​
491
# The command/entrypoint used to run the test inside the container.
492
command:
493
​
494
# Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with
495
# `GARDEN`) and values must be primitives or references to secrets.
496
env: {}
497
​
498
cpu:
499
# The minimum amount of CPU the test needs to be available for it to be deployed, in millicpus (i.e. 1000 = 1
500
# CPU)
501
min: 10
502
​
503
# The maximum amount of CPU the test can use, in millicpus (i.e. 1000 = 1 CPU)
504
max: 1000
505
​
506
memory:
507
# The minimum amount of RAM the test needs to be available for it to be deployed, in megabytes (i.e. 1024 = 1
508
# GB)
509
min: 90
510
​
511
# The maximum amount of RAM the test can use, in megabytes (i.e. 1024 = 1 GB)
512
max: 90
513
​
514
# List of volumes that should be mounted when deploying the test.
515
#
516
# Note: If neither `hostPath` nor `module` is specified, an empty ephemeral volume is created and mounted when
517
# deploying the container.
518
volumes:
519
- # The name of the allocated volume.
520
name:
521
​
522
# The path where the volume should be mounted in the container.
523
containerPath:
524
​
525
# _NOTE: Usage of hostPath is generally discouraged, since it doesn't work reliably across different platforms
526
# and providers. Some providers may not support it at all._
527
#
528
# A local path or path on the node that's running the container, to mount in the container, relative to the
529
# module source path (or absolute).
530
hostPath:
531
​
532
# The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will
533
# depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim
534
# module](./persistentvolumeclaim.md), for example.
535
#
536
# When a `module` is specified, the referenced module/volume will be automatically configured as a runtime
537
# dependency of this service, as well as a build dependency of this module.
538
#
539
# Note: Make sure to pay attention to the supported `accessModes` of the referenced volume. Unless it supports
540
# the ReadWriteMany access mode, you'll need to make sure it is not configured to be mounted by multiple
541
# services at the same time. Refer to the documentation of the module type in question to learn more.
542
module:
543
​
544
# If true, run the test's main container in privileged mode. Processes in privileged containers are essentially
545
# equivalent to root on the host. Defaults to false.
546
privileged:
547
​
548
# POSIX capabilities to add to the running test's main container.
549
addCapabilities:
550
​
551
# POSIX capabilities to remove from the running test's main container.
552
dropCapabilities:
553
​
554
# A list of tasks that can be run from this container module. These can be used as dependencies for services (executed
555
# before the service is deployed) or for other tasks.
556
tasks:
557
- # The name of the task.
558
name:
559
​
560
# A description of the task.
561
description:
562
​
563
# The names of any tasks that must be executed, and the names of any services that must be running, before this
564
# task is executed.
565
dependencies: []
566
​
567
# Set this to `true` to disable the task. You can use this with conditional template strings to enable/disable
568
# tasks based on, for example, the current environment or other variables (e.g. `enabled: \${environment.name !=
569
# "prod"}`). This can be handy when you only want certain tasks to run in specific environments, e.g. only for
570
# development.
571
#
572
# Disabling a task means that it will not be run, and will also be ignored if it is declared as a runtime
573
# dependency for another service, test or task.
574
#
575
# Note however that template strings referencing the task's outputs (i.e. runtime outputs) will fail to resolve
576
# when the task is disabled, so you need to make sure to provide alternate values for those if you're using them,
577
# using conditional expressions.
578
disabled: false
579
​
580
# Maximum duration (in seconds) of the task's execution.
581
timeout: null
582
​
583
# The arguments used to run the task inside the container.
584
args:
585
​
586
# Specify artifacts to copy out of the container after the run. The artifacts are stored locally under the
587
# `.garden/artifacts` directory.
588
#
589
# Note: Depending on the provider, this may require the container image to include `sh` `tar`, in order to enable
590
# the file transfer.
591
artifacts:
592
- # A POSIX-style path or glob to copy. Must be an absolute path. May contain wildcards.
593
source:
594
​
595
# A POSIX-style path to copy the artifacts to, relative to the project artifacts directory at
596
# `.garden/artifacts`.
597
target: .
598
​
599
# Set to false if you don't want the task's result to be cached. Use this if the task needs to be run any time
600
# your project (or one or more of the task's dependants) is deployed. Otherwise the task is only re-run when its
601
# version changes (i.e. the module or one of its dependencies is modified), or when you run `garden run task`.
602
cacheResult: true
603
​
604
# The command/entrypoint used to run the task inside the container.
605
command:
606
​
607
# Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with
608
# `GARDEN`) and values must be primitives or references to secrets.
609
env: {}
610
​
611
cpu:
612
# The minimum amount of CPU the task needs to be available for it to be deployed, in millicpus (i.e. 1000 = 1
613
# CPU)
614
min: 10
615
​
616
# The maximum amount of CPU the task can use, in millicpus (i.e. 1000 = 1 CPU)
617
max: 1000
618
​
619
memory:
620
# The minimum amount of RAM the task needs to be available for it to be deployed, in megabytes (i.e. 1024 = 1
621
# GB)
622
min: 90
623
​
624
# The maximum amount of RAM the task can use, in megabytes (i.e. 1024 = 1 GB)
625
max: 90
626
​
627
# List of volumes that should be mounted when deploying the task.
628
#
629
# Note: If neither `hostPath` nor `module` is specified, an empty ephemeral volume is created and mounted when
630
# deploying the container.
631
volumes:
632
- # The name of the allocated volume.
633
name:
634
​
635
# The path where the volume should be mounted in the container.
636
containerPath:
637
​
638
# _NOTE: Usage of hostPath is generally discouraged, since it doesn't work reliably across different platforms
639
# and providers. Some providers may not support it at all._
640
#
641
# A local path or path on the node that's running the container, to mount in the container, relative to the
642
# module source path (or absolute).
643
hostPath:
644
​
645
# The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will
646
# depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim
647
# module](./persistentvolumeclaim.md), for example.
648
#
649
# When a `module` is specified, the referenced module/volume will be automatically configured as a runtime
650
# dependency of this service, as well as a build dependency of this module.
651
#
652
# Note: Make sure to pay attention to the supported `accessModes` of the referenced volume. Unless it supports
653
# the ReadWriteMany access mode, you'll need to make sure it is not configured to be mounted by multiple
654
# services at the same time. Refer to the documentation of the module type in question to learn more.
655
module:
656
​
657
# If true, run the task's main container in privileged mode. Processes in privileged containers are essentially
658
# equivalent to root on the host. Defaults to false.
659
privileged:
660
​
661
# POSIX capabilities to add to the running task's main container.
662
addCapabilities:
663
​
664
# POSIX capabilities to remove from the running task's main container.
665
dropCapabilities:
Copied!

Configuration Keys

apiVersion

The schema version of this config (currently not used).
Type
Allowed Values
Default
Required
string
"garden.io/v0"
"garden.io/v0"
Yes

kind

Type
Allowed Values
Default
Required
string
"Module"
"Module"
Yes

type

The type of this module.
Type
Required
string
Yes
Example:
1
type: "container"
Copied!

name

The name of this module.
Type
Required
string
Yes
Example:
1
name: "my-sweet-module"
Copied!

build

Specify how to build the module. Note that plugins may define additional keys on this object.
Type
Default
Required
object
{"dependencies":[]}
No

build.dependencies[]

​build > dependencies
A list of modules that must be built before this module is built.
Type
Default
Required
array[object]
[]
No
Example:
1
build:
2
...
3
dependencies:
4
- name: some-other-module-name
Copied!

build.dependencies[].name

​build > dependencies > name
Module name to build ahead of this module.
Type
Required
string
Yes

build.dependencies[].copy[]

​build > dependencies > copy
Specify one or more files or directories to copy from the built dependency to this module.
Type
Default
Required
array[object]
[]
No

build.dependencies[].copy[].source

​build > dependencies > copy > source
POSIX-style path or filename of the directory or file(s) to copy to the target.
Type
Required
posixPath
Yes

build.dependencies[].copy[].target

​build > dependencies > copy > target
POSIX-style path or filename to copy the directory or file(s), relative to the build directory. Defaults to to same as source path.
Type
Default
Required
posixPath
""
No

build.timeout

​build > timeout
Maximum time in seconds to wait for build to finish.
Type
Default
Required
number
1200
No

build.projectType

​build > projectType
The type of project to build. Defaults to auto-detecting between gradle and maven (based on which files/directories are found in the module root), but in some cases you may need to specify it.
Type
Default
Required
string
"auto"
No

build.jdkVersion

​build > jdkVersion
The JDK version to use.
Type
Default
Required
number
11
No

build.dockerBuild

​build > dockerBuild
Build the image and push to a local Docker daemon (i.e. use the jib:dockerBuild / jibDockerBuild target).
Type
Default
Required
boolean
false
No

build.tarOnly

​build > tarOnly
Don't load or push the resulting image to a Docker daemon or registry, only build it as a tar file.
Type
Default
Required
boolean
false
No

build.tarFormat

​build > tarFormat
Specify the image format in the resulting tar file. Only used if tarOnly: true.
Type
Default
Required
string
"docker"
No

build.extraFlags[]

​build > extraFlags
Specify extra flags to pass to maven/gradle when building the container image.
Type
Required
array[string]
No

description

A description of the module.
Type
Required
string
No

disabled

Set this to true to disable the module. You can use this with conditional template strings to disable modules based on, for example, the current environment or other variables (e.g. disabled: \${environment.name == "prod"}). This can be handy when you only need certain modules for specific environments, e.g. only for development.
Disabling a module means that any services, tasks and tests contained in it will not be deployed or run. It also means that the module is not built unless it is declared as a build dependency by another enabled module (in which case building this module is necessary for the dependant to be built).
If you disable the module, and its services, tasks or tests are referenced as runtime dependencies, Garden will automatically ignore those dependency declarations. Note however that template strings referencing the module's service or task outputs (i.e. runtime outputs) will fail to resolve when the module is disabled, so you need to make sure to provide alternate values for those if you're using them, using conditional expressions.
Type
Default
Required
boolean
false
No

include[]

Specify a list of POSIX-style paths or globs that should be regarded as the source files for this module. Files that do not match these paths or globs are excluded when computing the version of the module, when responding to filesystem watch events, and when staging builds.
Note that you can also exclude files using the exclude field or by placing .gardenignore files in your source tree, which use the same format as .gitignore files. See the Configuration Files guide for details.
Also note that specifying an empty list here means no sources should be included.
If neither include nor exclude is set, and the module has a Dockerfile, Garden will parse the Dockerfile and automatically set include to match the files and folders added to the Docker image (via the COPY and ADD directives in the Dockerfile).
If neither include nor exclude is set, and the module specifies a remote image, Garden automatically sets include to [].
Type
Required
array[posixPath]
No
Example:
1
include:
2
- Dockerfile
3
- my-app.js
Copied!

exclude[]

Specify a list of POSIX-style paths or glob patterns that should be excluded from the module. Files that match these paths or globs are excluded when computing the version of the module, when responding to filesystem watch events, and when staging builds.
Note that you can also explicitly include files using the include field. If you also specify the include field, the files/patterns specified here are filtered from the files matched by include. See the Configuration Files guide for details.
Unlike the modules.exclude field in the project config, the filters here have no effect on which files and directories are watched for changes. Use the project modules.exclude field to affect those, if you have large directories that should not be watched for changes.
Type
Required
array[posixPath]
No
Example:
1
exclude:
2
- tmp/**/*
3
- '*.log'
Copied!

repositoryUrl

A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: #<branch|tag>
Garden will import the repository source code into this module, but read the module's config from the local garden.yml file.
Type
Required
`gitUrl
string`
Example:
1
repositoryUrl: "git+https://github.com/org/repo.git#v2.0"
Copied!

allowPublish

When false, disables pushing this module to remote registries.
Type
Default
Required
boolean
true
No

generateFiles[]

A list of files to write to the module directory when resolving this module. This is useful to automatically generate (and template) any supporting files needed for the module.
Type
Default
Required
array[object]
[]
No

generateFiles[].sourcePath

​generateFiles > sourcePath
POSIX-style filename to read the source file contents from, relative to the path of the module (or the ModuleTemplate configuration file if one is being applied). This file may contain template strings, much like any other field in the configuration.
Type
Required
posixPath
No

generateFiles[].targetPath

​generateFiles > targetPath
POSIX-style filename to write the resolved file contents to, relative to the path of the module source directory (for remote modules this means the root of the module repository, otherwise the directory of the module configuration).
Note that any existing file with the same name will be overwritten. If the path contains one or more directories, they will be automatically created if missing.
Type
Required
posixPath
Yes

generateFiles[].resolveTemplates

​generateFiles > resolveTemplates
By default, Garden will attempt to resolve any Garden template strings in source files. Set this to false to skip resolving template strings. Note that this does not apply when setting the value field, since that's resolved earlier when parsing the configuration.
Type
Default
Required
boolean
true
No

generateFiles[].value

​generateFiles > value
The desired file contents as a string.
Type
Required
string
No

variables

A map of variables scoped to this particular module. These are resolved before any other parts of the module configuration and take precedence over project-scoped variables. They may reference project-scoped variables, and generally use any template strings normally allowed when resolving modules.
Type
Required
object
No

varfile

Specify a path (relative to the module root) to a file containing variables, that we apply on top of the module-level variables field.
The format of the files is determined by the configured file's extension:
  • .env - Standard "dotenv" format, as defined by dotenv.
  • .yaml/.yml - YAML. The file must consist of a YAML document, which must be a map (dictionary). Keys may contain any value type.
  • .json - JSON. Must contain a single JSON object (not an array).
NOTE: The default varfile format will change to YAML in Garden v0.13, since YAML allows for definition of nested objects and arrays.
To use different module-level varfiles in different environments, you can template in the environment name to the varfile name, e.g. varfile: "my-module.\$\{environment.name\}.env (this assumes that the corresponding varfiles exist).
Type
Required
posixPath
No
Example:
1
varfile: "my-module.env"
Copied!

buildArgs

Specify build arguments to use when building the container image.
Note: Garden will always set a GARDEN_MODULE_VERSION argument with the module version at build time.
Type
Default
Required
object
{}
No

extraFlags[]

Specify extra flags to use when building the container image. Note that arguments may not be portable across implementations.
Type
Required
array[string]
No

image

Specify the image name for the container. Should be a valid Docker image identifier. If specified and the module does not contain a Dockerfile, this image will be used to deploy services for this module. If specified and the module does contain a Dockerfile, this identifier is used when pushing the built image.
Type
Required
string
No

hotReload

Specifies which files or directories to sync to which paths inside the running containers of hot reload-enabled services when those files or directories are modified. Applies to this module's services, and to services with this module as their sourceModule.
Type
Required
object
No

hotReload.sync[]

​hotReload > sync
Specify one or more source files or directories to automatically sync into the running container.
Type
Required
array[object]
Yes

hotReload.sync[].source

​hotReload > sync > source
POSIX-style path of the directory to sync to the target, relative to the module's top-level directory. Must be a relative path. Defaults to the module's top-level directory if no value is provided.
Type
Default
Required
posixPath
"."
No
Example:
1
hotReload:
2
...
3
sync:
4
- source: "src"
Copied!

hotReload.sync[].target

​hotReload > sync > target
POSIX-style absolute path to sync the directory to inside the container. The root path (i.e. "/") is not allowed.
Type
Required
posixPath
Yes
Example:
1
hotReload:
2
...
3
sync:
4
- target: "/app/src"
Copied!

hotReload.postSyncCommand[]

​hotReload > postSyncCommand
An optional command to run inside the container after syncing.
Type
Required
array[string]
No
Example:
1
hotReload:
2
...
3
postSyncCommand:
4
- rebuild-static-assets.sh
Copied!

dockerfile

POSIX-style name of Dockerfile, relative to module root.
Type
Required
posixPath
No

services[]

A list of services to deploy from this container module.
Type
Default
Required
array[object]
[]
No

services[].name

​services > name
Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must start with a letter, and cannot end with a dash), cannot contain consecutive dashes or start with garden, or be longer than 63 characters.
Type
Required
string