Dev services for Amazon Services

Quarkus Amazon Services automatically starts a LocalStack container in dev mode and when running tests. So, you don’t have to start one manually. The extension client is configured automatically.

Enabling / Disabling Dev Services for Amazon Services

Dev Services for Amazon Services is automatically enabled for each extensions added to pom.xml except in the following situations:

  • quarkus.devservices.enabled is set to false

  • devservices.enabled is set to false per extension (eg. quarkus.s3.devservices.enabled=false)

  • the endpoint-override is configured (eg. quarkus.s3.endpoint-override=http://localhost:4566)

  • Your environment does not support Docker. In test mode, it will cause the test to fail. Either disable Dev Services or configure the endpoint-override.

Shared services

By default, Dev Services for Amazon Services will start one LocalStack container with only the needed services.

If you need to share a particular service between applications, Dev Services for Amazon Services implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single container.

Dev Services for Amazon Services starts the container with the quarkus-dev-service-localstack label and service name as the value, which is used to identify the container. If you need multiple (shared) container, you can configure the devservices.service-name attribute for a given extension (eg. quarkus.s3.devservices.service-name) and indicate the container name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is localstack.

By default, to ease sharing containers across multiple applications, each service will be started in its own container (the value of the quarkus-dev-service-localstack label is suffixed by the extension name). However, sometimes, some services need to communicate with each other inside the same container (e.g., subscribing an Amazon SQS queue to an Amazon SNS topic). In this case, you can disable this behavior by setting the devservices.isolated attribute for a given extension to false.

Sharing is disabled by default in dev mode, and is always disabled in test mode. You can enable the sharing with devservices.shared=true for a given extension (e.g. quarkus.s3.devservices.shared=true). All other non-shared services will be grouped in another container.

Configuring the image

Dev Services for Amazon Services uses localstack/localstack image. You can configure the image and version using the quarkus.aws.devservices.localstack.image-name property:

quarkus.aws.devservices.localstack.image-name=localstack/localstack:3.7.2

Specific configuration

Dev Services for Amazon Services can support specific properties sent to the container. It can be globally applied to all containers or be specified per service as follows:

quarkus.aws.devservices.localstack.container-properties.START_WEB=0
quarkus.dynamodb.devservices.container-properties.DYNAMODB_HEAP_SIZE=1G

Refer to the LocalStack documentation for more configuration : https://docs.localstack.cloud/localstack/configuration/#local-aws-services. Note that not all environment variables are supported and some may affect Dev Services for Amazon Services.

Additional services

To start additional services for which a Quarkus extension does not exist or is not imported in the project, use the additional-services property:

quarkus.aws.devservices.localstack.additional-services."kinesis".enabled=true
quarkus.aws.devservices.localstack.additional-services."redshift".enabled=true

The key is the name of the service to enable and must be a valid LocalStack service name.

Additional setup

Some extensions support additional configuration to be applied at startup. Refer to the extension documentation.

Cognito

The Cognito extension is not using LocalStack but Moto.

Dev Services for Amazon Services uses the latest motoserver/moto image. You can configure the image and version using the quarkus.aws.devservices.moto.image-name property:

quarkus.aws.devservices.moto.image-name=motoserver/moto:3.0.2

Dev Services for Amazon Services can support specific properties sent to the container as follows:

quarkus.aws.devservices.moto.container-properties.MOTO_COGNITO_IDP_USER_POOL_ID_STRATEGY=HASH

Global DevServices Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.aws.devservices.localstack.image-name

The LocalStack container image to use.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_IMAGE_NAME

string

localstack/localstack:3.7.2

quarkus.aws.devservices.localstack.container-properties."container-properties"

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_CONTAINER_PROPERTIES__CONTAINER_PROPERTIES_

Map<String,String>

quarkus.aws.devservices.localstack.init-scripts-folder

Path to init scripts folder executed during localstack startup.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_INIT_SCRIPTS_FOLDER

string

quarkus.aws.devservices.localstack.init-scripts-classpath

Classpath to init scripts folder executed during localstack startup. initScriptsFolder has higher precedence.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_INIT_SCRIPTS_CLASSPATH

string

quarkus.aws.devservices.localstack.init-completion-msg

Specific container log message to be waiting for localstack init scripts completion.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_INIT_COMPLETION_MSG

string

quarkus.aws.devservices.localstack.port

Optional fixed port localstack will listen to.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_PORT

int

quarkus.aws.devservices.moto.image-name

The Moto container image to use.

Environment variable: QUARKUS_AWS_DEVSERVICES_MOTO_IMAGE_NAME

string

motoserver/moto

quarkus.aws.devservices.moto.container-properties."container-properties"

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_AWS_DEVSERVICES_MOTO_CONTAINER_PROPERTIES__CONTAINER_PROPERTIES_

Map<String,String>

quarkus.aws.devservices.localstack.additional-services."additional-services".enabled

If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_ADDITIONAL_SERVICES__ADDITIONAL_SERVICES__ENABLED

boolean

quarkus.aws.devservices.localstack.additional-services."additional-services".shared

Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.

The discovery uses the quarkus-dev-service-localstack label. The value is configured using the service-name property.

Sharing is not supported for the Cognito extension.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_ADDITIONAL_SERVICES__ADDITIONAL_SERVICES__SHARED

boolean

false

quarkus.aws.devservices.localstack.additional-services."additional-services".isolated

Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the quarkus-dev-service-localstack label will be suffixed by the service name (s3, sqs, …​)

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_ADDITIONAL_SERVICES__ADDITIONAL_SERVICES__ISOLATED

boolean

true

quarkus.aws.devservices.localstack.additional-services."additional-services".service-name

The value of the quarkus-dev-service-localstack label attached to the started container. In dev mode, when shared is set to true, before starting a container, Dev Services looks for a container with the quarkus-dev-service-localstack label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise it starts a new container with the quarkus-dev-service-localstack label set to the specified value. In test mode, Dev Services will group services with the same service-name value in one container instance.

This property is used when you need multiple shared LocalStack instances.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_ADDITIONAL_SERVICES__ADDITIONAL_SERVICES__SERVICE_NAME

string

localstack

quarkus.aws.devservices.localstack.additional-services."additional-services".container-properties."container-properties"

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_ADDITIONAL_SERVICES__ADDITIONAL_SERVICES__CONTAINER_PROPERTIES__CONTAINER_PROPERTIES_

Map<String,String>