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 awslocal wrapper
    • 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-versions file (currently set to 4.11.1)
  • Projects can override by setting localstack in 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

  1. Zero configuration for basic usage - just extend the template
  2. Flexible base image - override via image: attribute to match your project's runtime
  3. Service filtering - specify only the AWS services you need for faster startup
  4. Production-ready - includes retry logic, health checks, and error handling
  5. 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

Merge request reports

Loading