Describe how to use Localstack to improve the development experience …

…with AWS (#6875) * Create a new resource describing how to use LocalStack to improve local development with AWS * Add reference to using LocalStack in the ServiceControl Transport Configuration. Add LocalStack documentation in the menu. * add empty AWS index.md * Update nservicebus/aws/index.md * Update nservicebus/aws/index.md * Apply suggestions from code review Co-authored-by: David Boike <[email protected]> * Apply suggestions from code review Co-authored-by: David Boike <[email protected]> * Update nservicebus/aws/local-development.md * Update nservicebus/aws/local-development.md * Link to local development support from "at a glance" tables * Shows the configuration for all services * Apply suggestions from code review Co-authored-by: Mauro Servienti <[email protected]> * Fixit --------- Co-authored-by: Mauro Servienti <[email protected]> Co-authored-by: David Boike <[email protected]>
Particular · Nov 6, 2024 · 9d2d586 · 9d2d586
1 parent f7f264d
commit 9d2d586
Show file tree

Hide file tree

Showing 7 changed files with 77 additions and 5 deletions.
diff --git a/menu/menu.yaml b/menu/menu.yaml
@@ -1113,6 +1113,8 @@
       Title: Native Integration
     - Url: transports/sqs/operations-scripting
       Title: Scripting
+    - Url: nservicebus/aws/local-development
+      Title: Local development
     - Url: transports/sqs/troubleshooting
       Title: Troubleshooting
 
@@ -1360,6 +1362,8 @@
       Title: Outbox
     - Url: persistence/dynamodb/transactions
       Title: Transactions
+    - Url: nservicebus/aws/local-development
+      Title: Local development
 
 - Name: ServiceInsight
   Topics:

diff --git a/nservicebus/aws/index.md b/nservicebus/aws/index.md
@@ -0,0 +1,11 @@
+---
+title: Particular Platform AWS support
+summary: AWS services supported by the Particular Platform
+reviewed: 2024-10-29
+---
+
+The Particular Platform supports the following AWS services:
+
+- Amazon SQS and SNS through the [NServiceBus Amazon SQS transport](/transports/sqs/)
+- Amazon DynamoDB through the [NServiceBus AWS DynamoDB persistence](/persistence/dynamodb/)
+- The various relational databases available on AWS, such as RDS, MySQL, or PostgreSQL through the [NServiceBus SQL persistence](/persistence/sql/)
diff --git a/nservicebus/aws/local-development.md b/nservicebus/aws/local-development.md
@@ -0,0 +1,50 @@
+---
+title: AWS local development using LocalStack
+summary: How to use LocalStack for your development needs when using Amazon SQS Transport and DynamoDB Persistence
+reviewed: 2024-10-29
+---
+
+[LocalStack](https://www.localstack.cloud/) is a tool to develop and test your AWS applications locally, reducing development time and increasing productivity.
+
+> [!NOTE]
+> Refer to the [official LocalStack documentation](https://docs.localstack.cloud/getting-started/installation/) to learn how to install and run it locally.
+
+To configure an NServiceBus endpoint to connect to LocalStack instead of AWS, the AWS endpoint URL must be set to the address of the LocalStack instance. The simplest way is by defining the `AWS_ENDPOINT_URL` environment variable and setting its value to the LocalStack URL:
+
+```
+AWS_ENDPOINT_URL=http://localhost.localstack.cloud:4566
+```
+
+Alternatively, configure the AWS SDK `ServiceURL` configuration property, like in the following example programmatically for the Amazon SQS transport:
+
+```csharp
+var amazonSqsConfig = new AmazonSQSConfig();
+amazonSqsConfig.ServiceURL = "http://localhost.localstack.cloud:4566";
+var amazonSqsClient = new AmazonSQSClient(amazonSqsConfig);
+```
+
+Similarly, the Amazon SNS and DynamoDB configurations must follow the same patter. The following snippet shows the SNS configuration:
+
+```csharp
+var amazonSnsConfig = new AmazonSimpleNotificationServiceConfig();
+amazonSnsConfig.ServiceURL = "http://localhost.localstack.cloud:4566";
+var amazonSnsClient = new AmazonSimpleNotificationServiceClient(amazonSnsConfig);
+```
+
+The DynamoDB configuration is shown in the following example:
+
+```csharp
+var amazonDynamoDBConfig = new AmazonDynamoDBConfig();
+amazonDynamoDBConfig.ServiceURL = "http://localhost.localstack.cloud:4566";
+var amazonDynamoDBClient = new AmazonDynamoDBClient(amazonDynamoDBConfig);
+```
+
+> [!NOTE]
+> Remember that, even if you are not connecting to AWS cloud services, it is still required to specify access credentials and region.
+> From the LocalStack perspective they could be fake values, like the following:
+>
+> ```bash
+> AWS_ACCESS_KEY_ID=demo
+> AWS_SECRET_ACCESS_KEY=demo
+> AWS_REGION=us-east-1
+> ```
diff --git a/persistence/dynamodb/index.md b/persistence/dynamodb/index.md
@@ -21,7 +21,8 @@ For a description of each feature, see the [persistence at a glance legend](/per
 |Transactions               |Using `TransactWriteItems`
 |Concurrency control        |Optimistic concurrency, optional pessimistic concurrency
 |Scripted deployment        |Not supported
-|Installers                 |Table is created by installers.
+|Installers                 |Table is created by installers
+|Local development          |[Supported via LocalStack](/nservicebus/aws/local-development.md)
 
 ## Usage
 

diff --git a/servicecontrol/transports.md b/servicecontrol/transports.md
@@ -1,6 +1,6 @@
 ---
 title: Transport configuration
-summary: ServiceControl can be configured to use one of the supported message transports which are configured for each instance type 
+summary: ServiceControl can be configured to use one of the supported message transports which are configured for each instance type
 reviewed: 2024-07-19
 component: ServiceControl
 ---
@@ -99,6 +99,10 @@ The following ServiceControl connection string options are available:
 * `S3KeyPrefix=<value>` - S3 key prefix [option](/transports/sqs/configuration-options.md#offload-large-messages-to-s3-key-prefix).
 * `DoNotWrapOutgoingMessages=true` - Do not wrap outgoing messages [option](/transports/sqs/configuration-options.md#do-not-wrap-message-payload-in-a-transport-envelope).
 
+> [!NOTE]
+> When using SQS as a transport, for local development purposes it is possible to set up ServiceControl to connect to a LocalStack instance.
+> Refer to the [documentation](/nservicebus/aws/local-development.md) about how to configure the environment to use LocalStack.
+
 ## MSMQ
 
 To configure MSMQ as the transport, ensure the MSMQ service has been installed and configured as outlined in [MSMQ configuration](/transports/msmq/#msmq-configuration).

diff --git a/transports/sqs/index_transport-at-a-glance_sqs_[4,5).partial.md b/transports/sqs/index_transport-at-a-glance_sqs_[4,5).partial.md
@@ -1,6 +1,6 @@
 ## Transport at a glance
 
-|Feature                    |   |  
+|Feature                    |   |
 |:---                       |---
 |Transactions |None, ReceiveOnly (Message visibility timeout)
 |Pub/Sub                    |Message driven
@@ -10,3 +10,4 @@
 |Scripted Deployment        |PowerShell, CloudFormation, C#
 |Installers                 |Optional
 |Native integration         |Not supported
+|Local development          |[Supported via LocalStack](/nservicebus/aws/local-development.md)
diff --git a/transports/sqs/index_transport-at-a-glance_sqs_[5,).partial.md b/transports/sqs/index_transport-at-a-glance_sqs_[5,).partial.md
@@ -1,6 +1,6 @@
 ## Transport at a glance
 
-|Feature                    |   |  
+|Feature                    |   |
 |:---                       |---
 |Transactions |None, ReceiveOnly (Message visibility timeout)
 |Pub/Sub                    |Native (Requires SNS, supports hybrid-mode for migration purposes)
@@ -9,4 +9,5 @@
 |Scale-out             |Competing consumer
 |Scripted Deployment        |Built-in CLI, C#
 |Installers                 |Optional
-|Native integration         |[Supported](native-integration.md)
+|Native integration         |[Supported](native-integration.md)
+|Local development          |[Supported via LocalStack](/nservicebus/aws/local-development.md)