From a524edcca34ed52a60c879ddb4f6741854df240c Mon Sep 17 00:00:00 2001 From: Justin Lee Date: Tue, 22 Oct 2019 12:25:43 -0400 Subject: [PATCH 1/4] finish the documentation make the property names consistent --- .../asciidoc/amazon-lambda-http-guide.adoc | 106 +++++++++++++++++- .../lambda/http/AmazonLambdaHttpMojo.java | 6 +- .../lambda.http/GenerateAmazonConfigIT.java | 4 +- .../src/main/resources/application.properties | 2 +- .../src/main/resources/application.properties | 2 +- 5 files changed, 112 insertions(+), 8 deletions(-) diff --git a/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc b/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc index a315d445069f5..1aa8afa84317f 100644 --- a/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc +++ b/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc @@ -35,4 +35,108 @@ Quarkus project, you'll need to configure your application for deployment to Ama the scope of this document but you can find the full guide on https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html[Amazon's website]. -For the purposes of this guide, we'll be using RESTEasy and maven. \ No newline at end of file +For the purposes of this guide, we'll be using RESTEasy and maven. In order to deploy your REST application on AWS, +you'll need to add two dependencies: + +```xml + + io.quarkus + quarkus-amazon-lambda-http + + + io.quarkus + quarkus-resteasy + +``` + +NOTE: This example assumes the project is configured to use the BOM provided by the Quarkus project. + +Assuming you have properly configured your project to use Quarkus, this is almost all that is necessary. Now dev mode is available +as one would expect with a Quarkus application but, additionally, you can use +https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-start-api.html[SAM local] +if you are more comfortable with that approach. + +=== Existing Projects + +For existing projects, the following dependency will need to be added: + +[source,xml] +---- + + io.quarkus + quarkus-amazon-lambda-http + +---- + +It's likely there is already an HTTP dependency defined to serve your application. If not, however, the following +dependency can also be added: + +[source,xml] +---- + + io.quarkus + quarkus-resteasy + +---- + +Assuming the application is already configured with a YAML template for the SAM cli to use, you should be almost ready +to begin using Quarkus. One step remains, however. + +=== Updating the SAM template file + +In an existing AWS project, there will likely already be a yaml file for the SAM cli to use when developing locally and +deploying. However others will need an initial template to work with. To create that initial template, the following +plugin can be run from the root of the project: + +[source,shell script] +---- +mvn io.quarkus:quarkus-amazon-lambda-http-maven:configure-aws-lambda +---- + +If there is no existing template file one will be created with the default name of `template.yaml` and the resource name +will default to `Quarkus`. These names might not be preferable or there might be an existing template file to work with. +In this case, there are two properties that can configure these values: + +|=== +|Name |Description + +|amazon-lambda-http.template| The template file to use +|amazon-lambda-http.resource| The resource to manage +|=== + +NOTE: Running this plugin in an existing project will attempt to update the existing configuration. If the template +file has a different name, the plugin will assume there is no configuration and will generate a new file. + +This plugin will update the `Handler` and `Runtime` values for the named resource. Running this plugin once might be +sufficient. However, you might choose to always run this plugin to make sure your template file is always correct. +e.g., should implementation details on the Quarkus side ever change, it might be nice to have things automatically update +without having to worry about tracking changes. The pom can be configured to run automatically by adding the following +to the `plugins` section: + +[source,xml] +---- + + io.quarkus + quarkus-amazon-lambda-http-maven + ${quarkus.version} + + + amazon-lambda-http + + configure-aws-lambda + + compile + + + +---- + +This will bind the plugin to the `compile` phase and will ensure that the configuration is always up to date. If this +option is chosen some extra configuration will be required since always having to pass the properties above is not ideal. +It is possible to store these values in `src/main/properties/application.properties` alongside all of the other Quarkus +configuration values. In this case, you'll need to define the following entries: + +* quarkus.amazon-lambda-http.resource +* quarkus.amazon-lambda-http.template + +With these defined, the properties no longer need to be defined when invoking maven. \ No newline at end of file diff --git a/extensions/amazon-lambda-http/maven/src/main/java/io/quarkus/amazon/lambda/http/AmazonLambdaHttpMojo.java b/extensions/amazon-lambda-http/maven/src/main/java/io/quarkus/amazon/lambda/http/AmazonLambdaHttpMojo.java index 3b3a8c32b8619..c8099660772a4 100644 --- a/extensions/amazon-lambda-http/maven/src/main/java/io/quarkus/amazon/lambda/http/AmazonLambdaHttpMojo.java +++ b/extensions/amazon-lambda-http/maven/src/main/java/io/quarkus/amazon/lambda/http/AmazonLambdaHttpMojo.java @@ -21,17 +21,17 @@ public class AmazonLambdaHttpMojo extends AbstractMojo { public static final String SAM_HANDLER = HttpHandler.class.getName() + "::handleRequest"; public static final String SAM_RUNTIME = "java8"; public static final String SAM_TEMPLATE = "quarkus.amazon-lambda-http.template"; - public static final String SAM_RESOURCE = "quarkus.amazon-lambda-http.resource-name"; + public static final String SAM_RESOURCE = "quarkus.amazon-lambda-http.resource"; public static final String DEFAULT_TEMPLATE = "template.yaml"; public static final String DEFAULT_RESOURCE = "Quarkus"; @Parameter(defaultValue = "${project}") protected MavenProject project; - @Parameter(property = "sam.template", defaultValue = DEFAULT_TEMPLATE) + @Parameter(property = "amazon-lambda-http.template", defaultValue = DEFAULT_TEMPLATE) private String templateFile; - @Parameter(property = "sam.resource", defaultValue = DEFAULT_RESOURCE) + @Parameter(property = "amazon-lambda-http.resource", defaultValue = DEFAULT_RESOURCE) private String resourceName; @SuppressWarnings("unchecked") diff --git a/integration-tests/amazon-lambda-http/src/test/java/io/quarkus/amazon/lambda.http/GenerateAmazonConfigIT.java b/integration-tests/amazon-lambda-http/src/test/java/io/quarkus/amazon/lambda.http/GenerateAmazonConfigIT.java index ba1689f4b838a..3fcfb032b0a9d 100644 --- a/integration-tests/amazon-lambda-http/src/test/java/io/quarkus/amazon/lambda.http/GenerateAmazonConfigIT.java +++ b/integration-tests/amazon-lambda-http/src/test/java/io/quarkus/amazon/lambda.http/GenerateAmazonConfigIT.java @@ -79,10 +79,10 @@ private void invoke(String goal, String template, String resource) throws Except mavenProperties.put("projectArtifactId", "acme"); mavenProperties.put("projectVersion", "1.0-SNAPSHOT"); if (template != null) { - mavenProperties.put("sam.template", template); + mavenProperties.put("amazon-lambda-http.template", template); } if (resource != null) { - mavenProperties.put("sam.resource", resource); + mavenProperties.put("amazon-lambda-http.resource", resource); } final MavenProcessInvocationResult result = new RunningInvoker(testDir, false) diff --git a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-during-lifecycle/src/main/resources/application.properties b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-during-lifecycle/src/main/resources/application.properties index 7a3000dfbb75a..d06a03c76ba1b 100644 --- a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-during-lifecycle/src/main/resources/application.properties +++ b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-during-lifecycle/src/main/resources/application.properties @@ -1,2 +1,2 @@ -quarkus.amazon-lambda-http.resource-name=properties-resource +quarkus.amazon-lambda-http.resource=properties-resource quarkus.amazon-lambda-http.template=properties.yaml \ No newline at end of file diff --git a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-with-application-properties/src/main/resources/application.properties b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-with-application-properties/src/main/resources/application.properties index 7a3000dfbb75a..d06a03c76ba1b 100644 --- a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-with-application-properties/src/main/resources/application.properties +++ b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-with-application-properties/src/main/resources/application.properties @@ -1,2 +1,2 @@ -quarkus.amazon-lambda-http.resource-name=properties-resource +quarkus.amazon-lambda-http.resource=properties-resource quarkus.amazon-lambda-http.template=properties.yaml \ No newline at end of file From ccf314dc52c6d5a4a446185b44502521b438bb9c Mon Sep 17 00:00:00 2001 From: Justin Lee Date: Tue, 22 Oct 2019 14:25:57 -0400 Subject: [PATCH 2/4] removed old module/file remnant --- .../src/main/resources/META-INF/quarkus-extension.json | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 extensions/amazon-lambda-resteasy/runtime/src/main/resources/META-INF/quarkus-extension.json diff --git a/extensions/amazon-lambda-resteasy/runtime/src/main/resources/META-INF/quarkus-extension.json b/extensions/amazon-lambda-resteasy/runtime/src/main/resources/META-INF/quarkus-extension.json deleted file mode 100644 index 147909b38bed1..0000000000000 --- a/extensions/amazon-lambda-resteasy/runtime/src/main/resources/META-INF/quarkus-extension.json +++ /dev/null @@ -1,6 +0,0 @@ - -{ - "name": "Quarkus - Amazon Lambda RESTEasy", - "labels": [ - ] -} \ No newline at end of file From dc5cbdcf2eda0788676095405b2d1ec8f42992f2 Mon Sep 17 00:00:00 2001 From: Justin Lee Date: Tue, 22 Oct 2019 15:26:27 -0400 Subject: [PATCH 3/4] PR feedback changes more inconsistencies cleaned --- .../asciidoc/amazon-lambda-http-guide.adoc | 18 ++++++++++-------- .../src/main/resources/application.properties | 4 ++-- .../src/main/resources/application.properties | 5 ++--- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc b/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc index 1aa8afa84317f..9bc9aca49fd8d 100644 --- a/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc +++ b/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc @@ -20,7 +20,7 @@ To complete this guide, you need: * JDK 1.8 (Azure requires JDK 1.8) * Apache Maven 3.5.3+ * https://aws.amazon.com[An Amazon AWS account] -* https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-reference.html#serverless-sam-cli[Amazon SAM CLI] +* https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-reference.html#serverless-sam-CLI[Amazon SAM CLI] == Getting Started @@ -38,7 +38,8 @@ https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/s For the purposes of this guide, we'll be using RESTEasy and maven. In order to deploy your REST application on AWS, you'll need to add two dependencies: -```xml +[source,xml] +---- io.quarkus quarkus-amazon-lambda-http @@ -47,13 +48,13 @@ you'll need to add two dependencies: io.quarkus quarkus-resteasy -``` +---- NOTE: This example assumes the project is configured to use the BOM provided by the Quarkus project. Assuming you have properly configured your project to use Quarkus, this is almost all that is necessary. Now dev mode is available as one would expect with a Quarkus application but, additionally, you can use -https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-start-api.html[SAM local] +https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-CLI-command-reference-sam-local-start-api.html[SAM local] if you are more comfortable with that approach. === Existing Projects @@ -79,16 +80,17 @@ dependency can also be added: ---- -Assuming the application is already configured with a YAML template for the SAM cli to use, you should be almost ready -to begin using Quarkus. One step remains, however. +Assuming the application is already configured with a YAML template for the SAM CLI to use, you should be almost ready +to begin using Quarkus. One step remains, however. Your template file should look something like +https://github.com/awslabs/serverless-application-model/blob/master/examples/apps/hello-world/template.yaml[this]. === Updating the SAM template file -In an existing AWS project, there will likely already be a yaml file for the SAM cli to use when developing locally and +In an existing AWS project, there will likely already be a YAML file for the SAM CLI to use when developing locally and deploying. However others will need an initial template to work with. To create that initial template, the following plugin can be run from the root of the project: -[source,shell script] +[source,shell] ---- mvn io.quarkus:quarkus-amazon-lambda-http-maven:configure-aws-lambda ---- diff --git a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-named-template/src/main/resources/application.properties b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-named-template/src/main/resources/application.properties index 925a24a125f80..85e2fb170be9a 100644 --- a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-named-template/src/main/resources/application.properties +++ b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-named-template/src/main/resources/application.properties @@ -1,2 +1,2 @@ -quarkus.amazon-lambda.sam-template=sam.yaml -quarkus.amazon-lambda.resource-name=named-template \ No newline at end of file +quarkus.amazon-lambda-http.template=sam.yaml +quarkus.amazon-lambda-http.resource=named-template \ No newline at end of file diff --git a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-new-template/src/main/resources/application.properties b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-new-template/src/main/resources/application.properties index dac7479b5598e..3d1d14bd983b6 100644 --- a/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-new-template/src/main/resources/application.properties +++ b/integration-tests/amazon-lambda-http/src/test/resources/projects/configure-new-template/src/main/resources/application.properties @@ -1,3 +1,2 @@ -quarkus.amazon-lambda.sam-template=sam.yaml -quarkus.amazon-lambda.resource-name=new-template -quarkus.amazon-lambda.update-config=true \ No newline at end of file +quarkus.amazon-lambda-http.template=sam.yaml +quarkus.amazon-lambda-http.resource=new-template \ No newline at end of file From da71f84452bd1366061d86aca43634ed126c3e73 Mon Sep 17 00:00:00 2001 From: Justin Lee Date: Thu, 24 Oct 2019 11:52:07 -0400 Subject: [PATCH 4/4] PR feedback changes --- docs/src/main/asciidoc/amazon-lambda-http-guide.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc b/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc index 9bc9aca49fd8d..beb754d3b03b1 100644 --- a/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc +++ b/docs/src/main/asciidoc/amazon-lambda-http-guide.adoc @@ -110,10 +110,10 @@ NOTE: Running this plugin in an existing project will attempt to update the exis file has a different name, the plugin will assume there is no configuration and will generate a new file. This plugin will update the `Handler` and `Runtime` values for the named resource. Running this plugin once might be -sufficient. However, you might choose to always run this plugin to make sure your template file is always correct. -e.g., should implementation details on the Quarkus side ever change, it might be nice to have things automatically update -without having to worry about tracking changes. The pom can be configured to run automatically by adding the following -to the `plugins` section: +sufficient. However, you might choose to always run this plugin to make sure your template file is correct. +e.g., Should implementation details on the Quarkus side ever change, automatically updating the SAM template would +help eliminate any breakage due to Quarkus changes. The pom can be configured to run automatically by adding the +following to the `plugins` section: [source,xml] ---- @@ -141,4 +141,4 @@ configuration values. In this case, you'll need to define the following entries * quarkus.amazon-lambda-http.resource * quarkus.amazon-lambda-http.template -With these defined, the properties no longer need to be defined when invoking maven. \ No newline at end of file +With these defined, the properties no longer need to be passed to maven when building the project. \ No newline at end of file