Provisioning LocalStack AWS Resources in Spring Boot Tests

When writing integration tests for Spring Boot applications that interact with AWS services like S3, DynamoDB, SNS, SQS, and etc, you're most likely already using LocalStack to simulate the AWS environment.

Although LocalStack provides an emulated AWS environment, we're still required to provision the specific resources needed for testing our application. In this article, we'll explore how we can automate resource provisioning using Initialization Hooks in our LocalStack container.

In addition to looking at how Initialization Hooks can be used with Testcontainers during integration testing, we'll also explore their usage with Docker Compose for local development setups.

We'll first take a look at a basic example of provisioning an S3 bucket, and then we'll tackle a more complex scenario involving the creation of an SNS topic and an SQS queue, along with setting up a pub/sub relationship between them by subscribing the created queue with the SNS topic.

In simple terms, Initialization Hooks (or “init hooks”) are shell scripts that are executed by LocalStack at specific stages during the container lifecycle. For our use case of provisioning resources, we'll focus on the READY stage, which signifies that the LocalStack container is ready to accept requests.

Shell scripts to be executed can be mounted in the /etc/localstack/init/ready.d directory within the LocalStack container and are executed in alphanumerical order. This is particularly useful when setting up resources required for testing or local development, such as creating S3 buckets, DynamoDB tables, SNS topics, SQS queues, or any other supported AWS service.

We can use the awslocal command inside the shell scripts, which is a wrapper around the aws CLI that points to the LocalStack endpoints.

This setup ensures that the required AWS services are provisioned before any tests are executed.

Testcontainers exposes an execInContainer() method, which allows us to execute commands inside a running container. You might be wondering, why don't we just use this method to provision the required AWS resources by executing our awslocal commands directly in the LocalStack container?

Here are a few reasons why using initialization hooks is a better approach:

• Readability: By extracting the resource provisioning logic into separate shell scripts, our test code becomes cleaner and more focused. The test class is only responsible for starting the LocalStack container and mounting the scripts, making it easier to understand at a glance.

• Reusability: Init scripts can be reused across multiple test classes which require the same resources to be provisioned by simply mounting the created scripts into the container. With the execInContainer() method, we'd have to duplicate the provisioning logic in each of our test classes. Additionally, the created scripts can also be mounted when starting a LocalStack container via Docker Compose for local development.

• Maintainability: If there is any update required, we only need to change the content of our existing init scripts. This is much easier than hunting down every place where execInContainer() is used and updating the commands.

• Flexibility: Init scripts provide us with the full power of bash scripting. We can use variables, logs, loops, conditionals, and other constructs to create more dynamic provisioning logic. With the execInContainer() method, we're limited to executing simple, one-off commands.

With the above points, I think we can agree that initialization hooks offer a cleaner and a more powerful approach for provisioning AWS resources inside our LocalStack container.

Let's dive into a concrete example to understand how initialization hooks work. We'll start with a simple case of provisioning an S3 bucket for our tests.

First, we create a bash script named init-s3-bucket.sh in our src/test/resources directory with the following content:

The above script uses the awslocal command to create an S3 bucket named behl-rieck-bucket. We also add a couple of echo statements to print out a success message and the name of the executed script.

Next, in our integration test class, we'll configure and start a LocalStack container. At the time of this writing, the latest version of the LocalStack image is 3.4. We'll be using this version in our integration test class:

We use the withCopyFileToContainer() method to mount our init-s3-bucket.sh script into the LocalStack container's /etc/localstack/init/ready.d directory. The 0744 flag ensures that the script has the necessary execute permissions.

We also configure a wait strategy using the waitingFor() method to wait for the log Executed init-s3-bucket.sh to be printed, as defined in our init script. This ensures that our script has run and provisioned the required S3 bucket before any of our tests execute.

If we check the logs of the started LocalStack container, we'll see the output of our init script:

We can see that the S3 bucket behl-rieck-bucket was successfully created, and our init script was executed as expected. We can now use this S3 bucket in our integration tests and be confident about its existence.