SpringCloud/spring-cloud-function
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Organize main ref guide to contain adapter content

Browse Source
This commit is contained in:
Dave Syer
2018-06-04 10:29:38 +01:00
parent 047aabcbdd
commit f1e331bf98
13 changed files with 214 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/src/main/asciidoc/adapters/aws-intro.adoc Normal file
View File

@@ -0,0 +1,29 @@
The adapter has a couple of generic request handlers that you can use. The most generic is `SpringBootStreamHandler`, which uses a Jackson `ObjectMapper` provided by Spring Boot to serialize and deserialize the objects in the function. There is also a `SpringBootRequestHandler` which you can extend, and provide the input and output types as type parameters (enabling AWS to inspect the class and do the JSON conversions itself).
If your app has more than one `@Bean` of type `Function` etc. then you can choose the one to use by configuring `function.name` (e.g. as `FUNCTION_NAME` environment variable in AWS). The functions are extracted from the Spring Cloud `FunctionCatalog` (searching first for `Function` then `Consumer` and finally `Supplier`).
== Notes on JAR Layout
You don't need the Spring Cloud Function Web or Stream adapter at runtime in Lambda, so you might need to exclude those before you create the JAR you send to AWS. A Lambda application has to be shaded, but a Spring Boot standalone application does not, so you can run the same app using 2 separate jars (as per the sample). The sample app creates 2 jar files, one with an `aws` classifier for deploying in Lambda, and one executable (thin) jar that includes `spring-cloud-function-web` at runtime. Spring Cloud Function will try and locate a "main class" for you from the JAR file manifest, using the `Start-Class` attribute (which will be added for you by the Spring Boot tooling if you use the starter parent). If there is no `Start-Class` in your manifest you can use an environment variable `MAIN_CLASS` when you deploy the function to AWS.
== Upload
Build the sample under `spring-cloud-function-samples/function-sample-aws` and upload the `-aws` jar file to Lambda. The handler can be `example.Handler` or `org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler` (FQN of the class, _not_ a method reference, although Lambda does accept method references).
----
./mvnw -U clean package
----
Using the AWS command line tools it looks like this:
----
aws lambda create-function --function-name Uppercase --role arn:aws:iam::[USERID]:role/service-role/[ROLE] --zip-file fileb://function-sample-aws/target/function-sample-aws-1.0.0.BUILD-SNAPSHOT-aws.jar --handler org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler --description "Spring Cloud Function Adapter Example" --runtime java8 --region us-east-1 --timeout 30 --memory-size 1024 --publish
----
The input type for the function in the AWS sample is a Foo with a single property called "value". So you would need this to test it:
----
{
"value": "test"
}
----

32
docs/src/main/asciidoc/adapters/aws-readme.adoc
View File

@@ -1,33 +1,3 @@
This project provides an adapter layer for a Spring Cloud Function application onto AWS Lambda. You can write an app with a single `@Bean` of type `Function`, `Consumer` or `Supplier` and it will be deployable in AWS if you get the JAR file laid out right. The best way to make it work is to include `spring-cloud-function-context` as a dependency, but not the higher level adapters (e.g. `spring-cloud-function-stream`).
The adapter has a couple of generic request handlers that you can use. The most generic is `SpringBootStreamHandler`, which uses a Jackson `ObjectMapper` provided by Spring Boot to serialize and deserialize the objects in the function. There is also a `SpringBootRequestHandler` which you can extend, and provide the input and output types as type parameters (enabling AWS to inspect the class and do the JSON conversions itself).
If your app has more than one `@Bean` of type `Function` etc. then you can choose the one to use by configuring `function.name` (e.g. as `FUNCTION_NAME` environment variable in AWS). The functions are extracted from the Spring Cloud `FunctionCatalog` (searching first for `Function` then `Consumer` and finally `Supplier`).
=== Notes on JAR Layout
You don't need the Spring Cloud Function Web or Stream adapter at runtime in Lambda, so you might need to exclude those before you create the JAR you send to AWS. A Lambda application has to be shaded, but a Spring Boot standalone application does not, so you can run the same app using 2 separate jars (as per the sample here). The sample app creates 2 jar files, one with an `aws` classifier for deploying in Lambda, and one executable (thin) jar that includes `spring-cloud-function-web` at runtime. Spring Cloud Function will try and locate a "main class" for you from the JAR file manifest, using the `Start-Class` attribute (which will be added for you by the Spring Boot tooling if you use the starter parent). If there is no `Start-Class` in your manifest you can use an environment variable `MAIN_CLASS` when you deploy the function to AWS.
== Build
----
./mvnw -U clean package
----
== Upload
Build the sample under `spring-cloud-function-samples/function-sample-aws` and upload the `-aws` jar file to Lambda. The handler can be `example.Handler` or `org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler` (FQN of the class, _not_ a method reference, although Lambda does accept method references).
Using the AWS command line tools it looks like this:
----
aws lambda create-function --function-name Uppercase --role arn:aws:iam::[USERID]:role/service-role/[ROLE] --zip-file fileb://function-sample-aws/target/function-sample-aws-1.0.0.BUILD-SNAPSHOT-aws.jar --handler org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler --description "Spring Cloud Function Adapter Example" --runtime java8 --region us-east-1 --timeout 30 --memory-size 1024 --publish
----
The input type for the function in the AWS sample is a Foo with a single property called "value". So you would need this to test it:
----
{
"value": "test"
}
----
include::aws-intro.adoc[]

5
docs/src/main/asciidoc/adapters/aws.adoc Normal file
View File

@@ -0,0 +1,5 @@
The https://aws.amazon.com/[AWS] adapter takes a Spring Cloud Function app and converts it to a form that can run in AWS Lambda.
== Introduction
include::aws-intro.adoc[]

68
docs/src/main/asciidoc/adapters/azure-intro.adoc Normal file
View File

@@ -0,0 +1,68 @@
The adapter has a generic http request handler that you can use.
There is a `AzureSpringBootRequestHandler` which you must extend, and provide the input and output types as type parameters (enabling Azure to inspect the class and do the JSON conversions itself).
If your app has more than one `@Bean` of type `Function` etc. then you can choose the one to use by configuring `function.name`.
The functions are extracted from the Spring Cloud `FunctionCatalog`.
=== Notes on JAR Layout
You don't need the Spring Cloud Function Web at runtime in Azure, so you need to exclude this before you create the JAR you deploy to Azure.
A function application on Azure has to be shaded, but a Spring Boot standalone application does not, so you can run the same app using 2 separate jars (as per the sample here).
The sample app creates the shaded jar file, with an `azure` classifier for deploying in Azure.
=== JSON Configuration
The Azure tooling needs to find some JSON configuration files to tell it how to deploy and integrate the function (e.g. which Java class to use as the entry point, and which triggers to use). Those files can be created with the Maven plugin for a non-Spring function, but the tooling doesn't work yet with the adapter in its current form. There is an example `function.json` in the sample which hooks the function up as an HTTP endpoint:
```
{
"scriptFile" : "../function-sample-azure-1.0.0.BUILD-SNAPSHOT-azure.jar",
"entryPoint" : "example.FooHandler.execute",
"bindings" : [ {
"type" : "httpTrigger",
"name" : "foo",
"direction" : "in",
"authLevel" : "anonymous",
"methods" : [ "get", "post" ]
}, {
"type" : "http",
"name" : "$return",
"direction" : "out"
} ],
"disabled" : false
}
```
== Build
----
./mvnw -U clean package
----
== Running the sample
You can run the sample locally, just like the other Spring Cloud Function samples:
---
./mvnw spring-boot:run
---
and `curl -H "Content-Type: text/plain" localhost:8080/function -d '{"value": "hello foobar"}'`.
You will need the `az` CLI app and some node.js fu (see https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven for more detail). To deploy the function on Azure runtime:
----
$ az login
$ mvn azure-functions:deploy
----
On another terminal try this: `curl https://<azure-function-url-from-the-log>/api/uppercase -d '{"value": "hello foobar!"}'`. Please ensure that you use the right URL for the function above. Alternatively you can test the function in the Azure Dashboard UI (click on the function name, go to the right hand side and click "Test" and to the bottom right, "Run").
The input type for the function in the Azure sample is a Foo with a single property called "value". So you need this to test it with something like below:
----
{
"value": "foobar"
}
----

70
docs/src/main/asciidoc/adapters/azure-readme.adoc
View File

@@ -1,72 +1,4 @@
This work is experimental.
This project provides an adapter layer for a Spring Cloud Function application onto Azure.
You can write an app with a single `@Bean` of type `Function` and it will be deployable in Azure if you get the JAR file laid out right.
The adapter has a generic http request handler that you can use.
There is a `AzureSpringBootRequestHandler` which you must extend, and provide the input and output types as type parameters (enabling Azure to inspect the class and do the JSON conversions itself).
If your app has more than one `@Bean` of type `Function` etc. then you can choose the one to use by configuring `function.name`.
The functions are extracted from the Spring Cloud `FunctionCatalog`.
=== Notes on JAR Layout
You don't need the Spring Cloud Function Web at runtime in Azure, so you need to exclude this before you create the JAR you deploy to Azure.
A function application on Azure has to be shaded, but a Spring Boot standalone application does not, so you can run the same app using 2 separate jars (as per the sample here).
The sample app creates the shaded jar file, with an `azure` classifier for deploying in Azure.
=== JSON Configuration
The Azure tooling needs to find some JSON configuration files to tell it how to deploy and integrate the function (e.g. which Java class to use as the entry point, and which triggers to use). Those files can be created with the Maven plugin for a non-Spring function, but the tooling doesn't work yet with the adapter in its current form. There is an example `function.json` in the sample which hooks the function up as an HTTP endpoint:
```
{
"scriptFile" : "../function-sample-azure-1.0.0.BUILD-SNAPSHOT-azure.jar",
"entryPoint" : "example.FooHandler.execute",
"bindings" : [ {
"type" : "httpTrigger",
"name" : "foo",
"direction" : "in",
"authLevel" : "anonymous",
"methods" : [ "get", "post" ]
}, {
"type" : "http",
"name" : "$return",
"direction" : "out"
} ],
"disabled" : false
}
```
== Build
----
./mvnw -U clean package
----
== Running the sample
You can run the sample locally, just like the other Spring Cloud Function samples:
---
./mvnw spring-boot:run
---
and `curl -H "Content-Type: text/plain" localhost:8080/function -d '{"value": "hello foobar"}'`.
You will need the `az` CLI app and some node.js fu (see https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven for more detail). To deploy the function on Azure runtime:
----
$ az login
$ mvn azure-functions:deploy
----
On another terminal try this: `curl https://<azure-function-url-from-the-log>/api/uppercase -d '{"value": "hello foobar!"}'`. Please ensure that you use the right URL for the function above. Alternatively you can test the function in the Azure Dashboard UI (click on the function name, go to the right hand side and click "Test" and to the bottom right, "Run").
The input type for the function in the Azure sample is a Foo with a single property called "value". So you need this to test it with something like below:
----
{
"value": "foobar"
}
----
include::azure-intro.adoc[]

3
docs/src/main/asciidoc/adapters/azure.adoc Normal file
View File

@@ -0,0 +1,3 @@
The https://azure.microsoft.com[Azure] adapter bootstraps a Spring Cloud Function context and channels function calls from the Azure framework into the user functions, using Spring Boot configuration where necessary. Azure Functions has quite a unique, but invasive programming model, involving annotations in user code that are specific to the platform. The Spring Cloud Function Azure adapter trades the convenience of these annotations for portability of the function implementations. Instead of using the annotations you have to write some JSON by hand (at least for now) to guide the platform to call the right methods in the adapter.
include::azure-intro.adoc[]

80
docs/src/main/asciidoc/adapters/openwhisk-quick-start.adoc Normal file
View File

@@ -0,0 +1,80 @@
Implement a POF (be sure to use the `functions` package):
```
package functions;
import java.util.function.Function;
public class Uppercase implements Function<String, String> {
public String apply(String input) {
return input.toUpperCase();
}
}
```
Install it into your local Maven repository:
```
./mvnw clean install
```
Create a `function.properties` file that provides its Maven coordinates. For example:
```
dependencies.function: com.example:pof:0.0.1-SNAPSHOT
```
Copy the openwhisk runner JAR to the working directory (same directory as the properties file):
```
cp spring-cloud-function-adapters/spring-cloud-function-adapter-openwhisk/target/spring-cloud-function-adapter-openwhisk-1.0.0.BUILD-SNAPSHOT.jar runner.jar
```
Generate a m2 repo from the `--thin.dryrun` of the runner JAR with the above properties file:
```
java -jar -Dthin.root=m2 runner.jar --thin.name=function --thin.dryrun
```
Use the following Dockerfile:
```
FROM openjdk:8-jdk-alpine
VOLUME /tmp
COPY m2 /m2
ADD runner.jar .
ADD function.properties .
ENV JAVA_OPTS=""
ENTRYPOINT [ "java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "runner.jar", "--thin.root=/m2", "--thin.name=function", "--function.name=uppercase"]
EXPOSE 8080
```
> NOTE: you could use a Spring Cloud Function app, instead of just a jar with a POF in it, in which case you would have to change the way the app runs in the container so that it picks up the main class as a source file. For example, you could change the `ENTRYPOINT` above and add `--spring.main.sources=com.example.SampleApplication`.
Build the Docker image:
```
docker build -t [username/appname] .
```
Push the Docker image:
```
docker push [username/appname]
```
Use the OpenWhisk CLI (e.g. after `vagrant ssh`) to create the action:
```
wsk action create example --docker [username/appname]
```
Invoke the action:
```
wsk action invoke example --result --param payload foo
{
"result": "FOO"
}
```

80
docs/src/main/asciidoc/adapters/openwhisk-readme.adoc
View File

@@ -1,83 +1,7 @@
Implement a POF (be sure to use the `functions` package):
== Quick Start
```
package functions;
include::openwhisk-quick-start.adoc[]
import java.util.function.Function;
public class Uppercase implements Function<String, String> {
public String apply(String input) {
return input.toUpperCase();
}
}
```
Install it into your local Maven repository:
```
./mvnw clean install
```
Create a `function.properties` file that provides its Maven coordinates. For example:
```
dependencies.function: com.example:pof:0.0.1-SNAPSHOT
```
Copy the openwhisk runner JAR to the working directory (same directory as the properties file):
```
cp spring-cloud-function-adapters/spring-cloud-function-adapter-openwhisk/target/spring-cloud-function-adapter-openwhisk-1.0.0.BUILD-SNAPSHOT.jar runner.jar
```
Generate a m2 repo from the `--thin.dryrun` of the runner JAR with the above properties file:
```
java -jar -Dthin.root=m2 runner.jar --thin.name=function --thin.dryrun
```
Use the following Dockerfile:
```
FROM openjdk:8-jdk-alpine
VOLUME /tmp
COPY m2 /m2
ADD runner.jar .
ADD function.properties .
ENV JAVA_OPTS=""
ENTRYPOINT [ "java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "runner.jar", "--thin.root=/m2", "--thin.name=function", "--function.name=uppercase"]
EXPOSE 8080
```
> NOTE: you could use a Spring Cloud Function app, instead of just a jar with a POF in it, in which case you would have to change the way the app runs in the container so that it picks up the main class as a source file. For example, you could change the `ENTRYPOINT` above and add `--spring.main.sources=com.example.SampleApplication`.
Build the Docker image:
```
docker build -t [username/appname] .
```
Push the Docker image:
```
docker push [username/appname]
```
Use the OpenWhisk CLI (e.g. after `vagrant ssh`) to create the action:
```
wsk action create example --docker [username/appname]
```
Invoke the action:
```
wsk action invoke example --result --param payload foo
{
"result": "FOO"
}
```
== Examples
The following examples are built based on the details and explanations above, on how to deploy Spring Cloud Functions on to https://openwhisk.apache.org/[OpenWhisk]

4
docs/src/main/asciidoc/adapters/openwhisk.adoc Normal file
View File

@@ -0,0 +1,4 @@
The https://openwhisk.apache.org/[OpenWhisk] adapter is in the form of an executable jar that can be used in a a docker image to be deployed to Openwhisk. The platform works in request-response mode, listening on port 8080 on a specific endpoint, so the adapter is a simple Spring MVC application.
== Quick Start
include::openwhisk-quick-start.adoc[]

8
docs/src/main/asciidoc/intro.adoc
View File

@@ -1,9 +1,9 @@
Spring Cloud Function is a project with the following high-level goals:
* _Promote the implementation of business logic via functions._
* _Decouple the development lifecycle of business logic from any specific runtime target so that the same code can run as a web endpoint, a stream processor, or a task._
* _Support a uniform programming model across serverless providers, as well as the ability to run standalone (locally or in a PaaS)._
* _Enable Spring Boot features (auto-configuration, dependency injection, metrics) on serverless providers._
* Promote the implementation of business logic via functions.
* Decouple the development lifecycle of business logic from any specific runtime target so that the same code can run as a web endpoint, a stream processor, or a task.
* Support a uniform programming model across serverless providers, as well as the ability to run standalone (locally or in a PaaS).
* Enable Spring Boot features (auto-configuration, dependency injection, metrics) on serverless providers.
It abstracts away all of the transport details and
infrastructure, allowing the developer to keep all the familiar tools

17
docs/src/main/asciidoc/spring-cloud-function.adoc
View File

@@ -106,6 +106,12 @@ An incoming message is routed to a function (or consumer). If there is only one,
NOTE: some binders will fail on startup if the message broker is not available and the function catalog contains suppliers that immediately produce messages when accessed. You can switch off the automatic publishing from suppliers on startup using the `spring.cloud.function.strean.supplier.enabled=false` flag.
== Deploying a Packaged Function
Spring Cloud Function provides a "deployer" library that allows you to launch a jar file (or exploded archive, or set of jar files) with an isolated class loader and expose the functions defined in it. This is quite a powerful tool that would allow you to, for instance, adapt a function to a range of different input-output adapters without changing the target jar file. Serverless platforms often have this kind of feature built in, so you could see it as a building block for a function invoker in such a platform (indeed the https://projectriff.io[Riff] Java function invoker uses this library).
The standard entry point of the API is the Spring configuration annotation `@EnableFunctionDeployer`. If that is used in a Spring Boot application the deployer kicks in and looks for some configuration to tell it where to find the function jar. At a minimum the user has to provide a `function.location` which is a URL or resource location for the archive containing the functions. It can optionally use a `maven:` prefix to locate the artifact via a dependency lookup (see `FunctionProperties` for complete details). A Spring Boot application is bootstrapped from the jar file, using the `MANIFEST.MF` to locate a start class, so that a standard Spring Boot fat jar works well, for example. If the target jar can be launched successfully then the result is a function registered in the main application's `FunctionCatalog`. The registered function can be applied by code in the main application, even though it was created in an isolated class loader (by deault).
== Serverless Platform Adapters
As well as being able to run as a standalone process, a Spring Cloud
@@ -122,9 +128,14 @@ https://projectriff.io[Riff] supports Java functions and its
https://github.com/projectriff/java-function-invoker[Java Function
Invoker] acts natively is an adapter for Spring Cloud Function jars.
== Deploying a Packaged Function
=== AWS Lambda
Spring Cloud Function provides a "deployer" library that allows you to launch a jar file (or exploded archive, or set of jar files) with an isolated class loader and expose the functions defined in it. This is quite a powerful tool that would allow you to, for instance, adapt a function to a range of different input-output adapters without changing the target jar file. Serverless platforms often have this kind of feature built in, so you could see it as a building block for a function invoker in such a platform (indeed the https://projectriff.io[Riff] Java function invoker uses this library).
include::adapters/aws.adoc[leveloffset=+2]
The standard entry point of the API is the Spring configuration annotation `@EnableFunctionDeployer`. If that is used in a Spring Boot application the deployer kicks in and looks for some configuration to tell it where to find the function jar. At a minimum the user has to provide a `function.location` which is a URL or resource location for the archive containing the functions. It can optionally use a `maven:` prefix to locate the artifact via a dependency lookup (see `FunctionProperties` for complete details). A Spring Boot application is bootstrapped from the jar file, using the `MANIFEST.MF` to locate a start class, so that a standard Spring Boot fat jar works well, for example. If the target jar can be launched successfully then the result is a function registered in the main application's `FunctionCatalog`. The registered function can be applied by code in the main application, even though it was created in an isolated class loader (by default).
=== Azure Functions
include::adapters/azure.adoc[leveloffset=+2]
=== Apache Openwhisk
include::adapters/openwhisk.adoc[leveloffset=+2]

1
spring-cloud-function-adapters/spring-cloud-function-adapter-azure/README.adoc
View File

@@ -1,6 +1,5 @@
// Do not edit this file (e.g. go instead to src/main/asciidoc)
This work is experimental.
This project provides an adapter layer for a Spring Cloud Function application onto Azure.
You can write an app with a single `@Bean` of type `Function` and it will be deployable in Azure if you get the JAR file laid out right.

3
spring-cloud-function-adapters/spring-cloud-function-adapter-openwhisk/README.adoc
View File

@@ -1,5 +1,7 @@
// Do not edit this file (e.g. go instead to src/main/asciidoc)
== Quick Start
Implement a POF (be sure to use the `functions` package):
```
@@ -80,6 +82,7 @@ wsk action invoke example --result --param payload foo
"result": "FOO"
}
```
== Examples
The following examples are built based on the details and explanations above, on how to deploy Spring Cloud Functions on to https://openwhisk.apache.org/[OpenWhisk]