Specify a Helm chart (either in your repository or remote from a registry) to deploy. Refer to the Helm guide for usage instructions.

Below is the schema reference. For an introduction to configuring Garden modules, please look at our Configuration guide. The first section lists and describes the available schema keys. The second section contains the complete YAML schema.

helm modules also export values that are available in template strings under ${modules.<module-name>.outputs}. See the Outputs section below for details.

Configuration keys

apiVersion

The schema version of this module's config (currently not used).

kind

type

The type of this module.

Example:

type: "container"

name

The name of this module.

Example:

name: "my-sweet-module"

description

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.

Example:

include:
  - Dockerfile
  - my-app.js

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 guidefor details.

Example:

exclude:
  - tmp/**/*
  - '*.log'

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: #

Garden will import the repository source code into this module, but read the module's config from the local garden.yml file.

Example:

repositoryUrl: "git+https://github.com/org/repo.git#v2.0"

allowPublish

When false, disables pushing this module to remote registries.

build

Specify how to build the module. Note that plugins may define additional keys on this object.

build.dependencies[]

​build > dependencies

A list of modules that must be built before this module is built.

Example:

build:
  ...
  dependencies:
    - name: some-other-module-name

build.dependencies[].name

​build > dependencies > name

Module name to build ahead of this module.

build.dependencies[].copy[]

​build > dependencies > copy

Specify one or more files or directories to copy from the built dependency to this module.

build.dependencies[].copy[].source

​build > dependencies > copy > source

POSIX-style path or filename of the directory or file(s) to copy to the target.

build.dependencies[].copy[].target

​build > dependencies > copy > target

POSIX-style path or filename to copy the directory or file(s).

base

The name of another helm module to use as a base for this one. Use this to re-use a Helm chart across multiple services. For example, you might have an organization-wide base chart for certain types of services. If set, this module will by default inherit the following properties from the base module: serviceResource, values Each of those can be overridden in this module. They will be merged with a JSON Merge Patch (RFC 7396).

Example:

base: "my-base-chart"

chart

A valid Helm chart name or URI (same as you'd input to helm install). Required if the module doesn't contain the Helm chart itself.

Example:

chart: "stable/nginx-ingress"

chartPath

The path, relative to the module path, to the chart sources (i.e. where the Chart.yaml file is, if any). Not used when base is specified.

dependencies

List of names of services that should be deployed before this chart.

releaseName

Optionally override the release name used when installing (defaults to the module name).

repo

The repository URL to fetch the chart from.

serviceResource

The Deployment, DaemonSet or StatefulSet that Garden should regard as the Garden service in this module (not to be confused with Kubernetes Service resources). Because a Helm chart can contain any number of Kubernetes resources, this needs to be specified for certain Garden features and commands to work, such as hot-reloading. We currently map a Helm chart to a single Garden service, because all the resources in a Helm chart are deployed at once.

serviceResource.kind

​serviceResource > kind

The type of Kubernetes resource to sync files to.

serviceResource.name

​serviceResource > name

The name of the resource to sync to. If the chart contains a single resource of the specified Kind, this can be omitted. This can include a Helm template string, e.g. ''. This allows you to easily match the dynamic names given by Helm. In most cases you should copy this directly from the template in question in order to match it. Note that you may need to add single quotes around the string for the YAML to be parsed correctly.

serviceResource.containerName

​serviceResource > containerName

The name of a container in the target. Specify this if the target contains more than one container and the main container is not the first container in the spec.

serviceResource.containerModule

​serviceResource > containerModule

The Garden module that contains the sources for the container. This needs to be specified under serviceResource in order to enable hot-reloading for the chart, but is not necessary for tasks and tests. Must be a container module, and for hot-reloading to work you must specify the hotReload field on the container module. Note: If you specify a module here, you don't need to specify it additionally under build.dependencies

Example:

serviceResource:
  ...
  containerModule: "my-container-module"

serviceResource.hotReloadArgs[]

​serviceResource > hotReloadArgs

If specified, overrides the arguments for the main container when running in hot-reload mode.

Example:

serviceResource:
  ...
  hotReloadArgs:
    - nodemon
    - my-server.js

skipDeploy

Set this to true if the chart should only be built, but not deployed as a service. Use this, for example, if the chart should only be used as a base for other modules.

tasks

The task definitions for this module.

tasks[].name

​tasks > name

The name of the task.

tasks[].description

​tasks > description

A description of the task.

tasks[].dependencies[]

​tasks > dependencies

The names of any tasks that must be executed, and the names of any services that must be running, before this task is executed.

tasks[].timeout

​tasks > timeout

Maximum duration (in seconds) of the task's execution.

tasks[].resource

​tasks > resource

The Deployment, DaemonSet or StatefulSet that Garden should use to execute this task. If not specified, the serviceResource configured on the module will be used. If neither is specified, an error will be thrown.

tasks[].resource.kind

​tasks > resource > kind

The type of Kubernetes resource to sync files to.

tasks[].resource.name

​tasks > resource > name

The name of the resource to sync to. If the chart contains a single resource of the specified Kind, this can be omitted. This can include a Helm template string, e.g. ''. This allows you to easily match the dynamic names given by Helm. In most cases you should copy this directly from the template in question in order to match it. Note that you may need to add single quotes around the string for the YAML to be parsed correctly.

tasks[].resource.containerName

​tasks > resource > containerName

The name of a container in the target. Specify this if the target contains more than one container and the main container is not the first container in the spec.

tasks[].resource.containerModule

​tasks > resource > containerModule

The Garden module that contains the sources for the container. This needs to be specified under serviceResource in order to enable hot-reloading for the chart, but is not necessary for tasks and tests. Must be a container module, and for hot-reloading to work you must specify the hotReload field on the container module. Note: If you specify a module here, you don't need to specify it additionally under build.dependencies

Example:

tasks:
  - resource:
      ...
      containerModule: "my-container-module"

tasks[].resource.hotReloadArgs[]

​tasks > resource > hotReloadArgs

If specified, overrides the arguments for the main container when running in hot-reload mode.

Example:

tasks:
  - resource:
      ...
      hotReloadArgs:
        - nodemon
        - my-server.js

tasks[].command[]

​tasks > command

The command/entrypoint used to run the task inside the container.

Example:

tasks:
  - command:
    - /bin/sh
    - '-c'

tasks[].args[]

​tasks > args

The arguments to pass to the pod used for execution.

Example:

tasks:
  - args:
    - rake
    - 'db:migrate'

tasks[].env

​tasks > env

Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with GARDEN) and values must be primitives or references to secrets.

Example:

tasks:
  - env:
      MY_VAR: some-value
      MY_SECRET_VAR:
        secretRef:
          name: my-secret
          key: some-key

tests

The test suite definitions for this module.

tests[].name

​tests > name

The name of the test.

tests[].dependencies[]

​tests > dependencies

The names of any services that must be running, and the names of any tasks that must be executed, before the test is run.

tests[].timeout

​tests > timeout

Maximum duration (in seconds) of the test run.

tests[].resource

​tests > resource

The Deployment, DaemonSet or StatefulSet that Garden should use to execute this test suite. If not specified, the serviceResource configured on the module will be used. If neither is specified, an error will be thrown.

tests[].resource.kind

​tests > resource > kind

The type of Kubernetes resource to sync files to.

tests[].resource.name

​tests > resource > name

The name of the resource to sync to. If the chart contains a single resource of the specified Kind, this can be omitted. This can include a Helm template string, e.g. ''. This allows you to easily match the dynamic names given by Helm. In most cases you should copy this directly from the template in question in order to match it. Note that you may need to add single quotes around the string for the YAML to be parsed correctly.

tests[].resource.containerName

​tests > resource > containerName

The name of a container in the target. Specify this if the target contains more than one container and the main container is not the first container in the spec.

tests[].resource.containerModule

​tests > resource > containerModule

The Garden module that contains the sources for the container. This needs to be specified under serviceResource in order to enable hot-reloading for the chart, but is not necessary for tasks and tests. Must be a container module, and for hot-reloading to work you must specify the hotReload field on the container module. Note: If you specify a module here, you don't need to specify it additionally under build.dependencies

Example:

tests:
  - resource:
      ...
      containerModule: "my-container-module"

tests[].resource.hotReloadArgs[]

​tests > resource > hotReloadArgs

If specified, overrides the arguments for the main container when running in hot-reload mode.

Example:

tests:
  - resource:
      ...
      hotReloadArgs:
        - nodemon
        - my-server.js

tests[].args[]

​tests > args

The arguments to pass to the pod used for testing.

tests[].env

​tests > env

Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with GARDEN) and values must be primitives or references to secrets.

Example:

tests:
  - env:
      MY_VAR: some-value
      MY_SECRET_VAR:
        secretRef:
          name: my-secret
          key: some-key

version

The chart version to deploy.

values

Map of values to pass to Helm when rendering the templates. May include arrays and nested objects. When specified, these take precedence over the values in the values.yaml file (or the files specified in valueFiles).

valueFiles

Specify value files to use when rendering the Helm chart. These will take precedence over the values.yaml file bundled in the Helm chart, and should be specified in ascending order of precedence. Meaning, the last file in this list will have the highest precedence.

If you also specify keys under the values field, those will effectively be added as another file at the end of this list, so they will take precedence over other files listed here.

Note that the paths here should be relative to the module root, and the files should be contained in your module directory.

Complete YAML schema

apiVersion: garden.io/v0
kind: Module
type:
name:
description:
include:
exclude:
repositoryUrl:
allowPublish: true
build:
  dependencies:
    - name:
      copy:
        - source:
          target: <same as source path>
base:
chart:
chartPath: .
dependencies: []
releaseName:
repo:
serviceResource:
  kind: Deployment
  name:
  containerName:
  containerModule:
  hotReloadArgs:
skipDeploy: false
tasks:
  - name:
    description:
    dependencies: []
    timeout: null
    resource:
      kind: Deployment
      name:
      containerName:
      containerModule:
      hotReloadArgs:
    command:
    args:
    env: {}
tests:
  - name:
    dependencies: []
    timeout: null
    resource:
      kind: Deployment
      name:
      containerName:
      containerModule:
      hotReloadArgs:
    args:
    env: {}
version:
values: {}
valueFiles: []

Outputs

The following keys are available via the ${modules.<module-name>} template string key for helm modules.

modules.<module-name>.buildPath

The build path of the module.

Example:

buildPath: "/home/me/code/my-project/.garden/build/my-module"

modules.<module-name>.path

The local path of the module.

Example:

path: "/home/me/code/my-project/my-module"

modules.<module-name>.version

The current version of the module.

Example:

version: "v-17ad4cb3fd"

modules.<module-name>.outputs

The outputs defined by the module.

modules.<module-name>.outputs.release-name

​outputs > release-name

The Helm release name of the service.