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

Pour établir des connexions autorisées et chiffrées aux instances AlloyDB pour PostgreSQL, 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 ponctuelles, 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 disposer d'un chemin d'accès réseau vers l'instance AlloyDB en fonction de votre méthode de connexion :

  • Accès aux services privés (par défaut) : le client doit disposer d'une visibilité réseau sur le réseau cloud privé virtuel (VPC) où résident les instances. Les hôtes clients (tels que les instances Compute Engine) de ce réseau 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é 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 une interconnexion dédiée ou une interconnexion partenaire.
  • Private Service Connect : le réseau VPC du client doit disposer d'un point de terminaison Private Service Connect et d'un enregistrement DNS privé correspondant, et vous devez démarrer le client du proxy d'authentification avec l'option --psc.
  • Adresse IP publique : l'adresse IP publique doit être activée sur l'instance, et vous devez démarrer le client du proxy d'authentification avec l'option --public-ip. Lorsque vous vous connectez à l'aide du proxy d'authentification, vous n'avez pas besoin d'ajouter l'adresse IP de l'hôte client aux réseaux externes autorisés.

• Si l'hôte client dispose d'une stratégie de pare-feu sortante, il doit autoriser les connexions sortantes vers le port 5433 sur les adresses IP de vos instances AlloyDB et autoriser les connexions sortantes vers le port 443 (le 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 niveau d'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 du proxy d'authentification dépend de l'emplacement à partir duquel vous souhaitez vous connecter à vos instances AlloyDB (depuis son 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 du proxy d'authentification sur une instance de machine virtuelle (VM) Compute Engine s'exécutant sur le réseau VPC qui dispose d'un accès aux services privés à votre cluster.

Si vous avez l'intention 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 du proxy d'authentification sur une machine macOS ou Windows locale pour votre application, puis utiliser un serveur SOCKS exécuté sur 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 du proxy d'authentification. Google publie de nouvelles versions du client du proxy d'authentification tous les mois. Pour savoir quelle est la version actuelle, consultez la page GitHub relative aux versions du client du proxy d'authentification.

Linux

64 bits (AMD)

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

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/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 proxy d'authentification à 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.2/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 proxy d'authentification à 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.2/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 proxy d'authentification à 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.2/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 proxy d'authentification à 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.2/alloydb-auth-proxy.darwin.arm64

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

   chmod +x alloydb-auth-proxy

3. Ajoutez le client proxy d'authentification à 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.2/alloydb-auth-proxy.darwin.amd64

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

   chmod +x alloydb-auth-proxy

3. Ajoutez le client proxy d'authentification à 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.2/alloydb-auth-proxy-x64.exe et sélectionnez Enregistrer le lien sous pour télécharger le client du proxy d'authentification. Renommez le fichier en alloydb-auth-proxy.exe.

2. Ajoutez le client proxy d'authentification à 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.2/alloydb-auth-proxy-x86.exe et sélectionnez Enregistrer le lien sous pour télécharger le client du proxy d'authentification. Renommez le fichier en alloydb-auth-proxy.exe.

2. Ajoutez le client proxy d'authentification à 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 du proxy d'authentification 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 du proxy d'authentification à partir de la source.

Choisir le compte principal Identity and Access Management (IAM) et le préparer pour l'autorisation

Le proxy d'authentification AlloyDB accepte l'utilisation de ces types de comptes 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.

  L'utilisation de votre propre compte utilisateur est pratique 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 de l'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 de service.

  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 AlloyDB) et roles/serviceusage.serviceUsageConsumer (consommateur Service Usage).

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

Pour attribuer le rôle "Client AlloyDB" à un compte 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 ces autorisations :

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

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

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

Le client du proxy d'authentification 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 du proxy d'authentification 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 du proxy d'authentification détecte et utilise ces identifiants. Vous n'avez pas besoin de télécharger une 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 du proxy d'authentification 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 du proxy d'authentification 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 sur 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"
  

  Vous pouvez éventuellement spécifier le chemin d'accès avec l'option --credentials-file lorsque vous démarrez le client du proxy d'authentification :

  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 de courte durée pour vous, par exemple un pipeline d'intégration continue qui obtient un jeton avant de démarrer le client du proxy d'authentification.

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

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

• 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 flag --gcloud-auth permet au client du proxy d'authentification 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.

Récupérer les URI de connexion pour les instances AlloyDB

Lorsque vous démarrez le client du proxy d'authentification, 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ù se trouvent 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é

Récupérez l'URI de connexion de chaque instance à laquelle vous souhaitez vous connecter.

Démarrer le client du proxy d'authentification

Lorsque vous démarrez le client du proxy d'authentification, vous lui fournissez des informations sur les instances AlloyDB auxquelles se connecter et, si nécessaire, des informations d'identification à utiliser pour autoriser 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 IP publiques au réseau source, si l'adresse IP publique est activée sur l'instance.
• Configure une connexion mTLS 1.3 privée 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 d'un numéro de port pour chaque instance AlloyDB au-delà de la première. Vous pouvez spécifier une adresse d'écoute et des ports différents lorsque vous démarrez le client Auth Proxy.

Avertissement : Soyez vigilant lorsque vous associez le client proxy d'authentification à 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 du proxy d'authentification 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 d'une 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'écoute local par défaut que le client du proxy d'authentification 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 de jeton OAuth2 à utiliser pour l'autorisation de connexion.

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

• Facultatif : LOCAL_LISTENER_ADDRESS : adresse de l'écouteur à utiliser à la place 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 base de données associé au compte IAM qui exécute le client du proxy d'authentification. 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 gérée DNS et un enregistrement DNS.

L'option facultative --public-ip permet au proxy d'authentification de se connecter à une instance pour laquelle l'adresse IP publique est activée, en utilisant l'adresse IP publique de l'instance. Pour en savoir plus sur les adresses IP publiques, consultez Se connecter à l'aide d'une adresse IP publique.

L'option facultative --disable-built-in-telemetry désactive l'outil de reporting des métriques internes que le proxy d'authentification utilise pour générer des rapports sur l'état de la connexion et du réseau. Par défaut, le proxy d'authentification signale ses opérations internes au 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 cette option.

Conteneur Docker

Démarrez le client du proxy d'authentification à l'aide de la commande docker run.

Si vous utilisez les identifiants fournis par votre instance Compute Engine, vous pouvez utiliser une commande semblable à celle-ci :

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 du proxy d'authentification. La valeur par défaut est 5432.

• INSTANCE_URI : URI de connexion d'une 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'écoute local par défaut utilisé par le client Auth Proxy 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'option --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 de l'option --address est requise pour rendre l'écouteur accessible depuis l'extérieur du conteneur Docker.

Pour fournir des identifiants que vous avez stockés dans un fichier JSON local, incluez les options --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 manières de démarrer le client du proxy d'authentification. Ils utilisent les exemples d'URI de connexion d'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 dans myappaccount/key.json, puis commence à écouter les connexions locales à l'instance myprimary sur 127.0.0.1:5432.

Startup se connectant à 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 d'étapes d'autorisation normale, 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.

Écoute au démarrage 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, vous pouvez obtenir le même effet à 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 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 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 de Cloud SQL pour PostgreSQL.

Ces exemples sont basés sur un démarrage par défaut du client du proxy d'authentification, de sorte 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 auquel 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 les exemples Go 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);