feat: add localstack module

.github/dependabot.yml

@@ -12,6 +12,12 @@ updates:
         interval: weekly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/localstack
+      schedule:
+        interval: weekly
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/bigtable
       schedule:

.github/workflows/localstack-example.yml

@@ -0,0 +1,46 @@
+name: LocalStack example pipeline
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  test-localstack:
+    strategy:
+      matrix:
+        go-version: [1.18.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./modules/localstack
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./modules/localstack
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./modules/localstack
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-localstack*.xml"
+        if: always()

docs/examples/localstack.md

@@ -0,0 +1,134 @@
+# LocalStack
+
+The Testcontainers module for [LocalStack](http://localstack.cloud/) is _"a fully functional local AWS cloud stack"_, to develop and test your cloud and serverless apps without actually using the cloud.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the LocalStack module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/localstack
+```
+
+## Usage example
+
+Running LocalStack as a stand-in for multiple AWS services during a test:
+
+<!--codeinclude-->
+[Creating a LocalStack container](../../modules/localstack/v1/s3_test.go) inside_block:localStackCreateContainer
+<!--/codeinclude-->
+
+Environment variables listed in [Localstack's README](https://github.com/localstack/localstack#configurations) may be used to customize Localstack's configuration. 
+Use the `OverrideContainerRequest` option when creating the `LocalStackContainer` to apply configuration settings.
+
+## Creating a client using the AWS SDK for Go
+
+### Version 1
+
+<!--codeinclude-->
+[Test for a LocalStack container, usinv AWS SDK v1](../../modules/localstack/v1/s3_test.go) inside_block:awsSDKClientV1
+<!--/codeinclude-->
+
+For further reference on the SDK v1, please check out the AWS docs [here](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html).
+
+### Version 2
+
+<!--codeinclude-->
+[Test for a LocalStack container, usinv AWS SDK v2](../../modules/localstack/v2/s3_test.go) inside_block:awsSDKClientV2
+<!--/codeinclude-->
+
+For further reference on the SDK v2, please check out the AWS docs [here](https://aws.github.io/aws-sdk-go-v2/docs/getting-started)
+
+## `HOSTNAME_EXTERNAL` and hostname-sensitive services
+
+Some Localstack APIs, such as SQS, require the container to be aware of the hostname that it is accessible on - for example, for construction of queue URLs in responses.
+
+Testcontainers will inform Localstack of the best hostname automatically, using the `HOSTNAME_EXTERNAL` environment variable:
+
+* when running the Localstack container directly without a custom network defined, it is expected that all calls to the container will be from the test host. As such, the container address will be used (typically localhost or the address where the Docker daemon is running).
+
+    <!--codeinclude-->
+    [Localstack container running without a custom network](../../modules/localstack/localstack_legacy_mode_test.go) inside_block:withoutNetwork
+    <!--/codeinclude-->
+
+* when running the Localstack container [with a custom network defined](/features/networking/#advanced-networking), it is expected that all calls to the container will be **from other containers on that network**. `HOSTNAME_EXTERNAL` will be set to the *last* network alias that has been configured for the Localstack container.
+
+    <!--codeinclude-->
+    [Localstack container running with a custom network](../../modules/localstack/localstack_test.go) inside_block:withNetwork
+    <!--/codeinclude-->
+
+* Other usage scenarios, such as where the Localstack container is used from both the test host and containers on a custom network are not automatically supported. If you have this use case, you should set `HOSTNAME_EXTERNAL` manually.
+
+## Module reference
+
+The LocalStack module exposes one single function to create containers, and this function receives three parameters:
+
+- `context.Context`
+- `OverrideContainerRequestOption`
+- a variadic argument of `LocalStackContainerOption`
+
+### OverrideContainerRequestOption
+
+The `OverrideContainerRequestOption` functional option represents a way to override the default LocalStack container request:
+
+<!--codeinclude-->
+[Default container request](../../modules/localstack/localstack.go) inside_block:defaultContainerRequest
+<!--/codeinclude-->
+
+With simply passing your own instance of an `OverrideContainerRequestOption` type to the `StartContainer` function, you'll be able to configure the LocalStack container with your own needs.
+
+In the following example you check how it's possible to set certain environment variables that are needed by the tests. Besides, the container runs in a separate Docker network with an alias:
+
+<!--codeinclude-->
+[Overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:withNetwork
+<!--/codeinclude-->
+
+If you do not need to override the container request, you can pass `nil` or the `NoopOverrideContainerRequest` instance, which is exposed as a helper for this reason.
+
+<!--codeinclude-->
+[Skip overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:noopOverrideContainerRequest
+<!--/codeinclude-->
+
+### LocalStackContainerOption, variadic argument
+
+#### WithServices
+
+The `WithServices` functional option represents a way to pass as many AWS services as needed, in a variadic manner:
+
+<!--codeinclude-->
+[Passing AWS services to LocalStack](../../modules/localstack/v1/s3_test.go) inside_block:localStackCreateContainer
+<!--/codeinclude-->
+
+Using this method will internally populate the `SERVICES` environment variable, alongside the exposed ports of each service.
+
+### Available AWS Services
+
+The LocalStack module supports the following AWS services:
+
+- APIGateway
+- CloudFormation
+- CloudWatch
+- CloudWatchLogs
+- DynamoDB
+- DynamoDBStreams
+- EC2
+- Firehose
+- IAM
+- KMS
+- Kinesis
+- Lambda
+- Redshift
+- Route53
+- S3
+- SES
+- SNS
+- SQS
+- SSM
+- STS
+- SecretsManager
+- StepFunctions
+
+!!!info
+
+	At this moment, the tests for the module include tests for the S3 service, only. They live in two different Go packages of the LocalStack module,
+    `v1` and `v2`, where it'll be easier to add more examples for the rest of services.

examples/dependabot_test.go

@@ -53,7 +53,7 @@ func TestExamplesHasDependabotEntry(t *testing.T) {
 	require.NoError(t, err)
 
 	// we have to exclude the main and compose modules from the examples updates
-	assert.Equal(t, len(exampleUpdates)-2, len(examples))
+	assert.Equal(t, len(exampleUpdates)-3, len(examples))
 
 	// all example modules exist in the dependabot updates
 	for _, example := range examples {

examples/mkdocs_test.go

@@ -63,7 +63,7 @@ func TestExamples(t *testing.T) {
 	require.NoError(t, err)
 
 	// we have to remove the index.md file from the examples docs
-	assert.Equal(t, len(examplesDocs)-1, len(examples))
+	assert.Equal(t, len(examplesDocs)-2, len(examples))
 
 	// all example modules exist in the documentation
 	for _, example := range examples {

mkdocs.yml

@@ -53,6 +53,7 @@ nav:
         - examples/consul.md
         - examples/datastore.md
         - examples/firestore.md
+        - modules/localstack.md
         - examples/mongodb.md
         - examples/mysql.md
         - examples/nginx.md

modules/localstack/Makefile

@@ -0,0 +1,5 @@
+include ../../commons-test.mk
+
+.PHONY: test
+test:
+	$(MAKE) test-localstack

modules/localstack/go.mod

@@ -0,0 +1,79 @@
+module github.com/testcontainers/testcontainers-go/modules/localstack
+
+go 1.18
+
+require (
+	github.com/aws/aws-sdk-go v1.44.192
+	github.com/aws/aws-sdk-go-v2 v1.17.4
+	github.com/aws/aws-sdk-go-v2/config v1.18.12
+	github.com/aws/aws-sdk-go-v2/credentials v1.13.12
+	github.com/aws/aws-sdk-go-v2/service/s3 v1.30.2
+	github.com/docker/go-connections v0.4.0
+	github.com/imdario/mergo v0.3.12
+	github.com/stretchr/testify v1.8.1
+	github.com/testcontainers/testcontainers-go v0.17.0
+	golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4
+	gotest.tools/gotestsum v1.9.0
+)
+
+require (
+	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
+	github.com/Microsoft/go-winio v0.5.2 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.4.10 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.12.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.1.28 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.3.29 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.0.19 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.9.11 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.1.23 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.22 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.13.22 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.12.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.14.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.18.3 // indirect
+	github.com/aws/smithy-go v1.13.5 // indirect
+	github.com/cenkalti/backoff/v4 v4.2.0 // indirect
+	github.com/containerd/containerd v1.6.16 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dnephin/pflag v1.0.7 // indirect
+	github.com/docker/distribution v2.8.1+incompatible // indirect
+	github.com/docker/docker v20.10.20+incompatible // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/fatih/color v1.13.0 // indirect
+	github.com/fsnotify/fsnotify v1.5.4 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
+	github.com/google/uuid v1.3.0 // indirect
+	github.com/jmespath/go-jmespath v0.4.0 // indirect
+	github.com/klauspost/compress v1.15.9 // indirect
+	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/mattn/go-colorable v0.1.12 // indirect
+	github.com/mattn/go-isatty v0.0.16 // indirect
+	github.com/moby/patternmatcher v0.5.0 // indirect
+	github.com/moby/sys/sequential v0.5.0 // indirect
+	github.com/moby/term v0.0.0-20221128092401-c43b287e0e0f // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.0-rc2 // indirect
+	github.com/opencontainers/runc v1.1.3 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/sirupsen/logrus v1.9.0 // indirect
+	golang.org/x/net v0.1.0 // indirect
+	golang.org/x/sync v0.1.0 // indirect
+	golang.org/x/sys v0.4.0 // indirect
+	golang.org/x/term v0.1.0 // indirect
+	golang.org/x/tools v0.1.12 // indirect
+	google.golang.org/genproto v0.0.0-20220617124728-180714bec0ad // indirect
+	google.golang.org/grpc v1.47.0 // indirect
+	google.golang.org/protobuf v1.28.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	gotest.tools/v3 v3.4.0 // indirect
+)
+
+replace (
+	github.com/docker/docker => github.com/docker/docker v20.10.3-0.20221013203545-33ab36d6b304+incompatible // 22.06 branch
+	github.com/testcontainers/testcontainers-go => ../..
+)