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

Was this helpful?

  1. Using Garden With
  2. Containers

Building Containers

You can build containers with the container Build action:

kind: Build
name: api
type: container

Most commonly you'll then want to deploy this image or use it in Test or Run actions. You can do that by referencing the output from the build in your Deploy actions via the ${actions.build.outputs.api.<output-name>} template string.

For example, to deploy this image with Helm you can use the following config:

kind: Deploy
name: api
type: helm
dependencies: [build.api] # <--- We need to specify the dependency here
spec:
  values:
    repository: ${actions.build.api.outputs.deploymentImageName}
    tag: ${actions.build.api.version}

Or you can set it in your Kubernetes manifests with the patchResources field:


kind: Deploy
type: kubernetes
name: api
dependencies: [build.api] # <--- We need to specify the dependency here
spec:
  files: [my-manifests.yml]
  patchResources:
    - name: api # <--- The name of the resource to patch, should match the name in the K8s manifest
      kind: Deployment # <--- The kind of the resource to patch
      patch:
        spec:
          template:
            spec:
              containers:
                - name: api # <--- Should match the container name from the K8s manifest
                  image: ${actions.build.api.outputs.deployment-image-id} # <--- The output from the Build action

Examples

Building images

Following is a bare minimum Build action using the container type:

# garden.yml
kind: Build
type: container
name: my-container

Setting build arguments

# garden.yml
kind: Build
type: container
name: my-container
# Here, we ensure that the base image is built first. This is useful e.g. when you want to build a prod and a
# dev/testing variant of the image in your pipeline.
dependencies: [ build.base-image ]
spec:
  buildArgs:
    baseImageVersion: ${actions.build.base-image.version}

Using remote images

If you're not building the container image yourself and just need to deploy an image that already exists in a registry, you need to specify the image in the Deploy action's spec:

# garden.yml
kind: Deploy
type: container
name: redis
spec:
  image: redis:5.0.5-alpine   # <- replace with any docker image ID

Doing multi-platform builds

Garden supports building container images for multiple platforms and architectures. Use the platforms configuration field, to configure the platforms you want to build for e.g.:

# garden.yml
kind: Build
type: container
name: my-container
spec:
  platforms: ["linux/amd64", "linux/arm64"]

In-cluster building with kaniko does not support multi-platform builds.

The local-docker build backend requires some additional configurations. Docker Desktop users can enable the experimental containerd image store to also store multi-platform images locally. All other local docker solutions e.g. orbstack, podman currently need a custom buildx builder of type docker-container. Documemtation for both can be found here https://docs.docker.com/build/building/multi-platform. If your local docker image store does not support storing multi-platform images, consider configuring an environment where you only build single platform images when building locally e.g.:

# garden.yml
kind: Build
type: container
name: my-container
spec:
  platforms:
    $if: ${environment.name == "local"}
    $then: [ "linux/amd64"]
    $else: [ "linux/amd64", "linux/arm64" ]

Or you can specifiy to push your locally build images to a remote registry. If you are also using a Kubernetes provider and have a deploymentRegistry defined, the image will be pushed to this registry by default. If you are using garden only for building with the container provider, you can achieve the same behavior by specifying --push as an extra flag in your container action and setting localId to your registry name.

Publishing images

You can publish images that have been built in your cluster using the garden publish command.

Unless you're publishing to your configured deployment registry (when using the kubernetes provider), you need to specify the publishId field on the container action's spec in question to indicate where the image should be published. For example:

kind: Build
name: my-build
type: container
spec:
  publishId: my-repo/my-image:v1.2.3   # <- if you omit the tag here, the Garden action version will be used by default

By default, we use the tag specified in the container action's spec.publishId field. If none is set, we default to the corresponding Build action's version.

You can also set the --tag option on the garden publish command to override the tag used for images. You can both set a specific tag or you can use template strings for the tag. For example, you can

  • Set a specific tag on all published builds: garden publish --tag "v1.2.3"

  • Set a custom prefix on tags but include the Garden version hash: garden publish --tag 'v0.1-${build.hash}'

  • Set a custom prefix on tags with the current git branch: garden publish --tag 'v0.1-${git.branch}'

Note that you most likely need to wrap templated tags with single quotes, to prevent your shell from attempting to perform its own substitution.

Generally, you can use any template strings available for action configs for the tags, with the addition of the following:

  • ${build.name} — the name of the build being tagged

  • ${build.version} — the full Garden version of the build being tagged, e.g. v-abcdef1234

  • ${build.hash} — the Garden version hash of the build being tagged, e.g. abcdef1234 (i.e. without the v- prefix)

PreviousUsing Remote Container BuilderNextKubernetes

Last updated 1 month ago

Was this helpful?

You can learn more in the individual guides for the Kubernetes and actions.

If you have a Dockerfile in the same directory as this file, this is enough to tell Garden to build it. However, you can override the Dockerfile name or path by specifying spec.dockerfile: <path-to-Dockerfile>. You might also want to explicitly files in the build context.

You can specify using the field. This can be quite handy, especially when e.g. referencing other Build action as build dependencies:

Additionally, Garden automatically sets GARDEN_ACTION_VERSION as a build argument, which you can use to reference the version of action being built. You use it internally as a . For instance, to set versions, render docs, or clear caches.

Garden interacts with several local and remote builders. Currently support for multi-platform builds varies based on the builder backend. The following build backends support multi-platform builds out of the box: , cluster-buildkit, kaniko.

Deploy
Run and Test
include or exclude
Docker buildArg
Garden Container Builder
build arguments
spec.buildArgs