container

Description

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

​build > targetImage
For multi-stage Dockerfiles, specify which image to build (see https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target for details).
Type
Required
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
Yes

services[].dependencies[]

​services > dependencies
The names of any services that this service depends on at runtime, and the names of any tasks that should be executed before this service is deployed.
Type
Default
Required
array[string]
[]
No

services[].disabled

​services > disabled
Set this to true to disable the service. You can use this with conditional template strings to enable/disable services based on, for example, the current environment or other variables (e.g. enabled: \${environment.name != "prod"}). This can be handy when you only need certain services for specific environments, e.g. only for development.
Disabling a service means that it will not be deployed, and will also be ignored if it is declared as a runtime dependency for another service, test or task.
Note however that template strings referencing the service's outputs (i.e. runtime outputs) will fail to resolve when the service 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

services[].annotations

​services > annotations
Annotations to attach to the service (note: May not be applicable to all providers).
When using the Kubernetes provider, these annotations are applied to both Service and Pod resources. You can generally specify the annotations intended for both Pods or Services here, and the ones that don't apply on either side will be ignored (i.e. if you put a Service annotation here, it'll also appear on Pod specs but will be safely ignored there, and vice versa).
Type
Default
Required
object
{}
No
Example:
1
services:
2
- annotations:
3
nginx.ingress.kubernetes.io/proxy-body-size: '0'
Copied!

services[].command[]

​services > command
The command/entrypoint to run the container with when starting the service.
Type
Required
array[string]
No
Example:
1
services:
2
- command:
3
- /bin/sh
4
- '-c'
Copied!

services[].args[]

​services > args
The arguments to run the container with when starting the service.
Type
Required
array[string]
No
Example:
1
services:
2
- args:
3
- npm
4
- start