Garden v0.11 is finally out! 🎉

The big story here (and the reason why this release took a little longer than planned) is the migration from Helm 2 to Helm 3. We also used the chance to include some other breaking changes we had been lining up. These are mostly deprecated config styles that we're now dropping support for. Some are also UX improvements, for example Garden now throws an error when two modules have overlapping paths and Garden can't automatically detect which build context belongs to which module. Please review the full migration guide below and don't hesitate to get in touch on our community Slack if you run into any issues.

Beyond the breaking changes, this release also contains a whole heap of bug fixes, several improvements, and new features. Among those are support for KinD, and new plugins for validating and testing configuration. Namely, a hadolint plugin for Dockerfile linting and a conftest plugin which can be used to validate Kubernetes manifests (among other things).

Take a look at our hadolint and conftest examples for details on how to use these plugins to your projects.

Also note that with this release we're changing from opt-in to opt-out analytics. Here's the PR that introduces that change. And here's the analytics section of our readme.

As always, a big thanks to our community for the feedback, bug reports, and moral support! And a special shout out to @mjgallag and @khaled for their contributions to this release.

You'll find the full changelog here.

Migrating from v0.10.x to v.11.y

TL;DR

1. Run garden migrate [--write] to update your garden.yml files so that they're compatible with v0.11.
2. Run garden plugins kubernetes cluster-init --env <env-name> for environments that use the kubernetes plugin (you only need to run this once per cluster).

About

We understand that breaking changes and migrations can be frustrating so we've tried our very best to make the transition as smooth as possible. We've added a migrate command for updating your configuration files, and wrapped the helm-2to3 plugin to update Helm resources to v3.

The Migrating to v0.11 guide below takes your through the steps needed to migrate to v0.11. For most projects this should only a take a few minutes.

Further down you'll find the Breaking Changes section which covers each breaking change in more detail, and at the bottom there's a Downgrading section.

Migrating to v0.11

Note that not all of these steps may apply to your setup.

Step 1: Update garden.yml config files

If your configuration is already compatible with v0.11, you can skip this step.

For most users affected by breaking config changes, running garden migrate will suffice to update your garden.yml configuration. You can run it with the --write flag to update the configs in place. Make sure to review the changes before commiting them.

Running the command is a no-op if your configuration is already compatible with v0.11.

Step 2: Add include/exclude to overlapping modules

If don't have modules with overlapping paths, you can skip this step.

If you have multiple modules that have overlapping module paths, and if Garden can't deduce what to include from the context, you need to explicitly set the module-level include or exclude fields.

Note that in a lot of cases, Garden can figure out what to include automatically, for example by parsing the Dockerfiles of container modules. When it can't, you'll need to set these explicitly.

If, for example, you have two exec modules in the same garden.yml file, this:

kind: module
name: backend
type: exec
...

---

kind: module
name: frontend
type: exec
...

needs to be updated to this:

kind: module
name: backend
type: exec
include: [backend/**/*]
...

---

kind: module
name: frontend
type: exec
include: [frontend/**/*]
...

You'll find more details in the include/exclude required if module paths overlap section below.

Step 3: Remove garden init from scripts

If you're not calling garden init from scripts or other automated workflows, you can skip this step.

The garden init command has been removed so you'll need to remove it from any scripts or CI pipelines that might be calling it.

Step 4: Run cluster-init

If you don't use the kubernetes plugin, you can skip this step.

Users that use the kubernetes provider will need to run:

garden plugins kubernetes cluster-init --env <env-name>

for each Kubernetes cluster.

Note you that don't need to run this command for the local-kubernetes provider.

Step 5: Remove Tiller from project namespace

If you don't use the kubernetes or the local-kubernetes plugin, or, if you need Tiller in your project namespace, you can skip this step.

Garden does not remove Tiller from project namespaces since some users may actually need it.

To remove it from your project namespace for environments that use the kubernetes provider, run:

garden plugins kubernetes remove-tiller --env <env-name>

To remove it from your project namespace for environments that use the local-kubernetes provider, run:

garden plugins local-kubernetes remove-tiller --env <env-name>

And that's it, you're done! See below for more details on each individual breaking change.

Please reach out on our community Slack if you run into any issues! We're here to help 🙂

Breaking Changes

Set default include on Helm modules

Garden now sets default includes on helm modules if they are not specifically set via the include/exclude field. Specifically:

If neither include nor exclude is set, and the module has local chart sources, Garden
automatically sets include to: ["*", "charts/**/*", "templates/**/*"].

If neither include nor exclude is set and the module specifies a remote chart, Garden
automatically sets ìnclude to [].

Affected Users

Users that use the helm module type, don't set include/exclude, and have local chart sources that are not captured by the default include set by Garden. That is, that have Helm charts that are not in the module root, the charts directory, or the templates directory.

What You Need To Do

If the defaults described above don't work for your module, you can set the include field manually. For example:

kind: Module
type: helm
include: ["*", "charts/**/*", "templates/**/*", "other/charts/**/*"]

include/exclude required if module paths overlap

If two or more modules have overlapping paths and Garden is unable to automatically detect what source files they should include, it will throw an error.

Garden can detect what to include for:

• helm modules
• container modules (as long as they don't have a Dockerfile with ADD/COPY statements that have . as the source)
• kubernetes modules

Affected Users

Users that have modules with overlapping paths, that don't set the include or exclude fields, and that Garden can't automatically set an include for.

What You Need To Do

Manually set the include or exclude fields for the modules in question.

Helm 2.x is no longer supported

Helm 2.x is no longer supported. The migration (both for garden-system services and your project namespace) is handled automatically via the helm 2to3 plugin. It is possible that the automatic migration fails though (due to any number of potential issues with Helm or issues exposed with individual charts upon upgrade).

We've tried to cover and test for these cases as best we can, but can't rule out issues, so you may need to intervene (by e.g. manually removing resources or using the helm CLI directly) if migration or upgrades after deployment throw errors.

If you do run into tricky issues, please don't hesitate to log issues on GitHub or ping us on Slack and we'll be happy to help.

Affected Users

Anyone using the kubernetes provider.

What You Need To Do

For environments that use the kubernetes provider, run

garden plugins kubernetes cluster-init --env <env-name>

You only need to run this once per Kubernetes cluster.

The garden init command has been removed

This command is no longer needed and its existence (and name) just caused confusion.

Affected Users

Users that were calling the garden init command from scripts.

What You Need To Do

Remove the command from any scripts that were calling it. You don't need to add anything in its place.

The environmentDefaults field has been removed

The previously deprecated project-level environmentDefaults field has been removed. Instead, users need to use the top-level variables, varfiles, and providers fields.

Affected Users

Anyone using the environmentDefaults field.

What You Need To Do

Run garden migrate [--write].

Alternatively, resolve manually by mapping:

• environmentDefaults.varfile to varfile
• environmentDefaults.variables to variables
• environmentDefaults.providers to providers

in your project-level configuration.

You can use the environments key on the provider configurations to limit them to specific environments. Omitting the environments key means the provider is used in all environments, and setting it to an empty array effectively disables the provider.

The local-openfaas provider and module type have been removed

It was redudant and fully compatible with the openfaas provider and module type.

Affected Users

Anyone using the local-openfaas provider.

What You Need To Do

Run garden migrate [--write].

Alternatively, replace references to local-openfaas with openfaas manually in your project configuration.

Support for top-level project and module fields in garden.yml configs has been removed

It's no longer possible to set project and module as top-level fields and nest the rest of the configuration under them. Instead, we set kind: Project | Module.

Affected Users

Anyone with project or module as top-level fields. For example:

project:
  name: my-project
...

---

module:
  name: my-module

What You Need To Do

Run garden migrate [--write].

Alternatively, remove the top-level project and module fields manually and use kind instead. For example, this:

project:
  name: my-project
...

---

module:
  name: my-module
...

becomes this:

kind: Project
name: my-project
...

---

kind: Module
name: my-module
...

Downgrading

If, for some reason, you need to downgrade back to v0.10, you'll need to perform the following steps.

Uninstall system services

First you'll need to uninstall system services that have been migrated to Helm v3. Note that this will delete any build and test caches. You can uninstall the services with:

garden plugin kubernetes uninstall-garden-services --env <env-name>

for the kubernetes provider, and with:

garden plugin local-kubernetes uninstall-garden-services --env <env-name>

for the local-kubernetes provider.

You'll need to run these command with v0.11 of Garden.

Remove showOptInMessage from global-config.yml

Garden v0.11 adds a showOptInMessage entry to the global user config, located at ~/.garden/global-config.yml. This entry is incompatible with the v0.10 config schema and you'll need to remove it before using Garden v0.10 again.