Skip to content

Commit 17ccc83

Browse files
maciejwalkowiakmaciejwalkowiak
committed
Merge remote-tracking branch 'origin/2.3.x' into master
2 parents 0bba93f + 92c49c6 commit 17ccc83

File tree

224 files changed

+14336
-1961
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

224 files changed

+14336
-1961
lines changed

‎README.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Manual changes to this file will be lost when it is generated again.
44
Edit the files in the src/main/asciidoc/ directory instead.
55
////
66

7+
78
= Spring Cloud for Amazon Web Services
89

910
Spring Cloud for Amazon Web Services, part of the Spring Cloud umbrella project, eases the integration with hosted Amazon Web Services. It offers a convenient way to interact with AWS provided services using well-known Spring idioms and APIs, such as the messaging or caching API. Developers can build their application around the hosted services without having to care about infrastructure or maintenance.
@@ -88,7 +89,7 @@ addresses must be verified for the Amazon SES Service.
8889
To build with the integration tests you must execute
8990

9091
-----------------------------------------------------------------------------------------------------
91-
mvn verify -Dcloud.aws.credentials.access-key=<access key> -Dcloud.aws.credentials.secret-key=<secret key> -DrdsPassword=<rds password> -DsenderAddress=<sender address> -DrecipientAddress=<recipient address>
92+
mvn verify -Daws-integration-tests.access-key=<access key> -Daws-integration-tests.secret-key=<secret key> -DrdsPassword=<rds password> -DsenderAddress=<sender address> -DrecipientAddress=<recipient address>
9293
-----------------------------------------------------------------------------------------------------
9394

9495
The integration test will create an
@@ -101,7 +102,6 @@ there are no unnecessary costs.
101102
The costs for one integration test run should not be more than 0.40 $
102103
per hour (excl. VAT).
103104

104-
105105
= Developing using Amazon Web Services
106106

107107
During development it might be time-consuming to run the integration

‎docs/src/main/asciidoc/_configprops.adoc

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,57 @@
33

44
|aws.paramstore.default-context | application |
55
|aws.paramstore.enabled | true | Is AWS Parameter Store support enabled.
6+
|aws.paramstore.endpoint | | Overrides the default endpoint.
67
|aws.paramstore.fail-fast | true | Throw exceptions during config lookup if true, otherwise, log warnings.
78
|aws.paramstore.name | | Alternative to spring.application.name to use in looking up values in AWS Parameter Store.
89
|aws.paramstore.prefix | /config | Prefix indicating first level for every property. Value must start with a forward slash followed by a valid path segment or be empty. Defaults to "/config".
910
|aws.paramstore.profile-separator | _ |
10-
|aws.paramstore.region | | The specific region for Parameter Store integration.
11-
|aws.secretsmanager.default-context | application |
11+
|aws.paramstore.region | | If region value is not null or empty it will be used in creation of AWSSimpleSystemsManagement.
12+
|aws.secretsmanager.default-context | application |
1213
|aws.secretsmanager.enabled | true | Is AWS Secrets Manager support enabled.
14+
|aws.secretsmanager.endpoint | | Overrides the default endpoint.
1315
|aws.secretsmanager.fail-fast | true | Throw exceptions during config lookup if true, otherwise, log warnings.
1416
|aws.secretsmanager.name | | Alternative to spring.application.name to use in looking up values in AWS Secrets Manager.
1517
|aws.secretsmanager.prefix | /secret | Prefix indicating first level for every property. Value must start with a forward slash followed by a valid path segment or be empty. Defaults to "/config".
1618
|aws.secretsmanager.profile-separator | _ |
17-
|aws.secretsmanager.region | | The specific region for Secrets Manager integration.
19+
|aws.secretsmanager.region | | If region value is not null or empty it will be used in creation of AWSSecretsManager.
1820
|cloud.aws.credentials.access-key | | The access key to be used with a static provider.
1921
|cloud.aws.credentials.instance-profile | false | Configures an instance profile credentials provider with no further configuration.
2022
|cloud.aws.credentials.profile-name | | The AWS profile name.
2123
|cloud.aws.credentials.profile-path | | The AWS profile path.
2224
|cloud.aws.credentials.secret-key | | The secret key to be used with a static provider.
25+
|cloud.aws.elasticache.cache-names | |
26+
|cloud.aws.elasticache.clusters | | Configures the cache clusters for the caching configuration. Support one or multiple caches {@link Cluster} configurations with their physical cache name (as configured in the ElastiCache service) or their logical cache name if the caches are configured inside a stack and {@link org.springframework.cloud.aws.context.config.annotation.EnableStackConfiguration} annotation is used inside the application.
27+
|cloud.aws.elasticache.default-expiration | 0 | Configures the default expiration time in seconds if there is no custom expiration time configuration with a {@link Cluster} configuration for the cache. The expiration time is implementation specific (e.g. Redis or Memcached) and could therefore differ in the behaviour based on the cache implementation.
28+
|cloud.aws.elasticache.enabled | true | Enables ElastiCache integration.
29+
|cloud.aws.elasticache.expiry-time-per-cache | |
2330
|cloud.aws.loader.core-pool-size | 1 | The core pool size of the Task Executor used for parallel S3 interaction. @see org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor#setCorePoolSize(int)
2431
|cloud.aws.loader.max-pool-size | | The maximum pool size of the Task Executor used for parallel S3 interaction. @see org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor#setMaxPoolSize(int)
2532
|cloud.aws.loader.queue-capacity | | The maximum queue capacity for backed up S3 requests. @see org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor#setQueueCapacity(int)
26-
|cloud.aws.mail.region || The specific region for SES integration.
27-
|cloud.aws.region.static | |
28-
|cloud.aws.sns.region || The specific region for SNS integration.
29-
|cloud.aws.sqs.region || The specific region for SQS integration.
33+
|cloud.aws.mail.enabled | true | Enables Mail integration.
34+
|cloud.aws.mail.endpoint | |
35+
|cloud.aws.mail.region | |
36+
|cloud.aws.rds.enabled | true | Enables RDS integration.
37+
|cloud.aws.rds.endpoint | |
38+
|cloud.aws.rds.instances | | List of RdsInstances.
39+
|cloud.aws.rds.region | |
40+
|cloud.aws.s3.endpoint | | Overrides the default endpoint.
41+
|cloud.aws.s3.region | | Overrides the default region.
42+
|cloud.aws.sns.enabled | true | Enables SNS integration.
43+
|cloud.aws.sns.endpoint | |
44+
|cloud.aws.sns.region | |
45+
|cloud.aws.sqs.enabled | true | Enables SQS integration.
46+
|cloud.aws.sqs.endpoint | |
47+
|cloud.aws.sqs.handler.default-deletion-policy | | Configures global deletion policy used if deletion policy is not explicitly set on {@link SqsListener}.
48+
|cloud.aws.sqs.listener.auto-startup | true | Configures if this container should be automatically started.
49+
|cloud.aws.sqs.listener.back-off-time | | The number of milliseconds the polling thread must wait before trying to recover when an error occurs (e.g. connection timeout).
50+
|cloud.aws.sqs.listener.max-number-of-messages | 10 | The maximum number of messages that should be retrieved during one poll to the Amazon SQS system. This number must be a positive, non-zero number that has a maximum number of 10. Values higher then 10 are currently not supported by the queueing system.
51+
|cloud.aws.sqs.listener.queue-stop-timeout | | The queue stop timeout that waits for a queue to stop before interrupting the running thread.
52+
|cloud.aws.sqs.listener.visibility-timeout | | The duration (in seconds) that the received messages are hidden from subsequent poll requests after being retrieved from the system.
53+
|cloud.aws.sqs.listener.wait-timeout | 20 | The wait timeout that the poll request will wait for new message to arrive if the are currently no messages on the queue. Higher values will reduce poll request to the system significantly. The value should be between 1 and 20. For more information read the <a href= "https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html">documentation</a>.
54+
|cloud.aws.sqs.region | |
3055
|cloud.aws.stack.auto | true | Enables the automatic stack name detection for the application.
56+
|cloud.aws.stack.enabled | true | Enables Stack integration.
3157
|cloud.aws.stack.name | | The name of the manually configured stack name that will be used to retrieve the resources.
3258

33-
|===
59+
|===

‎docs/src/main/asciidoc/cloudformation.adoc

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
== Managing cloud environments
2+
Managing environments manually with the management console does not scale and can become error-prone with the increasing
3+
complexity of the infrastructure. Amazon Web services offers a https://aws.amazon.com/cloudformation/[CloudFormation]
4+
service that allows to define stack configuration templates and bootstrap the whole infrastructure with the services.
5+
In order to allow multiple stacks in parallel, each resource in the stack receives a unique physical name that contains
6+
some arbitrary generated name. In order to interact with the stack resources in a unified way Spring Cloud AWS allows
7+
developers to work with logical names instead of the random physical ones.
8+
9+
The next graphics shows a typical stack configuration.
10+
11+
image::cloudformation-overview.png[CloudFormation overview]
12+
13+
The *Template File* describes all stack resources with their _logical name_. The *CloudFormation* service parses the stack
14+
template file and creates all resources with their _physical name_. The application can use all the stack configured resources
15+
with the _logical name_ defined in the template. Spring Cloud AWS resolves all _logical names_ into the respective
16+
_physical name_ for the application developer.
17+
18+
=== Automatic CloudFormation configuration
19+
If the application runs inside a stack (because the underlying EC2 instance has been bootstrapped within the stack), then
20+
Spring Cloud AWS will automatically detect the stack and resolve all resources from the stack. Application developers
21+
can use all the logical names from the stack template to interact with the services. In the example below, the database
22+
resource is configured using a CloudFormation template, defining a logical name for the database instance.
23+
24+
[source,xml,indent=0]
25+
----
26+
"applicationDatabase": {
27+
"Type": "AWS::RDS::DBInstance",
28+
"Properties": {
29+
"AllocatedStorage": "5",
30+
"DBInstanceClass": "db.t1.micro",
31+
"DBName": "test"
32+
...
33+
]
34+
}
35+
}
36+
----
37+
38+
The datasource is then created and will receive a physical name (e.g. ir142c39k6o5irj) as the database service name. Application
39+
developers can still use the logical name (in this case `applicationDatabase`) to interact with the database. The example
40+
below shows the stack configuration which is defined by the element `aws-context:stack-configuration` and resolves automatically
41+
the particular stack. The `data-source` element uses the logical name for the `db-instance-identifier` attribute to work with
42+
the database.
43+
44+
[source,xml,indent=0]
45+
----
46+
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
47+
xmlns:aws-context="http://www.springframework.org/schema/cloud/aws/context"
48+
xmlns="http://www.springframework.org/schema/beans"
49+
xsi:schemaLocation="http://www.springframework.org/schema/cloud/aws/context
50+
http://www.springframework.org/schema/cloud/aws/context/spring-cloud-aws-context.xsd">
51+
52+
<aws-context:context-credentials>
53+
...
54+
</aws-context:context-credentials>
55+
56+
<aws-context:context-region .. />
57+
58+
<aws-context:stack-configuration/>
59+
60+
<jdbc:data-source db-instance-identifier="applicationDatabase" ... />
61+
</beans>
62+
----
63+
64+
[TIP]
65+
====
66+
Further detailed information on the Amazon RDS configuration and setup can be found in the respective chapter in this
67+
documentation.
68+
====
69+
70+
71+
=== Manual CloudFormation configuration
72+
If the application is not running inside a stack configured EC2 instance, then the stack configuration must be configured
73+
manually. The configuration consists of an additional element attribute `stack-name` that will be used to resolve all the
74+
respective stack configuration information at runtime.
75+
76+
[source,xml,indent=0]
77+
----
78+
<beans ....>
79+
...
80+
<aws-context:stack-configuration stack-name="myStackName" />
81+
...
82+
</beans>
83+
----
84+
85+
=== CloudFormation configuration with Java config classes
86+
Spring Cloud AWS also supports the configuration of the CloudFormation support within Java classes avoiding the use of
87+
XML inside the application configuration. Spring Cloud AWS provides the annotation
88+
`og.springframework.cloud.aws.context.config.annotation.EnableStackConfiguration` that allows the automatic and manual
89+
stack configuration. The next example shows a configuration class that configures the CloudFormation support with an
90+
explicit stack name (here `manualStackName`).
91+
92+
[source,java,indent=0]
93+
----
94+
@Configuration
95+
@EnableStackConfiguration(stackName = "manualStackName")
96+
class ApplicationConfiguration {
97+
}
98+
----
99+
100+
[TIP]
101+
====
102+
Do not define the `stackName` attribute if an automatic stack name should be enabled.
103+
====
104+
105+
=== CloudFormation configuration in Spring Boot
106+
Spring Cloud AWS also supports the configuration of the CloudFormation support within the Spring Boot configuration. The
107+
manual and automatic stack configuration can be defined with properties that are described in the table below.
108+
109+
[cols="3*", options="header"]
110+
|===
111+
|property
112+
|example
113+
|description
114+
115+
|cloud.aws.stack.name
116+
|myStackName
117+
|The name of the manually configured stack name that will be used to retrieve the resources.
118+
119+
|cloud.aws.stack.auto
120+
|true
121+
|Enables the automatic stack name detection for the application.
122+
123+
|===
124+
125+
126+
=== Manual name resolution
127+
Spring Cloud AWS uses the CloudFormation stack to resolve all resources internally using the logical names. In some circumstances
128+
it might be needed to resolve the physical name inside the application code. Spring Cloud AWS provides a pre-configured
129+
service to resolve the physical stack name based on the logical name. The sample shows a manual stack resource resolution.
130+
131+
[source,java,indent=0]
132+
----
133+
@Service
134+
public class ApplicationService {
135+
136+
private final ResourceIdResolver resourceIdResolver;
137+
138+
@Autowired
139+
public ApplicationService(ResourceIdResolver resourceIdResolver) {
140+
this.resourceIdResolver = resourceIdResolver;
141+
}
142+
143+
public void handleApplicationLogic() {
144+
String physicalBucketName =
145+
this.resourceIdResolver.resolveToPhysicalResourceId("someLogicalName");
146+
}
147+
}
148+
----
149+
150+
=== Stack Tags
151+
Like for the Amazon EC2 instances, CloudFormation also provides stack specific tags that can be used to
152+
configure stack specific configuration information and receive them inside the application. This can for example be a
153+
stage specific configuration property (like DEV, INT, PRD).
154+
155+
[source,xml,indent=0]
156+
----
157+
<beans ....>
158+
...
159+
<aws-context:stack-configuration user-tags-map="stackTags"/>
160+
...
161+
</beans>
162+
----
163+
164+
The application can then access the stack tags with an expression like `#{stackTags.key1}`.
165+
166+
=== Using custom CloudFormation client
167+
Like for the EC2 configuration setup, the `aws-context:stack-configuration` element supports a custom CloudFormation client
168+
with a special setup. The client itself can be configured using the `amazon-cloud-formation` attribute as shown in the example:
169+
170+
[source,xml,indent=0]
171+
----
172+
<beans>
173+
<aws-context:stack-configuration amazon-cloud-formation=""/>
174+
175+
<bean class="com.amazonaws.services.cloudformation.AmazonCloudFormationClient">
176+
</bean>
177+
</beans>
178+
----

‎docs/src/main/asciidoc/cloudwatch.adoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
== CloudWatch Metrics
2+
Spring Cloud AWS provides Spring Boot auto-configuration for Micrometer CloudWatch integration.
3+
To send metrics to CloudWatch add a dependency to `micrometer-registry-cloudwatch` module:
4+
5+
[source,xml,indent=0]
6+
----
7+
<dependency>
8+
<groupId>io.micrometer</groupId>
9+
<artifactId>micrometer-registry-cloudwatch</artifactId>
10+
</dependency>
11+
----
12+
13+
Additionally CloudWatch integration requires a value provided for `management.metrics.export.cloudwatch.namespace` configuration property.
14+
15+
Following configuration properties are available to configure CloudWatch integration:
16+
17+
[cols="3*", options="header"]
18+
|===
19+
|property
20+
|default
21+
|description
22+
23+
|management.metrics.export.cloudwatch.namespace
24+
|
25+
|The namespace which will be used when sending metrics to CloudWatch. This property is needed and must not be null.
26+
27+
|management.metrics.export.cloudwatch.enabled
28+
|true
29+
|If CloudWatch integration should be enabled. This property should be likely set to `false` for a local development profile.
30+
31+
|management.metrics.export.cloudwatch.region
32+
|
33+
|The specific region for CloudWatch integration.
34+
35+
|management.metrics.export.cloudwatch.step
36+
|1m
37+
|The interval at which metrics are sent to CloudWatch. The default is 1 minute.
38+
|===

0 commit comments

Comments
 (0)