Comment on page
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
- 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.
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).
Once you've got your Pulumi deploy actions configured, they will be deployed when you run
garden deployin your project; just like any other Garden deploy!
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-bby referencing that output:
# Here, you should list all stack references used by this action's pulumi program.
# 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).
This ensures that Garden deploys
pulumi-deploy-action-awhen running e.g.
If you make sure to include all stack references to Pulumi deploy actions in your project in the
stackReferencesfield, you can safely set
cacheStatus: truefor your deploy action, since Garden will factor the stack output values into its version calculations.
cacheStatusis set to
false, Garden runs
pulumi upon 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 upis a much more expensive operation (in terms of CPU, RAM and time used) than the calls to
pulumi stack tag set/getthat Garden uses when
cacheStatus = true.
With that in mind, we recommend using
cacheStatus = truein 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 = trueis only possible for Pulumi cloud managed state backends.
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:
reimportEach of the above wraps the pulumi command with the same name, except for
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).
garden plugins pulumi preview -- my-pulumi-deploy-action my-other-pulumi-deploy-action