# Pulumi CLI for LocalStack
**<u>DISCLAIMER</u>: pulumi-local currently does not support the _aws-native_ package. ([pulumi/pulumi-aws-native #108](https://github.com/pulumi/pulumi-aws-native/issues/108))**
This package provides the `pulumilocal` command, which is a thin wrapper around the `pulumi`
command line interface to use [`Pulumi`](https://github.com/pulumi/pulumi) with [LocalStack](https://github.com/localstack/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)
```shell
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][env_vars] and [local backend][local_backend]._
[env_vars]: https://www.pulumi.com/docs/cli/environment-variables/
[local_backend]: https://www.pulumi.com/docs/concepts/state/#local-filesystem
### Create a new Pulumi project with stack name lsdev
```shell
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.
```shell
pulumilocal stack select -c lsdev --cwd myproj
```
### Deploy the stack to LocalStack
```shell
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 instance
* `LOCALSTACK_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.
* `separate`: 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 `separate` 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.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`).
[pypi-version]: https://img.shields.io/pypi/v/pulumi-local.svg
[pypi]: https://pypi.org/project/pulumi-local/
Raw data
{
"_id": null,
"home_page": "https://github.com/localstack/pulumi-local",
"name": "pulumi-local",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "LocalStack Team",
"author_email": "info@localstack.cloud",
"download_url": "https://files.pythonhosted.org/packages/ca/66/c435c31828c6b8c18aaff187e6ebbd0c2cf3bfdfd3f4e0be1cd82ee51905/pulumi_local-1.3.0.tar.gz",
"platform": null,
"description": "# Pulumi CLI for LocalStack\n\n**<u>DISCLAIMER</u>: pulumi-local currently does not support the _aws-native_ package. ([pulumi/pulumi-aws-native #108](https://github.com/pulumi/pulumi-aws-native/issues/108))** \n\nThis package provides the `pulumilocal` command, which is a thin wrapper around the `pulumi`\ncommand line interface to use [`Pulumi`](https://github.com/pulumi/pulumi) with [LocalStack](https://github.com/localstack/localstack).\n\n## Installation\n\nYou can install the `pulumilocal` command via `pip`:\n\n```\npip install pulumi-local\n```\n\n## Prerequisites\n\nPlease make sure you have a LocalStack instance running on your local machine.\n\n## Usage\n\nThe `pulumilocal` command has the same usage as the `pulumi` command. For detailed usage,\nplease refer to the man pages of `pulumi -h`.\n\n### Add environment variables to store state on local backend (optional)\n```shell\nexport PULUMI_CONFIG_PASSPHRASE=lsdevtest\nexport PULUMI_BACKEND_URL=file://`pwd`/myproj\n```\n_Note: For further options please consult the official documentation on available [environment variables][env_vars] and [local backend][local_backend]._\n\n[env_vars]: https://www.pulumi.com/docs/cli/environment-variables/\n[local_backend]: https://www.pulumi.com/docs/concepts/state/#local-filesystem\n\n### Create a new Pulumi project with stack name lsdev\n```shell\nmkdir myproj\npulumilocal new typescript -y -s lsdev --cwd myproj\n```\n_Note: `--cwd` switch is unnecessary if commands are being run in project directory._\n\n### Select and create the lsdev Pulumi stack\nThis is unnecessary if you just did the `new typescript` command above as it will already be selected.\n```shell\npulumilocal stack select -c lsdev --cwd myproj\n```\n\n### Deploy the stack to LocalStack\n```shell\npulumilocal up --cwd myproj\n```\n\n## How it works\n\nWhen running any pulumi deployment command like `pulumilocal [\"up\", \"destroy\", \"preview\", \"cancel\"]`,\nthe wrapper script runs the `pulumi config` command to augment the pulumi config with LocalStack AWS configuration,\nand then runs the original pulumi command. \n\n## Configurations\n\nYou can configure the following environment variables:\n\n* `AWS_ENDPOINT_URL`: hostname and port of the target LocalStack instance\n* `LOCALSTACK_HOSTNAME`: __(Deprecated)__ Target host to use for connecting to LocalStack (default: `localhost`)\n* `EDGE_PORT`: __(Deprecated)__ Target port to use for connecting to LocalStack (default: `4566`)\n* `PULUMI_CMD`: Name of the executable Pulumi command on the system PATH (default: `pulumi`)\n* `CONFIG_STRATEGY`: the strategy to handle config merging. If stack config already exists `pulumi-local` will prompt for user input. Possible values are:\n * `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.\n * `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.\n * `separate`: creates a separate stack with the stack name set in the `LS_STACK_NAME` env variable.\n> [!NOTE]\n> 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.\n* `LS_STACK_NAME`: the stack name to use when the config file generated either with the `override` and `separate` strategy.\n* `DRY_RUN`: only usable with `CONFIG_STRATEGY=override`, as a result the created temporary stack config is not deleted.\n* `NON_INTERACTIVE`: starts a non-interactive session where all user prompts are automatically accepted\n\n> [!WARNING]\n> Using the `DRY_RUN` and `NON_INTERACTIVE` flags together changes the stack configuration without confirmation prompt. Use with caution!\n\n## Deploying to AWS\nUse your preferred Pulumi backend. https://www.pulumi.com/docs/concepts/state/#deciding-on-a-state-backend\nChange the `pulumilocal` command in the instructions above to `pulumi`.\n\n## Change Log\n\n* v1.3.0: Add config merging strategies, dry-run and non-interactive runs.\n* v1.2.2: Fix project URL in package metadata\n* v1.2.1: Add support for AWS_ENDPOINT_URL env variable\n* v1.2.0: Added dynamic endpoint generation and tests\n* v1.1: Added README to long description and update twine publish.\n* v1.0: Using `pulumi config set-all` to set all the AWS provider configurating instead of modifying\n the Stack file directly. Removed defaulting the stack name to `localstack`. Added argparse. \n Removed pyyaml dependency. Removed python2 package classifiers. \n* v0.6: Replace deprecated `s3ForcePathStyle` with `s3UsePathStyle` in default config\n* v0.5: Remove deprecated `mobileanalytics` service config to fix invalid key error\n* v0.4: Point pulumilocal.bat to the correct script\n* v0.3: Add apigatewayv2 service endpoint\n* v0.2: Add init command and add aws:region key by default\n* v0.1: Initial release\n\n## License\n\nThis software library is released under the Apache License, Version 2.0 (see `LICENSE`).\n\n[pypi-version]: https://img.shields.io/pypi/v/pulumi-local.svg\n[pypi]: https://pypi.org/project/pulumi-local/\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Thin wrapper script to use Pulumi with LocalStack",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/localstack/pulumi-local"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca66c435c31828c6b8c18aaff187e6ebbd0c2cf3bfdfd3f4e0be1cd82ee51905",
"md5": "776b7572d3613d8b5b39ddc46de5b56f",
"sha256": "440ae5151b037f78540f325251e760a93bd47406338b62f03efb2128833da8af"
},
"downloads": -1,
"filename": "pulumi_local-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "776b7572d3613d8b5b39ddc46de5b56f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13214,
"upload_time": "2024-09-30T09:25:58",
"upload_time_iso_8601": "2024-09-30T09:25:58.160604Z",
"url": "https://files.pythonhosted.org/packages/ca/66/c435c31828c6b8c18aaff187e6ebbd0c2cf3bfdfd3f4e0be1cd82ee51905/pulumi_local-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 09:25:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "localstack",
"github_project": "pulumi-local",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pulumi-local"
}
JSON
