Deploying to Google Cloud Platform (GCP)

本指南涵盖：

This guide covers:

Login to Google Cloud
Deploying a function to Google Cloud Functions
Deploying a JAR to Google App Engine Standard
Deploying a Docker image to Google App Engine Flexible Custom Runtimes
Deploying a Docker image to Google Cloud Run
Using Cloud SQL

Prerequisites

Unresolved directive in deploying-to-google-cloud.adoc - include::{includes}/prerequisites.adoc[]* A Google Cloud Account免费帐号有用。* Cloud SDK CLI Installed

Unresolved directive in deploying-to-google-cloud.adoc - include::{includes}/prerequisites.adoc[] * A Google Cloud Account. Free accounts work. * Cloud SDK CLI Installed

本指南将以在 Getting Started guide中开发的应用程序作为输入。

This guide will take as input an application developed in the Getting Started guide.

确保您已准备好入门应用程序，或克隆 Git 存储库：git clone {quickstarts-clone-url}，或下载一个 {quickstarts-archive-url}[存档]。解决方案位于 `getting-started`目录中。

Make sure you have the getting-started application at hand, or clone the Git repository: git clone {quickstarts-clone-url}, or download an {quickstarts-archive-url}[archive]. The solution is located in the getting-started directory.

Login to Google Cloud

部署应用程序需要登录 Google Cloud。可以按以下方式进行操作：

gcloud auth login

Deploying to Google Cloud Functions

Quarkus 支持通过以下扩展将您的应用程序部署到 Google Cloud Functions：

Quarkus supports deploying your application to Google Cloud Functions via the following extensions:

Google Cloud Functions: Build functions using the Google Cloud Functions API.
Google Cloud Functions HTTP binding: Build functions using Quarkus HTTP APIs: Quarkus REST (formerly RESTEasy Reactive, our Jakarta REST implementation), Undertow (Servlet), Vert.x Web, or Funqy HTTP.
Funky Google Cloud Functions: Build functions using Funqy.

每个扩展都支持特定类型的应用程序开发，请遵循特定指南以了解如何使用它们开发、打包和部署应用程序。

Each extension supports a specific kind of application development, follow the specific guides for more information on how to develop, package and deploy your applications using them.

Deploying to Google App Engine Standard

首先，请确保为您的 Google Cloud 项目初始化一个 App Engine 环境，如果没有，请通过 `gcloud app create --project=[YOUR_PROJECT_ID]`初始化一个。

First, make sure to have an App Engine environment initialized for your Google Cloud project, if not, initialize one via gcloud app create --project=[YOUR_PROJECT_ID].

然后，您需要创建一个 `src/main/appengine/app.yaml`文件，让我们仅使用选定的引擎使其保持简洁：

Then, you will need to create a src/main/appengine/app.yaml file, let’s keep it minimalistic with only the selected engine:

runtime: java11

这将为您的 App Engine 应用程序创建一个默认服务。

This will create a default service for your App Engine application.

您还可以通过定义 `runtime: java17`来使用新的 Java 17 运行时。

You can also use the new Java 17 runtime by defining runtime: java17 instead.

App Engine Standard 不支持 Quarkus 的默认特定打包布局，因此，您必须设置您的应用程序才能通过您的 `application.properties`文件打包成 uber-jar：

App Engine Standard does not support the default Quarkus' specific packaging layout, therefore, you must set up your application to be packaged as an uber-jar via your application.properties file:

quarkus.package.jar.type=uber-jar

然后，您可以选择手动构建应用程序或将该职责委派给 `gcloud`或 Google Cloud Maven 插件。

Then, you can choose to build the application manually or delegating that responsibility to gcloud or the Google Cloud Maven plugin.

Building the application manually

使用 `mvn clean package`使用 Maven 构建应用程序，它将生成一个包含您的应用程序的所有类及其依赖项的 JAR。

Use Maven to build the application using mvn clean package, it will generate a single JAR that contains all the classes of your application including its dependencies.

最后，使用 `gcloud`将您的应用程序部署为 App Engine 服务。

Finally, use gcloud to deploy your application as an App Engine service.

gcloud app deploy target/getting-started-1.0.0-SNAPSHOT-runner.jar

此命令将上传应用 jar 并随 App Engine 一同启动它。

This command will upload your application jar and launch it on App Engine.

完成后，输出将显示你应用的 URL（目标网址），你可以随 gcloud app browse 一同使用 curl 或直接在浏览器中打开。

When it’s done, the output will display the URL of your application (target url), you can use it with curl or directly open it in your browser using gcloud app browse.

Building the application via gcloud

你可以选择让 gcloud 为你生成你的应用，这是向 App Engine 部署的最简单方式。

You can choose to let gcloud build your application for you, this is the simplest way to deploy to App Engine.

接着，你只需在项目根目录启动 gcloud app deploy，它将上传你所有项目文件（可通过 .gcloudignore 文件减少清单），经由 Maven（或 Gradle）打包你的 JAR，然后随 App Engine 启动。

Then, you can just launch gcloud app deploy in the root of your project, it will upload all your project files (the list can be reduced via the .gcloudignore file), package your JAR via Maven (or Gradle) and launch it on App Engine.

完成后，输出将显示你应用的 URL（目标网址），你可以随 gcloud app browse 一同使用 curl 或直接在浏览器中打开。

When it’s done, the output will display the URL of your application (target url), you can use it with curl or directly open it in your browser using gcloud app browse.

Building the application via the Google Cloud Maven plugin

你也可以让 Maven 使用 App Engine Maven 插件控制你的应用部署。

You can also let Maven control the deployment of your application using the App Engine Maven plugin.

首先，将插件添加到你的 pom.xml：

First, add the plugin to your pom.xml:

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>2.4.4</version>
    <configuration>
        <projectId>GCLOUD_CONFIG</projectId> 1
        <version>gettingstarted</version>
        <artifact>${project.build.directory}/${project.artifactId}-${project.version}-runner.jar</artifact> 2
    </configuration>
</plugin>

1	Use the default `gcloud` configuration
2	Override the default JAR name to the one generated by the Quarkus Maven plugin

接着，你就可以通过 mvn clean package appengine:deploy 随 Maven 使用 Maven 来建立并部署你的应用至 App Engine。

Then you would be able to use Maven to build and deploy your application to App Engine via mvn clean package appengine:deploy.

完成后，输出将显示你应用的 URL（目标网址），你可以随 gcloud app browse 一同使用 curl 或直接在浏览器中打开。

When it’s done, the output will display the URL of your application (target URL), you can use it with curl or directly open it in your browser using gcloud app browse.

Deploying to Google App Engine Flexible Custom Runtimes

最重要的是，确保你的 Google Cloud 项目的 App Engine 环境已初始化，如果没有，请通过 gcloud app create --project=[YOUR_PROJECT_ID] 初始化一个。

Before all, make sure to have an App Engine environment initialized for your Google Cloud project, if not, initialize one via gcloud app create --project=[YOUR_PROJECT_ID].

App Engine 可弹性伸缩的自定义运行时使用 Docker 映像运行你的应用。

App Engine Flexible Custom Runtimes uses a Docker image to run your application.

首先，在项目根目录创建 app.yaml 文件，内容如下：

First, create an app.yaml file at the root of your project with the following content:

runtime: custom
env: flex

App Engine 可弹性伸缩的自定义运行时将应用部署为 Docker 容器，你可以选择部署应用内提供的其中一个 Dockerfile。

App Engine Flexible Custom Runtimes deploys your application as a Docker container, you can choose to deploy one of the Dockerfile provided inside your application.

JVM 及原生可执行版本都行得通。

Both JVM and native executable versions will work.

若要部署 JVM 应用：

To deploy a JVM application:

Copy the JVM Dockerfile to the root directory of your project: cp src/main/docker/Dockerfile.jvm Dockerfile.
Build your application using mvn clean package.

若要部署原生应用：

To deploy a native application:

Copy the native Dockerfile to the root directory of your project: cp src/main/docker/Dockerfile.native Dockerfile.
Build your application as a native executable using mvn clean package -Dnative.

最后在项目的根目录中启动 gcloud app deploy，它将上传项目的所有文件（可以通过 .gcloudignore 文件来减少列表），构建 Dockerfile，并在 App Engine Flexible 自有运行时中启动它。

Finally, launch gcloud app deploy in the root of your project, it will upload all your project files (the list can be reduced via the .gcloudignore file), build your Dockerfile and launch it on App Engine Flexible custom runtime.

它使用 Cloud Build 来构建 Docker 镜像，并将其部署到 Google Container Registry (GCR)。

It uses Cloud Build to build your Docker image and deploy it to Google Container Registry (GCR).

完成后，输出将显示应用程序的 URL（目标 URL），可以使用 curl 使用它或使用 gcloud app browse 直接在浏览器中打开它。

When done, the output will display the URL of your application (target url), you can use it with curl or directly open it in your browser using gcloud app browse.

App Engine Flexible 自有运行时支持 health checks，强烈建议使用 Quarkus 提供的 Smallrye Health 支持。

App Engine Flexible custom runtimes support health checks, it is strongly advised to provide them thanks to Quarkus Smallrye Health support.

Deploying to Google Cloud Run

Google Cloud Run 允许以托管方式在 Google Cloud Platform 中运行 Docker 容器。

Google Cloud Run allows you to run your Docker containers inside Google Cloud Platform in a managed way.

默认情况下，Quarkus 在端口 8080 上监听，这也是 Cloud Run 的默认端口。不需要使用 Cloud Run 中定义的 PORT 环境变量来自定义 Quarkus HTTP 端口。

By default, Quarkus listens on port 8080, and it’s also the Cloud Run default port. No need to use the PORT environment variable defined in Cloud Run to customize the Quarkus HTTP port.

Cloud Run 将使用 Cloud Build 来构建 Docker 镜像，并将其部署到 Google Container Registry (GCR)。

Cloud Run will use Cloud Build to build your Docker image and deploy it to Google Container Registry (GCR).

JVM 及原生可执行版本都行得通。

Both JVM and native executable versions will work.

若要部署 JVM 应用：

To deploy a JVM application:

Copy the JVM Dockerfile to the root directory of your project: cp src/main/docker/Dockerfile.jvm Dockerfile.
Build your application using mvn clean package.

若要部署原生应用：

To deploy a native application:

Copy the native Dockerfile to the root directory of your project: cp src/main/docker/Dockerfile.native Dockerfile.
Build your application as a native executable using mvn clean package -Dnative.

然后，创建一个 .gcloudignore 文件来告诉 gcloud 哪些文件不应该为 Cloud Build 上传，如果没有该文件，它将默认为 .gitignore，通常会将打包了应用程序创建的目标目录排除在外。

Then, create a .gcloudignore file to tell gcloud which files should be not be uploaded for Cloud Build, without it, it defaults to .gitignore that usually exclude the target directory where you packaged application has been created.

在此示例中，仅排除 src 目录：

In this example, I only exclude the src directory:

src/

然后，使用 Cloud Build 构建镜像，它将把应用程序的所有文件（除了 .gcloudignore 文件忽略的文件）上传到 Google Cloud Storage 存储分区，构建 Docker 镜像并将其推送到 Google Container Registry (GCR)。

Then, use Cloud Build to build your image, it will upload to a Google Cloud Storage bucket all the files of your application (except the ones ignored by the `.gcloudignore`file), build your Docker image and push it to Google Container Registry (GCR).

gcloud builds submit --tag gcr.io/PROJECT-ID/helloworld

你还可以本地构建镜像并将其推送到可公开访问的 Docker 注册表中，然后在下步中使用此镜像。

You can also build your image locally and push it to a publicly accessible Docker registry, then use this image in the next step.

最后，使用 Cloud Run 启动应用程序。

Finally, use Cloud Run to launch your application.

gcloud run deploy --image gcr.io/PROJECT-ID/helloworld

Cloud Run 会询问有关服务名称、区域以及是否允许未经身份验证的呼叫的问题。回答完这些问题后，它将部署应用程序。

Cloud run will ask you questions on the service name, the region and whether unauthenticated calls are allowed. After you answer to these questions, it will deploy your application.

完成部署后，输出将显示访问应用程序的 URL。

When the deployment is done, the output will display the URL to access your application.

Cloud Run 支持 health checks，强烈建议使用 Quarkus Smallrye Health 支持来提供它们。

Cloud Run supports health checks, it is strongly advised to provide them thanks to Quarkus Smallrye Health support.

Using Cloud SQL

Google Cloud SQL 提供了针对 MySQL、PostgreSQL 和 Microsoft SQL Server 的托管实例。Quarkus 支持所有这三个数据库。

Google Cloud SQL provides managed instances for MySQL, PostgreSQL and Microsoft SQL Server. Quarkus has support for all three databases.

Using Cloud SQL with a JDBC driver

要让应用程序与 Cloud SQL 协同工作，你首先需要使用相应的 JDBC 扩展，例如对于 PostgreSQL，添加 quarkus-jdbc-postgresql 扩展。

To make your applications work with Cloud SQL, you first need to use the corresponding JDBC extension, for example, for PostgreSQL, add the quarkus-jdbc-postgresql extension.

然后，你需在 pom.xml 中添加云 SQL JDBC 库，该库可提供与云 SQL 的附加连接。对于 PostgreSQL，你需包含下列依赖关系：

Then you need to add to your pom.xml the Cloud SQL JDBC library that provides the additional connectivity to Cloud SQL. For PostgreSQL you will need to include the following dependency:

<dependency>
    <groupId>com.google.cloud.sql</groupId>
    <artifactId>postgres-socket-factory</artifactId>
    <version>${postgres-socket-factory.version}</version>
</dependency>

最后，你需专门配置数据源，才能使用套接字工厂：

Finally, you need to configure your datasource specifically to use the socket factory:

quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.url=jdbc:postgresql:///mydatabase 1
quarkus.datasource.username=quarkus
quarkus.datasource.password=quarkus
quarkus.datasource.jdbc.additional-jdbc-properties.cloudSqlInstance=project-id:gcp-region:instance 2
quarkus.datasource.jdbc.additional-jdbc-properties.socketFactory=com.google.cloud.sql.postgres.SocketFactory 3

1	The JDBC URL should not include the hostname / IP of the database.
2	We add the `cloudSqlInstance` additional JDBC property to configure the instance id.
3	We add the `socketFactory` additional JDBC property to configure the socket factory used to connect to Cloud SQL, this one is coming from the `postgres-socket-factory` dependency.

目前在开发模式中，由于问题 #15782，无法使用 PostgreSQL 套接字工厂。

Using a PostgreSQL socket factory is not possible in dev mode at the moment due to issue #15782.

Using Cloud SQL with a reactive SQL client

你还可以使用我们的响应式 SQL 客户端（而非 JDBC 客户端）。若要使用云 SQL，请添加下列依赖关系（根据你的平台调整分类器）：

You can also use one of our reactive SQL client instead of the JDBC client. To do so with Cloud SQL, add the following dependency (adjust the classifier depending on your platform):

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <classifier>linux-x86_64</classifier>
</dependency>

然后配置你的响应式数据源，不使用主机名，而使用 Netty 本机传输：

Then configure your reactive datasource with no hostname and with the Netty native transport:

quarkus.datasource.reactive.url=postgresql://:5432/db-name?host=/cloudsql/project-id:zone:db-name
quarkus.vertx.prefer-native-transport=true

这仅在应用程序在由 Google Cloud 管理的运行时中运行时才起作用，例如 App Engine。

This only works when your application is running inside a Google Cloud managed runtime like App Engine.

Using Cloud SQL with native executables

生成本机可执行文件时，你还必须将 jnr.ffi.provider.jffi.NativeFinalizer$SingletonHolder 标记为运行时初始化。

When generating native executables, you must also mark jnr.ffi.provider.jffi.NativeFinalizer$SingletonHolder as runtime initialized.

quarkus.native.additional-build-args=--initialize-at-run-time=jnr.ffi.provider.jffi.NativeFinalizer$SingletonHolder

Going further

你可以在 Quarkiverse（一个由社区维护的 Quarukus 扩展名 GitHub 组织）中找到用于访问各种 Google Cloud 服务的一套扩展名，包括 PubSub、BigQuery、Storage、Spanner、Firestore、Secret Manager（访问代码库以获取受支持服务的确切列表）。

You can find a set of extensions to access various Google Cloud Services in the Quarkiverse (a GitHub organization for Quarkus extensions maintained by the community), including PubSub, BigQuery, Storage, Spanner, Firestore, Secret Manager (visit the repository for an accurate list of supported services).

你可以在 Quarkiverse Google Cloud Services documentation 中找到关于它们的文档。

You can find some documentation about them in the Quarkiverse Google Cloud Services documentation.