Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Kết nối ứng dụng Java với AlloyDB cho PostgreSQL bằng tính năng Xác thực IAM

1. Trước khi bắt đầu

Java và AlloyDB: Kết nối đơn giản, an toàn

AlloyDB cho PostgreSQL là dịch vụ cơ sở dữ liệu được quản lý hoàn toàn, tương thích với PostgreSQL của Google Cloud, dành cho các khối lượng công việc đòi hỏi khắt khe của doanh nghiệp. Để kết nối ứng dụng Java với AlloyDB một cách an toàn và hiệu quả, bạn có thể sử dụng Trình kết nối Java của AlloyDB (alloydb-jdbc-connector), một thư viện ứng dụng không chỉ là trình điều khiển JDBC tiêu chuẩn.

Sự kỳ diệu của Trình kết nối Java AlloyDB

alloydb-jdbc-connector hoạt động như một SocketFactory thông minh cho trình điều khiển JDBC PostgreSQL tiêu chuẩn (org.postgresql:postgresql). Trình điều khiển này tóm tắt việc thiết lập một kết nối cơ sở dữ liệu an toàn để bạn có thể tập trung vào logic ứng dụng thay vì bảo mật mạng hoặc thay đổi định kỳ thông tin xác thực:

Mã hoá mTLS 1.3: Tự động thiết lập kết nối TLS 1.3 được xác thực lẫn nhau giữa JVM và phiên bản AlloyDB mà không yêu cầu bạn quản lý chứng chỉ ứng dụng SSL/TLS theo cách thủ công.
Uỷ quyền dựa trên IAM: Thay vì dựa vào mật khẩu cơ sở dữ liệu tĩnh, trình kết nối này tận dụng Cloud IAM của Google và Thông tin xác thực mặc định của ứng dụng (ADC) để tự động lấy mã truy cập OAuth2 có thời hạn ngắn.
Phân giải IP động: Truy vấn API quản trị AlloyDB để phân giải địa chỉ IP hiện tại (PRIVATE, PUBLIC hoặc Private Service Connect PSC) của thực thể cơ sở dữ liệu một cách linh động. Bạn không cần phải cố định giá trị tên máy chủ hoặc địa chỉ IP trong mã, giúp quá trình chuyển đổi dự phòng và bảo trì diễn ra minh bạch.

Cách hoạt động của Trình kết nối Java AlloyDB

Điều kiện tiên quyết

Quen thuộc với Java, Maven và các khái niệm cơ bản về SQL/JDBC.
Hiểu biết cơ bản về Google Cloud CLI (gcloud) và vai trò IAM.

Bạn sẽ thực hiện

Định cấu hình một phiên bản AlloyDB và Tài khoản dịch vụ cho tính năng Xác thực cơ sở dữ liệu IAM không cần mật khẩu.
Cấp quyền tối thiểu đối với giản đồ và bảng PostgreSQL cho một tài khoản chính IAM.
Định cấu hình DataSource cấp phát hành công khai bằng Plain JDBC và HikariCP bằng SocketFactory AlloyDB.
Tích hợp Trình kết nối Java AlloyDB trong các ứng dụng Spring Boot, Quarkus và Micronaut.
Đăng ký SocketFactory AlloyDB để biên dịch GraalVM Native Image và khắc phục sự cố các lỗi thường gặp về xác thực IAM.

Bạn cần có

Một dự án trên đám mây của Google Cloud đã bật tính năng thanh toán và một Cụm AlloyDB và Thực thể chính đang hoạt động (xem hướng dẫn tạo cụm AlloyDB hoặc khởi động một cụm AlloyDB Express trong chưa đầy hai giây).
Vai trò IAM roles/alloydb.admin và roles/resourcemanager.projectIamAdmin đối với dự án của bạn.
Đã cài đặt Java 17 trở lên (nên dùng Java 17 hoặc 21 LTS) và Apache Maven.
Đã cài đặt CLI gcloud và ứng dụng psql (hoặc có quyền truy cập vào Google Cloud Shell).

2. Thiết lập tính năng Xác thực cơ sở dữ liệu IAM trên AlloyDB

Trước khi viết mã Java, bạn cần định cấu hình phiên bản AlloyDB để chấp nhận mã thông báo IAM và tạo danh tính IAM mà ứng dụng của bạn sẽ sử dụng trên ba lớp: Google Cloud IAM, Mặt phẳng điều khiển AlloyDB và Công cụ PostgreSQL.

Thiết lập ba lớp để xác thực cơ sở dữ liệu IAM của AlloyDB

Đặt biến môi trường

Trong dòng lệnh, hãy xuất các biến tương ứng với dự án trên đám mây của Google Cloud và thực thể AlloyDB của bạn (thay thế phần giữ chỗ bằng giá trị của bạn):

export PROJECT_ID="<PROJECT_ID>"
export REGION="europe-west1"
export CLUSTER_ID="<CLUSTER_ID>"
export INSTANCE_ID="<INSTANCE_ID>"
export DB_NAME="dvdrental"

Bật các API bắt buộc

Bật các API AlloyDB, Compute Engine, Cloud Resource Manager, IAM và Service Usage trong dự án của bạn:

gcloud services enable \
    alloydb.googleapis.com \
    compute.googleapis.com \
    cloudresourcemanager.googleapis.com \
    iam.googleapis.com \
    serviceusage.googleapis.com \
    --project="${PROJECT_ID}"

Tạo tài khoản dịch vụ và cấp vai trò IAM

Tạo một Tài khoản dịch vụ chuyên dụng đóng vai trò là danh tính của ứng dụng Java:

gcloud iam service-accounts create java-alloydb-connector \
    --project="${PROJECT_ID}" \
    --display-name="Java Application DB Connector"

Cấp cho Tài khoản dịch vụ hai vai trò IAM mà Trình kết nối Java của AlloyDB yêu cầu:

roles/alloydb.client: Cần thiết để tìm nạp siêu dữ liệu của thực thể và yêu cầu chứng chỉ mTLS tạm thời từ API quản trị AlloyDB.
roles/serviceusage.serviceUsageConsumer: Bắt buộc để xác thực cơ sở dữ liệu IAM.

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/alloydb.client"

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/serviceusage.serviceUsageConsumer"

Bật tính năng xác thực IAM trên phiên bản AlloyDB

Cập nhật cờ của phiên bản AlloyDB để đặt alloydb.iam_authentication=on. Đây là cờ động và có hiệu lực ngay lập tức mà không cần khởi động lại phiên bản:

gcloud alloydb instances update "${INSTANCE_ID}" \
    --cluster="${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --database-flags=alloydb.iam_authentication=on

Đăng ký Người dùng cơ sở dữ liệu IAM

Đăng ký Tài khoản dịch vụ làm người dùng cơ sở dữ liệu IAM_BASED trên cụm AlloyDB bằng gcloud:

gcloud alloydb users create "java-alloydb-connector@${PROJECT_ID}.iam" \
    --cluster="${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --type=IAM_BASED

Cấp quyền đối với giản đồ và bảng PostgreSQL

Theo mặc định, người dùng cơ sở dữ liệu IAM mới tạo không có đặc quyền đối với bảng. Kết nối với phiên bản AlloyDB của bạn với tư cách là người dùng quản trị postgres (thông qua psql hoặc AlloyDB Studio trong Cloud Console) và cấp quyền truy cập vào cơ sở dữ liệu và bảng mục tiêu (chẳng hạn như cơ sở dữ liệu mẫu DVD Rental):

-- Connect to your target database first
\c dvdrental

-- (Optional) Create a sample film table if your database is empty
CREATE TABLE IF NOT EXISTS public.film (
    film_id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    release_year INTEGER DEFAULT 2006,
    rating VARCHAR(10) DEFAULT 'PG',
    rental_rate NUMERIC(4,2) DEFAULT 2.99
);

INSERT INTO public.film (film_id, title, release_year, rating, rental_rate) VALUES
    (1, 'Academy Dinosaur', 2006, 'PG', 0.99),
    (2, 'Ace Goldfinger', 2006, 'G', 4.99),
    (3, 'Adaptation Holes', 2006, 'NC-17', 2.99),
    (4, 'Affair Prejudice', 2006, 'G', 2.99),
    (5, 'African Egg', 2006, 'G', 2.99)
ON CONFLICT (film_id) DO NOTHING;

-- Grant permissions to the IAM user (double quotes are required because of '@' and '.')
GRANT CONNECT ON DATABASE "dvdrental" TO "java-alloydb-connector@<PROJECT_ID>.iam";
GRANT USAGE ON SCHEMA public TO "java-alloydb-connector@<PROJECT_ID>.iam";
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "java-alloydb-connector@<PROJECT_ID>.iam";

Khi chạy các câu lệnh này trong AlloyDB Studio (hoặc psql), bạn có thể kiểm tra giản đồ public.film và xác minh các hàng mẫu:

Cấp quyền IAM và kiểm tra public.film trong AlloyDB Studio

Định cấu hình Thông tin xác thực mặc định của ứng dụng (ADC) cục bộ

Khi chạy trên Cloud Run, Google Kubernetes Engine (GKE) hoặc Compute Engine, hãy đính kèm Tài khoản dịch vụ java-alloydb-connector trực tiếp vào khối lượng công việc. Khi chạy cục bộ trên máy trạm, hãy mạo danh Tài khoản dịch vụ để ADC tạo mã thông báo cho danh tính đó:

gcloud auth application-default login \
    --impersonate-service-account="java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com"

3. Kết nối bằng JDBC thuần tuý và HikariCP

Đối với mọi ứng dụng Java cấp sản xuất, nhóm kết nối là yếu tố cần thiết và HikariCP là tiêu chuẩn ngành. Trong bước này, bạn sẽ xây dựng một ứng dụng JDBC + HikariCP đơn giản, uỷ quyền việc tạo ổ cắm cho com.google.cloud.alloydb.SocketFactory.

Tạo dự án Maven (`pom.xml`)

Tạo một thư mục mới jdbc-app có tệp pom.xml chứa trình điều khiển JDBC của PostgreSQL (42.7.14), Trình kết nối Java của AlloyDB (1.4.0) và HikariCP (7.1.0):

mkdir -p jdbc-app/src/main/java
cd jdbc-app

Tạo pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example.alloydb</groupId>
    <artifactId>alloydb-jdbc-sample</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <exec.mainClass>AlloyDBConnectivity</exec.mainClass>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.7.14</version>
        </dependency>

        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>alloydb-jdbc-connector</artifactId>
            <version>1.4.0</version>
        </dependency>

        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>7.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.16</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <cleanupDaemonThreads>false</cleanupDaemonThreads>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Tạo `AlloyDBConnectivity.java`

Tạo src/main/java/AlloyDBConnectivity.java (xem trên GitHub Gist):

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

public class AlloyDBConnectivity {
    // Retrieve configuration from environment variables
    private static final String ALLOYDB_INSTANCE_URI = System.getenv("ALLOYDB_INSTANCE_NAME"); // e.g., projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>
    private static final String ALLOYDB_DB_NAME = System.getenv("ALLOYDB_DB"); // e.g., "dvdrental"
    private static final String ALLOYDB_USER = System.getenv("ALLOYDB_USER"); // e.g., "java-alloydb-connector@<PROJECT_ID>.iam"
    private static final String ALLOYDB_PASS = System.getenv("ALLOYDB_PASS"); // Database password if not using IAM auth

    public static HikariDataSource createDataSource() {
        HikariConfig config = new HikariConfig();

        // The JDBC URL does not need a host or port. The SocketFactory will resolve the IP address.
        config.setJdbcUrl(String.format("jdbc:postgresql:///%s", ALLOYDB_DB_NAME));
        config.setUsername(ALLOYDB_USER);

        // Only set the password if you are NOT using IAM authentication.
        if (System.getenv("ALLOYDB_ENABLE_IAM_AUTH") == null || !System.getenv("ALLOYDB_ENABLE_IAM_AUTH").equalsIgnoreCase("true")) {
            config.setPassword(ALLOYDB_PASS);
        }

        // 1. Set the SocketFactory to the AlloyDB Connector's implementation.
        config.addDataSourceProperty("socketFactory", "com.google.cloud.alloydb.SocketFactory");

        // 2. Tell the connector which AlloyDB instance to connect to.
        config.addDataSourceProperty("alloydbInstanceName", ALLOYDB_INSTANCE_URI);

        // 3. (Recommended) Enable IAM database authentication.
        if (System.getenv("ALLOYDB_ENABLE_IAM_AUTH") != null && System.getenv("ALLOYDB_ENABLE_IAM_AUTH").equalsIgnoreCase("true")) {
            config.addDataSourceProperty("alloydbEnableIAMAuth", "true");
        }

        // 4. (Optional) Specify IP type (e.g., "PRIVATE", "PUBLIC", "PSC"). Defaults to PRIVATE.
        String ipType = System.getenv("ALLOYDB_IP_TYPE");
        if (ipType != null) {
            config.addDataSourceProperty("alloydbIpType", ipType);
        }

        // Baseline HikariCP settings
        config.setMaximumPoolSize(10);
        config.setMinimumIdle(2);
        config.setConnectionTimeout(30000); // 30 seconds
        config.setIdleTimeout(600000);      // 10 minutes
        config.setMaxLifetime(1800000);     // 30 minutes

        return new HikariDataSource(config);
    }

    public static void main(String[] args) {
        String sql = "SELECT title, release_year FROM public.film ORDER BY film_id LIMIT 5";

        try (HikariDataSource pool = createDataSource();
             Connection conn = pool.getConnection();
             PreparedStatement stmt = conn.prepareStatement(sql);
             ResultSet rs = stmt.executeQuery()) {
            System.out.println("Successfully connected to AlloyDB via IAM! Sample films:");
            while (rs.next()) {
                System.out.printf(" - %s (%d)%n", rs.getString("title"), rs.getInt("release_year"));
            }
        } catch (SQLException e) {
            System.err.println("Database connection failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Cấu trúc của URL JDBC AlloyDB và cấu hình HikariCP

Chạy ứng dụng JDBC thuần tuý

Xuất các biến môi trường cho phiên bản AlloyDB (đặt ALLOYDB_IP_TYPE="PUBLIC" nếu kết nối từ bên ngoài VPC qua IP công khai hoặc "PRIVATE"/"PSC" khi ở trong VPC) rồi chạy ứng dụng:

export ALLOYDB_INSTANCE_NAME="projects/${PROJECT_ID}/locations/${REGION}/clusters/${CLUSTER_ID}/instances/${INSTANCE_ID}"
export ALLOYDB_DB="${DB_NAME}"
export ALLOYDB_USER="java-alloydb-connector@${PROJECT_ID}.iam"
export ALLOYDB_ENABLE_IAM_AUTH="true"
export ALLOYDB_IP_TYPE="PRIVATE" # Set to PUBLIC if connecting over Public IP from a local laptop

mvn compile exec:java

Bạn sẽ thấy kết quả tương tự như sau:

[AlloyDBConnectivity.main()] INFO com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
[AlloyDBConnectivity.main()] INFO com.zaxxer.hikari.pool.HikariPool - HikariPool-1 - Added connection org.postgresql.jdbc.PgConnection@1998bf07
[AlloyDBConnectivity.main()] INFO com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
Successfully connected to AlloyDB via IAM! Sample films:
 - Academy Dinosaur (2006)
 - Ace Goldfinger (2006)
 - Adaptation Holes (2006)
 - Affair Prejudice (2006)
 - African Egg (2006)

Kết quả đầu ra của thiết bị đầu cuối của mẫu JDBC thuần tuý và HikariCP

4. Kết nối với Spring Boot

Spring Boot đơn giản hoá việc kết nối cơ sở dữ liệu bằng cách tự động định cấu hình nhóm kết nối HikariCP từ các thuộc tính ứng dụng của bạn. Bạn không cần viết mã bean DataSource tuỳ chỉnh để tích hợp Trình kết nối Java của AlloyDB.

Tạo dự án Spring Boot (`pom.xml`)

Tạo một thư mục mới spring-boot-app:

cd ..
mkdir -p spring-boot-app/src/main/java/com/example/alloydb
mkdir -p spring-boot-app/src/main/resources
cd spring-boot-app

Tạo pom.xml bằng spring-boot-starter-jdbc (bao gồm HikariCP), org.postgresql:postgresql và com.google.cloud:alloydb-jdbc-connector:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.0.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example.alloydb</groupId>
    <artifactId>alloydb-spring-boot-sample</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.7.14</version>
        </dependency>

        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>alloydb-jdbc-connector</artifactId>
            <version>1.4.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Định cấu hình `application.properties` hoặc Biến môi trường

Bạn có thể định cấu hình URL kết nối trong src/main/resources/application.properties:

# No host or port is needed; the SocketFactory handles it.
spring.datasource.url=jdbc:postgresql:///dvdrental?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>&alloydbEnableIAMAuth=true
spring.datasource.username=java-alloydb-connector@<PROJECT_ID>.iam
# No password required when alloydbEnableIAMAuth is true

Để giữ cho các tệp nguồn hoàn toàn không có mã dự án hoặc tên thực thể, bạn có thể để trống application.properties và cung cấp các biến môi trường Spring Boot tiêu chuẩn này trong thời gian chạy:

Biến môi trường	Giá trị
`SPRING_DATASOURCE_URL`	`jdbc:postgresql:///dvdrental?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects//locations//clusters//instances/&alloydbEnableIAMAuth=true`
`SPRING_DATASOURCE_USERNAME`	`java-alloydb-connector@.iam`

Tạo `AlloyDbTestApplication.java`

Tạo src/main/java/com/example/alloydb/AlloyDbTestApplication.java (xem trên GitHub Gist):

package com.example.alloydb;

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.jdbc.core.JdbcTemplate;

@SpringBootApplication
public class AlloyDbTestApplication {

    public static void main(String[] args) {
        System.exit(SpringApplication.exit(SpringApplication.run(AlloyDbTestApplication.class, args)));
    }

    @Bean
    CommandLineRunner testConnection(JdbcTemplate jdbcTemplate) {
        return args -> {
            String result = jdbcTemplate.queryForObject("SELECT 'Connection Successful!'", String.class);
            System.out.println(">>> ALLOYDB STATUS: " + result);
        };
    }
}

Chạy ứng dụng Spring Boot

Xuất các biến môi trường và chạy ứng dụng bằng mvn spring-boot:run:

export SPRING_DATASOURCE_URL="jdbc:postgresql:///${DB_NAME}?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects/${PROJECT_ID}/locations/${REGION}/clusters/${CLUSTER_ID}/instances/${INSTANCE_ID}&alloydbEnableIAMAuth=true"
export SPRING_DATASOURCE_USERNAME="java-alloydb-connector@${PROJECT_ID}.iam"

mvn spring-boot:run

Bạn sẽ thấy:

>>> ALLOYDB STATUS: Connection Successful!

Tự động định cấu hình Spring Boot và kết quả thực thi trực tiếp

5. Kết nối với Quarkus, Micronaut và GraalVM Native Image

Vì Trình kết nối Java của AlloyDB hoạt động ở cấp trình điều khiển JDBC, nên việc chuyển đổi giữa các khung Java gốc trên đám mây không làm thay đổi cách bạn bảo mật lưu lượng truy cập cơ sở dữ liệu hoặc quản lý danh tính. Cả Quarkus và Micronaut đều gói trình điều khiển JDBC cơ bản và uỷ quyền mã hoá mTLS, phân giải IP động và xác thực IAM cho trình kết nối thông qua ADC.

Khung Java gốc trên đám mây và Hình ảnh gốc GraalVM với AlloyDB

Cấu hình Quarkus (`application.properties` với Agroal)

Trong ứng dụng Quarkus (quarkus-agroal và quarkus-jdbc-postgresql), hãy thêm com.google.cloud:alloydb-jdbc-connector:1.4.0 vào các phần phụ thuộc và truyền tham số trình kết nối qua quarkus.datasource.jdbc.additional-jdbc-properties trong src/main/resources/application.properties:

quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=java-alloydb-connector@<PROJECT_ID>.iam
quarkus.datasource.jdbc.url=jdbc:postgresql:///dvdrental
quarkus.datasource.jdbc.additional-jdbc-properties.socketFactory=com.google.cloud.alloydb.SocketFactory
quarkus.datasource.jdbc.additional-jdbc-properties.alloydbInstanceName=projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>
quarkus.datasource.jdbc.additional-jdbc-properties.alloydbEnableIAMAuth=true

Cấu hình Micronaut (`application.yml` với HikariCP)

Trong ứng dụng Micronaut (micronaut-jdbc-hikari), hãy thêm com.google.cloud:alloydb-jdbc-connector:1.4.0 và định cấu hình src/main/resources/application.yml:

datasources:
  default:
    url: jdbc:postgresql:///dvdrental?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>&alloydbEnableIAMAuth=true
    username: java-alloydb-connector@<PROJECT_ID>.iam
    driver-class-name: org.postgresql.Driver

Đăng ký Trình kết nối cho GraalVM Native Image

Khi biên dịch ứng dụng thành GraalVM Native Image (bằng Spring Boot 3+, Quarkus hoặc Micronaut), có một chi tiết quan trọng: Reflection.

Trình điều khiển JDBC của PostgreSQL tạo thực thể com.google.cloud.alloydb.SocketFactory một cách linh động theo tên lớp bằng cách sử dụng phản chiếu. Để ngăn quá trình phân tích tĩnh của GraalVM loại bỏ lớp trong quá trình biên dịch gốc, hãy đăng ký lớp đó một cách rõ ràng:

Spring Boot 3 trở lên: Thêm @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class) vào ứng dụng chính hoặc lớp @Configuration:
```
@SpringBootApplication
@RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class)
public class AlloyDbTestApplication { ... }
```

Quarkus: Thêm @RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class) vào lớp chính hoặc bean CDI:

@QuarkusMain
@RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class)
public class QuarkusAlloyDbApp implements QuarkusApplication { ... }

6. Khắc phục sự cố thường gặp về IAM và khả năng kết nối

Nếu bạn gặp lỗi FATAL: password authentication failed for user hoặc AlloyDB IAM authentication failed, hãy xác minh 4 khía cạnh sau:

Bản tóm tắt về cách khắc phục sự cố kết nối và IAM của AlloyDB

1. Xoá `.gserviceaccount.com` khỏi Tên người dùng cơ sở dữ liệu của tài khoản dịch vụ

Nguyên nhân phổ biến nhất gây ra lỗi xác thực IAM là việc truyền địa chỉ email đầy đủ của Tài khoản dịch vụ dưới dạng tên người dùng cơ sở dữ liệu. AlloyDB định dạng tên người dùng cơ sở dữ liệu IAM theo cách khác nhau tuỳ thuộc vào loại tài khoản chính:

Đối với Tài khoản dịch vụ IAM (loại bỏ .gserviceaccount.com): Nếu email Tài khoản dịch vụ Google Cloud của bạn là java-alloydb-connector@.iam.gserviceaccount.com, thì bạn phải xoá hậu tố .gserviceaccount.com và đặt tên người dùng cơ sở dữ liệu JDBC/AlloyDB thành java-alloydb-connector@.iam.
Đối với Tài khoản người dùng hoặc Nhóm IAM (giữ nguyên địa chỉ email đầy đủ): Nếu bạn đang xác thực với tư cách là người dùng Google Workspace hoặc Cloud Identity, hãy sử dụng địa chỉ email đầy đủ của bạn mà không sửa đổi (ví dụ: ).

2. Xác minh cách tạo người dùng cơ sở dữ liệu

Bạn đã đăng ký người dùng qua gcloud alloydb users create --type=IAM_BASED (hoặc Console/Terraform) chưa? Việc tạo người dùng bằng SQL thô CREATE USER sẽ không hoạt động cho phương thức xác thực IAM vì AlloyDB hạn chế GRANT alloydbiamuser đối với mặt phẳng điều khiển.

3. Xác minh danh tính ADC đang hoạt động của bạn

Đảm bảo rằng môi trường nơi quy trình Java đang chạy thực sự được xác thực là tài khoản chính IAM mục tiêu:

Máy trạm cục bộ (kết nối dưới dạng Tài khoản dịch vụ): Chạy gcloud auth application-default login --impersonate-service-account=java-alloydb-connector@.iam.gserviceaccount.com để ADC tạo mã thông báo cho Tài khoản dịch vụ thay vì email cá nhân của bạn.
Cloud Run/GKE: Xác nhận rằng Tài khoản dịch vụ được đính kèm vào khối lượng công việc và có cả roles/alloydb.client và roles/serviceusage.serviceUsageConsumer.

4. Xem xét việc truyền IAM và định tuyến mạng

Độ trễ khi áp dụng IAM: Các liên kết chính sách IAM có thể mất từ 60 đến 120 giây để áp dụng. Nếu bạn vừa tạo Tài khoản dịch vụ hoặc mối liên kết vai trò, hãy đợi một phút rồi thử lại.
Truy cập mạng VPC: Theo mặc định, Trình kết nối Java của AlloyDB sẽ kết nối với IP PRIVATE của thực thể. Nếu ứng dụng của bạn chạy trên Cloud Run, hãy định cấu hình Direct VPC Egress (nên dùng để giảm độ trễ và chi phí so với Trình kết nối Serverless VPC Access cũ) hoặc kết nối qua Private Service Connect (PSC). Nếu kết nối từ một máy cục bộ bên ngoài VPC, hãy bật IP công khai trên thực thể và truyền alloydbIpType=PUBLIC.

7. Dọn dẹp

Để tránh phát sinh các khoản phí không cần thiết cho tài khoản Google Cloud và xoá các danh tính IAM được tạo trong lớp học lập trình này, hãy dọn dẹp các tài nguyên bên dưới.

1. Xoá Tài khoản dịch vụ và Người dùng cơ sở dữ liệu IAM của AlloyDB

Xoá người dùng cơ sở dữ liệu IAM khỏi cụm AlloyDB và xoá Tài khoản dịch vụ:

# Delete the IAM database user from AlloyDB
gcloud alloydb users delete "java-alloydb-connector@${PROJECT_ID}.iam" \
    --cluster="${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --quiet

# Remove IAM policy bindings
gcloud projects remove-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/alloydb.client"

gcloud projects remove-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/serviceusage.serviceUsageConsumer"

# Delete the Service Account
gcloud iam service-accounts delete \
    "java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --project="${PROJECT_ID}" \
    --quiet

2. Đặt lại thông tin xác thực mặc định của ứng dụng cục bộ

Nếu bạn đã định cấu hình tính năng mạo danh ADC cục bộ, hãy đặt lại thông tin xác thực cục bộ về danh tính người dùng mặc định:

gcloud auth application-default login

3. (Không bắt buộc) Xoá cụm AlloyDB

gcloud alloydb clusters delete "${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --force \
    --quiet

8. Xin chúc mừng

Bạn đã hoàn tất lớp học lập trình và thiết lập kết nối an toàn, không cần mật khẩu từ Java đến AlloyDB cho PostgreSQL!

Thành tích bạn đã đạt được

Đã định cấu hình tính năng Xác thực cơ sở dữ liệu IAM: Tạo một Tài khoản dịch vụ có đặc quyền tối thiểu, bật alloydb.iam_authentication=on, đăng ký người dùng IAM trên cụm AlloyDB và cấp đặc quyền cho bảng PostgreSQL.
Kết nối bằng JDBC thuần tuý và HikariCP: Định cấu hình HikariConfig bằng com.google.cloud.alloydb.SocketFactory để tự động mã hoá mTLS 1.3, làm mới mã thông báo IAM và phân giải IP động.
Khung gốc đám mây tích hợp: Đã định cấu hình Spring Boot, Quarkus (Agroal) và Micronaut (HikariCP) mà không cần mã nguyên mẫu nhóm kết nối tuỳ chỉnh, cùng với gợi ý phản ánh cho GraalVM Native Image.
Nắm vững cách khắc phục sự cố IAM: Tìm hiểu cách chẩn đoán định dạng tên người dùng, mạo danh ADC và các vấn đề về định tuyến VPC.