Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(readme): Add usage steps for aws-replicator extension #52

Merged
merged 3 commits into from
Feb 9, 2024
Merged

docs(readme): Add usage steps for aws-replicator extension #52

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e12dfbe
docs(readme): Add usage steps
lakkeger Feb 6, 2024
467680c
docs(readme): Add proxy container removal step
lakkeger Feb 6, 2024
7049c81
docs(readme): Apply suggestions from code review
lakkeger Feb 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 40 additions & 12 deletions aws-replicator/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,17 +20,53 @@ This extension currently offers two modes of operation: (1) the AWS connection p

The AWS connection proxy can be used to forward certain API calls in LocalStack to real AWS, in order to enable seamless transition between local and remote resources.

**Warning:** Be careful when using the proxy - make sure to _never_ give access to production accounts or any critical/sensitive data!

**Note:** The replicator CLI currently works only when installing the `localstack` CLI via `pip`. If you're downloading the `localstack` CLI as a [binary release](https://docs.localstack.cloud/getting-started/installation/#localstack-cli), then please use the proxy configuration UI described below.

### Usage

#### CLI
For example, in order to forward all API calls for DynamoDB/S3/Cognito to real AWS, the proxy can be started via the CLI as follows:

1. Start Localstack via CLI
lakkeger marked this conversation as resolved.
Show resolved Hide resolved
```
$ localstack start -d
```
2. Enable Localstack AWS replicator from the Web Application Extension Library
lakkeger marked this conversation as resolved.
Show resolved Hide resolved
3. After installation restart Localstack
4. Install the AWS replicator CLI package
```
$ pip install localstack-extension-aws-replicator
```
5. Configure real cloud account credentials in a new terminal session to allow access
```
# configure terminal session to allow access to a real cloud account
$ export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
# start proxy via the CLI
```
6. Start proxy in aforementioned terminal session via the CLI
```
$ localstack aws proxy -s dynamodb,s3,cognito-idp
```
7. Now for example awslocal or aws-cli with Localstack's endpoint URL should communicate with the real account.
lakkeger marked this conversation as resolved.
Show resolved Hide resolved

**Warning:** Be careful when using the proxy - make sure to _never_ give access to production accounts or any critical/sensitive data!
#### Proxy Configuration UI

**Note:** The replicator CLI currently works only when installing the `localstack` CLI via `pip`. If you're downloading the `localstack` CLI as a [binary release](https://docs.localstack.cloud/getting-started/installation/#localstack-cli), then please use the proxy configuration UI described below.
1. Start Localstack with extra CORS
```
EXTRA_CORS_ALLOWED_ORIGINS=https://aws-replicator.localhost.localstack.cloud:4566 localstack start -d
```

2. Enable Localstack AWS replicator from the Web Application Extension Library

3. Once the extension is installed, it will expose a small configuration endpoint in your LocalStack container under the following endpoint: http://localhost:4566/_localstack/aws-replicator/index.html .

4. Use this Web UI to define the proxy configuration (in YAML syntax), as well as the AWS credentials (AWS access key ID, secret access key, and optionally session token) and save configuration. The proxy should report enabled state and on the host a proxy container should spawn.

![configuration settings](etc/proxy-settings.png)

5. Now we can communicate with the real resources via Localstack.
lakkeger marked this conversation as resolved.
Show resolved Hide resolved

To clean up the running proxy container simply click disable on the Replicator UI.
lakkeger marked this conversation as resolved.
Show resolved Hide resolved

### Resource-specific proxying

Expand Down Expand Up @@ -72,14 +108,6 @@ make_bucket: test123

A more comprehensive sample, involving local Lambda functions combined with remote SQS queues and S3 buckets, can be found in the `example` folder of this repo.

### Proxy Configuration UI

Once the extension is installed, it will expose a small configuration endpoint in your LocalStack container under the following endpoint: http://localhost:4566/_localstack/aws-replicator/index.html .

Please use this Web UI to define the proxy configuration (in YAML syntax), as well as the AWS credentials (AWS access key ID, secret access key, and optionally session token).

![configuration settings](etc/proxy-settings.png)

## Resource Replicator CLI

The figure below illustrates how the extension can be used to replicate the state, e.g., an SQS queue and the messages contained in it, from AWS into your LocalStack instance.
Expand Down
Loading