Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revamp AWS Quickstarts with DevServices #1356

Merged
merged 1 commit into from
Jan 12, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 126 additions & 73 deletions amazon-dynamodb-quickstart/README.md
Original file line number Diff line number Diff line change
@@ -1,127 +1,180 @@
# Quarkus demo: DynamoDB Client
# Quarkus demo: Amazon DynamoDB Client

This example showcases how to use the AWS DynamoDB client with Quarkus. As a prerequisite install Install [AWS Command line interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
This example showcases how to use the AWS DynamoDB client with Quarkus.

# DynamoDB local instance
## Run the Demo in Dev Mode

Just run it as follows:
`docker run --rm --name local-dynamo -p 8000:4569 -e SERVICES=dynamodb -e START_WEB=0 -d localstack/localstack`
- Run `./mvnw clean quarkus:dev`

DynamoDB listens on `localhost:8000` for REST endpoints.
Go to [`http://localhost:8080/fruits.html`](http://localhost:8080/fruits.html), it should show a simple App to manage a list of Fruits.
You can add fruits to the list via the form.

Alternatively, go to [`http://localhost:8080/async-fruits.html`](http://localhost:8080/async-fruits.html) with the simple App communicating with Async resources.

# Using LocalStack

As a prerequisite, install the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).

Start LocalStack:

```sh
docker run \
--rm \
--name local-dynamodb \
-p 4566:4566 \
locals

DynamoDB listens on `localhost:4566` for REST endpoints.

Create an AWS profile for your local instance using AWS CLI:

```sh
aws configure --profile localstack
```
$ aws configure --profile localstack

```plain
AWS Access Key ID [None]: test-key
AWS Secret Access Key [None]: test-secret
Default region name [None]: us-east-1
Default output format [None]:
```

## Create table
## Create a DynamoDB table

Create a DynamoDB table using AWS CLI and the localstack profile.
```
aws dynamodb create-table --table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 \
--profile localstack --endpoint-url=http://localhost:8000

```sh
aws dynamodb create-table \
--table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 \
--profile localstack --endpoint-url=http://localhost:4566`
```

# Run the demo on dev mode
## Run the demo

- Run `./mvnw clean package` and then `java -jar ./target/quarkus-app/quarkus-run.jar`
- In dev mode `./mvnw clean quarkus:dev`
You can compile the application and run it with:

Go to [`http://localhost:8080/fruits.html`](http://localhost:8080/fruits.html), it should show a simple App to manage a list of Fruits.
You can add fruits to the list via the form.
```sh
./mvnw install
AWS_PROFILE=localstack java -Dquarkus.dynamodb.endpoint-override=http://localhost:4566 -jar ./target/quarkus-app/quarkus-run.jar
```

Alternatively, go to [`http://localhost:8080/async-fruits.html`](http://localhost:8080/async-fruits.html) with the simple App communicating with Async resources.
Go to [`http://localhost:8080/fruits.html`](http://localhost:8080/fruits.html) or [`http://localhost:8080/async-fruits.html`](http://localhost:8080/async-fruits.html), to test the application.

# Running in native
## Running in native

You can compile the application into a native executable using:

`./mvnw clean install -Pnative`

and run with:
```sh
./mvnw install -Dnative
```

`./target/amazon-dynamodb-quickstart-1.0.0-SNAPSHOT-runner`
And run it with:

```sh
AWS_PROFILE=localstack ./target/amazon-dynamodb-quickstart-1.0.0-SNAPSHOT-runner -Dquarkus.dynamodb.endpoint-override=http://localhost:4566
```

# Running native in container

Build a native image in container by running:
Build a native image in a container by running:

`./mvnw package -Pnative -Dnative-image.docker-build=true`
```sh
./mvnw install -Dnative -DskipTests -Dquarkus.native.container-build=true
```

Build a docker image:
`docker build -f src/main/docker/Dockerfile.native -t quarkus/amazon-dynamodb-quickstart .`
Build a Docker image:

Create a network that connects your container with localstack
`docker network create localstack`
```sh
docker build -f src/main/docker/Dockerfile.native -t quarkus/amazon-dynamodb-quickstart .
```

Stop your localstack container you started at the beginning
`docker stop local-dynamo`
Create a network that connects your container with LocalStack:

Start localstack and connect to the network
`docker run --rm --network=localstack --name localstack -p 8000:4569 -e SERVICES=dynamodb -e START_WEB=0 -d localstack/localstack`
```sh
docker network create localstack
```

Create Dynamo table
Stop your LocalStack container you started at the beginning:

```sh
docker stop local-dynamodb
```
aws dynamodb create-table --table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 \
--profile localstack --endpoint-url=http://localhost:8000

Start LocalStack and connect to the network:

```sh
docker run \
--rm \
--name local-dynamodb \
--network=localstack \
-p 4566:4566 \
localstack/localstack
```

Run quickstart container connected to that network (note that we're using internal port of the localstack)
`docker run -i --rm --network=localstack -p 8080:8080 quarkus/amazon-dynamodb-quickstart -Dquarkus.dynamodb.endpoint-override=http://localstack:4569`
Create a DynamoDB table using AWS CLI and the localstack profile.

Go to [`http://localhost:8080/fruits.html`](http://localhost:8080/fruits.html) or [`http://localhost:8080/async-fruits.html`](http://localhost:8080/async-fruits.html)
```sh
aws dynamodb create-table \
--table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 \
--profile localstack --endpoint-url=http://localhost:4566`
```

# Using AWS account
Run the Quickstart container connected to that network (note that we're using the internal port of the LocalStack container):

```sh
docker run -i --rm --network=localstack \
-p 8080:8080 \
-e QUARKUS_DYNAMODB_ENDPOINT_OVERRIDE="http://local-dynamodb:4566" \
-e QUARKUS_DYNAMODB_AWS_REGION="us-east-1" \
-e QUARKUS_DYNAMODB_AWS_CREDENTIALS_TYPE="static" \
-e QUARKUS_DYNAMODB_AWS_CREDENTIALS_STATIC_PROVIDER_ACCESS_KEY_ID="test-key" \
-e QUARKUS_DYNAMODB_AWS_CREDENTIALS_STATIC_PROVIDER_SECRET_ACCESS_KEY="test-secret" \
quarkus/amazon-dynamodb-quickstart
```

Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key.
For more information, see [Setting Up DynamoDB (Web Service)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SettingUp.DynamoWebService.html).
Go to `http://localhost:8080/dynamodb.html` or `http://localhost:8080/async-dynamodb.html`, to test the application.

Create a DynamoDB table using AWS CLI and your default AWS profile:
Clean up your environment:

```
aws dynamodb create-table --table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
```sh
docker stop local-dynamodb
docker network rm localstack
```

## Run demo
# Using AWS account

You can run the demo the same way as for a local instance, but you need to change the `application.properties`.
Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key.
For more information, see:
- [Sign up for AWS and Create an IAM User](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/signup-create-iam-user.html)
- [Set Up AWS Credentials and Region for Development](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/setup-credentials.html)

- remove or comment out `quarkus.dynamodb.endpoint-override` - as you are going to communicate with the AWS service now
- remove or comment out `quarkus.dynamodb.aws.region` - region is going to be retrieved via the default providers chain in the following order:
- `aws.region` system property
- `region` property from the profile file
- remove or comment out `quarkus.dynamodb.aws.credentials.type` - if not configured the client uses `default` credentials provider chain that looks for credentials in this order:
- Java System Properties - `aws.accessKeyId` and `aws.secretKey`
- Environment Variables - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
- Credential profiles file at the default location (`~/.aws/credentials`) shared by all AWS SDKs and the AWS CLI

Build the application
Create a DynamoDB table using AWS CLI and the localstack profile.

`./mvnw clean package`

And then run it
```sh
aws dynamodb create-table \
--table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
```
## Run demo

`java -jar ./target/quarkus-app/quarkus-run.jar`
You can run the demo the same way as for a local instance, but you don't need to override the endpoint as you are going to communicate with the AWS service with the default AWS profile.

Or, build as native executable
Run it:

`./mvnw clean package -Pnative`
```sh
java -Dbucket.name=quarkus.dynamodb.12.345.99 -jar ./target/quarkus-app/quarkus-run.jar
```

And then run it
Or, run it natively:

`./target/amazon-dynamodb-quickstart-1.0.0-SNAPSHOT-runner`
```sh
./target/amazon-dynamodb-quickstart-1.0.0-SNAPSHOT-runner -Dbucket.name=quarkus.dynamodb.12.345.99
```
2 changes: 1 addition & 1 deletion amazon-dynamodb-quickstart/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<quarkus-amazon-services.version>2.5.3</quarkus-amazon-services.version>
<quarkus-amazon-services.version>2.7.2</quarkus-amazon-services.version>
<awssdk.testcontainers.version>1.12.57</awssdk.testcontainers.version>
</properties>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +0,0 @@
quarkus.dynamodb.endpoint-override=http://localhost:8000

quarkus.dynamodb.aws.region=eu-central-1
quarkus.dynamodb.aws.credentials.type=static
quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secret

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.junit.QuarkusTest;
import java.util.Arrays;
import java.util.List;
Expand All @@ -15,7 +14,6 @@
import org.junit.jupiter.params.provider.ValueSource;

@QuarkusTest
@QuarkusTestResource(DynamodbResource.class)
public class DynamodbResourcesTest {

private static final BiFunction<String, String, String> FRUIT = (name, description) -> String
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
quarkus.aws.devservices.localstack.init-scripts-classpath=localstack-init
quarkus.aws.devservices.localstack.init-completion-msg=#### Tests init completed
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#!/bin/bash
awslocal dynamodb create-table \
--table-name QuarkusFruits \
--attribute-definitions AttributeName=fruitName,AttributeType=S \
--key-schema AttributeName=fruitName,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
#!/bin/bash
echo "#### Tests init completed"
Loading
Loading