feat(localstack): add Localstack integration test template
Summary
This MR adds a new LocalStack integration test template (.localstack_base) that makes it easy to run integration tests against AWS services locally in GitLab CI/CD pipelines.
LocalStack is a fully functional local AWS cloud stack that allows you to develop and test your cloud applications offline, without connecting to a remote cloud provider.
What's Included
Template File: localstack.yml
- Docker-in-Docker configuration with registry mirroring to avoid Docker Hub rate limits
-
LocalStack service with version management via
.tool-versions - Automatic readiness checks to ensure LocalStack is healthy before tests run
- AWS CLI and awslocal installation for convenient AWS service interaction
- Configurable timeouts and service selection for optimized startup times
Documentation: localstack.md
- Comprehensive usage examples for Go, Python, and Node.js projects
- Tips and best practices for:
- Specifying only needed services for faster startup
- Using the
awslocalwrapper - Controlling LocalStack version via
.tool-versions - Debugging LocalStack issues
- Initializing test data
- List of supported AWS services in LocalStack Community edition
Version Management
- LocalStack version controlled via
GL_ASDF_LOCALSTACK_VERSION - Auto-generated from
.tool-versionsfile (currently set to 4.11.1) - Projects can override by setting
localstackin their own.tool-versions
Usage Example
include:
- project: 'gitlab-com/gl-infra/common-ci-tasks'
ref: main
file: 'localstack.yml'
integration-tests:
image: golang:1.23
stage: verify
extends:
- .localstack_base
variables:
LOCALSTACK_SERVICES: "s3,dynamodb,secretsmanager"
script:
- awslocal s3 mb s3://test-bucket
- awslocal dynamodb create-table --table-name test-table --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST
- go test ./...
Key Features
- Zero configuration for basic usage - just extend the template
-
Flexible base image - override via
image:attribute to match your project's runtime - Service filtering - specify only the AWS services you need for faster startup
- Production-ready - includes retry logic, health checks, and error handling
- Follows project conventions - uses minimal clone, gitlab-org-docker tags, and ASDF version management
Documentation
- Main docs: localstack.md
- README updated with link to LocalStack template
I've tested this on gitlab-com/gl-infra/sandbox/donkey!76
Edited by Andrew Newdigate