Deprecations and updating to Cedar

Deprecations and updating to Cedar

The next major version of Garden, 0.14 (Cedar), will contain breaking changes. To make the update as seamless as possible for your team, avoid functionality that has been deprecated in Garden 0.13.

When using apiVersion: garden.io/v1 in your project configuration file, Garden will warn you if your configuration depends on features that will be removed in Garden 0.14.

We recommend to opt-in to the new behaviour in Garden 0.14 by using apiVersion: garden.io/v2 which you can do already on the latest Garden 0.13 version. This setting will make Garden throw errors whenever it detects use of deprecated functionality.

If your config is using apiVersion: garden.io/v2 and you don't see any errors, you can safely update to 0.14 without the update affecting your workflows.

Garden commands

Login requirement

For projects that are connected to Garden Cloud/Enterprise, Garden 0.14 will require you to login.

To suppress this warning and adopt the new behaviour described below, change the apiVersion setting in your project-level configuration to garden.io/v2 (See also The apiVersion config field).

Why

Garden 0.14 will use the Garden Cloud/Enterprise backend for determining the cache status of Kubernetes Test and Run actions kinds (See also ConfigMap-based cache for Kubernetes actions).

While we also introduce a local file-based cache backend, this means the cache results from other team members will only be available when you're logged in to Garden Cloud/Enterprise.

Logging in also enables you to use our Remote Container Builder which can significantly improve your Docker build performance.

To prevent your team from suffering from cache misses and bad performance, we'll require you to log in if your project is connected to Garden Cloud/Enterprise. A project is connected if the project-level Garden configuration has id and domain fields set.

Offline mode

We don't want to be in your way if you can't log in right now, be it because you are lacking permissions or because you're offline.

This is why we also offer an escape hatch: If you want to proceed without logging in, just call Garden with the option --offline or the environment variable GARDEN_OFFLINE=1.

ConfigMap-based cache for Kubernetes actions

The ConfigMap-based cache will not be available anymore in Garden 0.14.

Instead, Garden 0.14 will introduce two new cache storage options: A local file-based cache and a Team Cache as part of Garden Cloud/Enterprise.

To suppress this warning, change the apiVersion setting in your project-level configuration to garden.io/v2 (See also The apiVersion config field).

Why

We are making this change because ConfigMap resources in your Kubernetes cluster are not designed for storing Test and Run action statuses and have limitations on the amount of data that can be stored for each cache entry.

We've seen Kubernetes clusters where the number of ConfigMap resources grew significantly and caused reliability issues.

Additionally, the storage location of the cache limits the functionality: it's impossible, for instance, to share test results across multiple Kubernetes clusters. If your team is using the local-kubernetes provider, they cannot benefit from the cache of other team members.

Team Cache backend

With Garden 0.14, we are offering a Team Cache option with a new storage backend in Garden Cloud/Enterprise, putting us in the position of bringing Garden caching capabilities to the next level.

The Team Cache backend will be enabled by default for all projects that are connected to Garden Cloud/Enterprise. A project is connected if the project-level Garden configuration has id and domain fields set.

We'll also introduce a login requirement for these projects. See also Login Requirement for more information.

File-based backend

For projects that aren't connected to Garden Cloud/Enterprise, or when you're using the --offline option, we will automatically fall back to a file-based cache backend.

Garden will skip Test and Run actions that already ran from your local machine, but team members and CI workflows won't be able to benefit from the cache entries on your local machine.

garden kubernetes cluster-init

This command will be removed in 0.14. Do not use this command. It has no effect.

garden sync start

The command garden sync start will only be available inside the dev console (garden dev) in the next major version of Garden, 0.14. Do not use it as a standalone Garden command.

Please run garden deploy --sync instead, to start the dev console.

You can also start the dev console by running garden dev and then use the sync start command inside the dev shell. The same applies to all other sync commands.

garden sync stop

The command garden sync stop will only be available inside the dev console (garden dev) in the next major version of Garden, 0.14. Do not use it as a standalone Garden command. Instead, we recommend running garden deploy --sync, or alternatively starting syncs inside the dev console (garden dev) using sync stop.

See also the deprecation notice for the garden sync start command.

garden sync restart

The command garden sync restart will only be available inside the dev console (garden dev) in the next major version of Garden, 0.14. Do not use it as a standalone Garden command.

See also the deprecation notice for the garden sync start command.

garden sync status

The command garden sync status will only be available inside the dev console (garden dev) in the next major version of Garden, 0.14. Do not use it as a standalone Garden command.

See also the deprecation notice for the garden sync start command.

Kubernetes provider configuration

The deploymentStrategy config field

The deploymentStrategy config field will be removed in Garden 0.14. Do not use this config field. It has no effect as the experimental support for blue/green deployments (via the blue-green strategy) has been removed.

Action configs

spec.files in kubernetes Deploy actions

spec.files in kubernetes Deploy actions will be removed in Garden 0.14. Use spec.manifestTemplates and/or spec.manifestFiles instead.

Using templates in Kubernetes manifest files

If you want to keep using the Garden template language in your Kubernetes manifest files, use spec.manifestTemplates.

If you need to keep your Kubernetes manifests files compatible with kubectl, in other words, you don't want to use the Garden template language in your manifest files, use spec.manifestFiles instead.

Example:

# garden.yml
kind: Deploy
type: kubernetes
name: my-app
spec:
 manifestFiles:
   - manifests/**/*.yml # <-- Treat these files as pure Kubernetes manifest files
 manifestTemplates:
   - manifests/**/*.yml.tpl # <-- Use the Garden template language in files that end with `.yml.tpl`.

Why

Until now there wasn't a choice: Garden would always attempt to resolve template strings like ${fooBar} in Kubernetes manifest files.

This becomes problematic when, for example, the Kubernetes manifest contains a bash script:

# manifests/bash-script.yml
apiVersion: v1
kind: ConfigMap
metadata:
 name: bash-scripts
data:
   important-bash-script.sh: |
     #!/bin/bash
     echo "hello ${USERNAME:=world}"

This manifest file is valid and works when applied using kubectl apply < manifests/bash-script.yml.

Using this manifest file like so will not work as expected, but throw a template syntax error:

# garden.yml
kind: Deploy
type: kubernetes
name: bash-scripts
spec:
 files:
   - manifests/bash-script.yml # <-- Garden will parse template strings in `manifests/bash-script.yml` and fail with a syntax error.

One way to work around this problem in the past was to escape the template string by prepending a $ sign in the script; But this work-around also means that the manifest isn't compatible with kubectl apply anymore:

#!/bin/bash
echo "hello $${USERNAME:=world}" # <-- This is not a working bash script anymore :(

Errors when variables do not exist

When using apiVersion: garden.io/v1 in your project-level configuration, Garden will not throw errors when referencing variables or secrets that do not exist in Kubernetes manifest template files.

When using apiVersion: garden.io/v2 in the project-level configuration Garden will always throw an error when secrets or variables do not exist. If the secret or variable is meant to be optional, you can provide a default value using the logical or operator (Example: ${var.enable_xyz || false}).

Why

Ignoring errors when referencing variables or secrets that do not exist can lead to confusing follow-up problems in your infrastructure, and even security issues.

Consider this example:

# manifests/cookie-config.yml
apiVersion: v1
kind: ConfigMap
metadata:
 name: cookie-config
data:
   cookie-encryption-key: ${secrets.COOKIE_ENCRYPTION_KEY}

In older versions of Garden or when using apiVersion: garden.io/v1 in your project-level configuration, the plain string ${secrets.COOKIE_ENCRYPTION_KEY} might end up being used as an insecure encryption key, if the secret named COOKIE_ENCRYPTION_KEY did not exist.

Starting with Garden Cedar and when using apiVersion: garden.io/v1 in your project-level configuration, Garden will throw an error instead.

The build config field in container actions

Using the build config field in container actions will not be supported anymore in Garden 0.14.

Instead of using build, please reference the deploymentImageId output explicitly in each affected Deploy, Run and Test action spec of the container action type.

Other action types, like the exec, kubernetes and helm action types, are not affected and build can still be used to control the build staging directory of the action.

Referring to a container image via the build config field was confusing to some of our users, as it does not work for all action types that can reference containers, for example in kubernetes and helm actions configs.

That's why we decided to drop support for referencing container images via the build config field.

For example, a configuration like

kind: Build
name: backend
description: Backend service container image
type: container

---
kind: Deploy
name: backend
description: Backend service container
type: container
build: backend # <-- old config style uses `build` field. The `spec.image` did not need to be specified.

should be replaced with

kind: Build
name: backend
description: Backend service container image
type: container

---
kind: Deploy
name: backend
description: Backend service container
type: container
spec:
 image: ${actions.build.backend.outputs.deploymentImageId} # <--- the new config style is more explicit.

Garden automatically determines the execution order of actions (First building the backend container, then deploying the backend) based on the output references.

spec.waitForJobs in kubernetes Deploy actions

In Garden 0.14, the default value of spec.waitForJobs will change to true.

This means that Deploy actions will wait for Jobs to complete by default when applying Job manifests.

To suppress this warning and adopt the new behaviour, change the apiVersion setting in your project-level configuration to garden.io/v2 (See also The apiVersion config field).

For more information about Jobs, please refer to the official Kubernetes documentation on Jobs.

Project configuration

The dotIgnoreFiles config field

The dotIgnoreFiles config field will be removed in Garden 0.14. Use the dotIgnoreFile field instead. It only allows specifying one filename.

For more information, please refer to the dotIgnoreFile reference documentation.

The apiVersion config field

Garden 0.14 will introduce breaking changes.

Garden uses the apiVersion setting in your project configuration to understand which version of Garden your configuration has been written for.

Garden 0.14 (Cedar) will only support the setting apiVersion: garden.io/v2 in your project configuration file. Using this setting in the latest versions of Garden 0.13 (Bonsai) will reject using functionality that is not supported in Garden 0.14 (Cedar) anymore.

Using apiVersion: garden.io/v0, or not specifying apiVersion at all in the project configuration, indicates the configuration has been written for Garden version 0.12 (Acorn), and using apiVersion: garden.io/v1 means your configuration has been written for Garden version 0.13 (Bonsai). These settings will not be supported anymore in Garden 0.14 (Cedar).

Full Example:

# project.garden.yml
apiVersion: garden.io/v1 # <-- This indicates that the configuration has been written for Garden 0.13 (Bonsai).
kind: Project
name: garden-core

environments:
- name: dev

providers:
- name: local-kubernetes

Please follow the steps in this document when Garden tells you that you're affected by changed behaviour in 0.14. After that, you can change your apiVersion setting to garden.io/v2:

# project.garden.yml
apiVersion: garden.io/v2 # <-- Use this setting to adopt the new behaviour in Garden 0.14. Your configuration will work with the latest versions of Garden 0.13, and with any version of Garden 0.14.
kind: Project
name: garden-core

environments:
- name: dev

providers:
- name: local-kubernetes

The modules config field

The modules config field will be removed in Garden 0.14. Do not use the modules field, as it has been renamed to scan. Please use the scan field instead.

For more information, please refer to the scan reference documentation.

Garden plugins

The hadolint plugin

Do not use the hadolint plugin explicitly, as it will be removed in the next version of Garden, 0.14.

Hadolint is a Dockerfile linter written in Haskell. It can be used to enforce best practices.

If you want to keep using hadolint, you can use an exec action instead:

kind: test
type: exec
name: dockerfile-hadolint
include: ["Dockerfile"]
spec:
 command: [hadolint, "Dockerfile"]

The octant plugin

Do not use the octant plugin explicitly, as it will be removed in the next version of Garden, 0.14.

The octant plugin does not have any effect since the integrated dashboard has been removed in Garden 0.13.0.

The conftest plugin

Do not use the conftest plugin explicitly, as it will be removed in the next version of Garden, 0.14.

Conftest is a utility to help you write tests against structured configuration data.

If you want to keep using conftest, you can use an exec action instead:

kind: test
type: exec
name: conftest
include:
- "policy/**/*.rego"
- deployment.yaml
spec:
 command: [conftest, test, deployment.yaml]

The ephemeral-kubernetes provider

Use the kubernetes or local-kubernetes providers instead. We are currently exploring how to improve and offer a new hosted Kubernetes experience in the future – reach out on GitHub or Discord if you are interested or have any feedback!

container provider configuration

The gardenCloudBuilder setting in the container provider configuration has been renamed to gardenContainerBuilder. Use the setting gardenContainerBuilder instead of gardenCloudBuilder.

Local mode

Using spec.localMode in helm, kubernetes and container Deploy actions

The local mode will be removed in the next major version of Garden, 0.14.

Use the sync mode instead. You can also consider using mirrord or telepresence.

See also:

• spec.localMode in the kubernetes Deploy action reference.
• spec.localMode in the helm Deploy action reference.
• spec.localMode in the container Deploy action reference.

Environment variables

GARDEN_LEGACY_BUILD_STAGE

Do not use GARDEN_LEGACY_BUILD_STAGE environment variable. It will be removed in Garden 0.14.

Using the rsync-based build staging is not necessary when using the latest versions of Garden.

If you still need to use this environment variable for some reason, please reach out to us on GitHub, Discord or via the customer support.

GARDEN_CLOUD_BUILDER

The GARDEN_CLOUD_BUILDER environment variable will be removed in Garden 0.14. Use GARDEN_CONTAINER_BUILDER instead.

Garden action types

The configmap Deploy action type

The configmap Deploy action type will be removed in the next major version of Garden, 0.14. Please use the kubernetes Deploy action type with a configmap Kubernetes manifest instead.

Example:

# garden.yml
kind: Deploy
type: kubernetes
name: game-demo-configmap
spec:
 manifests:
   - apiVersion: v1
     kind: ConfigMap
     metadata:
       name: game-demo
     data:
       player_initial_lives: "3"
       ui_properties_file_name: "user-interface.properties"
       game.properties: |
         enemy.types=aliens,monsters
         player.maximum-lives=5
       user-interface.properties: |
         color.good=purple
         color.bad=yellow
         allow.textmode=true

The persistentvolumeclaim Deploy action type

The persistentvolumeclaim Deploy action type will be removed in the next major version of Garden, 0.14. Please use the kubernetes Deploy action type instead.

For more information how to use Persistent Volume Claims using Kubernetes manifests, refer to the official Kubernetes documentation on configuring persistent volume storage.

Volume container action references

Volume container action references will be removed in Garden 0.14. Use the kubernetes action type instead of the container action type if you need persistent volume claims or mount configmaps.

Referencing persistentvolumeclaim and configmap action or module types from container Deploy actions will not be supported anymore in Garden 0.14.

See also the deprecation notices for the persistentvolumeclaim Deploy action type and the configmap Deploy action type.

Template Language

Optional template expressions

The optional template expression syntax will be removed in Garden 0.14. Use explicit fallback values instead, e.g. ${var.foo || null}.

The optional template expression syntax can be used to mark a template expression as optional, meaning there will not be an error when looking up a variable inside the template expression fails.

Using a question mark (?) following a template expression to mark it as optional led to surprising and/or undesired behaviour in some cases.

In the following example, users would expect var.fullUrl to evaluate to https://example.com/?param=xyz.

# ...
variables:
 baseUrl: https://example.com/
 fullUrl: ${var.baseUrl}?param=xyz # <-- users expect this to evaluate to https://example.com/?param=xyz

Due to the optional template expression syntax, the value behind var.fullUrl actually evaluates to https://example.com/param=xyz (Notice the missing question mark after the value of var.baseUrl) when using apiVersion: garden.io/v1.

For this reason, we will remove the optional template expression syntax. You can adopt the new behaviour and prepare your configuration files for the release of Garden 0.14 by using apiVersion: garden.io/v2 in the project-level configuration.

When using apiVersion: garden.io/v2, the optional template syntax has been removed and thus var.fullUrl evaluates to https://example.com/?param=xyz and resolving the action will fail if var.baseUrl doesn't exist.

You can use explicit fallback values using the logical or operator in case you've been relying on the optional template expression syntax.