From 53ca2c7a26ea58d8315100468e7909e3d9f6e21b Mon Sep 17 00:00:00 2001 From: Waldemar Hummer Date: Mon, 30 Sep 2024 14:49:18 -0700 Subject: [PATCH] remove copy/replicate mode and focus on cloud proxy in replicator extension (#81) --- aws-replicator/README.md | 56 +++++-------------- .../aws_replicator/server/ui/app.js | 2 - .../aws_replicator/server/ui/index.html | 8 +-- 3 files changed, 16 insertions(+), 50 deletions(-) diff --git a/aws-replicator/README.md b/aws-replicator/README.md index 9d05512..d1661bc 100644 --- a/aws-replicator/README.md +++ b/aws-replicator/README.md @@ -1,10 +1,13 @@ -AWS Replicator Extension (experimental) +AWS Cloud Proxy Extension (experimental) ======================================== [![Install LocalStack Extension](https://localstack.cloud/gh/extension-badge.svg)](https://app.localstack.cloud/extensions/remote?url=git+https://github.com/localstack/localstack-extensions/#egg=localstack-extension-aws-replicator&subdirectory=aws-replicator) -A LocalStack extension to replicate AWS resources into your local machine. +A LocalStack extension to proxy and integrate AWS resources into your local machine. +This enables one flavor of "hybrid" or "remocal" setups where you can easily bridge the gap between LocalStack (local resources) and remote AWS (resources in the real cloud). -⚠️ Please note that this extension is experimental and currently under active development. +⚠️ Please note that this extension is experimental and still under active development. + +⚠️ Note: Given that the scope of this extension has recently changed (see [below](#resource-replicator-cli-deprecated)), it may get renamed from `aws-replicator` to `cloud-proxy` in an upcoming release. ## Prerequisites @@ -12,17 +15,14 @@ A LocalStack extension to replicate AWS resources into your local machine. * Docker * Python -## Overview - -This extension currently offers two modes of operation: (1) the AWS connection proxy, and (2) the resource replicator CLI. - -## AWS Connection Proxy +## AWS Cloud Proxy -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. +The AWS Cloud 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. +**Note:** The Cloud Proxy 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 @@ -66,7 +66,7 @@ EXTRA_CORS_ALLOWED_ORIGINS=https://aws-replicator.localhost.localstack.cloud:456 5. Now we can communicate with the real AWS cloud resources, directly via LocalStack. -To clean up the running proxy container simply click "disable" on the Replicator UI. +To clean up the running proxy container simply click "disable" on the Cloud Proxy UI. ### Resource-specific proxying @@ -117,38 +117,12 @@ In addition to the proxy services configuration shown above, the following confi **Note:** Due to some recent changes in the core framework, make sure to start up your LocalStack container with the `GATEWAY_SERVER=hypercorn` configuration enabled, for backwards compatibility. This will be fixed in an upcoming release. -## 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. - -![overview](etc/aws-replicate-overview.png) +## Resource Replicator CLI (deprecated) -To use the resource replicator, make sure that you have access to AWS configured in your terminal. Note: the extension will only talk to AWS in read-only mode, and will **not** make any changes to your real AWS account. +Note: Previous versions of this extension also offered a "replicate" mode to copy/clone (rather than proxy) resources from an AWS account into the local instance. +This functionality has been removed from this extension, and is now being migrated to a new extension (more details following soon). -The following command can be used to replicate SQS queues (incl. their messages) into your LocalStack instance: -``` -$ localstack aws replicate -s sqs -``` - -Once the command has completed, you should be able to list and interact with the queue that was replicated into your local account: -``` -$ awslocal sqs list-queues -... -$ awslocal sqs receive-message --queue-url ... -... -``` - -## Installing - -To install the CLI extension, use the following `pip` command: -```bash -pip install "git+https://github.com/localstack/localstack-extensions/#egg=localstack-extension-aws-replicator&subdirectory=aws-replicator" -``` - -To install the extension itself (server component running inside LocalStack), use the following `extensions` command: -```bash -localstack extensions install "git+https://github.com/localstack/localstack-extensions/#egg=localstack-extension-aws-replicator&subdirectory=aws-replicator" -``` +If you wish to access the deprecated instructions, they can be found [here](https://github.com/localstack/localstack-extensions/blob/fe0c97e8a9d94f72c80358493e51ce6c1da535dc/aws-replicator/README.md#resource-replicator-cli). ## Change Log diff --git a/aws-replicator/aws_replicator/server/ui/app.js b/aws-replicator/aws_replicator/server/ui/app.js index e4da2d5..c254530 100644 --- a/aws-replicator/aws_replicator/server/ui/app.js +++ b/aws-replicator/aws_replicator/server/ui/app.js @@ -112,8 +112,6 @@ const App = () => { -

AWS Resource Replicator

- Configuration switches coming soon ... ); } diff --git a/aws-replicator/aws_replicator/server/ui/index.html b/aws-replicator/aws_replicator/server/ui/index.html index 845f5d4..b4393f8 100644 --- a/aws-replicator/aws_replicator/server/ui/index.html +++ b/aws-replicator/aws_replicator/server/ui/index.html @@ -15,17 +15,11 @@
-

AWS Replicator - LocalStack Extension

+

AWS Cloud Proxy - LocalStack Extension

This extension allows you to mirror resources from real AWS accounts into your LocalStack instance, thereby "bridging the gap" between local and remote cloud resources.

Some common use cases are: developing a local Lambda function that accesses a remote DynamoDB table; running a local Athena SQL query in LocalStack accessing files in a real S3 bucket in AWS; seeding a local Terraform script with SSM parameters from a real AWS account -

- The extension currently offers two modes of operation: -

    -
  1. AWS Connection Proxy
    2. -
  2. AWS Resource Replicator
    3. -