# 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 <a href="#loginrequirement" id="loginrequirement"></a>

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](#apiversion)).

#### 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](#configmapbasedcache)).

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 <a href="#configmapbasedcache" id="configmapbasedcache"></a>

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](#apiversion)).

#### 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](#loginrequirement) 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` <a href="#kubernetesclusterinitcommand" id="kubernetesclusterinitcommand"></a>

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

### `garden sync start` <a href="#syncstartcommand" id="syncstartcommand"></a>

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` <a href="#syncstopcommand" id="syncstopcommand"></a>

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](#syncstartcommand).

### `garden sync restart` <a href="#syncrestartcommand" id="syncrestartcommand"></a>

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](#syncstartcommand).

### `garden sync status` <a href="#syncstatuscommand" id="syncstatuscommand"></a>

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](#syncstartcommand).

## Kubernetes provider configuration

### The `deploymentStrategy` config field <a href="#containerdeploymentstrategy" id="containerdeploymentstrategy"></a>

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 <a href="#kubernetesactionspecfiles" id="kubernetesactionspecfiles"></a>

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

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

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

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

```bash
#!/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:

```yaml
# 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 <a href="#buildconfigfieldonruntimeactions" id="buildconfigfieldonruntimeactions"></a>

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

```yaml
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

```yaml
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 <a href="#waitforjobs" id="waitforjobs"></a>

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](#apiversion)).

For more information about Jobs, please refer to the [official Kubernetes documentation on Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/).

## Project configuration

### The `dotIgnoreFiles` config field <a href="#dotignorefiles" id="dotignorefiles"></a>

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](https://docs.garden.io/bonsai-0.13/reference/project-config#dotIgnoreFile).

### The `apiVersion` config field <a href="#apiversion" id="apiversion"></a>

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:

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

```yaml
# 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 <a href="#projectconfigmodules" id="projectconfigmodules"></a>

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](https://docs.garden.io/bonsai-0.13/reference/project-config#scan).

## Garden plugins

### The `hadolint` plugin <a href="#hadolintplugin" id="hadolintplugin"></a>

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

[Hadolint](https://github.com/hadolint/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:

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

### The `octant` plugin <a href="#octantplugin" id="octantplugin"></a>

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 <a href="#conftestplugin" id="conftestplugin"></a>

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

[Conftest](https://www.conftest.dev/) 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:

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

### The `ephemeral-kubernetes` provider <a href="#ephemeralkubernetesprovider" id="ephemeralkubernetesprovider"></a>

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 <a href="#gardencloudbuilder" id="gardencloudbuilder"></a>

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 <a href="#localmode" id="localmode"></a>

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](https://mirrord.dev/) or [telepresence](https://www.telepresence.io/).

See also:

* [`spec.localMode` in the `kubernetes` Deploy action reference](https://docs.garden.io/bonsai-0.13/reference/action-types/deploy/container#spec.localmode).
* [`spec.localMode` in the `helm` Deploy action reference](https://docs.garden.io/bonsai-0.13/reference/action-types/deploy/helm#spec.localmode).
* [`spec.localMode` in the `container` Deploy action reference](https://docs.garden.io/bonsai-0.13/reference/action-types/deploy/container#spec.localmode).

## Environment variables

### `GARDEN_LEGACY_BUILD_STAGE` <a href="#rsyncbuildstaging" id="rsyncbuildstaging"></a>

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` <a href="#gardencloudbuilderenvvar" id="gardencloudbuilderenvvar"></a>

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 <a href="#configmapdeployaction" id="configmapdeployaction"></a>

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:

```yaml
# 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 <a href="#persistentvolumeclaimdeployaction" id="persistentvolumeclaimdeployaction"></a>

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](https://kubernetes.io/docs/tasks/configure-pod-container/configure-persistent-volume-storage/).

### Volume container action references <a href="#containervolumeactions" id="containervolumeactions"></a>

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](#persistentvolumeclaimdeployaction) and [the `configmap` Deploy action type](#configmapdeployaction).

## Template Language

### Optional template expressions <a href="#optionaltemplatevaluesyntax" id="optionaltemplatevaluesyntax"></a>

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`.

```yaml
# ...
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.