LogoLogo
Bonsai (0.13) DocsGitHubDiscord CommunityGarden Enterprise
Docs Edge
Docs Edge
  • Welcome to Garden!
  • Overview
    • What is Garden
    • Use Cases
      • Isolated On-Demand Preview Environments
      • Fast, Portable CI Pipelines that Run Anywhere
      • Shift Testing Left
      • Local Development With Remote Clusters
      • Jumpstart your Internal Developer Platform
    • Garden vs Other Tools
  • Getting Started
    • Quickstart
    • Garden Basics
    • Next Steps
  • Tutorials
    • Your First Project
      • 1. Create a Garden Project
      • 2. Pick a Kubernetes Plugin
      • 3. Add Actions
      • 4. Add Tests
      • 5. Code Syncing (Hot Reload)
      • 6. Next Steps
    • Setting up a Kubernetes cluster
      • 1. Create a Cluster
        • AWS
        • GCP
        • Azure
      • 2. Configure Container Registry
        • AWS
        • GCP
        • Azure
        • Docker Hub
      • 3. Set Up Ingress, TLS and DNS
      • 4. Configure the Provider
  • Using Garden With
    • Containers
      • Using Remote Container Builder
      • Building Containers
    • Kubernetes
      • Using Remote Kubernetes
      • Using Local Kubernetes
      • Deploying K8s Resources
      • Installing Helm charts
      • Running Tests and Tasks
    • Terraform
      • Using Terraform
      • Applying Terrform Stacks
    • Pulumi
      • Using Pulumi
      • Applying Pulumi Stacks
    • Local Scripts
  • Features
    • Remote Container Builder
    • Team Caching
    • Variables and Templating
    • Config Templates
    • Workflows
    • Code Synchronization
    • Custom Commands
    • Remote Sources
  • Guides
    • Connecting a Project
    • Environments and Namespaces
    • Installing Garden
    • Including/Excluding files
    • Installing Local Kubernetes
    • Migrating from Docker Compose to Garden
    • Using the CLI
    • Using Garden in CircleCI
    • Minimal RBAC Configuration for Development Clusters
    • Deploying to Production
    • Using a Registry Mirror
    • Local mode
  • Reference
    • Providers
      • container
      • ephemeral-kubernetes
      • exec
      • jib
      • kubernetes
      • local-kubernetes
      • otel-collector
      • pulumi
      • terraform
    • Action Types
      • Build
        • container Build
        • exec Build
        • jib-container Build
      • Deploy
        • configmap Deploy
        • container Deploy
        • exec Deploy
        • helm Deploy
        • kubernetes Deploy
        • persistentvolumeclaim Deploy
        • pulumi Deploy
        • terraform Deploy
      • Run
        • container Run
        • exec Run
        • helm-pod Run
        • kubernetes-exec Run
        • kubernetes-pod Run
      • Test
        • container Test
        • exec Test
        • helm-pod Test
        • kubernetes-exec Test
        • kubernetes-pod Test
    • Template Strings
      • Project template context
      • Environment template context
      • Provider template context
      • Action (all fields) template context
      • Action spec template context
      • Module template context
      • Remote Source template context
      • Project Output template context
      • Custom Command template context
      • Workflow template context
      • Template Helper Functions
    • Commands
    • Project Configuration
    • ConfigTemplate Reference
    • RenderTemplate Reference
    • Workflow Configuration
    • Garden Containers on Docker Hub
    • Glossary
    • Module Template Configuration
    • Module Types
      • configmap
      • container
      • exec
      • helm
      • jib-container
      • kubernetes
      • persistentvolumeclaim
      • pulumi
      • templated
      • terraform
  • Misc
    • FAQ
    • Troubleshooting
    • Telemetry
    • How Organizations Adopt Garden
    • New Garden Cloud Version
    • Migrating to Bonsai
  • Contributing to Garden
    • Contributor Covenant Code of Conduct
    • Contributing to the Docs
    • Setting up Your Developer Environment
    • Developing Garden
    • Config Resolution
    • Graph Execution
Powered by GitBook
On this page
  • Anatomy of a Garden project
  • Anatomy of a Garden action
  • Benefits
  • Wrapping up

Was this helpful?

  1. Getting Started

Garden 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
apiVersion: garden.io/v2
kind: Project
name: my-project
environments:
  - name: dev
  - name: ci

This is also where you configure your providers. Providers are what enables you to use different action types. You e.g. need the kubernetes provider to use Helm actions.

So if you're using Garden to deploy to a Kubernetes cluster, you'd add the kubernetes or local-kubernetes provider configuration here. For example:

# In project.garden.yml
apiVersion: garden.io/v2
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]
    context: my-ctx

Garden projects also have one or more actions. These actions can be spread across the repo in their own config files, often located next to the thing they describe. A common way to structure a project is like this:

Note that Garden is very flexible and will work with whatever structure you currently have. It even works across git repositories! You can e.g. have your service source code in one repo and manifests in another. Or have your micro services split across multiple repos.

Anatomy of a Garden action

Actions are the building blocks of a Garden project and describe how a given part of your system is built, deployed, or tested.

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

The type tells Garden how to execute it. Garden will know to build container actions, install helm actions, apply terraform actions, and so on.

The true power of Garden lies in the fact that actions can depend on one another and reference outputs from other actions. Here's an example:

apiVersion: garden.io/v2
kind: Project
name: my-project
environments: # <--- Specifying environments is required
  - name: dev
---
kind: Run
name: say-hello
type: exec
spec:
  command: ["echo", "Hello ${local.username}"]
---
kind: Run
name: say-what
type: exec
dependencies: [run.say-hello]
spec:
  command: ["echo", "Action say-hello says: '${actions.run.say-hello.outputs.log}'"]

If you now run:

garden run say-what

...Garden will first run the say-hello action (because say-what depends on it) and then the say-what action which prints the output from say-hello:

Action say-hello says: 'Hello gardener'

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 an action that just runs scripts. For real world projects these actions could be containers, Helm charts and even entire Terraform stacks. You tell Garden the "type", and it'll know how to execute it. That's how these simple concepts can be used to build very complex automations.

Benefits

The example above that just runs simple scripts is pretty trivial but this same pattern allows you to build, deploy and test a system of any complexity in a single command. With a single Garden command you could for example:

  • provision an ephemeral K8s cluster via Terraform and pass the output to other actions;

  • then build and deploy all your services into an isolated environment in that cluster;

  • then run your integration and end-to-end tests before tearing things down again.

You can add this command to a CI job, and just as easily run it from your laptop. You can also create re-usable config templates that you can share with your team.

Garden does more than just run the actions and interface with providers. It builds your containers faster thanks to our Remote Container Builder and caches the results of actions so that they don't run unless they have to, significantly speeding up the execution time.

The gif below shows the test caching in action:

Wrapping up

Don't worry too much about the different action kinds and types, we have plenty of examples to help you pick the right one. Just know that you can model a system of any complexity with this pattern, even if it's components are spread across multiple repos.

PreviousQuickstartNextNext Steps

Last updated 1 month ago

Was this helpful?

Garden project structure
The anatomy of an action
Run a test that passes then run it again. Note that the second time it's cached.

And if you have any questions, feel free to open an issue on Github or ping us on .

Discord
The anatomy of an action
The anatomy of an action
Garden project structure
Garden project structure