Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

IAM kimlik doğrulaması ile Java uygulamalarını PostgreSQL için AlloyDB'ye bağlama

1. Başlamadan önce

Java ve AlloyDB: Basit, Güvenli Bağlantı

AlloyDB for PostgreSQL, Google Cloud'un zorlu kurumsal iş yükleri için tasarlanmış, tümüyle yönetilen ve PostgreSQL ile uyumlu veritabanı hizmetidir. Java uygulamasını AlloyDB'ye güvenli ve verimli bir şekilde bağlamak için standart bir JDBC sürücüsünden daha fazlasını sunan bir istemci kitaplığı olan AlloyDB Java Connector (alloydb-jdbc-connector) kullanılır.

AlloyDB Java Connector'ın Sihri

alloydb-jdbc-connector, standart PostgreSQL JDBC sürücüsü (org.postgresql:postgresql) için akıllı bir SocketFactory işlevi görür. Güvenli bir veritabanı bağlantısı oluşturma işlemini soyutlar. Böylece ağ güvenliği veya kimlik doğrulama bilgileri değişim döngüsü yerine uygulama mantığına odaklanabilirsiniz:

mTLS 1.3 Şifreleme: SSL/TLS istemci sertifikalarını manuel olarak yönetmenize gerek kalmadan JVM'niz ile AlloyDB örneği arasında karşılıklı olarak kimliği doğrulanmış bir TLS 1.3 bağlantısı otomatik olarak oluşturur.
IAM Tabanlı Yetkilendirme: Bağlayıcı, statik veritabanı şifreleri kullanmak yerine Google Cloud IAM ve Uygulama Varsayılan Kimlik Bilgileri'nden (ADC) yararlanarak kısa süreli OAuth2 erişim jetonlarını otomatik olarak alır.
Dinamik IP Çözümleme: Veritabanı örneğinizin mevcut IP adresini (PRIVATE, PUBLIC veya Private Service Connect PSC) dinamik olarak çözümlemek için AlloyDB Admin API'yi sorgular. Ana makine adlarını veya IP adreslerini sabit kodlamanız gerekmez. Bu sayede yük devretme ve bakım işlemleri şeffaf bir şekilde gerçekleştirilir.

AlloyDB Java Connector'ın İşleyiş Şekli

Ön koşullar

Java, Maven ve temel SQL/JDBC kavramları hakkında bilgi sahibi olma
Google Cloud CLI (gcloud) ve IAM rolleri hakkında temel düzeyde bilgi sahibi olmak

Yapacaklarınız

Şifresiz IAM Veritabanı Kimlik Doğrulaması için bir AlloyDB örneği ve hizmet hesabı yapılandırma
Bir IAM sorumlusuna en az ayrıcalık ilkesine uygun PostgreSQL şeması ve tablo izinleri verme
AlloyDB SocketFactory kullanarak Plain JDBC ve HikariCP ile üretime hazır bir DataSource yapılandırın.
AlloyDB Java bağlayıcısını Spring Boot, Quarkus ve Micronaut uygulamalarına entegre etme
GraalVM Native Image derlemesi için AlloyDB SocketFactory'yi kaydetme ve yaygın IAM kimlik doğrulama sorunlarını giderme

İhtiyacınız olanlar

Faturalandırmanın etkin olduğu bir Google Cloud projesi ve etkin bir AlloyDB kümesi ile birincil örneği (AlloyDB kümesi oluşturma kılavuzuna bakın veya iki saniyeden kısa sürede bir AlloyDB Express kümesi oluşturun).
Projenizdeki roles/alloydb.admin ve roles/resourcemanager.projectIamAdmin IAM rolleri.
Java 17 veya sonraki sürümler (Java 17 veya 21 LTS önerilir) ve Apache Maven yüklü olmalıdır.
gcloud CLI ve psql istemcisi yüklü (veya Google Cloud Shell'e erişim).

2. AlloyDB'de IAM veritabanı kimlik doğrulamasını ayarlama

Java kodu yazmadan önce AlloyDB örneğinizi IAM jetonlarını kabul edecek şekilde yapılandırmanız ve uygulamanızın üç katmanda (Google Cloud IAM, AlloyDB kontrol düzlemi ve PostgreSQL motoru) kullanacağı IAM kimliğini oluşturmanız gerekir.

AlloyDB IAM Veritabanı Kimlik Doğrulaması İçin Üç Katmanlı Kurulum

Ortam değişkenlerini ayarlama

Terminalinizde, Google Cloud projenize ve AlloyDB örneğinize karşılık gelen değişkenleri dışa aktarın ( yer tutucularını kendi değerlerinizle değiştirin):

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

Gerekli API'leri etkinleştirme

Projenizde AlloyDB, Compute Engine, Cloud Resource Manager, IAM ve Service Usage API'lerini etkinleştirin:

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

Hizmet hesabı oluşturma ve IAM rolleri verme

Java uygulamanızın kimliği olarak kullanılacak özel bir hizmet hesabı oluşturun:

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

Hizmet hesabına AlloyDB Java Connector için gereken iki IAM rolünü verin:

roles/alloydb.client: Örnek meta verilerini almak ve AlloyDB Admin API'den geçici mTLS sertifikaları istemek için gereklidir.
roles/serviceusage.serviceUsageConsumer: IAM veritabanı kimlik doğrulaması için gereklidir.

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"

AlloyDB örneğinde IAM kimlik doğrulamasını etkinleştirme

alloydb.iam_authentication=on değerini ayarlamak için AlloyDB örneği işaretlerinizi güncelleyin. Bu dinamik bir işarettir ve örneği yeniden başlatmadan hemen geçerli olur:

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

IAM veritabanı kullanıcısını kaydetme

gcloud kullanarak hizmet hesabını AlloyDB kümenizde IAM_BASED veritabanı kullanıcısı olarak kaydedin:

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

PostgreSQL şeması ve tablo izinleri verme

Yeni oluşturulan IAM veritabanı kullanıcılarının varsayılan olarak tablo ayrıcalıkları yoktur. AlloyDB örneğinize postgres yönetici kullanıcısı olarak bağlanın (Cloud Console'da psql veya AlloyDB Studio aracılığıyla) ve hedef veritabanınıza ve tablolarınıza (ör. DVD Rental örnek veritabanı) erişim izni verin:

-- 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";

Bu ifadeleri AlloyDB Studio'da (veya psql) çalıştırırken public.film şemasını inceleyebilir ve örnek satırları doğrulayabilirsiniz:

AlloyDB Studio'da IAM İzinleri Verme ve public.film'i İnceleme

Yerel Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yapılandırma

Cloud Run, Google Kubernetes Engine (GKE) veya Compute Engine'de çalışırken java-alloydb-connector hizmet hesabını doğrudan iş yüküne ekleyin. İş istasyonunuzda yerel olarak çalışırken ADC'nin bu kimlik için jeton oluşturması amacıyla hizmet hesabının kimliğine bürünün:

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

3. Düz JDBC ve HikariCP ile bağlanma

Üretim düzeyindeki tüm Java uygulamaları için bağlantı havuzu gereklidir ve HikariCP endüstri standardıdır. Bu adımda, soket oluşturma işlemini com.google.cloud.alloydb.SocketFactory'e devreden basit bir JDBC + HikariCP uygulaması oluşturacaksınız.

Maven projesini oluşturma (`pom.xml`)

PostgreSQL JDBC sürücüsünü (42.7.14), AlloyDB Java Connector'ı (1.4.0) ve HikariCP'yi (7.1.0) içeren bir pom.xml dosyasıyla yeni bir jdbc-app dizini oluşturun:

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

pom.xml oluşturun:

<?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>

`AlloyDBConnectivity.java` oluştur

src/main/java/AlloyDBConnectivity.java oluşturun (GitHub Gist'te görüntüleyin):

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();
        }
    }
}

AlloyDB JDBC URL'sinin Anatomisi ve HikariCP Yapılandırması

Düz JDBC uygulamasını çalıştırma

AlloyDB örneğinizin ortam değişkenlerini dışa aktarın (VPC'nizin dışından herkese açık IP üzerinden bağlanıyorsanız ALLOYDB_IP_TYPE="PUBLIC", VPC'nin içinden bağlanıyorsanız "PRIVATE" / "PSC" değerini ayarlayın) ve uygulamayı çalıştırın:

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

Şuna benzer bir çıkış alırsınız:

[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)

Düz JDBC ve HikariCP Örneğinin Terminal Çıkışı

4. Spring Boot ile bağlanma

Spring Boot, uygulama özelliklerinizden bir HikariCP bağlantı havuzunu otomatik olarak yapılandırarak veritabanı bağlantısını basitleştirir. AlloyDB Java Connector'ı entegre etmek için özel DataSource bean kodu gerekmez.

Spring Boot projesini oluşturma (`pom.xml`)

Yeni bir dizin (spring-boot-app) oluşturun:

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

spring-boot-starter-jdbc (HikariCP dahil), org.postgresql:postgresql ve com.google.cloud:alloydb-jdbc-connector ile pom.xml oluşturun:

<?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>

`application.properties` veya Ortam Değişkenlerini Yapılandırma

Bağlantı URL'sini src/main/resources/application.properties üzerinden yapılandırabilirsiniz:

# 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

Kaynak dosyalarınızda proje kimlikleri veya örnek adları bulunmasını istemiyorsanız application.properties dosyasını boş bırakabilir ve çalışma zamanında şu standart Spring Boot ortam değişkenlerini sağlayabilirsiniz:

Ortam Değişkeni	Değer
`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`

`AlloyDbTestApplication.java` oluştur

src/main/java/com/example/alloydb/AlloyDbTestApplication.java oluşturun (GitHub Gist'te görüntüleyin):

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);
        };
    }
}

Spring Boot uygulamasını çalıştırma

Ortam değişkenlerini dışa aktarın ve uygulamayı mvn spring-boot:run ile çalıştırın:

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

Aşağıdaki bilgileri görürsünüz:

>>> ALLOYDB STATUS: Connection Successful!

Spring Boot Otomatik Yapılandırma ve Canlı Yürütme Çıkışı

5. Quarkus, Micronaut ve GraalVM Native Image ile bağlantı kurma

AlloyDB Java Connector, JDBC sürücüsü düzeyinde çalıştığından bulutta yerel Java çerçeveleri arasında geçiş yapmak, veritabanı trafiğini güvence altına alma veya kimlikleri yönetme şeklinizi değiştirmez. Hem Quarkus hem de Micronaut, temel JDBC sürücüsünü sarmalar ve mTLS şifrelemesini, dinamik IP çözümlemesini ve IAM kimlik doğrulamasını ADC aracılığıyla bağlayıcıya devreder.

AlloyDB ile Bulutta Yerel Java Çerçeveleri ve GraalVM Yerel Görüntüsü

Quarkus Yapılandırması (Agroal ile `application.properties`)

Bir Quarkus uygulamasında (quarkus-agroal ve quarkus-jdbc-postgresql), bağımlılıklarınıza com.google.cloud:alloydb-jdbc-connector:1.4.0 ekleyin ve bağlayıcı parametrelerini src/main/resources/application.properties içinde quarkus.datasource.jdbc.additional-jdbc-properties aracılığıyla iletin:

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

Micronaut Yapılandırması (HikariCP ile `application.yml`)

Bir Micronaut uygulamasında (micronaut-jdbc-hikari) com.google.cloud:alloydb-jdbc-connector:1.4.0 ekleyin ve src/main/resources/application.yml yapılandırın:

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

GraalVM Native Image için bağlayıcıyı kaydetme

Uygulamanızı GraalVM yerel görüntüsü olarak derlerken (Spring Boot 3+, Quarkus veya Micronaut ile) önemli bir ayrıntı vardır: Yansıma.

PostgreSQL JDBC sürücüsü, yansıma kullanarak sınıf adına göre com.google.cloud.alloydb.SocketFactory örneğini dinamik olarak oluşturur. GraalVM'nin statik analizinin yerel derleme sırasında sınıfı kaldırmasını önlemek için sınıfı açıkça kaydedin:

Spring Boot 3 ve sonraki sürümler: Ana uygulamanıza veya @Configuration sınıfınıza @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class) ekleyin:
```
@SpringBootApplication
@RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class)
public class AlloyDbTestApplication { ... }
```

Quarkus: Ana sınıfınıza veya bir CDI bean'e @RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class) ekleyin:

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

6. Sık Karşılaşılan IAM ve Bağlantı Sorunlarını Giderme

FATAL: password authentication failed for user veya AlloyDB IAM authentication failed hatasıyla karşılaşırsanız aşağıdaki dört alanı doğrulayın:

AlloyDB IAM ve Bağlantı Sorunlarını Giderme ile İlgili Özet Bilgiler

1. `.gserviceaccount.com` adlı kullanıcıyı Hizmet Hesabı Veritabanı Kullanıcı Adları'ndan kaldırın

IAM kimlik doğrulama hatalarının en yaygın nedeni, veritabanı kullanıcı adı olarak tam hizmet hesabı e-posta adresinin iletilmesidir. AlloyDB, IAM veritabanı kullanıcı adlarını, sorumlu türüne göre farklı şekilde biçimlendirir:

IAM hizmet hesapları için (.gserviceaccount.com kaldırın): Google Cloud hizmet hesabı e-postanız java-alloydb-connector@.iam.gserviceaccount.com ise .gserviceaccount.com son ekini kaldırmanız ve JDBC/AlloyDB veritabanı kullanıcı adınızı java-alloydb-connector@.iam olarak ayarlamanız gerekir.
IAM kullanıcı hesapları veya grupları için (tam e-posta adresini kullanın): Kimliğinizi gerçek bir Google Workspace veya Cloud Identity kullanıcısı olarak doğruluyorsanız tam e-posta adresinizi değiştirmeden kullanın (ör. ).

2. Veritabanı kullanıcısının nasıl oluşturulduğunu doğrulama

Kullanıcıyı gcloud alloydb users create --type=IAM_BASED (veya Console/Terraform) üzerinden kaydettiniz mi? AlloyDB, GRANT alloydbiamuser rolünü kontrol düzlemiyle kısıtladığından ham SQL CREATE USER ile kullanıcı oluşturmak IAM kimlik doğrulaması için işe yaramaz.

3. Etkin ADC kimliğinizi doğrulama

Java işleminin çalıştığı ortamın, hedef IAM sorumlusu olarak kimlik doğrulamasından geçtiğinden emin olun:

Yerel iş istasyonu (hizmet hesabı olarak bağlanma): ADC'nin kişisel e-postanız yerine hizmet hesabı için jeton oluşturması amacıyla gcloud auth application-default login --impersonate-service-account=java-alloydb-connector@.iam.gserviceaccount.com komutunu çalıştırın.
Cloud Run/GKE: Hizmet hesabının iş yüküne bağlı olduğunu ve hem roles/alloydb.client hem de roles/serviceusage.serviceUsageConsumer rollerine sahip olduğunu doğrulayın.

4. IAM yayılımı ve ağ yönlendirmesini hesaba katma

IAM yayılma gecikmesi: IAM politika bağlamalarının yayılması 60-120 saniye sürebilir. Hizmet hesabını veya rol bağlamayı yeni oluşturduysanız bir dakika bekleyip tekrar deneyin.
VPC ağı erişimi: AlloyDB Java Bağlayıcısı, varsayılan olarak örneğin PRIVATE IP'sine bağlanır. Uygulamanız Cloud Run'da çalışıyorsa Doğrudan VPC Çıkışı'nı yapılandırın (eski sunucusuz VPC erişim bağlayıcılarına kıyasla daha düşük gecikme süresi ve maliyet için önerilir) veya Private Service Connect (PSC) üzerinden bağlanın. VPC dışındaki yerel bir makineden bağlanıyorsanız örnekte genel IP'yi etkinleştirin ve alloydbIpType=PUBLIC değerini iletin.

7. Temizleme

Google Cloud hesabınızda gereksiz ücretlendirmelerden kaçınmak ve bu codelab sırasında oluşturulan IAM kimliklerini kaldırmak için aşağıdaki kaynakları temizleyin.

1. AlloyDB IAM veritabanı kullanıcısını ve hizmet hesabını kaldırma

IAM veritabanı kullanıcısını AlloyDB kümenizden silin ve hizmet hesabını kaldırın:

# 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. Yerel Uygulama Varsayılan Kimlik Bilgilerini Sıfırlama

Yerel ADC kimliğine bürünme özelliğini yapılandırdıysanız yerel kimlik bilgilerinizi varsayılan kullanıcı kimliğinize sıfırlayın:

gcloud auth application-default login

3. (İsteğe bağlı) AlloyDB kümesini silme

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

8. Tebrikler

Codelab'i tamamladınız ve Java'dan PostgreSQL için AlloyDB'ye güvenli, şifresiz bağlantı kurdunuz.

Başarılarınız

IAM Veritabanı Kimlik Doğrulaması'nı yapılandırdınız: En az ayrıcalık ilkesine uygun bir hizmet hesabı oluşturdunuz, alloydb.iam_authentication=on özelliğini etkinleştirdiniz, IAM kullanıcısını AlloyDB kümesine kaydettiniz ve PostgreSQL tablo ayrıcalıkları verdiniz.
Plain JDBC ve HikariCP ile bağlandı: Otomatik mTLS 1.3 şifrelemesi, IAM jetonu yenileme ve dinamik IP çözümlemesi için HikariConfig, com.google.cloud.alloydb.SocketFactory ile yapılandırıldı.
Entegre bulutta yerel çerçeveler: Spring Boot, Quarkus (Agroal) ve Micronaut (HikariCP) özel bağlantı havuzu standart kodu olmadan yapılandırıldı. Ayrıca GraalVM yerel görüntüsü için yansıma ipuçları da eklendi.
IAM Sorun Giderme Konusunda Uzmanlaşma: Kullanıcı adı biçimlendirme, ADC kimliğine bürünme ve VPC yönlendirme sorunlarını nasıl teşhis edeceğinizi öğrendiniz.