LogoLogo
Bonsai (0.13) DocsGitHubDiscord CommunityGarden Enterprise
Bonsai (0.13)
Bonsai (0.13)
  • Welcome to Garden!
  • 🌸Overview
    • How Garden Works
    • Core Concepts
    • Adopting Garden
    • Garden vs Other Tools
  • 🌳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
  • 🌻Getting Started
    • Quickstart Guide
    • Installing Garden
    • 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
  • 🌿Using Garden
    • About
    • Configuration Overview
    • Projects
    • Dashboard
    • Actions
    • Tests
    • Runs
    • Workflows
    • Variables and templating
    • Config Templates
    • Using the CLI
    • Modules
  • Kubernetes Plugins
    • About
    • Remote K8s Plugin Configuration
      • 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
    • Local K8s Plugin Configuration
      • 1. Install Local Kubernetes
      • 2. Configure the Provider
    • Ephemeral K8s Plugin Configuration
      • 1. Configure the Provider
      • 2. Login to the Garden dashboard
      • 3. Configure Ingress (optional)
      • 4. Retrieve Kubeconfig (optional)
    • Actions
      • Build
        • Container
      • Deploy
        • Kubernetes
        • Helm
        • Container
        • PersistentVolumeClaim
        • ConfigMap
      • Run and Test
        • Kubernetes Pod
        • Helm Pod
        • Kubernetes Exec
        • Container
    • Guides
      • In-Cluster Building
      • Minimal RBAC Configuration for Development Clusters
      • Deploying to Production
      • Using a Registry Mirror
  • ☘️Terraform Plugin
    • About
    • Plugin Configuration
    • Actions
  • 🌹Pulumi Plugin
    • About
    • Plugin Configuration
    • Actions
  • 🌼Other Plugins
    • Container
    • Exec (local scripts)
  • 🌷Guides
    • Migrating to Bonsai
    • Migrating from Docker Compose to Garden
    • Deprecations and updating to Cedar
    • Code Synchronization
    • Connecting a local application to a Kubernetes cluster (Local Mode)
    • Environments and namespaces
    • Using Garden in CircleCI
  • 🪷Advanced
    • Using Remote Sources
    • Custom Commands
  • 🎋Reference
    • Providers
      • conftest-container
      • conftest-kubernetes
      • conftest
      • container
      • ephemeral-kubernetes
      • exec
      • hadolint
      • jib
      • kubernetes
      • local-kubernetes
      • octant
      • 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
        • conftest-helm Test
        • conftest Test
        • container Test
        • exec Test
        • hadolint 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
    • Module Template Configuration
    • Module Types
      • configmap
      • conftest
      • container
      • exec
      • hadolint
      • helm
      • jib-container
      • kubernetes
      • persistentvolumeclaim
      • pulumi
      • templated
      • terraform
  • 🌸Misc
    • FAQ
    • Troubleshooting
    • Telemetry
    • New Garden Cloud Version
  • 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
  • Project Structure and Configuration
  • How do I include Builds with multiple Dockerfiles in the same directory?
  • Should I .gitignore the .garden dir?
  • How do I disable actions based on environments?
  • When should I use the action-level include/exclude fields? How are they different from the project-level scan.include/scan.exclude fields? What about ignore files?
  • How do I share a single service (like a database) across multiple namespaces?
  • How do I share code between Build actions?
  • What do all those v-<something> versions mean, and why are they different between building and deploying?
  • Builds
  • How do I target a specific image from a multi-stage Dockerfile?
  • How do I use base images?
  • Can I use runtime variables in builds (e.g. from Runs or Tests)?
  • How do I view container build logs?
  • Can I use a Dockerfile that lives outside the action directory?
  • How do I include files/dirs (e.g. shared libraries) from outside the action root with the build context?
  • How do I add Docker specific flags to the build command?
  • How do I use different Dockerfiles for different environments?
  • Remote Building
  • How do I delete the services in the garden-system namespace?
  • How do I pull a base image (using the FROM directive) from a private registry in in-cluster build mode?
  • How do I use my own private registry in in-cluster build mode?
  • Tests and Runs
  • Can I run a Run on only the first time a service starts but not on subsequent restarts/rebuilds?
  • If a Test has a Run as a dependency, is the Run re-run every time before the Test?
  • Why is my Run not running on garden deploy?
  • How do I clear cached Run results?
  • Secrets
  • How do I pass secrets to container actions?
  • How do I mount secrets as volumes?
  • Can I use Kubernetes secrets as buildArgs for docker Builds?
  • Can I access secrets across namespaces (e.g. if I have a global secret namespace)?
  • Volumes and Data
  • How do I mount persistent volumes?
  • How do I access files that are generated at runtime (e.g. migration files that are checked into version control)?
  • Kubernetes
  • How do I annotate ingresses with container actions?
  • What versions and variations of Kubernetes does Garden support?
  • Can I add Kubernetes-specific fields to container actions (e.g. annotations and labels)?
  • How do I avoid being rate limited by Docker Hub?
  • Local scripts
  • How do I execute long running local scripts?
  • Can I receive traffic to local service Telepresence style?
  • Misc
  • How do I install the edge release of Garden
  • When are you releasing the Plugin SDK?
  • How does Garden resolve the *.local.demo.garden domain?
  • Does garden support bi-directional syncing?
  • Is Garden stable or should I wait for 1.0?
  • Does Garden work offline?
  • How do I disable terminal colors?

Was this helpful?

  1. Misc

FAQ

PreviousMiscNextTroubleshooting

Last updated 2 months ago

Was this helpful?

Project Structure and Configuration

How do I include Builds with multiple Dockerfiles in the same directory?

You will have to use the top-level directive to specify which files belong to each Build. You will also have to provide the path to the Dockerfile with the directive.

See the for more.

Should I .gitignore the .garden dir?

Yes.

How do I disable actions based on environments?

You can use the disabled field to disable actions. See .

When should I use the action-level include/exclude fields? How are they different from the project-level scan.include/scan.exclude fields? What about ignore files?

Read all about it in of our docs.

How do I share a single service (like a database) across multiple namespaces?

We recommend using the Terraform or Pulumi actions for cloud services that are shared by your team.

You can also deploy kubernetes and helm actions to their own namespaces.

How do I share code between Build actions?

Alternatively you can hoist your garden.yml file so that it is at the same level or parent to all relevant build context and use the include field.

What do all those v-<something> versions mean, and why are they different between building and deploying?

You may notice that a version of a Build action is different from the version the Deploy for that Build. This is because the Deploy's version also factors in the runtime configuration for that deploy, which often differs between environments, but we don't want those changes to require a rebuild.

Builds

How do I target a specific image from a multi-stage Dockerfile?

How do I use base images?

Can I use runtime variables in builds (e.g. from Runs or Tests)?

Yes, but only since Garden 0.13.

How do I view container build logs?

Set the log-level to verbose or higher. For example:

garden build --log-level verbose

Can I use a Dockerfile that lives outside the action directory?

Yes. Generally Dockerfiles need to be in the same directory or a child directory relative to your Garden action but you can always set the source path for the action with the source.path field.

For example, let's say you have the following project structure:

.
├── api
│   ├── garden.yml
│   ├── manifests
│   └── src
└── dockerfiles
    └── api.dockerfile

In this case the recommended approach is to set the source.path field like so:

# In ./api/garden.yml
kind: Build
name: api
type: container
source:
  path: ../ # <--- Set the action source to the project root
include: [./api/**/*, ./dockerfiles/api.dockerfile] # <--- We need to specify includes since we told Garden the action source is at the root. The includes are relative to the source path we set.
spec:
  dockerfile: api.dockerfile # <--- If our Dockerfile isn't called 'Dockerfile' we need to specify the name here
---
kind: Deploy
name: api
type: kubernetes
spec:
  files: [./manifests/*] # <--- The Deploy action source path is still the ./api directory and specify the manifests with relative to it

Alternatively you can hoist the garden.yml for the api to the root of the project and e.g. call it api.garden.yml. In that case your config will look like this:

# In api.garden.yml
kind: Build
name: api
type: container
include: [./api/**/*, ./dockerfiles/api.dockerfile] # <--- We need to specify includes because the action is at the root of the project.
spec:
  dockerfile: api.dockerfile # <--- If our Dockerfile isn't called 'Dockerfile' we need to specify the name here
---
kind: Deploy
name: api
type: kubernetes
spec:
  files: [./api/manifests/*] # <--- The action config is at the root so we need to include the `./api` dir here

How do I include files/dirs (e.g. shared libraries) from outside the action root with the build context?

How do I add Docker specific flags to the build command?

How do I use different Dockerfiles for different environments?

spec:
  dockerfile: "${environment.name == 'prod' ? Dockerfile.prod : Dockerfile.dev}"

Remote Building

How do I delete the services in the garden-system namespace?

Please do not delete the garden-system namespace directly, because Kubernetes may fail to remove persistent volumes. Instead, use this command:

garden plugins kubernetes uninstall-garden-services --env <env-name>

It removes all cluster-wide Garden services.

How do I pull a base image (using the FROM directive) from a private registry in in-cluster build mode?

See this section of our docs.

How do I use my own private registry in in-cluster build mode?

See this section of our docs.

Tests and Runs

Can I run a Run on only the first time a service starts but not on subsequent restarts/rebuilds?

We've been pondering this, but there are a lot of variants to consider. The key issue is really that the notion of "first time" is kind of undefined as things stand.

So what we generally do is to make sure Runs are idempotent and exit early if they shouldn't run again. But that means the process still needs to be started, which is of course slower than not doing it at all.

If a Test has a Run as a dependency, is the Run re-run every time before the Test?

It is, which is why we recommend that Runs are written to be idempotent. Runs by nature don’t really have a status check, unlike Deploys.

Why is my Run not running on garden deploy?

The Run result is likely cached. Garden won't run Runs with cached results unless spec.cacheResult: false is set on the Run definition.

You can also run it manually with:

garden run <run-name>

This will run the Run even if the result is cached.

How do I clear cached Run results?

Garden stores the Run results as a ConfigMap in your namespace. You can delete them manually with this command:

kubectl delete -n <your-namespace> $(kubectl get configmap -n <your-namespace> -o name | grep run-result)

You can also run it manually with:

garden run <run-name>

This will run the Run even if the result is cached.

Secrets

How do I pass secrets to container actions?

How do I mount secrets as volumes?

Can I use Kubernetes secrets as buildArgs for docker Builds?

Also note that secrets as buildArgs are considered a bad practice and a security risk.

Can I access secrets across namespaces (e.g. if I have a global secret namespace)?

Volumes and Data

How do I mount persistent volumes?

How do I access files that are generated at runtime (e.g. migration files that are checked into version control)?

Kubernetes

How do I annotate ingresses with container actions?

What versions and variations of Kubernetes does Garden support?

Garden interfaces with your cluster via kubectl and by using the Kubernetes APIs directly and should therefore work with all Kubernetes clusters that implement these. Garden is committed to supporting the latest six stable versions of Kubernetes.

Can I add Kubernetes-specific fields to container actions (e.g. annotations and labels)?

No, you have to use the kubernetes action type for that.

How do I avoid being rate limited by Docker Hub?

We're in the process of applying for becoming a Verified Docker Publisher which should significantly reduce the chance of being rate limited.

In the meantime, you have the following options:

Option 1 — Crate a Docker Hub image pull secret:

Then add the name and namespace of the secret you created to the imagePullSecrets field of the Kubernetes provider:

kind: Project
name: my-project
#...
providers:
  - name: kubernetes
    imagePullSecrets:
      - name: <the-secret-name>
        namespace: <the-secret-namespace>

This also works for the local-kubernetes and ephemeral-kubernetes providers.

Option 2 — Use a registry mirror:

If you already have your own Docker Hub registry mirror set up you can use that by setting the utilImageRegistryDomain field on the Kubernetes provider:

kind: Project
name: my-project
#...
providers:
  - name: kubernetes
    utilImageRegistryDomain: https://<my-private-registry-domain>

This also works for the local-kubernetes and ephemeral-kubernetes providers.

Local scripts

How do I execute long running local scripts?

Can I receive traffic to local service Telepresence style?

Misc

How do I install the edge release of Garden

You can install the edge release of Garden by using the Garden self-update command like so:

garden self-update edge-bonsai

When are you releasing the Plugin SDK?

We're exploring how we can release it incrementally. Please let us know if this is something you're interested in.

How does Garden resolve the *.local.demo.garden domain?

The *.local.demo.garden domain resolves to 127.0.0.1 via our DNS provider for convenience. If you want to use a different hostname for local development, you’ll have to add the corresponding entry to your hosts file.

Does garden support bi-directional syncing?

Is Garden stable or should I wait for 1.0?

Garden is currently in use by many teams. We don’t have a set date or plan to label it as 1.0, but we don't expect to do it anytime soon.

Does Garden work offline?

Garden is not currently designed to work in air-gapped environments but if you have done the initial setup and use a local kubernetes provider it might work.

How do I disable terminal colors?

You can disable terminal colors with the NO_COLOR environment variable. For example:

NO_COLOR=1 garden deploy

You can use the for that. See .

See this for more discussion on the two approaches.

These are the Garden versions that are computed for each action in the Stack Graph at runtime, based on source files and configuration for each action. See for more information about how these work and how they're used.

Use the .

See .

If you need the Dockerfile outside of the Build root because you want to share it with other Build actions, you could also consider having a single base image instead and then let each action have its own Dockerfile that's built on the base image. See the for an example of this.

See .

Use the .

You can use the field. For example:

See also the for an example of this.

See of our docs.

You'll need to use the kubernetes or action types for that. Here's the official for mounting secrets as files.

No, Kubernetes secrets can only be used at runtime, by referencing them in the spec.env field of Run, Deploy and Test Actions. See of our docs for more.

No, secrets have to be in the same namespace as the project. This is how Kubernetes secrets are designed, see .

See of our docs.

You can generate the files via a Run, store them as artifacts, and copy them from the local artifacts directory. of this.

You can also use the action type to store data and share it across actions. See of our docs for more.

You can set annotations on ingresses under the .

Garden uses a handful of utility images that are hosted on under the gardendev repository and under heavy usage, users can get rate limited when deploying them.

First follow the steps in to create an image pull secret for Docker Hub.

By setting persistent: true on exec Deploy actions. for more.

Yes, by using the localMode field on the relevant Deploy action. for details.

You can learn more about .

Yes! two-way sync mode can be configured with Garden sync mode. See

We have a team of people working on it full-time, and we make it a priority to address all non-trivial bugs. We’re also happy to help out and answer questions via .

🌸
GitHub issue
this example project
base image example project
this example project
base image example project
helm
Kubernetes guide
here for reference
persistentvolumeclaim
this section
Docker Hub
this guide
See here
this guide
our Discord community
configuration overview documentation
this example project
this section of the actions documentation
Here's an example
this section
here
See here
updating Garden here
include
spec.dockerfile
copyFrom directive
spec.targetStage field
spec.extraFlags field
spec.dockerfile
spec.ingresses[] field
this section
the secrets section
this section