[](https://github.com/localstack/terraform-local/actions)
# `tflocal` - Terraform with LocalStack
This package provides `tflocal` - a small wrapper script to run [Terraform](https://terraform.io) against [LocalStack](https://localstack.cloud).
## Prerequisites
* Python 3.x
* `pip`
* `terraform`
## How it works
The script uses the [Terraform Override mechanism](https://www.terraform.io/language/files/override) and creates a temporary file `localstack_providers_override.tf` to configure the endpoints for the AWS `provider` section. The endpoints for all services are configured to point to the LocalStack API (`http://localhost:4566` by default).
## Installation
The `tflocal` command line interface can be installed via `pip`:
```
pip install terraform-local
```
## Configurations
The following environment variables can be configured:
* `DRY_RUN`: Generate the override file without invoking Terraform
* `TF_CMD`: Terraform command to call (default: `terraform`)
* `AWS_ENDPOINT_URL`: hostname and port of the target LocalStack instance
* `LOCALSTACK_HOSTNAME`: __(Deprecated)__ host name of the target LocalStack instance
* `EDGE_PORT`: __(Deprecated)__ port number of the target LocalStack instance
* `S3_HOSTNAME`: special hostname to be used to connect to LocalStack S3 (default: `s3.localhost.localstack.cloud`)
* `USE_EXEC`: whether to use `os.exec` instead of `subprocess.Popen` (try using this in case of I/O issues)
* `<SERVICE>_ENDPOINT`: setting a custom service endpoint, e.g., `COGNITO_IDP_ENDPOINT=http://example.com`
* `AWS_DEFAULT_REGION`: the AWS region to use (default: `us-east-1`, or determined from local credentials if `boto3` is installed)
* `CUSTOMIZE_ACCESS_KEY`: enables to override the static AWS Access Key ID. The following cases are taking precedence over each other from top to bottom:
* `AWS_ACCESS_KEY_ID` environment variable is set
* `access_key` is set in the Terraform AWS provider
* `AWS_PROFILE` environment variable is set and configured
* `AWS_DEFAULT_PROFILE` environment variable is set and configured
* `default` profile's credentials are configured
* falls back to the default `AWS_ACCESS_KEY_ID` mock value
* `AWS_ACCESS_KEY_ID`: AWS Access Key ID to use for multi account setups (default: `test` -> account ID: `000000000000`)
* `SKIP_ALIASES`: Allows to skip generating AWS provider overrides for specified aliased providers, e.g. `SKIP_ALIASES=aws_secrets,real_aws`
* `ADDITIONAL_TF_OVERRIDE_LOCATIONS`: Comma-separated list of folder paths that will also receive a temporary `localstack_providers_override.tf` file
## Usage
The `tflocal` command has the same usage as the `terraform` command. For detailed usage,
please refer to the man pages of `terraform --help`.
### Validation errors when using local terraform modules
Note that if your project uses local terraform modules, and those modules reference providers, those folders *also* need to receive a temporary `localstack_providers_override.tf` file. Without it, you would get an error that looks like this when starting to process code from inside the module
```
╷
│ Error: No valid credential sources found
│
│ with module.lambda.provider["registry.terraform.io/hashicorp/aws"],
│ on ../../providers.tf line 11, in provider "aws":
│ 11: provider "aws" {
│
│ Please see https://registry.terraform.io/providers/hashicorp/aws
│ for more information about providing credentials.
│
│ Error: failed to refresh cached credentials, no EC2 IMDS role found, operation error ec2imds: GetMetadata, access disabled to EC2 IMDS via client option, or "AWS_EC2_METADATA_DISABLED" environment variable
```
To address this issue, you may include a comma-separated list of folder paths that will recieve additional override files via an environment variable
```
ADDITIONAL_TF_OVERRIDE_LOCATIONS=/path/to/module1,path/to/module2 tflocal plan
```
[See this issue for more discussion](https://github.com/localstack/terraform-local/issues/67)
## Change Log
* v0.24.1: Exclude broken `python-hcl2` version from requirements
* v0.24.0: Add support to return `terraform-local` version when calling `tflocal -version` and fix AWS provider detection
* v0.23.1: Fix endpoint overrides for Terraform AWS provider >= 6.0.0-beta2
* v0.23.0: Add support for `terraform_remote_state` with `s3` backend to read the state stored in local S3 backend; fix S3 backend config detection with multiple Terraform blocks
* v0.22.0: Fix S3 backend forcing DynamoDB State Lock to be enabled by default
* v0.21.0: Add ability to drop an override file in additional locations
* v0.20.1: Fix list config rendering
* v0.20.0: Fix S3 backend option merging
* v0.19.0: Add `SKIP_ALIASES` configuration environment variable
* v0.18.2: Fix warning on aliased custom endpoint names
* v0.18.1: Fix issue with not proxied commands
* v0.18.0: Add `DRY_RUN` and patch S3 backend entrypoints
* v0.17.1: Add `packaging` module to install requirements
* v0.17.0: Add option to use new endpoints S3 backend options
* v0.16.1: Update Setuptools to exclude tests during packaging
* v0.16.0: Introducing semantic versioning and AWS_ENDPOINT_URL variable
* v0.15: Update endpoint overrides for Terraform AWS provider 5.22.0
* v0.14: Add support to multi-account environments
* v0.13: Fix S3 automatic `use_s3_path_style` detection when setting S3_HOSTNAME or LOCALSTACK_HOSTNAME
* v0.12: Fix local endpoint overrides for Terraform AWS provider 5.9.0; fix parsing of alias and region defined as value lists
* v0.11: Minor fix to handle boolean values in S3 backend configs
* v0.10: Add support for storing state files in local S3 backends
* v0.9: Fix unsupported provider override for emrserverless
* v0.8: Configure the endpoint for opensearch service
* v0.7: Add initial support for provider aliases
* v0.6: Fix selection of default region
* v0.5: Make AWS region configurable, add `region` to provider config
* v0.4: Fix using use_s3_path_style for S3_HOSTNAME=localhost; exclude `meteringmarketplace` service endpoint
* v0.3: Fix support for -chdir=... to create providers file in target directory
* v0.2: Add ability to specify custom endpoints; pass INT signals to subprocess
* 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/terraform-local.svg
[pypi]: https://pypi.org/project/terraform-local/
Raw data
{
"_id": null,
"home_page": "https://github.com/localstack/terraform-local",
"name": "terraform-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/06/8a/61237cd8b95d41f2e997fee78f1a05fd3f5e65845cfe7aae9362a9d28022/terraform_local-0.24.1.tar.gz",
"platform": null,
"description": "[](https://github.com/localstack/terraform-local/actions)\n\n# `tflocal` - Terraform with LocalStack\n\nThis package provides `tflocal` - a small wrapper script to run [Terraform](https://terraform.io) against [LocalStack](https://localstack.cloud).\n\n## Prerequisites\n\n* Python 3.x\n* `pip`\n* `terraform`\n\n## How it works\n\nThe script uses the [Terraform Override mechanism](https://www.terraform.io/language/files/override) and creates a temporary file `localstack_providers_override.tf` to configure the endpoints for the AWS `provider` section. The endpoints for all services are configured to point to the LocalStack API (`http://localhost:4566` by default).\n\n## Installation\n\nThe `tflocal` command line interface can be installed via `pip`:\n```\npip install terraform-local\n```\n\n## Configurations\n\nThe following environment variables can be configured:\n* `DRY_RUN`: Generate the override file without invoking Terraform\n* `TF_CMD`: Terraform command to call (default: `terraform`)\n* `AWS_ENDPOINT_URL`: hostname and port of the target LocalStack instance\n* `LOCALSTACK_HOSTNAME`: __(Deprecated)__ host name of the target LocalStack instance\n* `EDGE_PORT`: __(Deprecated)__ port number of the target LocalStack instance\n* `S3_HOSTNAME`: special hostname to be used to connect to LocalStack S3 (default: `s3.localhost.localstack.cloud`)\n* `USE_EXEC`: whether to use `os.exec` instead of `subprocess.Popen` (try using this in case of I/O issues)\n* `<SERVICE>_ENDPOINT`: setting a custom service endpoint, e.g., `COGNITO_IDP_ENDPOINT=http://example.com`\n* `AWS_DEFAULT_REGION`: the AWS region to use (default: `us-east-1`, or determined from local credentials if `boto3` is installed)\n* `CUSTOMIZE_ACCESS_KEY`: enables to override the static AWS Access Key ID. The following cases are taking precedence over each other from top to bottom:\n * `AWS_ACCESS_KEY_ID` environment variable is set\n * `access_key` is set in the Terraform AWS provider\n * `AWS_PROFILE` environment variable is set and configured\n * `AWS_DEFAULT_PROFILE` environment variable is set and configured\n * `default` profile's credentials are configured\n * falls back to the default `AWS_ACCESS_KEY_ID` mock value\n* `AWS_ACCESS_KEY_ID`: AWS Access Key ID to use for multi account setups (default: `test` -> account ID: `000000000000`)\n* `SKIP_ALIASES`: Allows to skip generating AWS provider overrides for specified aliased providers, e.g. `SKIP_ALIASES=aws_secrets,real_aws`\n* `ADDITIONAL_TF_OVERRIDE_LOCATIONS`: Comma-separated list of folder paths that will also receive a temporary `localstack_providers_override.tf` file\n\n## Usage\n\nThe `tflocal` command has the same usage as the `terraform` command. For detailed usage,\nplease refer to the man pages of `terraform --help`.\n\n### Validation errors when using local terraform modules\n\nNote that if your project uses local terraform modules, and those modules reference providers, those folders *also* need to receive a temporary `localstack_providers_override.tf` file. Without it, you would get an error that looks like this when starting to process code from inside the module\n\n```\n\u2577\n\u2502 Error: No valid credential sources found\n\u2502 \n\u2502 with module.lambda.provider[\"registry.terraform.io/hashicorp/aws\"],\n\u2502 on ../../providers.tf line 11, in provider \"aws\":\n\u2502 11: provider \"aws\" {\n\u2502 \n\u2502 Please see https://registry.terraform.io/providers/hashicorp/aws\n\u2502 for more information about providing credentials.\n\u2502 \n\u2502 Error: failed to refresh cached credentials, no EC2 IMDS role found, operation error ec2imds: GetMetadata, access disabled to EC2 IMDS via client option, or \"AWS_EC2_METADATA_DISABLED\" environment variable\n```\n\nTo address this issue, you may include a comma-separated list of folder paths that will recieve additional override files via an environment variable\n\n```\nADDITIONAL_TF_OVERRIDE_LOCATIONS=/path/to/module1,path/to/module2 tflocal plan\n```\n\n[See this issue for more discussion](https://github.com/localstack/terraform-local/issues/67)\n\n## Change Log\n\n* v0.24.1: Exclude broken `python-hcl2` version from requirements\n* v0.24.0: Add support to return `terraform-local` version when calling `tflocal -version` and fix AWS provider detection\n* v0.23.1: Fix endpoint overrides for Terraform AWS provider >= 6.0.0-beta2\n* v0.23.0: Add support for `terraform_remote_state` with `s3` backend to read the state stored in local S3 backend; fix S3 backend config detection with multiple Terraform blocks\n* v0.22.0: Fix S3 backend forcing DynamoDB State Lock to be enabled by default\n* v0.21.0: Add ability to drop an override file in additional locations\n* v0.20.1: Fix list config rendering\n* v0.20.0: Fix S3 backend option merging\n* v0.19.0: Add `SKIP_ALIASES` configuration environment variable\n* v0.18.2: Fix warning on aliased custom endpoint names\n* v0.18.1: Fix issue with not proxied commands\n* v0.18.0: Add `DRY_RUN` and patch S3 backend entrypoints\n* v0.17.1: Add `packaging` module to install requirements\n* v0.17.0: Add option to use new endpoints S3 backend options\n* v0.16.1: Update Setuptools to exclude tests during packaging\n* v0.16.0: Introducing semantic versioning and AWS_ENDPOINT_URL variable\n* v0.15: Update endpoint overrides for Terraform AWS provider 5.22.0\n* v0.14: Add support to multi-account environments\n* v0.13: Fix S3 automatic `use_s3_path_style` detection when setting S3_HOSTNAME or LOCALSTACK_HOSTNAME\n* v0.12: Fix local endpoint overrides for Terraform AWS provider 5.9.0; fix parsing of alias and region defined as value lists\n* v0.11: Minor fix to handle boolean values in S3 backend configs\n* v0.10: Add support for storing state files in local S3 backends\n* v0.9: Fix unsupported provider override for emrserverless\n* v0.8: Configure the endpoint for opensearch service\n* v0.7: Add initial support for provider aliases\n* v0.6: Fix selection of default region\n* v0.5: Make AWS region configurable, add `region` to provider config\n* v0.4: Fix using use_s3_path_style for S3_HOSTNAME=localhost; exclude `meteringmarketplace` service endpoint\n* v0.3: Fix support for -chdir=... to create providers file in target directory\n* v0.2: Add ability to specify custom endpoints; pass INT signals to subprocess\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/terraform-local.svg\n[pypi]: https://pypi.org/project/terraform-local/\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Thin wrapper script to run Terraform against LocalStack",
"version": "0.24.1",
"project_urls": {
"Homepage": "https://github.com/localstack/terraform-local"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c4e24a636ca3a9ec619de9c4fd1bb52564fe886a29fe7ccb1b92011589a70737",
"md5": "ec2dc0ee28537be5df2e7da36349c5d7",
"sha256": "159115b60851fd491d4e5037017078ad5e8d87d0f514a00c98d838ad8dab12a6"
},
"downloads": -1,
"filename": "terraform_local-0.24.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ec2dc0ee28537be5df2e7da36349c5d7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16454,
"upload_time": "2025-07-24T07:20:25",
"upload_time_iso_8601": "2025-07-24T07:20:25.847449Z",
"url": "https://files.pythonhosted.org/packages/c4/e2/4a636ca3a9ec619de9c4fd1bb52564fe886a29fe7ccb1b92011589a70737/terraform_local-0.24.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "068a61237cd8b95d41f2e997fee78f1a05fd3f5e65845cfe7aae9362a9d28022",
"md5": "47bbbff226e946da10bb0b6946cfb1ee",
"sha256": "2cfaeb283a1753083f3f59be1a2e08d225286913633694d695b04bba9913ae91"
},
"downloads": -1,
"filename": "terraform_local-0.24.1.tar.gz",
"has_sig": false,
"md5_digest": "47bbbff226e946da10bb0b6946cfb1ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23104,
"upload_time": "2025-07-24T07:10:21",
"upload_time_iso_8601": "2025-07-24T07:10:21.927076Z",
"url": "https://files.pythonhosted.org/packages/06/8a/61237cd8b95d41f2e997fee78f1a05fd3f5e65845cfe7aae9362a9d28022/terraform_local-0.24.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 07:10:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "localstack",
"github_project": "terraform-local",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "terraform-local"
}
JSON
