2. Basic setup

Before using the Spring Cloud AWS module developers have to pick the dependencies and configure the Spring Cloud AWS module. The next chapters describe the dependency management and also the basic configuration for the Spring AWS Cloud project.spring-doc.cn

2.1. Spring Cloud AWS maven dependency management

Spring Cloud AWS module dependencies can be used directly in Maven with a direct configuration of the particular module. The Spring Cloud AWS module includes all transitive dependencies for the Spring modules and also the Amazon SDK that are needed to operate the modules. The general dependency configuration will look like this:spring-doc.cn

<dependencies>
  <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-aws-context</artifactId>
    <version>{spring-cloud-version}</version>
  </dependency>
</dependencies>

Different modules can be included by replacing the module name with the respective one (e.g. spring-cloud-aws-messaging instead of spring-cloud-aws-context)spring-doc.cn

The example above works with the Maven Central repository. To use the Spring Maven repository (e.g. for milestones or developer snapshots), you need to specify the repository location in your Maven configuration. For full releases:spring-doc.cn

<repositories>
    <repository>
        <id>io.spring.repo.maven.release</id>
        <url>https://repo.spring.io/release/</url>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
</repositories>

For milestones:spring-doc.cn

<repositories>
    <repository>
        <id>io.spring.repo.maven.milestone</id>
        <url>https://repo.spring.io/milestone/</url>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
</repositories>

2.2. Amazon SDK dependency version management

Amazon SDK is released more frequently than Spring Cloud AWS. If you need to use newer version of AWS SDK than one configured by Spring Cloud AWS add AWS SDK BOM to dependency management section making sure it is declared before any other BOM dependency that configures AWS SDK dependencies.spring-doc.cn

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>${aws-java-sdk.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2.3. Amazon SDK configuration

The Spring Cloud AWS configuration is currently done using custom elements provided by Spring Cloud AWS namespaces. JavaConfig will be supported soon. The configuration setup is done directly in Spring XML configuration files so that the elements can be directly used. Each module of Spring Cloud AWS provides custom namespaces to allow the modular use of the modules. A typical XML configuration to use Spring Cloud AWS is outlined below:spring-doc.cn

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:aws-context="http://www.springframework.org/schema/cloud/aws/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
        https://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/cloud/aws/context
        http://www.springframework.org/schema/cloud/aws/context/spring-cloud-aws-context.xsd">

           <aws-context:context-region region="..."/>
</beans>

On application startup, for its internal purposes Spring Cloud AWS performs a check if application runs in AWS cloud environment by using EC2MetadataUtils class provided by AWS SDK. Starting from version 1.11.678, AWS SDK logs a warning message with exception when this check is made outside of AWS environment. This warning message can be hidden by setting ERROR logging level on com.amazonaws.util.EC2MetadataUtils class.spring-doc.cn

logging.level.com.amazonaws.util.EC2MetadataUtils=error

2.3.1. SDK credentials configuration

In order to make calls to the Amazon Web Service the credentials must be configured for the the Amazon SDK. Spring Cloud AWS provides support to configure an application context specific credentials that are used for each service call for requests done by Spring Cloud AWS components, with the exception of the Parameter Store and Secrets Manager Configuration. Therefore there must be exactly one configuration of the credentials for an entire application context.spring-doc.cn

The com.amazonaws.auth.DefaultAWSCredentialsProviderChain is used by all the clients if there is no dedicated credentials provider defined. This will essentially use the following authentication informationspring-doc.cn

  • use the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEYspring-doc.cn

  • use the system properties aws.accessKeyId and aws.secretKeyspring-doc.cn

  • use the user specific profile credentials filespring-doc.cn

  • use ECS credentials if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is setspring-doc.cn

  • use the instance profile credentials (see below)spring-doc.cn

Based on the overall credentials policy there are different options to configure the credentials. The possible ones are described in the following sub-chapters.spring-doc.cn

Simple credentials configuration

Credentials for the Amazon SDK consist of an access key (which might be shared) and a secret key (which must not be shared). Both security attributes can be configured using the XML namespaces for each Amazon SDK service created by the Spring Cloud AWS module. The overall configuration looks like thisspring-doc.cn

<beans ...>
  <aws-context:context-credentials>
   <aws-context:simple-credentials access-key="AKIAIO" secret-key="wJalrXUtnFEMI/K7M" />
  </aws-context:context-credentials>
</beans>

The access-key and secret-key should be externalized into property files (e.g. Spring Boot application configuration) and not be checked in into the source management system.spring-doc.cn
Instance profile configuration

An instance profile configuration allows to assign a profile that is authorized by a role while starting an EC2 instance. All calls made from the EC2 instance are then authenticated with the instance profile specific user role. Therefore there is no dedicated access-key and secret-key needed in the configuration. The configuration for the instance profile in Spring Cloud AWS looks like this:spring-doc.cn

<beans ...>
    <aws-context:context-credentials>
        <aws-context:instance-profile-credentials/>
    </aws-context:context-credentials>
</beans>
Mixing both security configurations

In some cases it is useful to combine both authentication strategies to allow the application to use the instance profile with a fallback for an explicit access-key and secret-key configuration. This is useful if the application is tested inside EC2 (e.g. on a test server) and locally for testing. The next snippet shows a combination of both security configurations.spring-doc.cn

<beans ...>
   <aws-context:context-credentials>
       <aws-context:instance-profile-credentials/>
       <aws-context:simple-credentials access-key="${accessKey:}" secret-key="${secretKey:}"/>
   </aws-context:context-credentials>
</beans>

The access-key and secret-key are defined using a placeholder expressions along with a default value to avoid bootstrap errors if the properties are not configured at all.spring-doc.cn
Parameter Store and Secrets Manager Configuration credentials and region configuration

The Parameter Store and Secrets Manager Configuration support uses a bootstrap context to configure a default AWSSimpleSystemsManagement client, which uses a com.amazonaws.auth.DefaultAWSCredentialsProviderChain and com.amazonaws.regions.DefaultAwsRegionProviderChain. If you want to override this, then you need to define your own Spring Cloud bootstrap configuration class with a bean of type AWSSimpleSystemsManagement that’s configured to use your chosen credentials and/or region provider. Because this context is created when your Spring Cloud Bootstrap context is created, you can’t simply override the bean in a regular @Configuration class.spring-doc.cn

2.3.2. Region configuration

Amazon Web services are available in different regions. Based on the custom requirements, the user can host the application on different Amazon regions. The spring-cloud-aws-context module provides a way to define the region for the entire application context.spring-doc.cn

Explicit region configuration

The region can be explicitly configured using an XML element. This is particularly useful if the region can not be automatically derived because the application is not hosted on a EC2 instance (e.g. local testing) or the region must be manually overridden.spring-doc.cn

<beans ...>
    <aws-context:context-region region="eu-west-1"/>
</beans>

It is also allowed to use expressions or placeholders to externalize the configuration and ensure that the region can be reconfigured with property files or system properties.spring-doc.cn
Automatic region configuration

If the application context is started inside an EC2 instance, then the region can automatically be fetched from the instance metadata and therefore must not be configured statically. The configuration will look like this:spring-doc.cn

<beans ...>
  <aws-context:context-region auto-detect="true" />
</beans>
Service specific region configuration

A region can also be overridden for particular services if one application context consumes services from different regions. The configuration can be done globally like described above and configured for each service with a region attribute. The configuration might look like this for a database service (described later)spring-doc.cn

<beans ...>
 <aws-context:context-region region="eu-central-1" />
 <jdbc:data-source ... region="eu-west-1" />
</beans>

While it is theoretically possible to use multiple regions per application, we strongly recommend to write applications that are hosted only inside one region and split the application if it is hosted in different regions at the same time.spring-doc.cn

2.3.3. Spring Boot auto-configuration

Following the Spring Cloud umbrella project, Spring Cloud AWS also provides dedicated Spring Boot support. Spring Cloud AWS can be configured using Spring Boot properties and will also automatically guess any sensible configuration based on the general setup.spring-doc.cn

Maven dependencies

Spring Cloud AWS provides a dedicated module to enable the Spring Boot support. That module must be added to the general maven dependency inside the application. The typical configuration will look like thisspring-doc.cn

<dependencies>
  <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-aws-autoconfigure</artifactId>
    <version>{spring-cloud-version}</version>
  </dependency>
</dependencies>

Additional dependencies to enable particular features like messaging and JDBC have to be added. Spring Cloud AWS will only configure classes that are available in the Spring Boot application’s classpath.spring-doc.cn

Configuring credentials

Spring Boot provides a standard way to define properties with property file or YAML configuration files. Spring Cloud AWS provides support to configure the credential information with the Spring Boot application configuration files. Spring Cloud AWS provides the following properties to configure the credentials setup for the whole application.spring-doc.cn

Unless cloud.aws.credentials.use-default-aws-credentials-chain is set to true, Spring Cloud AWS configures following credentials chain:spring-doc.cn

  1. AWSStaticCredentialsProvider if cloud.aws.credentials.access-key is providedspring-doc.cn

  2. EC2ContainerCredentialsProviderWrapper unless cloud.aws.credentials.instance-profile is set to falsespring-doc.cn

  3. ProfileCredentialsProviderspring-doc.cn

property example description

cloud.aws.credentials.access-keyspring-doc.cn

AKIAIOSFODNN7EXAMPLEspring-doc.cn

The access key to be used with a static providerspring-doc.cn

cloud.aws.credentials.secret-keyspring-doc.cn

wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYspring-doc.cn

The secret key to be used with a static providerspring-doc.cn

cloud.aws.credentials.instance-profilespring-doc.cn

truespring-doc.cn

Configures an instance profile credentials provider with no further configurationspring-doc.cn

cloud.aws.credentials.profile-namespring-doc.cn

defaultspring-doc.cn

The name of a configuration profile in the specified configuration filespring-doc.cn

cloud.aws.credentials.profile-pathspring-doc.cn

~/.aws/credentialsspring-doc.cn

The file path where the profile configuration file is located. Defaults to ~/.aws/credentials if value is not providedspring-doc.cn

cloud.aws.credentials.use-default-aws-credentials-chainspring-doc.cn

truespring-doc.cn

Use the DefaultAWSCredentials Chain instead of configuring a custom credentials chainspring-doc.cn
Configuring region

Like for the credentials, the Spring Cloud AWS module also supports the configuration of the region inside the Spring Boot configuration files. The region can be automatically detected or explicitly configured (e.g. in case of local tests against the AWS cloud).spring-doc.cn

The properties to configure the region are shown belowspring-doc.cn

property example description

cloud.aws.region.autospring-doc.cn

truespring-doc.cn

Enables automatic region detection based on the EC2 meta data servicespring-doc.cn

cloud.aws.region.use-default-aws-region-chainspring-doc.cn

truespring-doc.cn

Use the DefaultAWSRegion Chain instead of configuring a custom region chainspring-doc.cn

cloud.aws.region.staticspring-doc.cn

eu-west-1spring-doc.cn

Configures a static region for the application. Possible regions are (currently) us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-southeast-1, ap-northeast-1, sa-east-1, cn-north-1 and any custom region configured with own region meta dataspring-doc.cn