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

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. To ease sharing, each service will be started in its own 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.services-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.

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:1.0.3

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

LocalStack Configuration

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:1.0.3

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-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.container-properties

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_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".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

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_AWS_DEVSERVICES_LOCALSTACK_ADDITIONAL_SERVICES__ADDITIONAL_SERVICES__CONTAINER_PROPERTIES

Map<String,String>

Moto Configuration

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

Configuration property

Type

Default

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

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_AWS_DEVSERVICES_MOTO_CONTAINER_PROPERTIES

Map<String,String>