Pulumi CLI for LocalStack
DISCLAIMER: pulumi-local currently does not support the aws-native package. (pulumi/pulumi-aws-native #108)
This package provides the pulumilocal command, which is a thin wrapper around the pulumi
command line interface to use Pulumi with LocalStack.
Installation
You can install the pulumilocal command via pip:
pip install pulumi-local
Prerequisites
Please make sure you have a LocalStack instance running on your local machine.
Usage
The pulumilocal command has the same usage as the pulumi command. For detailed usage,
please refer to the man pages of pulumi -h.
Add environment variables to store state on local backend (optional)
export PULUMI_CONFIG_PASSPHRASE=lsdevtest
export PULUMI_BACKEND_URL=file://`pwd`/myproj
Note: For further options please consult the official documentation on available environment variables and local backend.
Create a new Pulumi project with stack name lsdev
mkdir myproj
pulumilocal new typescript -y -s lsdev --cwd myproj
Note: --cwd switch is unnecessary if commands are being run in project directory.
Select and create the lsdev Pulumi stack
This is unnecessary if you just did the new typescript command above as it will already be selected.
pulumilocal stack select -c lsdev --cwd myproj
Deploy the stack to LocalStack
pulumilocal up --cwd myproj
How it works
When running any pulumi deployment command like pulumilocal ["up", "destroy", "preview", "cancel"],
the wrapper script runs the pulumi config command to augment the pulumi config with LocalStack AWS configuration,
and then runs the original pulumi command.
Configurations
You can configure the following environment variables:
AWS_ENDPOINT_URL: hostname and port of the target LocalStack instanceLOCALSTACK_HOSTNAME: (Deprecated) Target host to use for connecting to LocalStack (default: localhost)EDGE_PORT: (Deprecated) Target port to use for connecting to LocalStack (default: 4566)PULUMI_CMD: Name of the executable Pulumi command on the system PATH (default: pulumi)CONFIG_STRATEGY: the strategy to handle config merging. If stack config already exists pulumi-local will prompt for user input. Possible values are:
overwrite (default): pulumi-local will overwrite the stack's config and replaces it with values necessary to communicate with LocalStack. This strategy is equivalent of the legacy behaviour.override: generates a temporary config file from the current stack config and overrides it's values, after run this file will be deleted. The name of the file is generated from the LS_STACK_NAME variable.separation: creates a separate stack with the stack name set in the LS_STACK_NAME env variable.
[!NOTE]
The fall through to the default strategy with a misconfigured or missing CONFIG_STRATEGY environment variable will be deprecated by the next pulumi-local version.
LS_STACK_NAME: the stack name to use when the config file generated either with the override and separation strategy.DRY_RUN: only usable with CONFIG_STRATEGY=override, as a result the created temporary stack config is not deleted.NON_INTERACTIVE: starts a non-interactive session where all user prompts are automatically accepted
[!WARNING]
Using the DRY_RUN and NON_INTERACTIVE flags together changes the stack configuration without confirmation prompt. Use with caution!
Deploying to AWS
Use your preferred Pulumi backend. https://www.pulumi.com/docs/concepts/state/#deciding-on-a-state-backend
Change the pulumilocal command in the instructions above to pulumi.
Change Log
- v1.3.1: Add support for
import command.
- v1.3.0: Add config merging strategies, dry-run and non-interactive runs.
- v1.2.2: Fix project URL in package metadata
- v1.2.1: Add support for AWS_ENDPOINT_URL env variable
- v1.2.0: Added dynamic endpoint generation and tests
- v1.1: Added README to long description and update twine publish.
- v1.0: Using
pulumi config set-all to set all the AWS provider configurating instead of modifying
the Stack file directly. Removed defaulting the stack name to localstack. Added argparse.
Removed pyyaml dependency. Removed python2 package classifiers.
- v0.6: Replace deprecated
s3ForcePathStyle with s3UsePathStyle in default config
- v0.5: Remove deprecated
mobileanalytics service config to fix invalid key error
- v0.4: Point pulumilocal.bat to the correct script
- v0.3: Add apigatewayv2 service endpoint
- v0.2: Add init command and add aws:region key by default
- v0.1: Initial release
License
This software library is released under the Apache License, Version 2.0 (see LICENSE).
