LogoLogo
Bonsai (0.13) DocsGitHubDiscord CommunityGarden Enterprise
Edge Release
Edge Release
  • 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
  • Reference
    • Providers
      • container
      • exec
      • jib
      • kubernetes
      • local-kubernetes
      • otel-collector
      • pulumi
      • terraform
    • Action Types
      • Build
        • container Build
        • exec Build
        • jib-container Build
      • Deploy
        • container Deploy
        • exec Deploy
        • helm Deploy
        • kubernetes 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
      • container
      • exec
      • helm
      • jib-container
      • kubernetes
      • pulumi
      • templated
      • terraform
  • Misc
    • FAQ
    • Troubleshooting
    • Telemetry
    • How Organizations Adopt Garden
    • New Garden Cloud Version
    • Migrating to Cedar
    • Migrating to Bonsai
    • Ingress NGINX Vulnerability
    • Deprecations
  • 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
  • Step 1 — Create a project
  • Step 2 — Configure Kubernetes provider
  • Step 3 — Add actions
  • Step 4 — Add more environments and providers
  • Summary

Was this helpful?

  1. Getting Started

Next Steps

PreviousGarden BasicsNextYour First Project

Last updated 1 month ago

Was this helpful?

If you've kicked the tires with the you've seen how Garden lets you spin up production-like environments for development, testing, and CI—with blazing fast caching.

Now is the time to set up Garden for your own project to get these benefits and more.

This guide describes the main steps involved. It's meant as a roadmap for the configuration process with links to more in-depth resources. The configuration snippets are mostly for demonstration purposes to help you understand how your config evolves.

For a more high level guide of adopting Garden in your organization, check out our .

Step 1 — Create a project

The first thing you need to do is to create a project level Garden config file at the root of your project, typically called garden.yml or project.garden.yml.

Here's a simple example:

# At the root of your project
apiVersion: garden.io/v2
kind: Project
name: my-project

environments: # <--- Every Garden project has one more environments
  - name: local
  - name: ci

Step 2 — Configure Kubernetes provider

Here we're assuming you're using Garden for Kubernetes workflows which is the most common use case. But you can also start with the or providers.

Next you need to tell Garden how to connect to your Kubernetes cluster by adding the relevant provider configuration to your project-level config file.

At that point, your configuration will look something like this:

# At the root of your project
apiVersion: garden.io/v2
kind: Project
name: my-project

environments:
  - name: local
  - name: ci

providers:
 - name: local-kubernetes
   environments: [local]
 - name: kubernetes
   environments: [ci]
   context: my-k8s-ctx
   # ...

Step 3 — Add actions

Once you've configured your provider, it's time to add actions.

Actions are the basic building blocks that make up your Garden project. The different action types determine how they're executed.

For example, you can use the container Build action and the kubernetes or helm Deploy actions to build and the deploy a given service.

We recommend putting each action in its own garden.yml file and locating it next to any source files.

Here's a simple example with actions for deploying an ephemeral database and an API server, and a Test action for running integration tests:

# In db/garden.yml
kind: Deploy
name: db
type: helm
description: Install Postgres via Helm
spec:
  chart:
    name: postgresql
    repo: https://charts.bitnami.com/bitnami
    version: "11.6.12"
---
kind: Run
name: db-init
type: container
description: Seed the DB after it's been deployed
dependencies: [deploy.db]
spec:
  image: postgres:11.6-alpine
  command: ["/bin/sh", "db-init-script.sh"]

# In api/garden.yml
kind: Build
name: api
type: container
description: Build the api image
---
kind: Deploy
name: api
type: kubernetes
description: Deploy the api after its been built and the DB seeded
dependencies: [build.api, run.db-init]
spec:
  manifestFiles: [ api-manifests.yml ]
---
kind: Test
name: api-integ
type: container
description: Integration testing the api after its been deployed
dependencies: [build.api, deploy.api]
spec:
  image: ${actions.build.api.outputs.deploymentImageId}
  command: [./integ-tests.sh]

Depending on the size of your project, you may want to add a handful of actions to get started and then gradually add more as needed.

Once that's done, you can deploy your project to a production-like environment with:

garden deploy

Similarly, you can run your integration or end-to-end tests in a production-like environment with:

garden test

Step 4 — Add more environments and providers

At this point, you should be able to deploy and test your project from your laptop in a single command with the Garden CLI.

Next step is to add more environments so you can e.g. create preview environments in your CI pipeline for every pull request.

You may also want to add our Terraform or Pulumi plugins if you're using those tools, following the same process as in step 2 and step 3 above.

Garden also lets you define variables and use templating to ensure the environments are configured correctly. Below is how you commonly configure environments with dynamic templating:

# At the root of your project
apiVersion: garden.io/v2
kind: Project
name: my-project

environments:
  - name: local
  - name: dev
    defaultNamespace: my-project-dev-${kebabCase(local.username)} # <--- Ensure each developer has a unique namespace
  - name: ci
    defaultNamespace: my-project-ci-${git.commitHash} # <--- Ensure each CI run is in a unique namespace
    variables:
      hostname: ${git.commitHash}.my-company.com # <--- Ensure CI test environments are isolated by templating in the commit hash
  - name: staging
    variables:
      hostname: staging.my-company.com

providers:
  - name: local-kubernetes
    environments: [local]
  - name: kubernetes
    environments: [dev, ci]
    namespace: ${enironment.namespace} # <--- This is the defaultNamespace we configured above
    context: my-ci-cluster
    # ...
  - name: kubernetes
    environments: [staging]
    namespace: staging
    context: my-staging-cluster
    # ...
  - name: terraform # <--- Use the Terraform plugin for the staging environment to provision cloud managed services
    environments: [staging]

# In api/garden.yml
kind: Deploy
name: api
type: kubernetes
spec:
  manifestFiles: "[path/to/your/${environment.name}/k8s/manifests]" # <--- Pick manifests based on env

Now, you can create preview environments on demand from your laptop with:

garden deploy --env dev

...or from your CI pipelines with:

garden deploy --env ci

Summary

And that's the gist of it!

We encourage you to try adding Garden to your own project. You won't need to change any of your existing code or configuration, only sprinkle in some Garden config files to codify your workflows and you'll be going from zero to a running system in a single command.

You can use if you have Kubernetes installed locally and for remote clusters (see config details in links).

Garden actions and their configuration can be spread across different files and even .

, our commercial offering, includes secrets management and RBAC to ensure you don’t need to add any secrets to your CI provider or setup secrets for development. This ensures 100% portability across all your environments.

Checkout our guide for more details.

And if you have any questions, don't hesitate to reach out to our .

Quickstart guide
Adopting Garden guide
Terraform
Pulumi
the local Kubernetes provider
the Kubernetes provider
across multiple git repos
Garden Enterprise
in-depth guide on configuring environments
our Discord community