Container Modules

Search…
Container Modules
Garden includes a container module type, which provides a high-level abstraction around container-based services, that's easy to understand and use.
container modules can be used to just build container images, or they can specify deployable services through the optional services key, as well as tasks and tests. So you might in one scenario use a container module to both build and deploy services, and in another you might only build the image using a container module, and then refer to that image in a helm or kubernetes module.
Below we'll walk through some usage examples. For a full reference of the container module type, please take a look at the reference.
Note: Even though we've spent the most time on supporting Kubernetes, we've tried to design this module type in a way that makes it generically applicable to other container orchestrators as well, such as Docker Swarm, Docker Compose, AWS ECS etc. This will come in handy as we add more providers, that can then use the same module type.
Building images
A bare minimum container module just specifies common required fields:
1
# garden.yml
2
kind: Module
3
type: container
4
name: my-container
Copied!
If you have a Dockerfile next to this file, this is enough to tell Garden to build it. You can also specify dockerfile: <path-to-Dockerfile> if you need to override the Dockerfile name. You might also want to explicitly include or exclude files in the build context.
Build arguments
You can specify build arguments using the buildArgs field. This can be quite handy, especially when e.g. referencing other modules such as build dependencies:
1
# garden.yml
2
kind: Module
3
type: container
4
name: my-container
5
build:
6
  depdendencies: [base-image]
7
buildArgs:
8
  baseImageVersion: ${modules.base-image.version}
Copied!
Garden will also automatically set GARDEN_MODULE_VERSION as a build argument, so that you can reference the version of module being built.
Using remote images
If you're not building the container image yourself and just need to deploy an external image, you can skip the Dockerfile and specify the image field:
1
# garden.yml
2
kind: Module
3
type: container
4
name: redis
5
image: redis:5.0.5-alpine   # <- replace with any docker image ID
6
services:
7
  ...
Copied!
Note that if there is a Dockerfile in the same directory as the module configuration, and you still don't want to build it, you have to tell Garden not to pick it up by setting include: [] in your module configuration.
Publishing images
You can publish images that have been built in your cluster using the garden publish command.
Unless you're publishing to your configured deployment registry (when using the kubernetes provider), you need to specify the image field on the container module in question to indicate where the image should be published. For example:
1
kind: Module
2
name: my-module
3
image: my-repo/my-image:v1.2.3   # <- if you omit the tag here, the Garden module version will be used by default
4
...
Copied!
By default, we use the tag specified in the container module image field, if any. If none is set there, we default to the Garden module version.
You can also set the --tag option on the garden publish command to override the tag used for images. You can both set a specific tag or you can use template strings for the tag. For example, you can
Set a specific tag on all published modules: garden publish --tag "v1.2.3"
Set a custom prefix on tags but include the Garden version hash: garden publish --tag 'v0.1-${module.hash}'
Set a custom prefix on tags with the current git branch: garden publish --tag 'v0.1-${git.branch}'
Note that you most likely need to wrap templated tags with single quotes, to prevent your shell from attempting to perform its own substitution.
Generally, you can use any template strings available for module configs for the tags, with the addition of the following:
${module.name} — the name of the module being tagged
${module.version} — the full Garden version of the module being tagged, e.g. v-abcdef1234
${module.hash} — the Garden version hash of the module being tagged, e.g. abcdef1234 (i.e. without the v- prefix)
Deploying services
container modules also have an optional services field, which you can use to deploy the container image using your configured providers (such as kubernetes/local-kubernetes).
In the case of Kubernetes, Garden will take the simplified container service specification and convert it to the corresponding Kubernetes manifests, i.e. Deployment, Service and (if applicable) Ingress resources.
Here, for example, is the spec for the frontend service in our example demo project:
1
kind: Module
2
name: frontend
3
description: Frontend service container
4
type: container
5
services:
6
  - name: frontend
7
    ports:
8
      - name: http
9
        containerPort: 8080
10
    healthCheck:
11
      httpGet:
12
        path: /hello-frontend
13
        port: http
14
    ingresses:
15
      - path: /hello-frontend
16
        port: http
17
      - path: /call-backend
18
        port: http
19
    dependencies:
20
      - backend
21
...
Copied!
This, first of all, tells Garden that it should deploy the built frontend container as a service with the same name. We also configure a health check, a couple of ingress endpoints, and specify that this service depends on the backend service. There is a number of other options, which you can find in the container module reference.
If you need to use advanced (or otherwise very specific) features of the underlying platform, you may need to use more platform-specific module types (e.g. kubernetes or helm). The container module type is not intended to capture all those features.
Environment variables
Container services can specify environment variables, using the services[].env field:
1
kind: Module
2
type: container
3
name: my-container
4
services:
5
  - name: my-container-service
6
    ...
7
    env:
8
      MY_ENV_VAR: foo
9
      MY_TEMPLATED_ENV_VAR: ${var.some-project-variable}
10
    ...
11
...
Copied!
env is a simple mapping of "name: value". Above, we see a simple example with a string value, but you'll also commonly use template strings to interpolate variables to be consumed by the container service.
Secrets
As of Garden v0.10.1 you can reference secrets in environment variables. For Kubernetes, this translates to valueFrom.secretKeyRef fields in the Pod specs, which direct Kubernetes to mount values from Secret resources that you have created in the application namespace, as environment variables in the Pod.
For example:
1
kind: Module
2
type: container
3
name: my-container
4
services:
5
  - name: my-container-service
6
    ...
7
    env:
8
      MY_SECRET_VAR:
9
        secretRef:
10
          name: my-secret
11
          key: some-key-in-secret
12
    ...
13
...
Copied!
This will pull the some-key-in-secret key from the my-secret Secret resource in the application namespace, and make available as an environment variable.
Note that you must create the Secret manually for the Pod to be able to reference it.
For Kubernetes, this is commonly done using kubectl. For example, to create a basic generic secret you could use:
1
kubectl --namespace <my-app-namespace> create secret generic --from-literal=some-key-in-secret=foo
Copied!
Where <my-app-namespace> is your project namespace (which is either set with namespace in your provider config, or defaults to your project name). There are notably other, more secure ways to create secrets via kubectl. Please refer to the offical Kubernetes Secrets docs for details.
Also check out the Kubernetes Secrets example project for a working example.
Running tests
You can define both tests and tasks as part of any container module. The two are configured in very similar ways, using the tests and tasks keys, respectively. Here, for example, is a configuration for two different test suites:
1
kind: Module
2
type: container
3
name: my-container
4
...
5
tests:
6
  - name: unit
7
    command: [npm, test]
8
  - name: integ
9
    command: [npm, run, integ]
10
    dependencies:
11
      - some-service
12
...
Copied!
Here we first define a unit test suite, which has no dependencies, and simply runs npm test in the container. The integ suite is similar but adds a runtime dependency. This means that before the integ test is run, Garden makes sure that some-service is running and up-to-date.
When you run garden test or garden dev we will run those tests. In both cases, the tests will be executed by running the container with the specified command in your configured environment (as opposed to locally on the machine you're running the garden CLI from).
The names and commands to run are of course completely up to you, but we suggest naming the test suites consistently across your different modules.
See the reference for all the configurable parameters for container tests.
Running tasks
Tasks are defined very similarly to tests:
1
kind: Module
2
type: container
3
name: my-container
4
...
5
tasks:
6
  - name: db-migrate
7
    command: [rake, db:migrate]
8
    dependencies:
9
      - my-database
10
...
Copied!
In this example, we define a db-migrate task that runs rake db:migrate (which is commonly used for database migrations, but you can run anything you like of course). The task has a dependency on my-database, so that Garden will make sure the database is up and running before running the migration task.
Unlike tests, tasks can also be dependencies for services and other tasks. For example, you might define another task or a service with db-migrate as a dependency, so that it only runs after the migrations have been executed.
One thing to note, is that tasks should in most cases be idempotent, meaning that running the same task multiple times should be safe.
See the reference for all the configurable parameters for container tasks.
Referencing from other modules
Modules can reference outputs from each other using template strings. container modules are, for instance, often referenced by other module types such as helm module types. For example:
1
kind: Module
2
description: Helm chart for the worker container
3
type: helm
4
name: my-service
5
...
6
build:
7
  dependencies: [my-image]
8
values:
9
  image:
10
    name: ${modules.my-image.outputs.deployment-image-name}
11
    tag: ${modules.my-image.version}
Copied!
Here, we declare my-image as a dependency for the my-service Helm chart. In order for the Helm chart to be able to reference the built container image, we must provide the correct image name and version.
For a full list of keys that are available for the container module type, take a look at the outputs reference.
Mounting volumes
container services, tasks and tests can all mount volumes, using volume modules. One such is the persistentvolumeclaim module type, supported by the kubernetes provider. To mount a volume, you need to define a volume module, and reference it using the volumes key on your services, tasks and/or tests.
Example:
1
kind: Module
2
name: my-volume
3
type: persistentvolumeclaim
4
spec:
5
  accessModes: [ReadWriteOnce]
6
  resources:
7
    requests:
8
      storage: 1Gi
9
---
10
kind: Module
11
name: my-module
12
type: container
13
services:
14
  - name: my-service
15
    replicas: 1  # <- Important! Unless your volume supports ReadWriteMany, you can't run multiple replicas with it
16
    volumes:
17
      - name: my-volume
18
        module: my-volume
19
        containerPath: /volume
20
    ...
Copied!
This will mount the my-volume PVC at /volume in the my-service service when it is run. The my-volume module creates a PersistentVolumeClaim resource in your project namespace, and the spec field is passed directly to the same field on the PVC resource.
Notice the accessModes field in the volume module above. The default storage classes in Kubernetes generally don't support being mounted by multiple Pods at the same time. If your volume module doesn't support the ReadWriteMany access mode, you must take care not to use the same volume in multiple services, tasks or tests, or multiple replicas. See Shared volumes below for how to share a single volume with multiple Pods.
You can do the same for tests and tasks using the tests.volumes and tasks.volumes fields. persistentvolumeclaim volumes can of course also be referenced in kubernetes and helm modules, since they are deployed as standard PersistentVolumeClaim resources.
Take a look at the persistentvolumeclaim module type and container module docs for more details.
Mounting Kubernetes ConfigMaps
Very similarly to the above example, you can also mount Kubernetes ConfigMaps on container modules using the configmap module type, supported by the kubernetes provider. Here's a simple example:
Example:
1
kind: Module
2
name: my-configmap
3
type: configmap
4
data:
5
  config.properties: |
6
    some: data
7
    or: something
8
---
9
kind: Module
10
name: my-module
11
type: container
12
services:
13
  - name: my-service
14
    volumes:
15
      - name: my-configmap
16
        module: my-configmap
17
        containerPath: /config
18
    ...
Copied!
This mounts all the keys in the data field on the my-configmap module under the /config directory in the container. In this case, you'll find the file /config/config.properties there, with the value above (some: data ...) as the file contents.
You can do the same for tests and tasks using the tests.volumes and tasks.volumes fields. configmap volumes can of course also be referenced in kubernetes and helm modules, since they are deployed as standard ConfigMap resources.
Take a look at the configmap module type and container module docs for more details.
Shared volumes
For a volume to be shared between multiple replicas, or multiple services, tasks and/or tests, it needs to be configured with a storage class (using the storageClassName field) that supports the ReadWriteMany (RWX) access mode. The available storage classes that support RWX vary by cloud providers and cluster setups, and in many cases you need to define a StorageClass or deploy a storage class provisioner to your cluster.
You can find a list of storage options and their supported access modes here. Here are a few commonly used RWX provisioners and storage classes:
​NFS Server Provisioner​
​Azure File​
​AWS EFS Provisioner​
​Ceph (via Rook)​
Once any of those is set up you can create a persistentvolumeclaim module that uses the configured storage class. Here, for example, is how you might use a shared volume with a configured azurefile storage class:
1
kind: Module
2
name: shared-volume
3
type: persistentvolumeclaim
4
spec:
5
  accessModes: [ReadWriteMany]
6
  resources:
7
    requests:
8
      storage: 1Gi
9
  storageClassName: azurefile
10
---
11
kind: Module
12
name: my-module
13
type: container
14
services:
15
  - name: my-service
16
    volumes:
17
      - &volume   # <- using a YAML anchor to re-use the volume spec in tasks and tests
18
        name: shared-volume
19
        module: shared-volume
20
        containerPath: /volume
21
    ...
22
tasks:
23
  - name: my-task
24
    volumes:
25
      - *volume
26
    ...
27
tests:
28
  - name: my-test
29
    volumes:
30
      - *volume
31
    ...
Copied!
Here the same volume is used across a service, task and a test in the same module. You could similarly use the same volume across multiple container modules.
Guides - Previous
Code Synchronization (Dev Mode)
Next - Guides
Helm Charts
Last modified 2mo ago
Copy link
Contents
Environment variables
Running tests
Running tasks
Referencing from other modules
Mounting volumes
Mounting Kubernetes ConfigMaps
Shared volumes