Connecter des applications Java à AlloyDB pour PostgreSQL avec l'authentification IAM

1. Avant de commencer

AlloyDB pour PostgreSQL est le service de base de données entièrement géré de Google Cloud, compatible avec PostgreSQL, pour les charges de travail d'entreprise exigeantes. Pour connecter une application Java à AlloyDB de manière sécurisée et efficace, utilisez le connecteur Java AlloyDB (alloydb-jdbc-connector), une bibliothèque cliente qui va au-delà d'un pilote JDBC standard.

La magie du connecteur Java AlloyDB

Le alloydb-jdbc-connector fonctionne comme un SocketFactory intelligent pour le pilote JDBC PostgreSQL standard (org.postgresql:postgresql). Il élimine la nécessité d'établir une connexion sécurisée à la base de données, ce qui vous permet de vous concentrer sur la logique de l'application plutôt que sur la sécurité réseau ou la rotation des identifiants :

• Chiffrement mTLS 1.3 : établit automatiquement une connexion TLS 1.3 mutuellement authentifiée entre votre JVM et l'instance AlloyDB, sans que vous ayez à gérer manuellement les certificats client SSL/TLS.
• Autorisation basée sur IAM : au lieu de s'appuyer sur des mots de passe de base de données statiques, le connecteur exploite Google Cloud IAM et les identifiants par défaut de l'application (ADC) pour obtenir automatiquement des jetons d'accès OAuth2 de courte durée.
• Résolution d'adresse IP dynamique : interroge l'API AlloyDB Admin pour résoudre dynamiquement l'adresse IP actuelle (PRIVATE, PUBLIC ou Private Service Connect PSC) de votre instance de base de données. Vous n'avez pas besoin de coder en dur les noms d'hôte ni les adresses IP, ce qui rend les basculements et la maintenance transparents.

Remarque sur l'architecture : connecteur Java AlloyDB et proxy d'authentification AlloyDB : pour les applications JVM, le connecteur Java AlloyDB s'exécute en cours de traitement en tant que SocketFactory JDBC, ce qui élimine la surcharge opérationnelle liée au déploiement et à la gestion d'un conteneur side-car distinct. Réservez le binaire du proxy d'authentification AlloyDB autonome pour les outils non-JVM, les anciennes applications pour lesquelles vous ne pouvez pas modifier le classpath JDBC ou les environnements où un proxy externe est obligatoire.

Prérequis

• Connaissance de Java, Maven et des concepts de base de SQL/JDBC.
• Connaissances de base de la Google Cloud CLI (gcloud) et des rôles IAM

Objectifs de l'atelier

• Configurer une instance AlloyDB et un compte de service pour l'authentification IAM pour les bases de données sans mot de passe.
• Attribuez à un compte principal IAM des autorisations sur les schémas et les tables PostgreSQL selon le principe du moindre privilège.
• Configurez un DataSource de niveau production avec Plain JDBC et HikariCP à l'aide de l'SocketFactory AlloyDB.
• Intégrez le connecteur Java AlloyDB dans les applications Spring Boot, Quarkus et Micronaut.
• Enregistrer l'SocketFactory AlloyDB pour la compilation GraalVM Native Image et résoudre les problèmes courants d'authentification IAM.

Prérequis

• Un projet Google Cloud avec la facturation activée, ainsi qu'un cluster et une instance principale AlloyDB actifs (consultez le guide de création de cluster AlloyDB ou lancez un cluster AlloyDB Express en moins de deux secondes).
• Les rôles IAM roles/alloydb.admin et roles/resourcemanager.projectIamAdmin sur votre projet.
• Java 17 ou version ultérieure (Java 17 ou 21 LTS recommandé) et Apache Maven installés.
• La CLI gcloud et le client psql doivent être installés (ou vous devez avoir accès à Google Cloud Shell).

2. Configurer l'authentification IAM pour les bases de données sur AlloyDB

Avant d'écrire du code Java, vous devez configurer votre instance AlloyDB pour qu'elle accepte les jetons IAM et créer l'identité IAM que votre application utilisera sur trois couches : Google Cloud IAM, le plan de contrôle AlloyDB et le moteur PostgreSQL.

Définir des variables d'environnement

Dans votre terminal, exportez les variables correspondant à votre projet Google Cloud et à votre instance AlloyDB (remplacez les espaces réservés par vos valeurs) :

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

Activer les API requises

Activez les API AlloyDB, Compute Engine, Cloud Resource Manager, IAM et API Service Usage dans votre projet :

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

Créer un compte de service et attribuer des rôles IAM

Créez un compte de service dédié qui servira d'identité à votre application Java :

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

Attribuez au compte de service les deux rôles IAM requis par le connecteur Java AlloyDB :

1. roles/alloydb.client : requis pour récupérer les métadonnées d'instance et demander des certificats mTLS éphémères à l'API AlloyDB Admin.
2. roles/serviceusage.serviceUsageConsumer : requis pour l'authentification IAM pour les bases de données.

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"

Activer l'authentification IAM sur l'instance AlloyDB

Mettez à jour les options de votre instance AlloyDB pour définir alloydb.iam_authentication=on. Il s'agit d'un flag dynamique qui prend effet immédiatement sans redémarrer l'instance :

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

Enregistrer l'utilisateur de la base de données IAM

Enregistrez le compte de service en tant qu'utilisateur de base de données IAM_BASED sur votre cluster AlloyDB à l'aide de gcloud :

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

Règles cruciales de dénomination et de plan de contrôle :

1. Supprimer .gserviceaccount.com : pour les comptes de service, le nom d'utilisateur AlloyDB ne doit pas inclure le suffixe .gserviceaccount.com (java-alloydb-connector@.iam).
2. Utilisez gcloud, Terraform ou la console Cloud : n'essayez pas de créer un utilisateur IAM via une instruction SQL CREATE USER ...; GRANT alloydbiamuser TO ...; brute. AlloyDB limite l'attribution du rôle interne alloydbiamuser au plan de contrôle (ERROR: grant or revoke of role "alloydbiamuser" is not allowed).

Accorder des autorisations sur les schémas et les tables PostgreSQL

Par défaut, les utilisateurs de base de données IAM nouvellement créés ne disposent d'aucun droit sur les tables. Connectez-vous à votre instance AlloyDB en tant qu'administrateur postgres (via psql ou AlloyDB Studio dans la console Cloud) et accordez l'accès à votre base de données et à vos tables cibles (comme l'exemple de base de données de location de DVD) :

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

Lorsque vous exécutez ces instructions dans AlloyDB Studio (ou psql), vous pouvez inspecter le schéma public.film et vérifier les exemples de lignes :

Configurer les identifiants par défaut de l'application (ADC) locaux

Lors de l'exécution sur Cloud Run, Google Kubernetes Engine (GKE) ou Compute Engine, associez le compte de service java-alloydb-connector directement à la charge de travail. Lorsque vous exécutez l'application localement sur votre poste de travail, empruntez l'identité du compte de service pour que les ADC génèrent des jetons pour cette identité :

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

Raccourci de développement local : vous pouvez également enregistrer l'adresse e-mail de votre propre utilisateur Google Cloud en tant qu'utilisateur IAM (gcloud alloydb users create --cluster=${CLUSTER_ID} --region=${REGION} --type=IAM_BASED), lui accorder les mêmes autorisations de table SQL et exécuter gcloud auth application-default login sans emprunt d'identité d'un compte de service.

3. Se connecter avec JDBC standard et HikariCP

Pour toute application Java de niveau production, un pool de connexions est essentiel, et HikariCP est la norme du secteur. Dans cette étape, vous allez créer une application JDBC + HikariCP simple qui délègue la création de sockets à com.google.cloud.alloydb.SocketFactory.

Créer le projet Maven (pom.xml)

Créez un répertoire jdbc-app avec un fichier pom.xml contenant le pilote JDBC PostgreSQL (42.7.14), le connecteur Java AlloyDB (1.4.0) et HikariCP (7.1.0) :

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

Créez 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>

Remarque sur les coordonnées Maven : veillez à utiliser com.google.cloud pour alloydb-jdbc-connector dans votre pom.xml. La classe Java SocketFactory se trouve dans le package com.google.cloud.alloydb, mais l'artefact Maven est publié sous le groupId com.google.cloud.

Conseil : Maintenez les versions des dépendances à jour : de nouvelles versions de alloydb-jdbc-connector, du pilote JDBC PostgreSQL (org.postgresql:postgresql), de HikariCP et des BOM de framework (Spring Boot, Quarkus, Micronaut) sont publiées régulièrement avec des améliorations de sécurité et de performances. Pensez à consulter Maven Central ou à exécuter mvn versions:display-dependency-updates pour mettre à jour vos dépendances pom.xml vers les dernières versions.

Créer AlloyDBConnectivity.java

Créez src/main/java/AlloyDBConnectivity.java (afficher sur 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();
        }
    }
}

Concept clé : Pourquoi l'URL JDBC n'a pas d'hôte ni de port : notez que jdbc:postgresql:///%s contient trois barres obliques et aucun nom d'hôte ni port. Lorsque socketFactory=com.google.cloud.alloydb.SocketFactory est défini, le pilote PostgreSQL délègue la création du socket au connecteur AlloyDB, qui recherche l'URI alloydbInstanceName via l'API AlloyDB Admin et se connecte directement à l'adresse IP résolue via mTLS 1.3.

Exécuter l'application JDBC simple

Exportez les variables d'environnement de votre instance AlloyDB (définissez ALLOYDB_IP_TYPE="PUBLIC" si vous vous connectez depuis l'extérieur de votre VPC via une adresse IP publique, ou "PRIVATE" / "PSC" si vous vous trouvez dans le VPC) et exécutez l'application :

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

Un résultat semblable à celui-ci s'affiche :

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

4. Se connecter avec Spring Boot

Spring Boot simplifie la connectivité à la base de données en configurant automatiquement un pool de connexions HikariCP à partir des propriétés de votre application. L'intégration du connecteur Java AlloyDB ne nécessite aucun code de bean DataSource personnalisé.

Créer le projet Spring Boot (pom.xml)

Créez un répertoire 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

Créez pom.xml avec spring-boot-starter-jdbc (qui inclut HikariCP), org.postgresql:postgresql et 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>

Configurer application.properties ou les variables d'environnement

Vous pouvez configurer l'URL de connexion dans 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

Pour que vos fichiers sources ne contiennent aucun ID de projet ni nom d'instance, vous pouvez laisser application.properties vide et fournir ces variables d'environnement Spring Boot standards au moment de l'exécution :

Variable d'environnement	Valeur
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

Conseils pour Spring Cloud GCP et Secret Manager :

• Si vous préférez les propriétés structurées à une longue URL JDBC, vous pouvez utiliser com.google.cloud:spring-cloud-gcp-starter-alloydb et définir spring.cloud.gcp.alloydb.database-name, spring.cloud.gcp.alloydb.instance-connection-uri et spring.cloud.gcp.alloydb.iam-auth-enabled=true.
• Si votre organisation nécessite toujours des mots de passe de base de données statiques au lieu de l'authentification IAM, ne les codez jamais en dur. Injectez-les de manière dynamique depuis Google Cloud Secret Manager à l'aide de spring.config.import=sm:// et spring.datasource.password=${sm://alloydb-password}.

Créer AlloyDbTestApplication.java

Créez src/main/java/com/example/alloydb/AlloyDbTestApplication.java (afficher sur 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);
        };
    }
}

Exécuter l'application Spring Boot

Exportez les variables d'environnement et exécutez l'application avec 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

Vous devriez obtenir le résultat suivant :

>>> ALLOYDB STATUS: Connection Successful!

5. Se connecter avec Quarkus, Micronaut et GraalVM Native Image

Étant donné que le connecteur Java AlloyDB fonctionne au niveau du pilote JDBC, le passage d'un framework Java cloud natif à un autre ne modifie pas la façon dont vous sécurisez le trafic de la base de données ou gérez les identités. Quarkus et Micronaut encapsulent le pilote JDBC sous-jacent et délèguent le chiffrement mTLS, la résolution d'adresse IP dynamique et l'authentification IAM au connecteur via ADC.

Configuration Quarkus (application.properties avec Agroal)

Dans une application Quarkus (quarkus-agroal et quarkus-jdbc-postgresql), ajoutez com.google.cloud:alloydb-jdbc-connector:1.4.0 à vos dépendances et transmettez les paramètres du connecteur via quarkus.datasource.jdbc.additional-jdbc-properties dans 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

Conseil sur la priorité de la nomenclature pour Quarkus et Micronaut : Lorsque vous utilisez com.google.cloud:alloydb-jdbc-connector:1.4.0 dans un projet avec quarkus-bom ou micronaut-parent, importez com.google.cloud:libraries-bom en premier dans votre section . Cela garantit que les versions plus récentes de protobuf-java (4.x) et gRPC requises par le client d'administration AlloyDB sont prioritaires sur les versions plus anciennes gérées par la nomenclature du framework.

Configuration de Micronaut (application.yml avec HikariCP)

Dans une application Micronaut (micronaut-jdbc-hikari), ajoutez com.google.cloud:alloydb-jdbc-connector:1.4.0 et configurez 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

Enregistrer le connecteur pour l'image native GraalVM

Lorsque vous compilez votre application dans une image native GraalVM (avec Spring Boot 3+, Quarkus ou Micronaut), il y a un détail important : la réflexion.

Le pilote JDBC PostgreSQL instancie com.google.cloud.alloydb.SocketFactory de manière dynamique par nom de classe à l'aide de la réflexion. Pour empêcher l'analyse statique de GraalVM de supprimer la classe lors de la compilation native, enregistrez-la explicitement :

• Spring Boot 3 ou version ultérieure : ajoutez @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class) à votre application principale ou à votre classe @Configuration :

  @SpringBootApplication
  @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class)
  public class AlloyDbTestApplication { ... }
  

• Quarkus : ajoutez @RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class) à votre classe principale ou à un bean CDI :

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

6. Résoudre les problèmes courants liés à IAM et à la connectivité

Si vous rencontrez une erreur FATAL: password authentication failed for user ou AlloyDB IAM authentication failed, vérifiez les quatre points suivants :

1. Supprimer .gserviceaccount.com des noms d'utilisateur de la base de données du compte de service

La cause la plus fréquente des échecs d'authentification IAM est l'utilisation de l'adresse e-mail complète du compte de service comme nom d'utilisateur de la base de données. AlloyDB formate les noms d'utilisateur de base de données IAM différemment selon le type de compte principal :

• Pour les comptes de service IAM (supprimez .gserviceaccount.com) : si l'adresse e-mail de votre compte de service Google Cloud est java-alloydb-connector@.iam.gserviceaccount.com, vous devez supprimer le suffixe .gserviceaccount.com et définir le nom d'utilisateur de votre base de données JDBC/AlloyDB sur java-alloydb-connector@.iam.
• Pour les comptes utilisateur ou les groupes IAM (conservez l'adresse e-mail complète) : si vous vous authentifiez en tant qu'utilisateur humain Google Workspace ou Cloud Identity, utilisez votre adresse e-mail complète sans la modifier (par exemple, ).

2. Vérifier comment l'utilisateur de la base de données a été créé

Avez-vous enregistré l'utilisateur via gcloud alloydb users create --type=IAM_BASED (ou la console/Terraform) ? La création d'un utilisateur avec du code SQL brut CREATE USER ne fonctionnera pas pour l'authentification IAM, car AlloyDB limite GRANT alloydbiamuser au plan de contrôle.

3. Vérifier votre identité ADC active

Assurez-vous que l'environnement dans lequel le processus Java s'exécute est bien authentifié en tant que compte principal IAM cible :

• Poste de travail local (connexion en tant que compte de service) : exécutez gcloud auth application-default login --impersonate-service-account=java-alloydb-connector@.iam.gserviceaccount.com pour que les ADC génèrent des jetons pour le compte de service plutôt que pour votre adresse e-mail personnelle.
• Cloud Run/GKE : vérifiez que le compte de service est associé à la charge de travail et qu'il dispose des rôles roles/alloydb.client et roles/serviceusage.serviceUsageConsumer.

4. Prendre en compte la propagation IAM et le routage réseau

• Délai de propagation IAM : la propagation des liaisons de stratégie IAM peut prendre entre 60 et 120 secondes. Si vous venez de créer le compte de service ou la liaison de rôle, patientez une minute, puis réessayez.
• Accès au réseau VPC : par défaut, le connecteur Java AlloyDB se connecte à l'adresse IP PRIVATE de l'instance. Si votre application s'exécute sur Cloud Run, configurez la sortie VPC directe (recommandée pour réduire la latence et les coûts par rapport aux anciens connecteurs d'accès au VPC sans serveur) ou connectez-vous via Private Service Connect (PSC). Si vous vous connectez depuis une machine locale en dehors du VPC, activez l'adresse IP publique sur l'instance et transmettez alloydbIpType=PUBLIC.

7. Effectuer un nettoyage

Pour éviter que des frais inutiles ne soient facturés sur votre compte Google Cloud et pour supprimer les identités IAM créées lors de cet atelier de programmation, nettoyez les ressources ci-dessous.

1. Supprimer l'utilisateur de base de données et le compte de service IAM AlloyDB

Supprimez l'utilisateur de base de données IAM de votre cluster AlloyDB et supprimez le compte de service :

# 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. Réinitialiser les identifiants par défaut de l'application locale

Si vous avez configuré l'emprunt d'identité ADC local, rétablissez vos identifiants locaux sur votre identité utilisateur par défaut :

gcloud auth application-default login

3. (Facultatif) Supprimer le cluster AlloyDB

Attention : La suppression d'un cluster AlloyDB détruit définitivement toutes les instances et bases de données qu'il contient. N'exécutez la commande ci-dessous que si vous avez créé un cluster de test dédié exclusivement à cet atelier de programmation.

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

8. Félicitations

Vous avez terminé l'atelier de programmation et établi une connectivité sécurisée sans mot de passe entre Java et AlloyDB pour PostgreSQL.

Ce que vous avez accompli

1. Authentification IAM pour les bases de données configurée : vous avez créé un compte de service avec le moindre privilège, activé alloydb.iam_authentication=on, enregistré l'utilisateur IAM sur le cluster AlloyDB et accordé des droits d'accès à la table PostgreSQL.
2. Connecté avec Plain JDBC et HikariCP : HikariConfig a été configuré avec com.google.cloud.alloydb.SocketFactory pour le chiffrement mTLS 1.3 automatique, l'actualisation des jetons IAM et la résolution d'adresse IP dynamique.
3. Frameworks cloud natifs intégrés : configuration de Spring Boot, Quarkus (Agroal) et Micronaut (HikariCP) sans code récurrent de pool de connexions personnalisé, ainsi que des indications de réflexion pour GraalVM Native Image.
4. Maîtriser le dépannage IAM : vous avez appris à diagnostiquer les problèmes de formatage des noms d'utilisateur, d'emprunt d'identité ADC et de routage VPC.

En savoir plus

• Documentation AlloyDB pour PostgreSQL
• Dépôt GitHub du connecteur Java AlloyDB
• Présentation de la connexion AlloyDB
• Présentation d'AlloyDB Express
• Documentation AlloyDB Omni