diff --git a/menu/menu.yaml b/menu/menu.yaml index 5e38cc5d212..c325cbde2ae 100644 --- 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 new file mode 100644 index 00000000000..e70e2bb0938 --- /dev/null +++ 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 new file mode 100644 index 00000000000..1b2106849d7 --- /dev/null +++ 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 index 3f3ca435b19..7ca60520e4a 100644 --- 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 index 89fb891a330..3a300d5e859 100644 --- 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=` - 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 index ce21803cc9b..c0366eff5ed 100644 --- 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 index ed855fe7cb9..0fe55a5edce 100644 --- 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) \ No newline at end of file +|Native integration |[Supported](native-integration.md) +|Local development |[Supported via LocalStack](/nservicebus/aws/local-development.md) \ No newline at end of file