Cette page explique comment se connecter à Cloud SQL avec le client psql, installé sur une instance Compute Engine.
Vous pouvez utiliser une adresse IP privée, une adresse IP publique, le proxy d'authentification Cloud SQL ou l'image Docker du proxy d'authentification Cloud SQL.
Pour obtenir des instructions détaillées sur l'exécution d'un exemple d'application Web Compute Engine connectée à Cloud SQL, consultezDémarrage rapide pour la connexion à partir de Compute Engine.
Avant de commencer
Cette tâche n'inclut pas d'instructions pour la configuration de l'instance Compute Engine. Si vous avez besoin d'aide pour créer et configurer une instance Compute Engine, consultez la documentation de Compute Engine.
Adresse IP privée
Pour pouvoir vous connecter à Cloud SQL depuis une instance Compute Engine à l'aide d'une adresse IP privée, l'accès aux services privés doit être configuré pour votre environnement, et votre instance Cloud SQL doit être configurée pour utiliser une adresse IP privée. L'instance Compute Engine doit se trouver dans la même région que votre instance Cloud SQL et sur le réseau configuré pour une connexion privée. En savoir plus
1. Configurer votre instance pour qu'elle utilise une adresse IP privée
Suivez les instructions de la section Configurer la connectivité IP privée.
2. Ouvrez une connexion de terminal Cloud Shell à l'instance Compute Engine.
Suivez les instructions correspondantes, en fonction du système d'exploitation de l'instance :
- Pour Linux, consultez la section Se connecter à des VM Linux.
- Pour Windows, consultez la section Se connecter à des VM Windows.
Si l'instance Compute Engine exécute une image publique RHEL ou CentOS, SELinux risque de bloquer la connexion proxy. Le cas échéant, vous devez configurer la fonctionnalité SELinux pour autoriser la connexion.
Pour en savoir plus sur SELinux pour RHEL, consultez la documentation RHEL. Pour plus d'informations sur SELinux for CentOS, consultez la documentation CentOS.
3. Si ce n'est pas déjà fait, installez le client psql sur l'instance Compute Engine.
Debian/Ubuntu
Installez le client psql à partir du gestionnaire de packages :
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Installez le client psql à partir du gestionnaire de packages :
sudo yum install postgresql
openSUSE
Installez le client psql à partir du gestionnaire de packages :
sudo zypper install postgresql
Autres plates-formes
- Téléchargez PostgreSQL Core Distribution sur votre plate-forme depuis la page des téléchargements PostgreSQL.
Core Distribution inclut le client psql. - Installez la base de données PostgreSQL en suivant les instructions de la page de téléchargement.
4. Connectez-vous à l'aide du client psql.
psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME
Vous pouvez trouver cette adresse IP privée sur la page Instances Cloud SQL ou en exécutant la commande gcloud
suivante :
gcloud sql instances list
Adresse IP publique
Pour vous connecter à l'aide d'une adresse IP publique, procédez comme suit :
1. Ajoutez une adresse IP statique IPv4 à l'instance Compute Engine, si elle n'en a pas déjà une.
Vous ne pouvez pas vous connecter à Compute Engine avec le protocole IPv6. Pour en savoir plus sur l'ajout d'adresse IP statique, consultez la section Réserver une nouvelle adresse IP externe statique dans la documentation de Compute Engine.
2. Autorisez l'adresse IP statique de l'instance Compute Engine en tant que réseau pouvant se connecter à l'instance Cloud SQL.
Pour en savoir plus, consultez la page Configurer l'accès pour les connexions IP publiques.
3. Ouvrez une connexion de terminal Cloud Shell à l'instance Compute Engine.
Suivez les instructions correspondantes, en fonction du système d'exploitation de l'instance :
- Pour Linux, consultez la section Se connecter à des VM Linux.
- Pour Windows, consultez la section Se connecter à des VM Windows.
Si l'instance Compute Engine exécute une image publique RHEL ou CentOS, SELinux risque de bloquer la connexion proxy. Le cas échéant, vous devez configurer la fonctionnalité SELinux pour autoriser la connexion.
Pour en savoir plus sur SELinux pour RHEL, consultez la documentation RHEL. Pour plus d'informations sur SELinux for CentOS, consultez la documentation CentOS.
4. Si ce n'est pas déjà fait, installez le client psql sur l'instance Compute Engine.
Debian/Ubuntu
Installez le client psql à partir du gestionnaire de packages :
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Installez le client psql à partir du gestionnaire de packages :
sudo yum install postgresql
openSUSE
Installez le client psql à partir du gestionnaire de packages :
sudo zypper install postgresql
Autres plates-formes
- Téléchargez PostgreSQL Core Distribution sur votre plate-forme depuis la page des téléchargements PostgreSQL.
Core Distribution inclut le client psql. - Installez la base de données PostgreSQL en suivant les instructions de la page de téléchargement.
5. Connectez-vous à l'aide du client psql.
psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME
Vous pouvez trouver l'adresse IP publique sur la page des instances Cloud SQL ou en exécutant la commande gcloud
suivante :
gcloud sql instances list
Pour obtenir un exemple de connexion à l'aide de SSL, consultez la section Se connecter à l'aide de SSL.
6. L'invite psql apparaît.
7. Si vous souhaitez que les connexions inutilisées restent actives, procédez comme suit :
Définissez le message keepalive TCP.
Pour en savoir plus, consultez la page Communication entre vos instances et Internet dans la documentation de Compute Engine.
Les connexions sont automatiquement maintenues actives pour les instances.
Proxy d'authentification Cloud SQL
Pour vous connecter à l'aide du proxy d'authentification Cloud SQL à partir de Compute Engine :1. Activez l'API Cloud SQL Admin.
2. Créez un compte de service.
- Dans Google Cloud Console, accédez à la page Comptes de service.
- Sélectionnez le projet contenant l'instance Cloud SQL.
- Cliquez sur Créer un compte de service.
- Dans le champ Nom du compte de service, attribuez un nom descriptif au compte de service.
- Remplacez l'ID du compte de service par une valeur unique et facilement reconnaissable, puis cliquez sur Créer et continuer.
-
Cliquez sur le champ Sélectionner un rôle, puis sélectionnez l'un des rôles suivants :
- Cloud SQL > Client Cloud SQL
- Cloud SQL > Éditeur Cloud SQL
- Cloud SQL > Administrateur Cloud SQL
- Cliquez sur OK pour terminer la création du compte de service.
- Cliquez sur le menu Action de votre nouveau compte de service, puis sélectionnez Gérer les clés.
- Cliquez sur le menu déroulant Ajouter une clé, puis sur Créer une clé.
-
Vérifiez que le type de clé est bien JSON et cliquez sur Créer.
Le fichier de clé privée est téléchargé sur votre machine. Vous pouvez le changer d'emplacement. Conservez le fichier de clé dans un endroit sécurisé.
Si l'instance Compute Engine se trouve dans un projet différent de celui de l'instance Cloud SQL, assurez-vous que le compte de service dispose des autorisations appropriées dans le projet qui contient l'instance Cloud SQL :
- Accédez à la liste des instances Compute Engine dans Google Cloud Console.
- Si nécessaire, sélectionnez le projet associé à l'instance Compute Engine.
- Sélectionnez l'instance Compute Engine pour afficher ses propriétés.
- Dans les propriétés de l'instance Compute Engine, copiez le nom du compte de service.
- Accédez à la section des projets de la page IAM et administration dans Google Cloud Console.
Accéder à la section des projets de la page "IAM et administration"
- Sélectionnez le projet contenant l'instance Cloud SQL.
- Recherchez le nom du compte de service.
-
Si le compte de service est déjà présent et qu'il dispose d'un rôle comprenant l'autorisation
cloudsql.instances.connect
, vous pouvez passer à l'étape 4.Les rôles
Cloud SQL Client
,Cloud SQL Editor
etCloud SQL Admin
accordent tous les autorisations nécessaires, de même que les anciens rôles de projetEditor
etOwner
. - Sinon, ajoutez le compte de service en cliquant sur Ajouter.
Dans la boîte de dialogue Ajouter des comptes principaux, indiquez le nom du compte de service et sélectionnez un rôle qui inclut l'autorisation
cloudsql.instances.connect
(n'importe quel rôle Cloud SQL prédéfini peut être utilisé, à l'exception du rôle "Lecteur").Vous pouvez également utiliser le rôle de base d'éditeur en sélectionnant Projet > Éditeur. Sachez toutefois que celui-ci dispose d'autorisations sur l'ensemble de Google Cloud.
Si vous ne voyez pas ces rôles, votre utilisateur Google Cloud peut ne pas disposer de l'autorisation
resourcemanager.projects.setIamPolicy
. Pour vérifier vos autorisations, accédez à la page IAM de Google Cloud Console et recherchez votre ID utilisateur.- Cliquez sur Ajouter.
Le compte de service répertorié s'affiche maintenant avec le rôle spécifié.
3. Ouvrez une connexion de terminal à l'instance Compute Engine.
Suivez les instructions correspondantes, en fonction du système d'exploitation de l'instance :
- Pour Linux, consultez la section Se connecter à des instances Linux.
- Pour Windows, consultez la section Se connecter à des instances Windows.
Si l'instance Compute Engine exécute une image publique RHEL ou CentOS, SELinux risque de bloquer la connexion proxy. Le cas échéant, vous devez configurer la fonctionnalité SELinux pour autoriser la connexion.
Pour en savoir plus sur SELinux pour RHEL, consultez la documentation RHEL. Pour plus d'informations sur SELinux for CentOS, consultez la documentation CentOS.
4. Si ce n'est pas déjà fait, installez le client psql sur l'instance Compute Engine.
Debian/Ubuntu
Installez le client psql à partir du gestionnaire de packages :
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Installez le client psql à partir du gestionnaire de packages :
sudo yum install postgresql
openSUSE
Installez le client psql à partir du gestionnaire de packages :
sudo zypper install postgresql
Autres plates-formes
- Téléchargez PostgreSQL Core Distribution sur votre plate-forme depuis la page des téléchargements PostgreSQL.
Core Distribution inclut le client psql. - Installez la base de données PostgreSQL en suivant les instructions de la page de téléchargement.
5. Installez le proxy d'authentification Cloud SQL sur l'instance Compute Engine.
Linux 64 bits
- Téléchargez le proxy d'authentification Cloud SQL :
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/cloud-sql-proxy.linux.amd64
- Rendez le proxy d'authentification Cloud SQL exécutable :
chmod +x cloud-sql-proxy
Linux 32 bits
- Téléchargez le proxy d'authentification Cloud SQL :
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/cloud-sql-proxy.linux.386
- Si la commande
curl
est introuvable, exécutezsudo apt install curl
puis répétez la commande de téléchargement. - Rendez le proxy d'authentification Cloud SQL exécutable :
chmod +x cloud-sql-proxy
Windows 64 bits
Effectuez un clic droit sur https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/cloud-sql-proxy.x64.exe et sélectionnez Enregistrer le lien sous pour télécharger le proxy d'authentification Cloud SQL. Renommez le fichier encloud-sql-proxy.exe
.
Windows 32 bits
Effectuez un clic droit sur https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/cloud-sql-proxy.x86.exe et sélectionnez Enregistrer le lien sous pour télécharger le proxy d'authentification Cloud SQL. Renommez le fichier encloud-sql-proxy.exe
.
Image Docker du proxy d'authentification Cloud SQL
Le proxy d'authentification Cloud SQL possède différentes images de conteneur, telles que distroless
, alpine
et buster
. L'image de conteneur du proxy d'authentification Cloud SQL par défaut utilise distroless
, qui ne contient aucune interface système. Si vous avez besoin d'une interface système ou d'outils associés, téléchargez une image basée sur alpine
ou buster
.
Pour plus d'informations, consultez la page Images de conteneurs du proxy d'authentification Cloud SQL.
Vous pouvez extraire la dernière image sur votre ordinateur local en utilisant Docker avec la commande suivante :
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.4
Autres systèmes d'exploitation
Pour les autres systèmes d'exploitation non inclus ici, vous pouvez compiler le proxy d'authentification Cloud SQL à partir de la source.6. Démarrez le proxy d'authentification Cloud SQL.
Selon le langage et l'environnement que vous utilisez, vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP, de sockets Unix ou de l'image Docker du proxy d'authentification Cloud SQL. Le binaire du proxy d'authentification Cloud SQL se connecte aux instances Cloud SQL spécifiées sur la ligne de commande et ouvre une connexion locale en tant que socket TCP ou Unix. D'autres applications et services, tels que votre code d'application ou vos outils clients de gestion de base de données, peuvent se connecter aux instances Cloud SQL via ces connexions de sockets TCP ou Unix.
Sockets TCP
Pour les connexions TCP, le proxy d'authentification Cloud SQL écoute localhost
(127.0.0.1
) par défaut.
Ainsi, lorsque vous spécifiez --port PORT_NUMBER
pour une instance, la connexion locale est à 127.0.0.1:PORT_NUMBER
.
Vous pouvez également spécifier une autre adresse pour la connexion locale.
Par exemple, voici comment faire en sorte que le proxy d'authentification Cloud SQL écoute 0.0.0.0:1234
pour la connexion locale :
./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME
Copiez le nom de connexion de votre instance (INSTANCE_CONNECTION_NAME). Vous le trouverez sur la page Présentation de votre instance dans la console Google Cloud ou en exécutant la commande suivante :
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Exemple : myproject:myregion:myinstance.
- Si des adresses IP publiques et privées sont configurées pour l'instance et que vous souhaitez que le proxy d'authentification Cloud SQL utilise l'adresse IP privée, vous devez indiquer l'option suivante au démarrage du proxy d'authentification Cloud SQL :
--private-ip
- Si vous utilisez un compte de service pour authentifier le proxy d'authentification Cloud SQL, notez l'emplacement sur votre machine cliente du fichier de clé privée généré au moment de la création du compte de service.
- Démarrez le proxy d'authentification Cloud SQL.
Voici des exemples de chaînes d'appel du proxy d'authentification Cloud SQL :
- Avec l'authentification via le SDK Cloud :
./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
Le port spécifié ne doit pas déjà être utilisé, par exemple par un serveur de base de données local. - Utilisez un compte de service et incluez explicitement le nom de la connexion à l'instance (recommandé pour les environnements de production) :
./cloud-sql-proxy \ --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Pour en savoir plus sur les options du proxy d'authentification Cloud SQL, consultez Options d'authentification du proxy d'authentification Cloud SQL.
- Avec l'authentification via le SDK Cloud :
Sockets Unix
Le proxy d'authentification Cloud SQL peut écouter un socket Unix, qui est un mécanisme POSIX standard permettant d'utiliser un dossier pour gérer la communication entre deux processus exécutés sur le même hôte. Les avantages des sockets Unix sont les suivants : amélioration de la sécurité et latence réduite. Toutefois, vous ne pouvez pas accéder à un socket Unix depuis une machine externe.
Pour créer et utiliser un socket Unix, le répertoire cible doit exister. Le proxy d'authentification Cloud SQL et l'application doivent également disposer tous les deux d'un accès en lecture et en écriture.
Copiez le nom de connexion de votre instance (INSTANCE_CONNECTION_NAME). Vous le trouverez sur la page Présentation de votre instance dans la console Google Cloud ou en exécutant la commande suivante :
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Exemple : myproject:myregion:myinstance.
- Créez le répertoire où se situeront les sockets du proxy d'authentification Cloud SQL :
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- Si vous utilisez un compte de service pour authentifier le proxy d'authentification Cloud SQL, notez l'emplacement sur votre machine cliente du fichier de clé privée généré au moment de la création du compte de service.
- Ouvrez une nouvelle fenêtre de terminal Cloud Shell et démarrez le proxy d'authentification Cloud SQL.
Voici des exemples de chaînes d'appel du proxy d'authentification Cloud SQL :
- Avec l'authentification via le Google Cloud SDK :
./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
- Avec un compte de service :
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Démarrez le proxy d'authentification Cloud SQL dans son propre terminal Cloud Shell afin de pouvoir surveiller sa sortie sans qu'elle ne soit mélangée avec celle d'autres programmes.
Pour en savoir plus sur les options du proxy d'authentification Cloud SQL, consultez Options d'authentification du proxy d'authentification Cloud SQL.
- Avec l'authentification via le Google Cloud SDK :
Docker
Pour exécuter le proxy d'authentification Cloud SQL dans un conteneur Docker, utilisez l'image Docker du proxy d'authentification Cloud SQL disponible dans Google Container Registry.
Vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP ou Unix, au moyen des commandes indiquées ci-dessous. Les options utilisent une chaîne de connexion INSTANCE_CONNECTION_NAME pour identifier une instance Cloud SQL. Pour trouver la chaîne de connexion INSTANCE_CONNECTION_NAME, accédez à la page Présentation de votre instance dans Google Cloud Console ou exécutez la commande suivante :
gcloud sql instances describe INSTANCE_NAME.
Exemple : myproject:myregion:myinstance
.
Selon le langage et l'environnement que vous employez, vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP ou Unix. Les sockets Unix ne sont pas compatibles avec les applications écrites en langage de programmation Java ou avec un environnement Windows.
Utiliser des sockets TCP
docker run -d \\ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\ -p 127.0.0.1:5432:5432 \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.4 \\ --address 0.0.0.0 --port 5432 \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Si vous utilisez les identifiants fournis par votre instance Compute Engine, n'incluez pas le paramètre --credentials-file
ni la ligne -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Spécifiez toujours le préfixe 127.0.0.1
dans -p afin de ne pas exposer le proxy d'authentification Cloud SQL en dehors de l'hôte local. La valeur "0.0.0.0" dans les paramètres de l'instance est requise pour rendre le port accessible de l'extérieur du conteneur Docker.
Utiliser des sockets Unix
docker run -d -v /cloudsql:/cloudsql \\ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.4 --unix-socket=/cloudsql \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Si vous utilisez les identifiants fournis par votre instance Compute Engine, n'incluez pas le paramètre --credentials-file
ni la ligne -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Si vous utilisez une image de conteneur optimisée, utilisez un répertoire avec accès en écriture à la place de /cloudsql
, par exemple :
-v /mnt/stateful_partition/cloudsql:/cloudsql
Vous pouvez spécifier plusieurs instances en les séparant par des virgules. Il est également possible d'utiliser les métadonnées Compute Engine afin de déterminer de manière dynamique les instances auxquelles vous connecter. Apprenez-en plus sur les paramètres du proxy d'authentification Cloud SQL.
7. Démarrez la session psql.
La chaîne de connexion que vous utilisez varie selon que vous avez démarré le proxy d'authentification Cloud SQL à l'aide d'un socket TCP ou UNIX, ou Docker.
Sockets TCP
- Démarrez le client psql :
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Même si le paramètre
sslmode
est défini surdisable
, le proxy d'authentification Cloud SQL fournit une connexion chiffrée.Lorsque vous vous connectez à l'aide de sockets TCP, l'accès au proxy d'authentification Cloud SQL s'effectue via
127.0.0.1
. - Si vous y êtes invité, saisissez le mot de passe.
- L'invite psql s'affiche.
Utiliser des sockets Unix
- Démarrez le client psql :
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
Même si le paramètre
sslmode
est défini surdisable
, le proxy d'authentification Cloud SQL fournit une connexion chiffrée. - Saisissez le mot de passe.
- L'invite psql s'affiche.
Besoin d'aide ? Pour obtenir de l'aide sur le dépannage du proxy, consultez la section Dépannage des connexions via le proxy d'authentification Cloud SQL ou la page Assistance Cloud SQL.
Étapes suivantes
- Obtenez de l'aide pour résoudre les problèmes de connexion relatifs au proxy d'authentification Cloud SQL.
- Créez des utilisateurs et des bases de données.
- Apprenez-en plus sur les adresses IP privées.
- Découvrez les options de connexion à l'instance depuis une application.
- Découvrez le client psql.
- En savoir plus sur les Options de support