diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 5eb44e3..5abcf2b 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -16,7 +16,7 @@ export default defineConfig({ // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, - // { text: 'Guides', link: '/what-is-spring-cloud-aws' }, + { text: 'Guides', link: '/what-is-spring-cloud-aws' }, { text: 'Reference Docs', link: 'https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/reference/html/index.html' } ], @@ -33,10 +33,10 @@ export default defineConfig({ items: [ { text: 'Messaging with SQS', link: '/markdown-examples' }, { text: 'Publishing notifications with SNS', link: '/api-examples' }, - { text: 'File storage with S3', link: '/api-examples' }, - { text: 'Persistence with DynamoDb', link: '/api-examples' }, + { text: 'Uploading files to S3', link: '/guides/upload-files-s3' }, + { text: 'Persistence with DynamoDB', link: '/api-examples' }, { text: 'Configuration with Secrets Manager', link: '/guides/secrets-manager' }, - { text: 'Configuration with Parameter Store', link: '/api-examples' }, + { text: 'Configuration with Parameter Store', link: '/guides/parameter-store' }, ] } ], diff --git a/.vitepress/theme/style.css b/.vitepress/theme/style.css index 17accd4..6b6b525 100644 --- a/.vitepress/theme/style.css +++ b/.vitepress/theme/style.css @@ -137,3 +137,23 @@ --docsearch-primary-color: var(--vp-c-brand-1) !important; } +/** + * Youtube Embed + */ + +/* full-width embeds like one from youtube */ +.embed-container { + position: relative; + padding-bottom: 56.25%; + height: 0; + overflow: hidden; + max-width: 100%; +} + +.embed-container iframe, .embed-container object, .embed-container embed { + position: absolute; + top: 0; + left: 0; + width: 100%; + height: 100%; +} diff --git a/contributing.md b/contributing.md index 0e0e81d..36049bc 100644 --- a/contributing.md +++ b/contributing.md @@ -1,6 +1,55 @@ -## How to contribute to Spring Cloud AWS +# How to contribute to Spring Cloud AWS -#### **Did you find a bug?** +## Checking out and building + +To check out the project and build it from source, do the following: + +``` +git clone https://github.com/awspring/spring-cloud-aws.git +cd spring-cloud-aws +./mvnw package +``` + +To build and install jars into your local Maven cache: + +``` +./mvnw install +``` + +For faster builds, we recommend using [Maven Daemon](https://github.com/apache/maven-mvnd) and using following commands: + +Build: + +``` +make build +``` + +Clean: + +``` +make clean +``` + +Format code: + +``` +make format +``` + +## Building documentation + +Documentation can be built by activating the `docs` profile in the maven build. + +``` +make docs +``` + +It generates: + +- reference documentation in `docs/target/generated-docs/` +- API docs in `target/site/` + +## **Did you find a bug?** * **Do not open up a GitHub issue if the bug is a security vulnerability in Spring Cloud AWS**, and instead to refer to our [security policy](https://github.com/awspring/spring-cloud-aws/blob/main/SECURITY.md). @@ -9,13 +58,13 @@ * If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/awspring/spring-cloud-aws/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, ideally with a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring. -#### **Did you write a patch that fixes a bug?** +### **Did you write a patch that fixes a bug?** * Open a new GitHub pull request with the patch. * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. -#### **Do you intend to add a new feature or change an existing one?** +### **Do you intend to add a new feature or change an existing one?** * Suggest your change in the [Issues](https://github.com/awspring/spring-cloud-aws/issues). @@ -30,16 +79,14 @@ * each package has to have `package-info.java` file definining nullability rules ([example](https://github.com/awspring/spring-cloud-aws/blob/main/spring-cloud-aws-core/src/main/java/io/awspring/cloud/core/package-info.java)) * each nullable field, method parameter, method return value, if can be null, has to be annotated with `org.springframework.lang.Nullable`. -#### **Do you have questions about the source code?** +### **Do you have questions about the source code?** * Ask any question about how to use Spring Cloud AWS in the [Discussions](https://github.com/awspring/spring-cloud-aws/discussions). -#### **Using Gitpod** +### **Using Gitpod** To avoid setting up your local development environment, you can use [Gitpod](https://www.gitpod.io/) and develop directly in browser based Visual Studio Code, or [JetBrains Client via JetBrains Gateway](https://www.gitpod.io/docs/ides-and-editors/jetbrains-gateway). -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/from-referrer/) - -**Note**: The above button does not work on Privacy oriented browsers, please [click here](https://gitpod.io/#https://github.com/awspring/spring-cloud-aws/) to open the project on gitpod. +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/awspring/spring-cloud-aws/) Thanks! diff --git a/guides/parameter-store.md b/guides/parameter-store.md new file mode 100644 index 0000000..731b504 --- /dev/null +++ b/guides/parameter-store.md @@ -0,0 +1,116 @@ +# Configuration with AWS Parameter Store + +Spring Cloud AWS Parameter Store implementation, provides the ability to populate Spring's `Environment` with properties defined in [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html). + +## Create properties in Parameter Store + +Parameters can be created through AWS Console, infrastructure as code solution like Terraform or AWS CDK, or with command line. This guide uses command line interface to AWS, so before you start make sure you have [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) installed. + +Parameter Store uses [hierarchies](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-hierarchies.html) to organize configuration parameters. Spring Cloud AWS does not enforce any specific way parameters should be organized - it loads all parameters that name starts with a prefix configured in Spring configuration. + +In this guide, we will assume that all parameters starting with prefix `/config/spring/` belong to our application - later in this guide you'll find where exactly it is configured. + +Create parameters in Parameter Store with AWS CLI: + +```bash +$ aws ssm put-parameter \ + --name "/config/spring/host" \ + --type "String" \ + --value "http://some-host.net" +``` + +```bash +$ aws ssm put-parameter \ + --name "/config/spring/port" \ + --type "String" \ + --value "8888" +``` + +## Create new Spring Boot application + +1. Go to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you. +2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java. +3. Click Generate. + +Download the resulting ZIP file, extract it, and open in IDE of your choice. + +## Add dependencies + +First configure dependency management, to make sure that all Spring Cloud AWS and AWS SDK dependencies are compatible and you don't need to manage versions manually: + +In Maven: + +```xml + + + + io.awspring.cloud + spring-cloud-aws-dependencies + 3.0.3 + pom + import + + + +``` + +In Gradle: + +```groovy +dependencies { + implementation platform("io.awspring.cloud:spring-cloud-aws-dependencies:3.0.3") +} +``` + +Next, add the dependency to Parameter Store starter: + +In Maven: + +```xml + + io.awspring.cloud + spring-cloud-aws-starter-parameter-store + +``` + +In Gradle: + +```groovy +implementation 'io.awspring.cloud:spring-cloud-aws-starter-parameter-store' +``` + +## Configure Spring Boot + +In `application.properties` or `application.yml`, add `spring.config.import` entry pointing to properties in Parameter Store: + +```properties +spring.config.import=aws-parameterstore:/config/spring/ +``` + +Once this entry is added, all properties where name starts with `/config/spring/` are added to Spring `Environment` + +## Use parameters in Spring Boot configuration + +Parameters now can be used in `application.properties` or `application.yml`: + +```properties +client.host=${host} +client.port=${port} +``` + +## Use parameters in Java code + +Properties values can be also referenced with `@Value` annotation or through `Environment#getProperty` method: + +```java +@Service +class MyService { + + @Value("${host}") + private String host; +} +``` + +## Read more + +This was just a glympse of what Spring Cloud AWS can do. For more details about Parameter Store integration go to the [reference documentation](https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/reference/html/index.html#spring-cloud-aws-parameter-store). diff --git a/guides/secrets-manager.md b/guides/secrets-manager.md index 0785601..360ac07 100644 --- a/guides/secrets-manager.md +++ b/guides/secrets-manager.md @@ -1,2 +1,111 @@ -# Application configuration with AWS Secrets Manager +# Configuration with AWS Secrets Manager +Spring Cloud AWS Secrets Manager implementation, provides the ability to populate Spring's `Environment` with properties - secrets - defined in [Secrets Manager](https://aws.amazon.com/secrets-manager/). + +Integration supports both plain text secrets and JSON secrets. In this guide we use JSON variant. To learn how to use plain text secrets, go to the [reference documentation](https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/reference/html/index.html#using-plain-text-secrets). + +## Create a secret in Secrets Manager + +Secrets can be created through AWS Console, infrastructure as code solution like Terraform or AWS CDK, or with command line. This guide uses command line interface to AWS, so before you start make sure you have [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) installed. + +Create a file with secrets `mycreds.json`: + +```json +{ + "username": "some-user", + "password": "secret-password" +} +``` + +Create secret in Secrets Manager with AWS CLI: + +```bash +$ aws secretsmanager create-secret --name /secrets/database-secrets --secret-string file://mycreds.json +``` + +## Create new Spring Boot application + +1. Go to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you. +2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java. +3. Click Generate. + +Download the resulting ZIP file, extract it, and open in IDE of your choice. + +## Add dependencies + +First configure dependency management, to make sure that all Spring Cloud AWS and AWS SDK dependencies are compatible and you don't need to manage versions manually: + +In Maven: + +```xml + + + + io.awspring.cloud + spring-cloud-aws-dependencies + 3.0.3 + pom + import + + + +``` + +In Gradle: + +```groovy +dependencies { + implementation platform("io.awspring.cloud:spring-cloud-aws-dependencies:3.0.3") +} +``` + +Next, add the dependency to Secrets Manager starter: + +In Maven: + +```xml + + io.awspring.cloud + spring-cloud-aws-starter-secrets-manager + +``` + +In Gradle: + +```groovy +implementation 'io.awspring.cloud:spring-cloud-aws-starter-secrets-manager' +``` + +## Configure Spring Boot + +In `application.properties` or `application.yml`, add `spring.config.import` entry pointing to a secret in Secrets Manager: + +```properties +spring.config.import=aws-secretsmanager:/secrets/database-secrets +``` + +## Use secret in Spring Boot configuration + +All properties from a JSON secret gets added to Spring `Environment`, which means you can refer them in `application.properties` or `application.yml` code: + +```properties +spring.datasource.username=${username} +spring.datasource.password=${password} +``` + +## Use secret in Java code + +Secret values can be also referenced with `@Value` annotation or through `Environment#getProperty` method: + +```java +@Service +class MyService { + + @Value("${password}") + private String password; +} +``` + +## Read more + +This was just a glympse of what Spring Cloud AWS can do. For more details about Secrets Manager integration go to the [reference documentation](https://docs.awspring.io/spring-cloud-aws/docs/3.0.2/reference/html/index.html#spring-cloud-aws-secrets-manager). diff --git a/what-is-spring-cloud-aws.md b/what-is-spring-cloud-aws.md index 7e7e05d..3740282 100644 --- a/what-is-spring-cloud-aws.md +++ b/what-is-spring-cloud-aws.md @@ -1,14 +1,15 @@ -# 🍃 Spring Cloud AWS +# Spring Cloud AWS -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/from-referrer/) +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/awspring/spring-cloud-aws/) -Simplifies using AWS managed services in a Spring and Spring Boot applications. +Spring Cloud AWS simplifies using AWS managed services in a Spring and Spring Boot applications. For a deep dive into the project, refer to the Spring Cloud AWS documentation: | Version | Reference Docs | API Docs | |------------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| -| Spring Cloud AWS 3.0.3 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/apidocs/index.html) | +| Spring Cloud AWS 3.1.0 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.1.0/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.1.0/apidocs/index.html) | +| Spring Cloud AWS 3.0.4 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.0.4/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.0.4/apidocs/index.html) | | Spring Cloud AWS 2.4.4 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.4.4/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.4.4/apidocs/index.html) | | Spring Cloud AWS 2.3.5 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.3.5/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.3.5/apidocs/index.html) | @@ -22,11 +23,12 @@ Big thanks to [LocalStack](https://localstack.cloud) for providing PRO licenses This project has dependency and transitive dependencies on Spring Projects. The table below outlines the versions of Spring Cloud, Spring Boot and Spring Framework versions that are compatible with certain Spring Cloud AWS version. -| Spring Cloud AWS | Spring Cloud | Spring Boot | Spring Framework | AWS Java SDK | -|------------------------------|-----------------------------------------------------------------------------------------------------------------------|--------------|------------------|--------------| -| 2.3.x (maintenance mode) | [2020.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2020.0-Release-Notes) (3.0/Illford) | 2.4.x, 2.5.x | 5.3.x | 1.x | -| 2.4.x (maintenance mode) | [2021.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2021.0-Release-Notes) (3.1/Jubilee) | 2.6.x, 2.7.x | 5.3.x | 1.x | -| 3.0.x | [2022.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2022.0-Release-Notes) (4.0/Kilburn) | 3.0.x, 3.1.x | 6.0.x | 2.x | +| Spring Cloud AWS | Spring Cloud | Spring Boot | Spring Framework | AWS Java SDK | +|-----------------------------|-----------------------------------------------------------------------------------------------------------------------|--------------|------------------|--------------| +| 2.3.x (maintenance mode) | [2020.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2020.0-Release-Notes) (3.0/Illford) | 2.4.x, 2.5.x | 5.3.x | 1.x | +| 2.4.x (maintenance mode) | [2021.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2021.0-Release-Notes) (3.1/Jubilee) | 2.6.x, 2.7.x | 5.3.x | 1.x | +| 3.0.x | [2022.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2022.0-Release-Notes) (4.0/Kilburn) | 3.0.x, 3.1.x | 6.0.x | 2.x | +| 3.1.x | [2023.0.x](https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-2023.0-Release-Notes) (4.0/Kilburn) | 3.2.x | 6.1.x | 2.x | **Note**: 3.0.0-M2 is the last version compatible with Spring Boot 2.7.x and Spring Cloud 3.1. Starting from 3.0.0-M3, project has switched to Spring Boot 3.0. @@ -54,56 +56,6 @@ Note, that Spring provides support for other AWS services in following projects: - [Spring Cloud Config Server](https://github.com/spring-cloud/spring-cloud-config) supports AWS Parameter Store and Secrets Manager - [Spring Integration for AWS](https://github.com/spring-projects/spring-integration-aws) - -## Checking out and building - -To check out the project and build it from source, do the following: - -``` -git clone https://github.com/awspring/spring-cloud-aws.git -cd spring-cloud-aws -./mvnw package -``` - -To build and install jars into your local Maven cache: - -``` -./mvnw install -``` - -For faster builds, we recommend using [Maven Daemon](https://github.com/apache/maven-mvnd) and using following commands: - -Build: - -``` -make build -``` - -Clean: - -``` -make clean -``` - -Format code: - -``` -make format -``` - -## Building documentation - -Documentation can be built by activating the `docs` profile in the maven build. - -``` -make docs -``` - -It generates: - -- reference documentation in `docs/target/generated-docs/` -- API docs in `target/site/` - ## Getting in touch - [Discussions on Github](https://github.com/awspring/spring-cloud-aws/discussions) - the best way to discuss anything Spring Cloud AWS related