Back to Guides

Google Cloud Functions (Serverless)

The quarkus-google-cloud-functions extension allows you to use Quarkus to build your Google Cloud Functions. Your functions can use injection annotations from CDI or Spring and other Quarkus facilities as you need them.

This technology is considered preview.

In preview, backward compatibility and presence in the ecosystem is not guaranteed. Specific improvements might require changing configuration or APIs, and plans to become stable are under way. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker.

For a full list of possible statuses, check our FAQ entry.

Prerequisites

To complete this guide, you need:

Solution

This guide walks you through generating a sample project followed by creating multiple functions showing how to implement HttpFunction, BackgroundFunction and RawBackgroundFunction in Quarkus. Once built, you will be able to deploy the project to Google Cloud.

If you don’t want to follow all these steps, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the google-cloud-functions-quickstart directory.

Creating the Maven Deployment Project

Create an application with the quarkus-google-cloud-functions extension. You can use the following Maven command to create it:

CLI
quarkus create app org.acme:google-cloud-functions \
    --extension='google-cloud-functions' \
    --no-code
cd google-cloud-functions

To create a Gradle project, add the --gradle or --gradle-kotlin-dsl option.

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.9.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=google-cloud-functions \
    -Dextensions='google-cloud-functions' \
    -DnoCode
cd google-cloud-functions

To create a Gradle project, add the -DbuildTool=gradle or -DbuildTool=gradle-kotlin-dsl option.

For Windows users:

  • If using cmd, (don’t use backward slash \ and put everything on the same line)

  • If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=google-cloud-functions"

Login to Google Cloud

Login to Google Cloud is necessary for deploying the application. It can be done as follows:

gcloud auth login

Creating the functions

For this example project, we will create four functions, one HttpFunction, one BackgroundFunction (Storage event), one RawBackgroundFunction (PubSub event) and one CloudEventsFunction (storage event using the Cloud Events specification).

Quarkus supports Cloud Functions gen 1 and gen 2. For an overview of Cloud Functions gen 2 see this page on the Google Cloud Functions documentation. To use gen 2 you must add the --gen2 parameter.

Choose Your Function

The quarkus-google-cloud-functions extension scans your project for a class that directly implements the Google Cloud HttpFunction, BackgroundFunction, RawBackgroundFunction or CloudEventsFunction interface. It must find a class in your project that implements one of these interfaces, or it will throw a build time failure. If it finds more than one function classes, a build time exception will also be thrown.

Sometimes, though, you might have a few related functions that share code and creating multiple maven modules is just an overhead you don’t want to do. The extension allows you to bundle multiple functions in one project and use configuration or an environment variable to pick the function you want to deploy.

To configure the name of the function, you can use the following configuration property:

quarkus.google-cloud-functions.function=test

The quarkus.google-cloud-functions.function property tells Quarkus which function to deploy. This can be overridden with an environment variable too.

The CDI name of the function class must match the value specified within the quarkus.google-cloud-functions.function property. This must be done using the @Named annotation.

@Named("test")
public class TestHttpFunction implements HttpFunction {
}

The HttpFunction

import java.io.Writer;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.inject.Named;
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import io.quarkus.gcp.function.test.service.GreetingService;

@Named("httpFunction") (1)
@ApplicationScoped (2)
public class HttpFunctionTest implements HttpFunction { (3)
    @Inject GreetingService greetingService; (4)

    @Override
    public void service(HttpRequest httpRequest, HttpResponse httpResponse) throws Exception { (5)
        Writer writer = httpResponse.getWriter();
        writer.write(greetingService.hello());
    }
}
1 The @Named annotation allows to name the CDI bean to be used by the quarkus.google-cloud-functions.function property, this is optional.
2 The function must be a CDI bean
3 This is a regular Google Cloud Function implementation, so it needs to implement com.google.cloud.functions.HttpFunction.
4 Injection works inside your function.
5 This is standard Google Cloud Function implementation, nothing fancy here.

The BackgroundFunction

This BackgroundFunction is triggered by a Storage event, you can use any events supported by Google Cloud instead.

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.inject.Named;
import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import io.quarkus.gcp.function.test.service.GreetingService;


@Named("storageTest") (1)
@ApplicationScoped (2)
public class BackgroundFunctionStorageTest implements BackgroundFunction<BackgroundFunctionStorageTest.StorageEvent> { (3)
    @Inject GreetingService greetingService;  (4)

    @Override
    public void accept(StorageEvent event, Context context) throws Exception { (5)
        System.out.println("Receive event: " + event);
        System.out.println("Be polite, say " + greetingService.hello());
    }

    //
    public static class StorageEvent { (6)
        public String name;
    }
}
1 The @Named annotation allows to name the CDI bean to be used by the quarkus.google-cloud-functions.function property, this is optional.
2 The function must be a CDI bean
3 This is a regular Google Cloud Function implementation, so it needs to implement com.google.cloud.functions.BackgroundFunction.
4 Injection works inside your function.
5 This is standard Google Cloud Function implementation, nothing fancy here.
6 This is the class the event will be deserialized to.

The RawBackgroundFunction

This RawBackgroundFunction is triggered by a PubSub event, you can use any events supported by Google Cloud instead.

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.inject.Named;
import com.google.cloud.functions.Context;
import com.google.cloud.functions.RawBackgroundFunction;
import io.quarkus.gcp.function.test.service.GreetingService;

@Named("rawPubSubTest") (1)
@ApplicationScoped (2)
public class RawBackgroundFunctionPubSubTest implements RawBackgroundFunction { (3)
    @Inject GreetingService greetingService; (4)

    @Override
    public void accept(String event, Context context) throws Exception { (5)
        System.out.println("PubSub event: " + event);
        System.out.println("Be polite, say " + greetingService.hello());
    }
}
1 The @Named annotation allows to name the CDI bean to be used by the quarkus.google-cloud-functions.function property, this is optional.
2 The function must be a CDI bean
3 This is a regular Google Cloud Function implementation, so it needs to implement com.google.cloud.functions.RawBackgroundFunction.
4 Injection works inside your function.
5 This is standard Google Cloud Function implementation, nothing fancy here.

The CloudEventsFunction

CloudEventsFunction is a feature of Cloud Functions gen 2 only.

This CloudEventsFunction is triggered by a Cloud Events Storage event, you can use any Cloud Events supported by Google Cloud instead.

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.inject.Named;

import com.google.cloud.functions.CloudEventsFunction;

import io.cloudevents.CloudEvent;
import io.quarkus.gcp.function.test.service.GreetingService;

@Named("cloudEventTest") (1)
@ApplicationScoped (2)
public class CloudEventStorageTest implements CloudEventsFunction { (3)
    @Inject
    GreetingService greetingService;  (4)

    @Override
    public void accept(CloudEvent cloudEvent) throws Exception { (5)
        System.out.println("Receive event Id: " + cloudEvent.getId());
        System.out.println("Receive event Subject: " + cloudEvent.getSubject());
        System.out.println("Receive event Type: " + cloudEvent.getType());
        System.out.println("Receive event Data: " + new String(cloudEvent.getData().toBytes())); (6)
        System.out.println("Be polite, say " + greetingService.hello());
    }
}
1 The @Named annotation allows to name the CDI bean to be used by the quarkus.google-cloud-functions.function property, this is optional.
2 The function must be a CDI bean
3 This is a regular Google Cloud Function implementation, so it needs to implement com.google.cloud.functions.CloudEventsFunction.
4 Injection works inside your function.
5 This is standard Google Cloud Function implementation, nothing fancy here except that it receives a io.cloudevents.CloudEvent.
6 This is the storage event inside the Cloud Events.

Build and Deploy to Google Cloud

To build your application, you can package it using the standard command:

CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

The result of the previous command is a single JAR file inside the target/deployment repository that contains classes and dependencies of the project.

Then you will be able to use gcloud to deploy your function to Google Cloud. The gcloud command will be different depending on which event triggers your function.

We will use the Java 17 runtime but you can switch to the Java 21 runtime by using --runtime=java21 instead of --runtime=java17 on the deploy commands.

The first time you launch this command, you can have the following error message:

ERROR: (gcloud.functions.deploy) OperationError: code=7, message=Build Failed: Cloud Build has not been used in project <project_name> before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudbuild.googleapis.com/overview?project=<my-project> then retry.

This means that Cloud Build is not activated yet. To overcome this error, open the URL shown in the error, follow the instructions and then wait a few minutes before retrying the command.

The HttpFunction

This is an example command to deploy your HttpFunction to Google Cloud:

gcloud functions deploy quarkus-example-http \
  --entry-point=io.quarkus.gcp.functions.QuarkusHttpFunction \
  --runtime=java17 --trigger-http --allow-unauthenticated --source=target/deployment

The entry point must always be set to io.quarkus.gcp.functions.QuarkusHttpFunction as this is the class that integrates Cloud Functions with Quarkus.

This command will give you as output a httpsTrigger.url that points to your function.

The BackgroundFunction

Before deploying your function, you need to create a bucket.

gsutil mb gs://quarkus-hello

This is an example command to deploy your BackgroundFunction to Google Cloud, as the function is triggered by a Storage event, it needs to use --trigger-event google.storage.object.finalize and the --trigger-resource parameter with the name of a previously created bucket:

gcloud functions deploy quarkus-example-storage \
    --entry-point=io.quarkus.gcp.functions.QuarkusBackgroundFunction \
    --trigger-resource quarkus-hello --trigger-event google.storage.object.finalize \
    --runtime=java17 --source=target/deployment

The entry point must always be set to io.quarkus.gcp.functions.QuarkusBackgroundFunction as this is the class that integrates Cloud Functions with Quarkus.

To trigger the event, you can send a file to the GCS quarkus-hello bucket, or you can use gcloud to simulate one:

gcloud functions call quarkus-example-storage  --data '{"name":"test.txt"}'
--data contains the GCS event, it is a JSON document with the name of the file added to the bucket.

The RawBackgroundFunction

This is an example command to deploy your RawBackgroundFunction to Google Cloud, as the function is triggered by a PubSub event, it needs to use --trigger-event google.pubsub.topic.publish and the --trigger-resource parameter with the name of a previously created topic:

gcloud functions deploy quarkus-example-pubsub \
  --entry-point=io.quarkus.gcp.functions.QuarkusBackgroundFunction \
  --runtime=java17 --trigger-resource hello_topic --trigger-event google.pubsub.topic.publish --source=target/deployment

The entry point must always be set to io.quarkus.gcp.functions.QuarkusBackgroundFunction as this is the class that integrates Cloud Functions with Quarkus.

To trigger the event, you can send a file to the hello_topic topic, or you can use gcloud to simulate one:

gcloud functions call quarkus-example-pubsub --data '{"data":{"greeting":"world"}}'

The CloudEventsFunction

CloudEventsFunction is a feature of Cloud Functions gen 2 only.

This is an example command to deploy your CloudEventsFunction to Google Cloud, as the function is triggered by a Storage event, it needs to use --trigger-bucket parameter with the name of a previously created bucket:

gcloud functions deploy quarkus-example-cloud-event --gen2 \
  --entry-point=io.quarkus.gcp.functions.QuarkusCloudEventsFunction \
  --runtime=java17 --trigger-bucket=example-cloud-event --source=target/deployment

The entry point must always be set to io.quarkus.gcp.functions.QuarkusCloudEventsFunction as this is the class that integrates Cloud Functions with Quarkus.

To trigger the event, you can send a file to the GCS example-cloud-event bucket.

Running locally

The easiest way to locally run your function is using the Cloud Function invoker JAR.

You can download it via Maven using the following command:

mvn dependency:copy \
  -Dartifact='com.google.cloud.functions.invoker:java-function-invoker:1.3.0' \
  -DoutputDirectory=.

Before using the invoker, you first need to build your function via:

CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

The HttpFunction

For an HttpFunction, you can use this command to launch your function locally.

java -jar java-function-invoker-1.3.0.jar \
  --classpath target/google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.gcp.functions.QuarkusHttpFunction
The --classpath parameter needs to be set to the previously packaged JAR that contains your function class and all Quarkus related classes.

Your endpoints will be available on http://localhost:8080.

The BackgroundFunction

For background functions, you launch the invoker with a target class of io.quarkus.gcp.functions.BackgroundFunction.

java -jar java-function-invoker-1.3.0.jar \
  --classpath target/google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.gcp.functions.QuarkusBackgroundFunction
The --classpath parameter needs to be set to the previously packaged JAR that contains your function class and all Quarkus related classes.

Then you can call your background function via an HTTP call with a payload containing the event:

curl localhost:8080 -d '{"data":{"name":"hello.txt"}}'

This will call your Storage background function with an event {"name":"hello.txt"}, so an event on the hello.txt file.

The RawBackgroundFunction

For background functions, you launch the invoker with a target class of io.quarkus.gcp.functions.BackgroundFunction.

java -jar java-function-invoker-1.3.0.jar \
  --classpath target/google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.gcp.functions.QuarkusBackgroundFunction
The --classpath parameter needs to be set to the previously packaged JAR that contains your function class and all Quarkus related classes.

Then you can call your background function via an HTTP call with a payload containing the event:

curl localhost:8080 -d '{"data":{"greeting":"world"}}'

This will call your PubSub background function with a PubSubMessage {"greeting":"world"}.

The CloudEventsFunction

CloudEventsFunction is a feature of Cloud Function gen 2 only.

For cloud events functions, you launch the invoker with a target class of io.quarkus.gcp.functions.QuarkusCloudEventsFunction.

java -jar java-function-invoker-1.3.0.jar \
  --classpath target/google-cloud-functions-1.0.0-SNAPSHOT-runner.jar \
  --target io.quarkus.gcp.functions.QuarkusCloudEventsFunction
The --classpath parameter needs to be set to the previously packaged JAR that contains your function class and all Quarkus related classes.

Then you can call your cloud events function via an HTTP call with a payload containing the event:

curl localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -H "ce-id: 123451234512345" \
  -H "ce-specversion: 1.0" \
  -H "ce-time: 2020-01-02T12:34:56.789Z" \
  -H "ce-type: google.cloud.storage.object.v1.finalized" \
  -H "ce-source: //storage.googleapis.com/projects/_/buckets/MY-BUCKET-NAME" \
  -H "ce-subject: objects/MY_FILE.txt" \
  -d '{
        "bucket": "MY_BUCKET",
        "contentType": "text/plain",
        "kind": "storage#object",
        "md5Hash": "...",
        "metageneration": "1",
        "name": "MY_FILE.txt",
        "size": "352",
        "storageClass": "MULTI_REGIONAL",
        "timeCreated": "2020-04-23T07:38:57.230Z",
        "timeStorageClassUpdated": "2020-04-23T07:38:57.230Z",
        "updated": "2020-04-23T07:38:57.230Z"
      }'

This will call your cloud events function with an event on the "MY_FILE.txt file.

Testing your function

Quarkus provides built-in support for testing your Google Cloud functions via the quarkus-test-google-cloud-functions dependency.

To use it, you must add the following test dependency in your pom.xml.

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-test-google-cloud-functions</artifactId>
    <scope>test</scope>
</dependency>

This extension provides a @WithFunction annotation that can be used to annotate @QuarkusTest test cases to start a Cloud Function invoker before you test cases and stop it at the end. This annotation must be configured with the type of the function you want to launch, and optionally the name of the function in case you have multiple functions inside your application.

The default Quarkus test port configuration (quarkus.http.test-port) will be honored and if you set it to 0 a random port will be assigned to the function invoker.

The HttpFunction

import static io.restassured.RestAssured.when;
import static org.hamcrest.Matchers.is;

import org.junit.jupiter.api.Test;

import io.quarkus.google.cloud.functions.test.FunctionType;
import io.quarkus.google.cloud.functions.test.WithFunction;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest (1)
@WithFunction(FunctionType.HTTP) (2)
class HttpFunctionTestCase {
    @Test
    public void test() {
        when()
                .get()
                .then()
                .statusCode(200)
                .body(is("Hello World!")); (3)
    }
}

  1. This is a standard Quarkus test that must be annotated by @QuarkusTest.

  2. @WithFunction(FunctionType.HTTP) indicates to launch the function as an HTTP function. If multiple functions exist in the same application, the functionName attribute must be used to denote which one should be launched.

  3. REST-assured is used to test the function, Hello World! will be sent to it via the invoker.

The BackgroundFunction

import static io.restassured.RestAssured.given;

import org.junit.jupiter.api.Test;

import io.quarkus.google.cloud.functions.test.FunctionType;
import io.quarkus.google.cloud.functions.test.WithFunction;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest (1)
@WithFunction(FunctionType.BACKGROUND) (2)
class BackgroundFunctionStorageTestCase {
    @Test
    public void test() {
        given()
                .body("{\"data\":{\"name\":\"hello.txt\"}}") (3)
                .when()
                .post()
                .then()
                .statusCode(200);
    }
}

  1. This is a standard Quarkus test that must be annotated by @QuarkusTest.

  2. @WithFunction(FunctionType.BACKGROUND) indicates to launch the function as a background function. If multiple functions exist in the same application, the functionName attribute must be used to denote which one should be launched.

  3. REST-assured is used to test the function, {"name":"hello.txt"} will be sent to it via the invoker.

The RawBackgroundFunction

import static io.restassured.RestAssured.given;

import org.junit.jupiter.api.Test;

import io.quarkus.google.cloud.functions.test.FunctionType;
import io.quarkus.google.cloud.functions.test.WithFunction;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest (1)
@WithFunction(FunctionType.RAW_BACKGROUND) (2)
class RawBackgroundFunctionPubSubTestCase {
    @Test
    public void test() {
        given()
                .body("{\"data\":{\"name\":\"hello.txt\"}}") (3)
                .when()
                .post()
                .then()
                .statusCode(200);
    }
}

  1. This is a standard Quarkus test that must be annotated by @QuarkusTest.

  2. @WithFunction(FunctionType.RAW_BACKGROUND) indicates to launch the function as a raw background function. If multiple functions exist in the same application, the functionName attribute must be used to denote which one should be launched.

  3. REST-assured is used to test the function, {"name":"hello.txt"} will be sent to it via the invoker.

The CloudEventsFunction

Cloud Events Function is a feature of Cloud Functions gen 2 only. 
import static io.restassured.RestAssured.given;

import org.junit.jupiter.api.Test;

import io.quarkus.google.cloud.functions.test.FunctionType;
import io.quarkus.google.cloud.functions.test.WithFunction;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest (1)
@WithFunction(FunctionType.CLOUD_EVENTS) (2)
class CloudEventStorageTestCase {
    @Test
    public void test() {
        // test the function using RestAssured
        given()
                .body("{\n" + (3)
                        "        \"bucket\": \"MY_BUCKET\",\n" +
                        "        \"contentType\": \"text/plain\",\n" +
                        "        \"kind\": \"storage#object\",\n" +
                        "        \"md5Hash\": \"...\",\n" +
                        "        \"metageneration\": \"1\",\n" +
                        "        \"name\": \"MY_FILE.txt\",\n" +
                        "        \"size\": \"352\",\n" +
                        "        \"storageClass\": \"MULTI_REGIONAL\",\n" +
                        "        \"timeCreated\": \"2020-04-23T07:38:57.230Z\",\n" +
                        "        \"timeStorageClassUpdated\": \"2020-04-23T07:38:57.230Z\",\n" +
                        "        \"updated\": \"2020-04-23T07:38:57.230Z\"\n" +
                        "      }")
                .header("ce-specversion", "1.0") (4)
                .header("ce-id", "1234567890")
                .header("ce-type", "google.cloud.storage.object.v1.finalized")
                .header("ce-source", "//storage.googleapis.com/projects/_/buckets/MY-BUCKET-NAME")
                .header("ce-subject", "objects/MY_FILE.txt")
                .when()
                .post()
                .then()
                .statusCode(200);
    }
}

  1. This is a standard Quarkus test that must be annotated by @QuarkusTest.

  2. @WithFunction(FunctionType.CLOUD_EVENTS) indicates to launch the function as a cloud events function. If multiple functions exist in the same application, the functionName attribute must be used to denote which one should be launched.

  3. REST-assured is used to test the function, this payload that describe a storage event will be sent to it via the invoker.

  4. The cloud events headers must be sent via HTTP headers.

What’s next?

If you are looking for Jakarta REST, Servlet or Vert.x support for Google Cloud Functions, we have it thanks to our Google Cloud Functions HTTP binding.

If you are looking for a provider-agnostic implementation of your Google Cloud Functions, we have it thanks to our Funqy Google Cloud Functions extension.

Related content

On the same topics

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license.

This website was built with Jekyll, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Follow Us
Get Help
Languages
Quarkus is made of community projects
CC by 3.0 | Privacy Policy Sponsored by