Se connecter à l'aide du proxy d'authentification AlloyDB

Pour établir des connexions chiffrées et autorisées aux instances AlloyDB, vous pouvez utiliser le proxy d'authentification AlloyDB. Pour en savoir plus, consultez À propos du proxy d'authentification AlloyDB.

Pour utiliser le proxy d'authentification AlloyDB, vous devez effectuer plusieurs étapes de configuration uniques, puis démarrer le client du proxy d'authentification et l'utiliser pour vous connecter à une base de données.

Avant de commencer

L'hôte client doit répondre aux exigences suivantes :

• Le client doit avoir une visibilité réseau sur le réseau de cloud privé virtuel (VPC) où résident les instances auxquelles vous souhaitez vous connecter. Les hôtes clients (comme les instances Compute Engine) de ce réseau de cloud privé virtuel (VPC) disposent intrinsèquement de cette visibilité réseau.

  Les hôtes clients des réseaux externes (réseaux sur site ou réseaux VPC différents) disposent de cette visibilité sur le réseau si le réseau VPC de l'instance AlloyDB est connecté au réseau externe à l'aide d'un tunnel Cloud VPN ou d'un rattachement de VLAN pour Dedicated Interconnect ou Partner Interconnect.

• Si l'hôte client dispose d'une stratégie de pare-feu sortante, il doit autoriser les connexions sortantes au port 5433 sur les adresses IP de vos instances AlloyDB et autoriser les connexions sortantes au port 443 (port HTTPS standard) vers toutes les adresses IP.

• Si vous utilisez une instance Compute Engine comme hôte client, elle doit disposer du niveau d'accès https://www.googleapis.com/auth/cloud-platform pour pouvoir utiliser l'API AlloyDB. Si nécessaire, modifiez son champ d'application de l'accès pour inclure ce champ d'application.

Télécharger le client proxy d'authentification

La machine sur laquelle vous téléchargez le client Auth Proxy dépend de l'endroit depuis lequel vous souhaitez vous connecter à vos instances AlloyDB : depuis leur réseau VPC ou depuis l'extérieur.

Si vous souhaitez vous connecter à votre cluster à l'aide de l'accès aux services privés, vous pouvez télécharger le client Auth Proxy sur une instance de machine virtuelle (VM) Compute Engine s'exécutant dans le réseau VPC qui dispose d'un accès aux services privés à votre cluster.

Si vous prévoyez de vous connecter à votre cluster depuis l'extérieur du VPC, la machine sur laquelle vous l'installez dépend de la stratégie de connexion externe que vous utilisez. Par exemple, vous pouvez installer le client Auth Proxy sur une machine macOS ou Windows locale à votre application, puis utiliser un serveur SOCKS exécuté dans votre réseau VPC AlloyDB comme intermédiaire de connexion. Pour en savoir plus, consultez Se connecter à un cluster depuis l'extérieur de son VPC.

Remarque : Assurez-vous d'utiliser la dernière version du client Auth Proxy. Google publie de nouvelles versions du client Auth Proxy tous les mois. Pour connaître la version actuelle, consultez la page GitHub sur les versions du client Auth Proxy.

Linux

64 bits (AMD)

1. Téléchargez le client proxy d'authentification :

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

2. Rendez le client du proxy d'authentification exécutable :

   chmod +x alloydb-auth-proxy

3. Ajoutez le client Auth Proxy à votre PATH :

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Pour conserver ces modifications d'une session à l'autre, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre fichier ~/.bashrc ou ~/.zshrc.

32 bits (AMD)

1. Téléchargez le client proxy d'authentification :

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

2. Rendez le client du proxy d'authentification exécutable :

   chmod +x alloydb-auth-proxy

3. Ajoutez le client Auth Proxy à votre PATH :

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Pour conserver ces modifications d'une session à l'autre, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre fichier ~/.bashrc ou ~/.zshrc.

64 bits (ARM)

1. Téléchargez le client proxy d'authentification :

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

2. Rendez le client du proxy d'authentification exécutable :

   chmod +x alloydb-auth-proxy

3. Ajoutez le client Auth Proxy à votre PATH :

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Pour conserver ces modifications d'une session à l'autre, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre fichier ~/.bashrc ou ~/.zshrc.

32 bits (ARM)

1. Téléchargez le client proxy d'authentification :

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

2. Rendez le client du proxy d'authentification exécutable :

   chmod +x alloydb-auth-proxy

3. Ajoutez le client Auth Proxy à votre PATH :

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Pour conserver ces modifications d'une session à l'autre, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre fichier ~/.bashrc ou ~/.zshrc.

macOS

ARM64

1. Téléchargez le client proxy d'authentification :

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.darwin.arm64

2. Rendez le client du proxy d'authentification exécutable :

   chmod +x alloydb-auth-proxy

3. Ajoutez le client Auth Proxy à votre PATH :

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Pour conserver ces modifications d'une session à l'autre, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre fichier ~/.bashrc ou ~/.zshrc.

AMD64

1. Téléchargez le client proxy d'authentification :

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.darwin.amd64

2. Rendez le client du proxy d'authentification exécutable :

   chmod +x alloydb-auth-proxy

3. Ajoutez le client Auth Proxy à votre PATH :

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Pour conserver ces modifications d'une session à l'autre, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre fichier ~/.bashrc ou ~/.zshrc.

Windows

64 bits

1. Effectuez un clic droit sur https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy-x64.exe et sélectionnez Enregistrer le lien sous pour télécharger le client Auth Proxy. Renommez le fichier en alloydb-auth-proxy.exe.

2. Ajoutez le client Auth Proxy à votre PATH :

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

32 bits

1. Effectuez un clic droit sur https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy-x86.exe et sélectionnez Enregistrer le lien sous pour télécharger le client Auth Proxy. Renommez le fichier en alloydb-auth-proxy.exe.

2. Ajoutez le client Auth Proxy à votre PATH :

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

Image Docker

Pour plus de commodité, plusieurs images de conteneur contenant le client Auth Proxy sont disponibles dans Artifact Registry.

Vous pouvez extraire la dernière image sur votre ordinateur local en utilisant Docker avec la commande suivante :

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Autres systèmes d'exploitation

Pour les autres systèmes d'exploitation non inclus ici, vous pouvez compiler le client Auth Proxy à partir de la source.

Choisir le compte principal IAM et le préparer pour l'autorisation

Le proxy d'authentification AlloyDB est compatible avec l'utilisation de ces types de principaux IAM pour autoriser les connexions entre votre client et une instance AlloyDB :

• Un compte de service associé. Si votre hôte client s'exécute surGoogle Cloud(par exemple, sur une instance Compute Engine), vous pouvez autoriser les connexions à l'aide du compte de service associé à cette ressource.

  Nous vous recommandons d'utiliser un compte de service pour l'autorisation dans les environnements de production. Un compte de service associé est l'option la plus sécurisée, car il ne nécessite pas de clé téléchargée.

• Votre compte utilisateur : Vous pouvez utiliser votre propre compte utilisateur IAM pour autoriser les connexions.

  Il est pratique d'utiliser votre propre compte utilisateur dans les environnements de développement où vous gérez les ressources AlloyDB à l'aide de la gcloud CLI, développez la base de données à l'aide d'un outil tel que psql et développez le code d'application sur le même hôte.

• Un compte de service géré par l'utilisateur. Vous pouvez créer un compte de service IAM pour votre application, puis autoriser les connexions à l'aide de ce compte.

  Utilisez un compte de service géré par l'utilisateur lorsque votre hôte client s'exécute en dehors deGoogle Cloud et ne peut pas utiliser de compte de service associé.

Après avoir choisi le compte principal IAM à utiliser, vérifiez qu'il dispose des autorisations IAM requises et que ses identifiants sont disponibles sur votre hôte client.

Autorisations IAM requises

Le compte principal IAM que vous utilisez pour autoriser les connexions doit disposer des autorisations fournies par les rôles prédéfinis roles/alloydb.client (Client Cloud AlloyDB) et roles/serviceusage.serviceUsageConsumer (Consommateur Service Usage).

Remarque : Le rôle roles/alloydb.admin (Administrateur AlloyDB pour Cloud) fournit également les autorisations requises.

Pour attribuer le rôle Client Cloud AlloyDB à un principal IAM :

• L'API Cloud Resource Manager doit être activée dans le projet Google Cloud .

• Vous devez disposer du rôle IAM de base roles/owner (Propriétaire) dans le projetGoogle Cloud , ou d'un rôle qui accorde les autorisations suivantes :

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  Pour obtenir ces autorisations tout en suivant le principe du moindre privilège, demandez à votre administrateur de vous attribuer le rôle roles/resourcemanager.projectIamAdmin (Administrateur IAM du projet).

Rendre les identifiants IAM disponibles sur l'hôte client

Le client Auth Proxy utilise les identifiants par défaut de l'application (ADC) pour localiser les identifiants IAM sur l'hôte client. Dans la plupart des environnements, ces identifiants sont déjà présents. Vous n'avez donc rien à configurer. Le client Auth Proxy recherche les sources d'identifiants suivantes, dans l'ordre :

• Votre compte utilisateur. Lorsque vous développez en local, authentifiez-vous avec votre propre compte utilisateur en exécutant la commande gcloud CLI suivante :

  gcloud auth application-default login
  

  Le client Auth Proxy détecte et utilise ces identifiants. Vous n'avez pas besoin de télécharger de clé de compte de service.

• Un compte de service associé. Lorsque votre hôte client s'exécute surGoogle Cloud(par exemple, sur une instance Compute Engine), le serveur de métadonnées de l'environnement fournit les identifiants du compte de service associé. Le client Auth Proxy découvre et utilise ces identifiants sans configuration supplémentaire.

Autres sources d'identifiants

N'utilisez les méthodes suivantes que lorsque les identifiants par défaut de l'application ne sont pas disponibles (par exemple, lorsque vous exécutez le client Auth Proxy en dehors deGoogle Cloudou lorsque vous devez remplacer les identifiants dans l'environnement).

• Une clé de compte de service. Utilisez une clé de compte de service lorsque votre hôte client s'exécute en dehors de Google Cloud(par exemple, dans un centre de données sur site ou chez un autre fournisseur de services cloud) et que vous ne pouvez pas utiliser la fédération d'identité de charge de travail.

  Créez une clé de compte de service au format JSON et téléchargez-la sur votre hôte client. Ensuite, définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès du fichier de clé :

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
  

  Si vous le souhaitez, vous pouvez spécifier le chemin d'accès avec l'indicateur --credentials-file lorsque vous démarrez le client Auth Proxy :

  alloydb-auth-proxy --credentials-file /path/to/service-account-key.json INSTANCE_URI
  

  Attention : Les clés de compte de service constituent un risque pour la sécurité si elles ne sont pas gérées correctement. Avant de créer une clé, envisagez une alternative plus sécurisée.

• Un jeton d'accès OAuth 2.0. Utilisez un jeton d'accès lorsqu'un autre système émet déjà des jetons à courte durée de vie pour vous. Par exemple, un pipeline d'intégration continue qui obtient un jeton avant de démarrer le client Auth Proxy.

  Si vous disposez déjà d'un jeton d'accès OAuth 2.0 valide, transmettez-le directement lorsque vous démarrez le client Auth Proxy :

  alloydb-auth-proxy --token "ACCESS_TOKEN" INSTANCE_URI
  

• Vos identifiants gcloud CLI N'utilisez l'option --gcloud-auth que lorsque vous devez réutiliser une session gcloud auth login existante et que vous ne pouvez pas exécuter gcloud auth application-default login.

  Le paramètre --gcloud-auth permet au client Auth Proxy d'utiliser le compte avec lequel vous vous êtes authentifié avec gcloud auth login au lieu d'utiliser les Identifiants par défaut de l'application. Nous ne recommandons pas cette option. Exécutez plutôt gcloud auth application-default login.

Collecter les URI de connexion pour les instances AlloyDB

Lorsque vous démarrez le client Auth Proxy, vous identifiez la ou les instances AlloyDB auxquelles vous souhaitez vous connecter à l'aide de ce format d'URI de connexion :

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Pour afficher la liste des URI de connexion de toutes vos instances, utilisez la commande gcloud CLI alloydb instances list :

gcloud alloydb instances list \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID

Remplacez les éléments suivants :

• REGION_ID : région où sont placées les instances
• CLUSTER_ID : ID du cluster dans lequel les instances sont placées
• PROJECT_ID : ID du projet dans lequel le cluster est placé

Collectez l'URI de connexion de chaque instance à laquelle vous souhaitez vous connecter.

Démarrer le client Auth Proxy

Lorsque vous démarrez le client Auth Proxy, vous lui fournissez des informations sur les instances AlloyDB auxquelles se connecter et, si nécessaire, des informations d'identification à utiliser lors de l'autorisation de ces connexions.

Lorsqu'il démarre, le client du proxy d'authentification :

• Autorise les connexions aux instances AlloyDB à l'aide des identifiants et des autorisations IAM du compte principal IAM que vous avez configuré. Il recherche les identifiants en suivant une séquence d'étapes spécifique.
• Autorise automatiquement les connexions à l'adresse IP publique au réseau source si l'adresse IP publique est activée pour l'instance.
• Configure une connexion privée mTLS 1.3 au serveur proxy d'authentification de chaque instance.
• Commence à écouter les demandes de connexion des clients locaux.

Par défaut, le client du proxy d'authentification écoute les connexions TCP sur l'adresse IP 127.0.0.1, en commençant par le port 5432 et en incrémentant le numéro de port de 1 pour chaque instance AlloyDB au-delà de la première. Vous pouvez spécifier une adresse d'écouteur et des ports différents lorsque vous démarrez le client Auth Proxy.

Avertissement : Soyez vigilant lorsque vous associez le client Auth Proxy à une interface externe. Toute personne ayant accès à cette interface ou à ce port est autorisée à se connecter à votre instance.

Remarque : Google vous recommande d'exécuter le client Auth Proxy en tant que service persistant dans les environnements de production.

Ligne de commande

alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

Remplacez les éléments suivants :

• INSTANCE_URI : URI de connexion de l'instance AlloyDB à laquelle se connecter, spécifié au format suivant :

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  Vous pouvez remplacer le port d'écouteur local par défaut que le client Auth Proxy utilisera pour l'instance en ajoutant le paramètre de requête port à l'URI :

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• Facultatif : PATH_TO_KEY_FILE : chemin d'accès au fichier de clé JSON du compte de service géré par l'utilisateur à utiliser pour l'autorisation de connexion.

• Facultatif : OAUTH_ACCESS_TOKEN : valeur du jeton OAuth2 à utiliser pour l'autorisation de connexion.

• Facultatif : INITIAL_PORT_NUMBER : numéro de port de début à utiliser au lieu du port par défaut 5432 lors de l'écoute des connexions TCP locales.

• Facultatif : LOCAL_LISTENER_ADDRESS : adresse d'écouteur à utiliser au lieu de l'adresse par défaut 127.0.0.1 lors de l'écoute des connexions TCP locales.

L'option facultative --auto-iam-authn vous permet de vous authentifier automatiquement auprès de l'instance. Cela ne fonctionne que pour l'utilisateur de la base de données associé au compte IAM qui exécute le client Auth Proxy. Pour en savoir plus, consultez S'authentifier automatiquement à l'aide du proxy d'authentification.

L'option facultative --psc permet au proxy d'authentification de se connecter à une instance sur laquelle Private Service Connect est activé. Pour en savoir plus sur la configuration du DNS avec Private Service Connect, consultez Configurer une zone DNS gérée et un enregistrement DNS.

L'indicateur --public-ip facultatif permet au proxy d'authentification de se connecter à une instance dont l'adresse IP publique est activée en utilisant l'adresse IP publique de l'instance. Pour en savoir plus sur l'adresse IP publique, consultez Se connecter à l'aide d'une adresse IP publique.

L'indicateur --disable-built-in-telemetry facultatif désactive le rapporteur de métriques interne utilisé par le proxy d'authentification pour générer des rapports sur l'état de la connexion et du réseau. Par défaut, le proxy d'authentification génère des rapports sur ses opérations internes avec le préfixe de métrique système alloydb.googleapis.com. Ces métriques aident AlloyDB à améliorer les performances et à identifier les problèmes de connectivité des clients. Cette option est utile pour les applications qui fonctionnent dans des environnements où l'exportation de métriques sortantes est limitée. Pour désactiver cette télémétrie, utilisez cet indicateur.

Conteneur Docker

Démarrez le client Auth Proxy à l'aide de la commande docker run.

Si vous utilisez les identifiants fournis par votre instance Compute Engine, vous pouvez utiliser une commande semblable à la suivante :

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

Remplacez les éléments suivants :

• PORT : port à utiliser pour les connexions locales au client Auth Proxy. La valeur par défaut est 5432.

• INSTANCE_URI : URI de connexion de l'instance AlloyDB à laquelle se connecter, spécifié au format suivant :

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  Vous pouvez remplacer le port d'écouteur local par défaut que le client Auth Proxy utilise pour l'instance en ajoutant le paramètre de requête port à l'URI :

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Spécifiez toujours le préfixe 127.0.0.1 dans l'indicateur --publish afin de ne pas exposer le client du proxy d'authentification en dehors de l'hôte local.

La valeur 0.0.0.0 dans l'indicateur --address est requise pour rendre l'écouteur accessible de l'extérieur du conteneur Docker.

Pour fournir des identifiants que vous avez stockés dans un fichier JSON local, incluez les indicateurs --volume et --credentials-file lorsque vous exécutez la commande docker run :

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Remplacez PATH_TO_KEY_FILE par le chemin d'accès au fichier de clé JSON du compte de service géré par l'utilisateur à utiliser pour l'autorisation de connexion.

Exemples de start-up

Les exemples suivants montrent différentes façons de démarrer le client Auth Proxy. Ils utilisent les exemples d'URI de connexion à l'instance suivants :

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Démarrage de base

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432.

Démarrage à l'aide d'un compte de service géré par l'utilisateur

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --credentials-file "myappaccount/key.json"

Dans cet exemple, le client du proxy d'authentification autorise la connexion à l'aide de la clé JSON du compte de service géré par l'utilisateur stockée à l'emplacement myappaccount/key.json, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432.

Démarrage de la connexion à plusieurs instances

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432 et à l'instance myreadpool sur 127.0.0.1:5433.

Démarrage de l'écoute sur des ports personnalisés

L'utilisation de ports personnalisés pour le client du proxy d'authentification peut être utile lorsque vous devez réserver le port 5432 pour d'autres connexions PostgreSQL.

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

Dans cet exemple, le client du proxy d'authentification autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5000 et à l'instance myreadpool sur 127.0.0.1:5001.

Comme ces ports personnalisés sont séquentiels, le même effet peut être obtenu à l'aide de cette commande de démarrage :

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Démarrage de l'écoute sur une adresse IP personnalisée

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

Dans cet exemple, le client Auth Proxy autorise la connexion en suivant sa séquence normale d'étapes d'autorisation, puis commence à écouter les connexions locales à l'instance myprimary sur 0.0.0.0:5432.

Connecter une application à une base de données à l'aide du proxy d'authentification AlloyDB

Les exemples suivants montrent comment connecter une application à une base de données à l'aide du proxy d'authentification AlloyDB.

L'exemple psql montre comment connecter un outil de ligne de commande.

Pour plusieurs langages de programmation, la connexion à une instance AlloyDB à l'aide du proxy d'authentification est identique à la connexion à une instance Cloud SQL pour PostgreSQL à l'aide du proxy d'authentification Cloud SQL. Les exemples de langage sont donc les mêmes que ceux pour Cloud SQL pour PostgreSQL.

Ces exemples sont basés sur un démarrage par défaut du client Auth Proxy afin qu'il écoute les connexions TCP locales sur 127.0.0.1:5432.

Remarque : Avec un nouveau cluster, vous pouvez vous connecter en tant qu'utilisateur postgres à l'aide du mot de passe que vous avez spécifié lors de la création du cluster.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Remplacez DB_USER par l'utilisateur de la base de données avec lequel vous souhaitez vous connecter (par exemple, postgres).

Vous êtes alors invité à saisir le mot de passe de l'utilisateur DB_USER.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    INSTANCE_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

package alloydb

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %v", err)
	}

	// ...

	return dbPool, nil
}

C#

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);