Basics

Garden is a powerful tool but the basic concepts are quite simple. We highly recommend that you spend a few minutes reading through this guide to grasp them.

If you do that, everything else that follows should feel quite intuitive.

Anatomy of a Garden project

Every Garden project has the same structure: A project configuration and one or more actions.

As a convention, the project configuration is in a file called project.garden.yml, typically at the root of a given repo. A simple project configuration looks like this:

# In project.garden.yml
kind: Project
name: my-project
environments:
  - name: dev
  - name: ci

This is also where you configure your providers. If you're e.g. using Garden to deploy to a Kubernetes cluster, you'd add the relevant configuration here. For example:

# In project.garden.yml
kind: Project
name: my-project
environments:
  - name: dev
  - name: ci

providers:
  - name: local-kubernetes
    environments: [dev]
  - name: kubernetes # <--- Use a remote K8s cluster in CI
    environments: [ci]

Similarly you can add your Terraform and Pulumi configuration here.

Anatomy of a Garden action

Garden projects also have one or more actions. These actions can be spread across a repo in their own config files, often located next to the thing they describe. They can also be pulled in from other git repos.

Every Garden action has the same common fields like kind, name and type—and a spec field that is specific to the action type:

# In my-action/garden.yml
kind: Build # One of Build, Deploy, Run Test
name: my-action
type: exec # There's several different action types that determine how it's executed
spec: # The spec is unique to the action type
  # ...

The true power of Garden lies in the fact that actions can depend on one another and reference outputs from other actions. A simple but complete Garden project demonstrating this looks like this:

kind: Project
name: my-project
environements:
  - name: dev
---
kind: Run
name: run-a
type: exec
spec:
  command: ["echo", "Hello from A"]
---
kind: Run
name: run-b
type: exec
depenencies: [run.run-a]
spec:
  command: ["echo", "Action run-a says: ${actions.run.run-a.outputs.log}"]

If you run garden run run-b in this project it'll first run action run-a (because run-b depends on it) and then action run-b which prints the output from run-a.

And that is essentially the core concept: Actions run in dependency order and can reference the output from each other.

This is obviously a contrived example where we're using the exec action which just runs scripts on the host. For real world projects these actions could be containers, Helm charts and even entire Terraform stacks. So these seemingly simple concepts can be used to build very complex automations.

And Garden adds a lot smarts on top to make these executions fast, including smart graph-aware caching, accelerated container builds and more.

Wrapping up

For now, don't worry too much about the different action kinds and types. Just know that you can model a system of any complexity with this pattern, even if it's parts are spread across multiple repos.

Now that you understand the basic concept, check out our Recipes section which contains a lot of examples you can pull directly into your project.

And if you don't find you're looking for, feel free to open an issue on Github or ping us on Discord.