En ocasiones nuestros servicios deben integrarse con infraestructuras difíciles de reproducir en local para el desarrollo o para ejecutar los tests, y AWS es un ejemplo de ello.

Para los tests, a veces con mocks puede bastar para sortear el problema.

Pero, para probar nuestro servicio en local, deberíamos usar nuestras credenciales de AWS y conectarnos al entorno real? Y... los demás miembros del equipo?

En este post veremos qué es LocalStack y lo usaremos para hacer funcionar en local un servicio para almacenar ficheros en S3.

LocalStack bajo el lema "a fully functional local AWS cloud stack" puede ser la herramienta que necesitemos para algunos de nuestros desarrollos con los SDKs de AWS.

Dispone de una versión gratuita que nos permitirá desarrollar contra servicios como S3, SQS, DynamoDb, ...
Y otra versión de pago con servicios como CloudFront, Neptune, ...

ver detalle de servicios en cada versión...

Por poner un ejemplo (y código 🤓), supongamos que necesitamos una API contra la que postear imágenes que luego vamos a usar para servirlas en un entorno web.

Este es un caso de uso ideal para usar un bucket de S3 como sistema de almacenamiento y CloudFront como sistema de recuperación.

Así que... vamos a probar LocalStack 💻🚀

Nota: CloudFront forma parte de los servicios de la distribución de pago de LocalStack, así que no lo podremos probar en local sin pagar... aunque... si sabemos cómo acaba linkado un bucket de S3 como origin de una distribución de CloudFront y cómo afecta a las URL para recuperar los ficheros almacenados en S3, algo se nos va a ocurrir :)

Ejemplo

Name: Usando AWS S3 en local con LocalStack
Rating: 4.7 (7330 reviews)
Author: alextremp

alextremp / s3-storage-service-demo

AWS S3 storage en local con LocalStack

Este proyecto es una demo para un artículo en dev.to/alextremp

Servicio de almacenamiento de ficheros a bucket de S3

Un endpoint POST para enviar un fichero a un path específico.
El servicio almacenará el fichero a un bucket de S3.
Devolverá la URL de acceso del fichero, ya sea local, de S3 o de CloudFront si se dispone.

Uso

El endpoint de ejemplo estará expuesto para POST en http://localhost:8080/storage Acepta form-data con:

file: El fichero que queremos guardar en S3
path: La ruta donde queremos guardar el fichero, relativa respecto el bucket

Ejecución en local contra LocalStack

docker-compose up -d
./gradlew bootRun

Ejecución en local contra bucket real

# active profile set to production
PROFILE="--spring.profiles.active=pro"
# your AWS access key
ACCESS="--s3-storage.accessKey="
# your AWS secret key
SECRET="--s3-storage.secretKey="
# your AWS S3 bucket

…

View on GitHub

Stack:



java, spring-boot, aws-sdk, testcontainers

Levantando S3 con docker-compose

Configuremos el servicio de localstack:

docker-compose.yml



version: '3.5'

services:
  s3-storage:
    image: localstack/localstack:0.12.5
    environment:
      # permite más servicios separados por comas
      - SERVICES=s3 
      - DEBUG=1
      - DEFAULT_REGION=eu-west-1
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test
    ports:
      # localstack usa rango de puertos, para el ejemplo,
      # usaremos solo el de S3, mapeado en local a 14566 en un 
      # fichero docker-compose.override.yml para permitir 
      # tests con puerto dinámico
      - '4566'
    volumes:
      # inicializaremos un bucket aquí
      - './volumes/s3-storage/.init:/docker-entrypoint-initaws.d'
      # no versionado, localstack nos generará aquí el .pem 
      # para nuestras claves de acceso fake
      - './volumes/s3-storage/.localstack:/tmp/localstack'

Podemos generar un bucket al iniciar el docker-compose:

./volumes/s3-storage/.init/buckets.sh



#!/bin/bash
aws --endpoint-url=http://localhost:4566 s3 mb s3://com.github.alextremp.storage

Al ejecutar docker-compose up deberíamos ver que el cliente de AWS de la imagen de localstack ha generado el bucket que le hemos indicado en el script de inicialización:

Interactuando con el bucket

Para el artículo me interesa explicaros sólo unos puntos concretos del código de ejemplo, para que veamos cómo podemos hacerlo funcionar en local con LocalStack y en entorno productivo con AWS.

Tomando como referencia el repositorio que usará el SDK de AWS para S3 de cara a guardar un fichero (en realidad el InputStream de un recurso recibido en un POST multipart):



  public S3ResourceRepository(S3Client s3Client,
                              S3ResourceRepositoryOptions repositoryOptions,
                              DestinationFactory destinationFactory) {
    this.s3Client = s3Client;
    this.repositoryOptions = repositoryOptions;
    this.destinationFactory = destinationFactory;
  }

  @Override
  public Destination save(StreamableResource streamableResource, ResourceOptions resourceOptions) {
    PutObjectRequest.Builder requestBuilder = PutObjectRequest.builder()
          // the target bucket
          .bucket(repositoryOptions.getBucket())
          // the target path in the bucket
          .key(resourceOptions.getPath());

    // setting the content-type makes it web-friendly when being read
    requestBuilder.contentType(URLConnection.guessContentTypeFromName(resourceOptions.getPath()));
    // it's highly recommendable to specify the cache-control for presupposed repetitive reads, specially if it's combined with CloudFront
    requestBuilder.cacheControl(String.format("public, max-age=%s", resourceOptions.getMaxAge()));

    if (!repositoryOptions.hasOriginReference()) {
      // when needed to be read directly from S3, no need if it's a bucket linked to CloudFront
      requestBuilder.acl(ObjectCannedACL.PUBLIC_READ);
    }

    PutObjectRequest objectRequest = requestBuilder.build();
    s3Client.putObject(objectRequest, RequestBody.fromInputStream(streamableResource.stream(), streamableResource.contentLength()));

    return destinationFactory.create(resourceOptions.getPath());
  }

En realidad, para que el servicio sea funcional en local igual que en producción (e incluso si tuviéramos un entorno intermedio de desarrollo o pre-producción en la nube), lo más interesante son las opciones que podemos necesitar modificar para el funcionamiento del repositorio en cada uno de los entornos.



@Data
@FieldDefaults(level = AccessLevel.PRIVATE)
@Accessors(chain = true)
@NoArgsConstructor
public class S3ResourceRepositoryOptions {
  String region;
  String accessKey;
  String secretKey;
  String bucket;
  String endpoint;
  String originFor;

  public Boolean hasCustomEndpoint() {
    return StringUtils.isNotBlank(endpoint);
  }

  public Boolean hasOriginReference() {
    return StringUtils.isNotBlank(originFor);
  }
}

S3 Endpoint Override



# application-dev.yml
s3-storage:
  endpoint: http://localhost:14566

Con respecto a la opción hasCustomEndpoint, en local, tanto para podernos comunicar con S3 al guardar un fichero (por defecto, tipo s3://BUCKET/PATH), como para luego poderlo recuperar vía HTTP (por defecto, tipo https://s3-REGION.amazonaws.com/BUCKET/PATH), necesitamos modificar el endpoint que expone S3 en LocalStack y usarlo en el servicio para comunicarnos con él.

En LocalStack ya lo hemos hecho en el script de inicialización en docker-compose mediante aws --endpoint-url=http://localhost:4566 ...
En la creación del cliente de S3, debemos ligarlo mediante la opción endpointOverride:



@Configuration
@ComponentScan("com.github.alextremp.storage.infrastructure.aws")
public class AwsConfiguration {

  @Bean
  @ConfigurationProperties(prefix = "s3-storage")
  public S3ResourceRepositoryOptions s3ResourceRepositoryOptions() {
    return new S3ResourceRepositoryOptions();
  }

  @Bean
  public S3Client s3Client(S3ResourceRepositoryOptions s3ResourceRepositoryOptions) {
    S3ClientBuilder s3ClientBuilder = S3Client.builder()
          .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(
                s3ResourceRepositoryOptions.getAccessKey(),
                s3ResourceRepositoryOptions.getSecretKey()
          )))
          .region(Region.of(s3ResourceRepositoryOptions.getRegion()));

    if (s3ResourceRepositoryOptions.hasCustomEndpoint()) {
      s3ClientBuilder.endpointOverride(URI.create(s3ResourceRepositoryOptions.getEndpoint()));
    }
    return s3ClientBuilder.build();
  }
}

Esto nos permitirá guardar correctamente ficheros en localhost:

Así como recuperarlos vía HTTP:

Habilitando salida en CloudFront para PROD

Si usáramos este servicio para interactuar con un bucket real, sin CloudFront, p.ej.:



# application-pro.yml
s3-storage:
  bucket: a.dcdn.es

  # add the accessKey and secretKey config...

La URL que necesitaríamos generar para poder acceder vía HTTPS al mismo recurso en S3, sería algo así:
https://s3-eu-west-1.amazonaws.com/a.dcdn.es/demo/demo-image.png

Sin embargo, si tuviéramos ese bucket mapeado como origen en una distribución de CloudFront, p.ej.:

Aunque no podamos probar CloudFront en LocalStack, podríamos configurar el servicio para que generara las URL necesarias para la salida via CloudFront:



# application-pro.yml
s3-storage:
  bucket: a.dcdn.es
  originFor: a.dcdn.es

  # add the accessKey and secretKey config...

Para que esto sea así, y para terminar con el ejemplo de código, sólo necesitaremos que nuestro servicio sea capaz de generar las URL según las propiedades del storage:



@Component
public class AwsDestinationFactory implements DestinationFactory {

  private static final String HTTPS_PROTOCOL = "https://";
  private static final String AWS_S3_DOMAIN_TEMPLATE = "s3-%s.amazonaws.com";

  private final S3ResourceRepositoryOptions options;

  public AwsDestinationFactory(S3ResourceRepositoryOptions options) {
    this.options = options;
  }

  @Override
  @SneakyThrows
  public Destination create(String path) {
    StringBuilder rootBuilder = new StringBuilder();
    if (options.hasOriginReference()) {
      rootBuilder.append(HTTPS_PROTOCOL)
            .append(options.getOriginFor());
    } else if (options.hasCustomEndpoint()) {
      rootBuilder.append(options.getEndpoint())
            .append(Destination.SEPARATOR)
            .append(options.getBucket());
    } else {
      rootBuilder.append(HTTPS_PROTOCOL)
            .append(String.format(AWS_S3_DOMAIN_TEMPLATE, options.getRegion()))
            .append(Destination.SEPARATOR)
            .append(options.getBucket());
    }
    return new Destination(rootBuilder.toString(), path);
  }
}

🚀🚀

Conclusiones

Desde mi punto de vista, cuando hay código en producción cuya ejecución no es reproducible en local / automatizable en tests, tenemos dos opciones: hacerlo reproducible en local, o cruzar los dedos 😬

Pero como necesitamos los dedos para teclear, LocalStack, junto con Docker Compose y Test Containers pueden ayudarnos a solventar los problemas de infraestructura para la ejecución local cuando trabajamos integrados con servicios de AWS, de modo que nosotros podamos focalizarnos en el código más que en el entorno de ejecución.

Si algún día hacéis algo con S3, sois libres de copy-pastear lo que necesitéis :)