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
  • How it works
  • Deploying your Pulumi stacks
  • Referencing stack outputs in other Garden actions
  • Plugin commands
  • Pulumi varfile schema
  • Next steps

Was this helpful?

  1. Using Garden With

Pulumi

PreviousApplying Terrform StacksNextUsing Pulumi

Last updated 1 month ago

Was this helpful?

The Pulumi plugin is already being used in large projects, but is still considered experimental. Please let us know if you have any questions or if any issues come up!

Garden includes an experimental Pulumi plugin that wraps the Pulumi CLI. This way, you can incorporate Pulumi stacks into your Garden project with minimal extra configuration. The benefits of using this plugin include:

  • Leveraging Garden's dependency semantics with your Pulumi stacks.

    • For example, Kubernetes actions can depend on infrastructure deployed with Pulumi (and access stack outputs via the ${actions.deploy.[pulumi-deploy-action-name].outputs}) key).

    • Deploy, preview, update, refresh or destroy Pulumi stacks in dependency order with a single command.

  • Fast incremental deploys that use Garden's versioning system in combination with Pulumi stack tags to implement efficient service status checks.

We strongly recommend that you (if you haven't already) before using it with Garden.

How it works

Internally, Garden simply wraps the Pulumi CLI, calling the appropriate Pulumi CLI commands to deploy, delete or check the status of a service.

The Pulumi plugin can optionally make use of stack tags to implement fast service status checks, which can be a major boost to performance when deploying projects containing several Pulumi stacks.

Finally, the plugin defines several plugin-specific commands that let you run Pulumi commands in one or more Pulumi deploy actions in dependency order (which can be very useful for projects with several Pulumi stacks).

Deploying your Pulumi stacks

Once you've got your Pulumi deploy actions configured, they will be deployed when you run garden deploy in your project; just like any other Garden deploy!

Referencing stack outputs in other Garden actions

Pulumi stacks can define .

Garden's dependency graph functionality is a great fit for stack references. For example, if pulumi-deploy-action-a's Pulumi program uses a stack references to an IP address that's an output of pulumi-deploy-action-b's Pulumi program, you can add a dependency on pulumi-deploy-action-b by referencing that output:

kind: Deploy
type: pulumi
name: pulumi-deploy-action-a
spec:
  cacheStatus: true
  # Here, you should list all stack references used by this action's pulumi program.
  stackReferences:
    - ${actions.deploy.pulumi-deploy-action-b.outputs.ip-address}
  # Make sure to add a dependency on each pulumi action you're using for stack references
  # above (otherwise an error will be thrown when you deploy).
  dependencies:
    - deploy.pulumi-deploy-action-b

This ensures that Garden deploys pulumi-deploy-action-b before pulumi-deploy-action-a when running e.g. garden deploy.

If you make sure to include all stack references to Pulumi deploy actions in your project in the stackReferences field, you can safely set cacheStatus: true for your deploy action, since Garden will factor the stack output values into its version calculations.

If cacheStatus is set to false, Garden runs pulumi up on every deploy. While this is safe and easy to reason about, it's much slower and more resource-intensive than using cacheStatus = true.

This is because running pulumi up is a much more expensive operation (in terms of CPU, RAM and time used) than the calls to pulumi stack tag set/get that Garden uses when cacheStatus = true.

With that in mind, we recommend using cacheStatus = true in your pulumi deploy actions whenever possible, once you've made sure you've included all relevant stack references in your pulumi deploy action configs. However, setting cacheStatus = true is only possible for Pulumi cloud managed state backends.

Plugin commands

The pulumi plugin also comes with plugin-specific commands, which are designed to run pulumi commands in dependency order (and with access to Garden's full config/templating capabilities).

The currently available plugin commands are:

  • preview

  • cancel

  • refresh

  • destroy

  • reimport Each of the above wraps the pulumi command with the same name, except for reimport (which wraps pulumi export | pulumi import—a workflow that's occasionally needed).

By default, each command runs for every pulumi deploy action in the project. Each plugin command also accepts an optional list of pulumi deploy action names as CLI arguments.

When a list of deploy action names is provided, the pulumi command will only be run for those deploy actions (still in dependency order).

For example:

garden plugins pulumi preview -- my-pulumi-deploy-action my-other-pulumi-deploy-action

Pulumi varfile schema

By default Garden uses a schema for the Pulumi varfiles that expects all content in a varfile to be values that are set under the config key in the pulumi config file. Garden will resolve any template strings in varfiles and then add them to the config section of the pulumi config file.

Example of old varfile schema:

kubernetes:context: orbstack
pulumi-k8s:namespace: ns-from-the-varfile

Since this does not allow for setting other top-level values like e.g. secretsprovider this schema has been updated and now requires config values to be referenced under the config key.

Example of new varfile schema:

secretsprovider: gcpkms://projects/xyz/locations/global/keyRings/pulumi/cryptoKeys/pulumi-secrets
encryptedkey: 123456
config:
  kubernetes:context: orbstack
  pulumi-k8s:namespace: ns-from-the-varfile

To use the new schema in a single pulumi deploy action set action.spec.useNewPulumiVarfileSchema to true. To use the new schema for all of your pulumi deploy actions set useNewPulumiVarfileSchema in your pulumi provider to true. The flag will be removed in the next major release and the new schema will be used.

Next steps

These can then be read by other Pulumi stacks via .

Check out the project.

Also take a look at the and the for details on all the configuration parameters.

If you're having issues with pulumi itself, please refer to the .

learn about Pulumi
stack outputs
stack references
pulumi example
pulumi provider reference
pulumi's deploy action type reference
official docs