You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/aws/connecting/aws-cli.md
+24-78Lines changed: 24 additions & 78 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,31 +8,31 @@ sidebar:
8
8
9
9
## Introduction
10
10
11
-
The [AWS Command Line Interface (CLI)](https://aws.amazon.com/cli/) is a unified tool for creating and managing AWS services via a command line interface.
12
-
All CLI commands applicable to services implemented within [LocalStack](/aws/connecting/aws-cli/)can be executed when operating against LocalStack.
11
+
The [AWS Command Line Interface (CLI)](https://aws.amazon.com/cli/) is the standard tool from Amazon for creating and managing AWS services via a command line interface.
12
+
Due to LocalStack's compatibility with the AWS APIs, this tool can also access LocalStack's emulated services.
13
13
14
-
You can use the AWS CLI with LocalStack using either of the following approaches:
14
+
You can use the AWS CLI with LocalStack using one or more of the following approaches:
15
15
16
-
[AWS CLI](#aws-cli)
16
+
-[AWS CLI](#aws-cli) - Use the standard `aws` command with hand-crafted configuration options necessary to communicate with LocalStack.
17
+
-[LocalStack AWS CLI](#localstack-aws-cli-lstk-aws) - Use the `lstk aws` command to set the configuration options for you.
18
+
-[Using AWS CLI from a pre-built container](#using-aws-cli-from-a-pre-built-container) - Use Amazon's pre-built AWS CLI container image instead of installing `aws` locally.
`lstk aws` supersedes the older [`awslocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#awslocal), which is deprecated but still available if you need it.
22
+
:::
19
23
20
24
## AWS CLI
21
25
22
-
You can install `aws` by using the following command if it's not already installed.
23
-
24
-
```bash
25
-
pip install awscli
26
-
```
26
+
If you don't already have `aws` (version 2) installed, follow the [official AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
27
27
28
-
You can configure the AWS CLI to redirect AWS API requests to LocalStack using two approaches:
28
+
Once installed, you can configure the AWS CLI to redirect AWS API requests to LocalStack using two approaches:
29
29
30
30
-[Configuring an endpoint URL](#configuring-an-endpoint-url)
31
31
-[Configuring a custom profile](#configuring-a-custom-profile)
32
32
33
33
### Configuring an endpoint URL
34
34
35
-
You can use AWS CLI with an endpoint URL by configuring test environment variables and include the `--endpoint-url=<localstack-url>` flag in your `aws` CLI commands.
35
+
You can use AWS CLI with an endpoint URL by configuring environment variables and including the `--endpoint-url=<localstack-url>` flag in your `aws` CLI commands.
36
36
For example:
37
37
38
38
```bash
@@ -80,86 +80,32 @@ aws s3 ls --profile localstack
80
80
Alternatively, you can also set the `AWS_PROFILE=localstack` environment variable, in which case the `--profile localstack` parameter can be omitted in the commands above.
81
81
:::
82
82
83
-
## LocalStack AWS CLI (`awslocal`)
83
+
## LocalStack AWS CLI (`lstk aws`)
84
84
85
-
`awslocal` serves as a thin wrapper and a substitute for the standard `aws` command, enabling you to run AWS CLI commands within the LocalStack environment without specifying the `--endpoint-url` parameter or a profile.
85
+
`lstk aws` serves as a thin wrapper and a substitute for the standard `aws` command, enabling you to run AWS CLI commands within the LocalStack environment without specifying the `--endpoint-url` parameter or a profile.
86
86
87
87
### Installation
88
88
89
-
Install the `awslocal` command using the following command:
90
-
91
-
```bash
92
-
pip install awscli-local[ver1]
93
-
```
89
+
To make use of `lstk aws`, you must install both the `lstk` CLI and the standard `aws` command from Amazon.
94
90
95
-
:::tip
96
-
97
-
The above command installs the most recent version of the underlying AWS CLI version 1 (`awscli`) package.
98
-
If you would rather manage your own `awscli` version (e.g., `v1` or `v2`) and only install the wrapper script, you can use the following command:
99
-
100
-
```bash
101
-
pip install awscli-local
102
-
```
103
-
104
-
:::
105
-
106
-
:::note
107
-
108
-
Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section](#current-limitations) for more details).
109
-
:::
91
+
1. To install `lstk`, follow the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation).
92
+
2. To install `aws`, follow the [official AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
110
93
111
94
### Usage
112
95
113
-
The `awslocal` command shares identical usage with the standard `aws` command.
114
-
For comprehensive usage instructions, refer to the manual pages by running `awslocal help`.
| AWS_ENDPOINT_URL | The endpoint URL to connect to (takes precedence over USE_SSL/LOCALSTACK_HOST) |
125
-
| LOCALSTACK_HOST | (deprecated) A variable defining where to find LocalStack (default: localhost:4566) |
126
-
| USE_SSL | (deprecated) Whether to use SSL when connecting to LocalStack (default: False) |
127
-
128
-
### Current Limitations
129
-
130
-
Please note that there is a known limitation for using the `cloudformation package ...` command with the AWS CLI v2.
131
-
The problem is that the AWS CLI v2 is [not available as a package on pypi.org](https://github.com/aws/aws-cli/issues/4947), but is instead shipped as a binary package that cannot be easily patched from `awslocal`.
132
-
To work around this issue, you have 2 options:
133
-
134
-
- Downgrade to the v1 AWS CLI (this is the recommended approach)
135
-
- There is an unofficial way to install AWS CLI v2 from sources.
136
-
We do not recommend this, but it is technically possible.
137
-
Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system:
96
+
The `lstk aws` command shares identical usage with the standard `aws` command.
97
+
For comprehensive usage instructions, refer to the manual pages by running `lstk aws help`.
Please also note there is a known limitation for issuing requests using
146
-
`--no-sign-request` with the AWS CLI.
147
-
LocalStack's routing mechanism depends on
148
-
the signature of each request to identify the correct service for the request.
149
-
Thus, adding the flag `--no-sign-requests` provokes your request to reach the
150
-
wrong service.
151
-
One possible way to address this is to use the `awslocal` CLI
152
-
instead of AWS CLI.
153
-
154
-
## AWS CLI v2
155
-
156
-
Automatic installation of AWS CLI version 2 is currently not supported (at the time of writing there is no official pypi package for v2 available), but the awslocal technically also works with AWS CLI v2 (see this section for more details).
157
103
158
-
### AWS CLI v2 with Docker and LocalStack
104
+
##Using AWS CLI from a pre-built container
159
105
160
-
By default, the container running [amazon/aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-docker.html)is isolated from `0.0.0.0:4566` on the host machine, that means that aws-cli cannot reach localstack through your shell.
106
+
As an alternative to installing the `aws` command directly on your local machine, Amazon provides a [pre-built container image with the AWS CLI pre-installed](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-docker.html). This approach is most suitable when working in multi-container environments, rather than single-machine installations. If you take this approach, an extra step is required for communication with LocalStack, also running inside a container.
161
107
162
-
To ensure that the two docker containers can communicate create a network on the docker engine:
108
+
By default, the AWS CLI container is isolated from `0.0.0.0:4566` on the host machine, which means the AWS CLI cannot reach LocalStack. To ensure the two docker containers can communicate create a network on the docker engine:
163
109
164
110
```bash
165
111
docker network create localstack
@@ -175,7 +121,7 @@ networks:
175
121
name: 'localstack'
176
122
```
177
123
178
-
Run AWS Cli v2 docker container using this network (example):
124
+
Run the AWS CLI v2 docker container using this network (example):
179
125
180
126
```bash
181
127
docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566 lambda list-functions
Copy file name to clipboardExpand all lines: src/content/docs/aws/connecting/infrastructure-as-code/aws-cdk.md
+23-36Lines changed: 23 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,40 +14,43 @@ The AWS Cloud Development Kit (CDK) is an Infrastructure-as-Code (IaC) tool usin
14
14
15
15
## AWS CDK CLI for LocalStack
16
16
17
-
`cdklocal` is a thin wrapper script for using the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack.
17
+
[`lstk cdk`](/aws/developer-tools/running-localstack/lstk/#cdk) proxies the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack. It requires the AWS CDK CLI version `2.177.0` or newer on your `PATH`.
18
+
19
+
:::note
20
+
`lstk cdk` supersedes the older [`cdklocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#cdklocal), which is deprecated but still available if you need it.
21
+
:::
18
22
19
23
### Installation
20
24
21
-
The `cdklocal` command line is published as an [npm library](https://www.npmjs.com/package/aws-cdk-local):
25
+
Install `lstk` by following the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation).
26
+
You'll also need the AWS CDK CLI installed separately:
22
27
23
28
```bash
24
29
# Install globally
25
-
npm install -g aws-cdk-local aws-cdk
30
+
npm install -g aws-cdk
26
31
27
32
# Verify it installed correctly
28
-
cdklocal --version
29
-
# e.g. 1.65.5
33
+
cdk --version
30
34
```
31
35
32
-
:::note
33
-
34
-
Using `cdklocal` locally (e.g. within the `node_modules` of your repo instead of globally installed) does not work at the moment for some setups, so make sure you install both `aws-cdk` and `aws-cdk-local` with the `-G` flag.
35
-
:::
36
-
37
36
### Usage
38
37
39
-
`cdklocal` can be used as a drop-in replacement of where you would otherwise use `cdk` when targeting the AWS Cloud.
38
+
`lstk cdk` can be used as a drop-in replacement of where you would otherwise use `cdk` when targeting the AWS Cloud.
40
39
41
40
```bash
42
-
cdklocal --help
41
+
lstk cdk --help
43
42
```
44
43
45
44
### Configuration
46
45
46
+
`lstk cdk`'s only lstk-specific flag (before the CDK action) is `--region <region>` (default `us-east-1`); CDK always targets the default LocalStack account `000000000000`, so there is no `--account` flag.
47
+
47
48
The following environment variables can be configured:
48
49
49
50
-`AWS_ENDPOINT_URL`: The endpoint URL (i.e., protocol, host, and port) to connect to LocalStack (default: `http://localhost.localstack.cloud:4566`)
50
-
-`LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `hot-reload` S3 bucket name)
51
+
-`AWS_ENDPOINT_URL_S3`: The S3-specific endpoint URL, required alongside `AWS_ENDPOINT_URL` and must include `.s3.` to correctly identify S3 API calls
52
+
-`LSTK_CDK_CMD`: Binary to invoke (default `cdk`)
53
+
-`AWS_REGION`: Fallback for `--region`
51
54
52
55
### Example
53
56
@@ -62,20 +65,20 @@ The CDK command line ships with a sample app generator to run a quick test for g
62
65
```bash
63
66
# create sample app
64
67
mkdir /tmp/test;cd /tmp/test
65
-
cdklocal init sample-app --language=javascript
68
+
lstk cdk init sample-app --language=javascript
66
69
67
70
# bootstrap localstack environment
68
-
cdklocal bootstrap
71
+
lstk cdk bootstrap
69
72
70
73
# deploy the sample app
71
-
cdklocal deploy
74
+
lstk cdk deploy
72
75
> Do you wish to deploy these changes (y/n)? y
73
76
```
74
77
75
-
Once the deployment is done, you can inspect the created resources via the [`awslocal`](https://github.com/localstack/awscli-local) command line
78
+
Once the deployment is done, you can inspect the created resources via the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command line
76
79
77
80
```bash
78
-
awslocal sns list-topics
81
+
lstk aws sns list-topics
79
82
{
80
83
"Topics": [
81
84
{
@@ -107,21 +110,5 @@ When this lambda is executed locally from the `/tmp` folder, the package can not
107
110
108
111
## CDK Version Compatibility
109
112
110
-
`cdklocal` works with all installed versions of the Node.js `aws-cdk` package.
111
-
However, issues exist for `aws-cdk >= 2.177.0`.
112
-
113
-
For these versions:
114
-
115
-
- We unset AWS-related environment variables like `AWS_PROFILE` before calling `cdk`.
116
-
- We explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to point to LocalStack.
117
-
118
-
Some environment variables may cause conflicting config, such as wrong region or accidental deploys to real AWS.
119
-
To allow specific variables (e.g., `AWS_REGION`), use `AWS_ENVAR_ALLOWLIST`:
If you manually set `AWS_ENDPOINT_URL`, it will be used.
126
-
You must also set `AWS_ENDPOINT_URL_S3`, and it must include `.s3.` to correctly identify S3 API calls.
127
-
See full configuration details [on our configuration docs](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations).
113
+
`lstk cdk` requires AWS CDK CLI `2.177.0` or newer, as noted in [Installation](#installation).
114
+
If you're using an older `aws-cdk` version, or the legacy `cdklocal` wrapper script, see [CDK Version Compatibility](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#cdklocal) on the deprecated wrapper scripts page for the relevant environment-variable workarounds.
Copy file name to clipboardExpand all lines: src/content/docs/aws/connecting/infrastructure-as-code/aws-sam.md
+29-19Lines changed: 29 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,29 +12,29 @@ The AWS Serverless Application Model (SAM) is an open-source framework for devel
12
12
It uses a simplified syntax to define functions, APIs, databases, and event source mappings.
13
13
When you deploy, SAM converts its syntax into AWS CloudFormation syntax, helping you create serverless applications more quickly.
14
14
15
-
LocalStack can work with SAM using the AWS SAM CLI for LocalStack.
16
-
This CLI comes in the form of a `samlocal` wrapper script, which lets you deploy SAM applications on LocalStack.
17
-
This guide explains how to set up local AWS resources using the `samlocal` wrapper script.
15
+
LocalStack can work with SAM using [`lstk sam`](/aws/developer-tools/running-localstack/lstk/#sam), which lets you deploy SAM applications on LocalStack.
16
+
This guide explains how to set up local AWS resources using `lstk sam`.
18
17
19
-
## `samlocal` wrapper script
18
+
## `lstk sam`
20
19
21
-
`samlocal` is a wrapper for the `sam` command line interface, facilitating the use of SAM framework with LocalStack.
22
-
When executing deployment commands like `samlocal ["build", "deploy", "validate", "package"]`, the script configures the SAM settings for LocalStack and runs the specified SAM command.
20
+
`lstk sam` proxies the `sam` command line interface, facilitating the use of the SAM framework with LocalStack.
21
+
When executing deployment commands like `lstk sam [ build | deploy | validate | package]`, it configures the SAM settings for LocalStack and runs the specified SAM command.
23
22
24
-
### Install the `samlocal` wrapper script
23
+
:::note
24
+
`lstk sam` supersedes the older [`samlocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#samlocal), which is deprecated but still available if you need it.
25
+
:::
25
26
26
-
You can install the `samlocal` wrapper script by running the following command:
27
+
### Install lstk
27
28
28
-
```bash
29
-
pip install aws-sam-cli-local
30
-
```
29
+
To use `lstk sam`, install `lstk` by following the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation).
30
+
You'll also need the [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) (version `1.95.0` or newer) installed and on your `PATH`.
31
31
32
32
### Create a new SAM project
33
33
34
34
You can initialize a new SAM project using the following command:
35
35
36
36
```bash
37
-
samlocal init
37
+
lstk sam init
38
38
```
39
39
40
40
Select `1` to create a new SAM application using an AWS Quick Start template.
@@ -50,19 +50,29 @@ Then, enter the project name and press `Enter`.
50
50
After initializing the SAM project, enter the project directory and deploy the application using the following command:
51
51
52
52
```bash
53
-
samlocal deploy --guided
53
+
lstk sam deploy --guided
54
54
```
55
55
56
56
Enter the default values for the deployment, such as the stack name, region, and confirm the changes.
57
-
The `samlocal` wrapper will package and deploy the application to LocalStack.
57
+
`lstk sam` will package and deploy the application to LocalStack.
58
58
59
59
### Configuration
60
60
61
-
| Environment Variable | Default value | Description |
Copy file name to clipboardExpand all lines: src/content/docs/aws/connecting/infrastructure-as-code/cloud-custodian.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ You can use Cloud Custodian with LocalStack by just specifying the Cloud Custodi
16
16
17
17
## Getting started
18
18
19
-
This guide is designed for users who are new to Cloud Custodian and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script.
19
+
This guide is designed for users who are new to Cloud Custodian and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command.
20
20
21
21
Start your LocalStack container using your preferred method.
22
22
We will demonstrate how you can spin up an EC2 instance and tag it with the key `Custodian`, and then use Cloud Custodian to stop the instance.
@@ -33,12 +33,12 @@ After installing Cloud Custodian, you can configure a [custom LocalStack profile
33
33
34
34
### Create an EC2 instance
35
35
36
-
You can create an EC2 instance using the `awslocal` wrapper script.
36
+
You can create an EC2 instance using `lstk aws`.
37
37
You can use the [`RunInstances`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API to create an EC2 instance.
38
38
The following example creates an EC2 instance with the tag `Custodian` (any value):
0 commit comments