Se connecter à l'aide du proxy d'authentification Cloud SQL

Cette page explique comment se connecter à votre instance Cloud SQL en utilisant le proxy d'authentification Cloud SQL.

Pour en savoir plus sur le fonctionnement du proxy d'authentification Cloud SQL, consultez la page À propos du proxy d'authentification Cloud SQL.

Présentation

L'utilisation du proxy d'authentification Cloud SQL est la méthode recommandée pour se connecter à une instance Cloud SQL. Le proxy d'authentification Cloud SQL :

  • fonctionne avec les points de terminaison d'adresses IP publiques et privées ;
  • valide les connexions à l'aide des identifiants d'un utilisateur ou d'un compte de service ;
  • encapsule la connexion dans une couche SSL/TLS autorisée pour une instance Cloud SQL.

Certains services et applications Google Cloud utilisent le proxy d'authentification Cloud SQL pour fournir des connexions aux chemins d'accès des adresses IP publiques avec chiffrement et autorisation, y compris :

Les applications exécutées dans Google Kubernetes Engine peuvent se connecter à l'aide du proxy d'authentification Cloud SQL.

Pour une présentation rapide de son utilisation, reportez-vous au Guide de démarrage rapide pour l'utilisation du proxy d'authentification Cloud SQL.

Vous pouvez également vous connecter, avec ou sans proxy d'authentification Cloud SQL, à l'aide d'un client psql à partir d'une machine locale ou de Compute Engine.

Avant de commencer

Pour pouvoir vous connecter à une instance Cloud SQL, procédez comme suit :

    • Pour un utilisateur ou un compte de service, assurez-vous que le compte dispose du rôle Client Cloud SQL. Ce rôle contient l'autorisation cloudsql.instances.connect, qui autorise un compte principal à se connecter à toutes les instances Cloud SQL d'un projet.

      Accéder à la page IAM

    • Vous pouvez éventuellement inclure une condition IAM dans la liaison de stratégie IAM qui autorise le compte à se connecter à une seule instance Cloud SQL spécifique.
  1. Activez l'API Cloud SQL Admin

    Activer l'API

  2. Installez et initialisez gcloud CLI.
  3. Facultatif. Installez le client Docker du proxy d'authentification Cloud SQL.

Télécharger le proxy d'authentification Cloud SQL

Linux 64 bits

  1. 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.10.1/cloud-sql-proxy.linux.amd64
    
  2. Rendez le proxy d'authentification Cloud SQL exécutable :
    chmod +x cloud-sql-proxy
    

Linux 32 bits

  1. 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.10.1/cloud-sql-proxy.linux.386
    
  2. Si la commande curl est introuvable, exécutez sudo apt install curl puis répétez la commande de téléchargement.
  3. Rendez le proxy d'authentification Cloud SQL exécutable :
    chmod +x cloud-sql-proxy
    

macOS 64 bits

  1. 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.10.1/cloud-sql-proxy.darwin.amd64
    
  2. Rendez le proxy d'authentification Cloud SQL exécutable :
    chmod +x cloud-sql-proxy
    

Mac M1

  1. 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.10.1/cloud-sql-proxy.darwin.arm64
      
  2. 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.10.1/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 en cloud-sql-proxy.exe.

Windows 32 bits

Effectuez un clic droit sur https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/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 en cloud-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.10.1

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.

Démarrer 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
  1. Copiez le nom de connexion de votre instance (INSTANCE_CONNECTION_NAME). Vous le trouverez sur la page Présentation de votre instance dans Google Cloud Console ou en exécutant la commande suivante :

        gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
    .

    Exemple : myproject:myregion:myinstance.

  2. 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
  3. 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.
  4. 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 les sections Options du proxy d'authentification Cloud SQL et Options de spécification d'instances.

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.

  1. Si vous utilisez une spécification explicite d'instance, copiez la chaîne de connexion INSTANCE_CONNECTION_NAME. Pour la trouver, accédez à la page Présentation de votre instance dans la console Google Cloud ou exécutez la commande suivante :

    gcloud sql instances describe INSTANCE_NAME  --format='value(connectionName)'

    Exemple : myproject:myregion:myinstance.

  2. Créez le répertoire où se situeront les sockets du proxy d'authentification Cloud SQL :
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. 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.
  4. 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 :

    • Utilisez un compte de service et incluez explicitement le nom de la connexion à l'instance (recommandé pour les environnements de production) :
      ./cloud-sql-proxy --unix-socket /cloudsql
      --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
    • Avec l'authentification via le SDK Cloud et la détection automatique d'instances :
      ./cloud-sql-proxy --unix-socket /cloudsql &

    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 les sections Options du proxy d'authentification Cloud SQL et Options de spécification d'instances.

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.10.1 \\
  --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.10.1 --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.

Se connecter à l'aide du client psql

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

  1. Téléchargez PostgreSQL Core Distribution sur votre plate-forme depuis la page des téléchargements PostgreSQL.
    Core Distribution inclut le client psql.
  2. Installez la base de données PostgreSQL en suivant les instructions de la page de téléchargement.

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

  1. 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 sur disable, 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.

  2. Si vous y êtes invité, saisissez le mot de passe.
  3. L'invite psql s'affiche.

Utiliser des sockets Unix

  1. 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 sur disable, le proxy d'authentification Cloud SQL fournit une connexion chiffrée.

  2. Saisissez le mot de passe.
  3. 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.

Se connecter avec une application

Vous pouvez vous connecter au proxy d'authentification Cloud SQL au moyen de n'importe quel langage permettant la connexion à un socket Unix ou TCP. Vous trouverez ci-dessous des extraits de code tirés d'exemples complets disponibles sur GitHub pour vous aider à comprendre comment ils fonctionnent ensemble dans votre application.

Autres sujets

Arguments de ligne de commande du proxy d'authentification Cloud SQL

Les exemples ci-dessus couvrent les cas d'utilisation les plus courants, mais le proxy d'authentification Cloud SQL propose d'autres options de configuration pouvant être définies avec des arguments de ligne de commande. Pour obtenir de l'aide sur les arguments de ligne de commande, utilisez l'option --help pour consulter la dernière documentation :

./cloud-sql-proxy --help

Pour obtenir d'autres exemples sur l'utilisation des options de ligne de commande du proxy d'authentification Cloud SQL, consultez le fichier README sur le dépôt GitHub du proxy d'authentification Cloud SQL.

Options d'authentification du proxy d'authentification Cloud SQL

Toutes ces 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 --project PROJECT_ID INSTANCE_CONNECTION_NAME

Par exemple : gcloud sql instances describe --project myproject myinstance.

Certaines de ces options utilisent un fichier d'identifiants JSON qui inclut la clé privée RSA du compte. Pour obtenir des instructions sur la création d'un fichier d'identifiants JSON pour un compte de service, consultez la page Créer un compte de service.

Le proxy d'authentification Cloud SQL propose plusieurs alternatives pour l'authentification, en fonction de votre environnement. Le proxy d'authentification Cloud SQL recherche chacun des éléments suivants, dans cet ordre, et effectue une tentative d'authentification avec le premier qu'il trouve :

  1. Identifiants fournis par l'option credential_file

    Utilisez un compte de service pour créer et télécharger le fichier JSON associé, et définissez l'option --credentials-file sur le chemin du fichier lorsque vous démarrez le proxy d'authentification Cloud SQL. Le compte de service doit disposer des autorisations requises pour l'instance Cloud SQL.

    Pour utiliser cette option sur la ligne de commande, appelez la commande cloud-sql-proxy avec l'option --credentials-file définie sur le chemin d'accès et le nom de fichier d'un fichier d'identifiants JSON. Le chemin d'accès peut être absolu, ou relatif au répertoire de travail actuel. Exemple :

    ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
    INSTANCE_CONNECTION_NAME
      

    Pour obtenir des instructions détaillées sur l'ajout de rôles IAM à un compte de service, consultez la page Attribuer des rôles aux comptes de service.

    Pour en savoir plus sur les rôles acceptés par Cloud SQL, consultez la page Rôles IAM pour Cloud SQL.

  2. Identifiants fournis par un jeton d'accès

    Créez un jeton d'accès et appelez la commande cloud-sql-proxy avec l'option --token définie sur un jeton d'accès OAuth 2.0. Exemple :
    ./cloud-sql-proxy --token ACCESS_TOKEN \
    INSTANCE_CONNECTION_NAME
      
  3. Identifiants fournis par une variable d'environnement

    Cette option est semblable à l'utilisation de l'option --credentials-file, sauf que vous spécifiez le fichier d'identifiants JSON que vous définissez dans la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS au lieu d'utiliser l'argument de ligne de commande --credentials-file.
  4. Identifiants d'un client gcloud CLI authentifié.

    Si vous avez installé gcloud CLI et que vous vous êtes authentifié avec votre compte personnel, le proxy d'authentification Cloud SQL peut utiliser les mêmes identifiants de compte. Cette méthode est particulièrement utile pour rendre opérationnel un environnement de développement.

    Pour permettre au proxy d'authentification Cloud SQL d'utiliser vos identifiants de gcloud CLI, exécutez la commande suivante pour authentifier gcloud CLI :

    gcloud auth application-default login
  5. Identifiants associés à l'instance Compute Engine

    Si vous vous connectez à Cloud SQL depuis une instance Compute Engine, le proxy d'authentification Cloud SQL peut utiliser le compte de service associé à celle-ci. Si le compte de service dispose des autorisations requises pour l'instance Cloud SQL, l'authentification du proxy d'authentification Cloud SQL aboutit.

    Si l'instance Compute Engine se trouve dans le même projet que l'instance Cloud SQL, le compte de service par défaut de l'instance Compute Engine dispose des autorisations nécessaires pour authentifier le proxy d'authentification Cloud SQL. Si ces deux instances sont dans des projets différents, vous devez ajouter le compte de service de l'instance Compute Engine au projet contenant l'instance Cloud SQL.

  6. Compte de service par défaut de l'environnement

    Si le proxy d'authentification Cloud SQL ne trouve pas les identifiants dans l'un des emplacements abordés précédemment, il suit la logique décrite dans la section Configurer l'authentification pour les applications de production serveur à serveur. Certains environnements (tels que Compute Engine, App Engine et d'autres) fournissent un compte de service par défaut que votre application peut utiliser pour s'authentifier par défaut. Si vous utilisez un compte de service par défaut, celui-ci doit disposer des autorisations décrites dans la section Rôles et autorisations. Pour en savoir plus sur l'approche de Google Cloud en matière d'authentification, consultez la page Présentation de l'authentification.

Créer un compte de service

  1. Dans Google Cloud Console, accédez à la page Comptes de service.

    Accéder à la page "Comptes de service"

  2. Sélectionnez le projet contenant l'instance Cloud SQL.
  3. Cliquez sur Créer un compte de service.
  4. Dans le champ Nom du compte de service, attribuez un nom descriptif au compte de service.
  5. Remplacez l'ID du compte de service par une valeur unique et facilement reconnaissable, puis cliquez sur Créer et continuer.
  6. 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
  7. Cliquez sur OK pour terminer la création du compte de service.
  8. Cliquez sur le menu Action de votre nouveau compte de service, puis sélectionnez Gérer les clés.
  9. Cliquez sur le menu déroulant Ajouter une clé, puis sur Créer une clé.
  10. 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é à un endroit sécurisé.

Utiliser le proxy d'authentification Cloud SQL avec une adresse IP privée

Pour permettre la connexion à une instance Cloud SQL à l'aide d'une adresse IP privée, le proxy d'authentification Cloud SQL doit se trouver sur une ressource ayant accès au même réseau VPC que l'instance.

Le proxy d'authentification Cloud SQL utilise une adresse IP pour établir une connexion avec votre instance Cloud SQL. Par défaut, le proxy d'authentification Cloud SQL tente de se connecter à l'aide d'une adresse IPv4 publique.

Si votre instance Cloud SQL n'a qu'une adresse IP privée ou si l'instance est configurée à la fois avec une adresse IP publique et une adresse IP privée, 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

Utiliser le proxy d'authentification Cloud SQL avec des instances sur lesquelles Private Service Connect est activé

Vous pouvez utiliser le proxy d'authentification Cloud SQL pour vous connecter à une instance Cloud SQL avec Private Service Connect activé.

Le proxy d'authentification Cloud SQL est un connecteur qui fournit un accès sécurisé à cette instance sans nécessiter de réseaux autorisés ni de configuration SSL.

Pour autoriser les connexions client via le proxy d'authentification Cloud SQL, vous devez configurer un enregistrement DNS correspondant au nom DNS recommandé fourni pour l'instance. L'enregistrement DNS est un mappage entre une ressource DNS et un nom de domaine.

Pour en savoir plus sur l'utilisation du proxy d'authentification Cloud SQL pour vous connecter à des instances avec Private Service Connect activé, consultez la section Se connecter à l'aide du proxy d'authentification Cloud SQL.

Exécuter le proxy d'authentification Cloud SQL dans un processus distinct

L'exécution du proxy d'authentification Cloud SQL dans un processus de terminal Cloud Shell distinct peut être utile pour éviter de mélanger le résultat de la console avec le résultat d'autres programmes. Utilisez la syntaxe ci-dessous pour appeler le proxy d'authentification Cloud SQL dans un processus distinct.

Linux

Sous Linux ou macOS, insérez un & final sur la ligne de commande pour lancer le proxy d'authentification Cloud SQL dans un processus distinct :

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

Dans Windows PowerShell, utilisez la commande Start-Process pour lancer le proxy d'authentification Cloud SQL dans un processus distinct :

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Exécuter le proxy d'authentification Cloud SQL dans un conteneur 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 installer l'image Docker du proxy d'authentification Cloud SQL à l'aide de la commande gcloud suivante :

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1

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.

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.10.1 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Sockets Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

Si vous utilisez une image optimisée pour les conteneurs, utilisez un répertoire avec accès en écriture à la place de /cloudsql, par exemple :

v /mnt/stateful_partition/cloudsql:/cloudsql

Si vous utilisez les identifiants fournis par votre instance Compute Engine, n'incluez pas le paramètre credential_file ni la ligne -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Exécuter le proxy d'authentification Cloud SQL en tant que service

L'exécution du proxy d'authentification Cloud SQL en tant que service d'arrière-plan est une option pour les charges de travail de développement et de production locales. En phase de développement, lorsque vous devez accéder à votre instance Cloud SQL, vous pouvez démarrer le service en arrière-plan et l'arrêter lorsque vous avez terminé.

Pour les charges de travail de production, le proxy d'authentification Cloud SQL ne fournit actuellement pas d'assistance intégrée pour l'exécution en tant que service Windows, mais des gestionnaires de services tiers peuvent être utilisés pour l'exécuter en tant que service. Par exemple, vous pouvez utiliser NSSM pour configurer le proxy d'authentification Cloud SQL en tant que service Windows afin que NSSM surveille le proxy d'authentification Cloud SQL et le redémarre automatiquement s'il cesse de répondre. Pour plus d'informations, consultez la documentation NSSM.

Imposer l'utilisation du proxy d'authentification Cloud SQL

Activez l'utilisation du proxy d'authentification Cloud SQL dans Cloud SQL à l'aide de ConnectorEnforcement.

gcloud

La commande suivante impose l'utilisation de connecteurs Cloud SQL.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

Pour désactiver cette application forcée, utilisez la ligne de code suivante : --connector-enforcement NOT_REQUIRED. La mise à jour ne déclenche pas de redémarrage.

REST v1

La commande suivante impose l'utilisation de connecteurs Cloud SQL.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • project-id : ID du projet
  • instance-id : ID de l'instance.

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Pour désactiver cette application forcée, utilisez plutôt "connectorEnforcement": "NOT_REQUIRED". La mise à jour ne déclenche pas de redémarrage.

REST v1beta4

La commande suivante impose l'utilisation de connecteurs Cloud SQL.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • project-id : ID du projet
  • instance-id : ID de l'instance.

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Pour désactiver cette application forcée, utilisez plutôt "connectorEnforcement": "NOT_REQUIRED". La mise à jour ne déclenche pas de redémarrage.

Conseils d'utilisation du proxy d'authentification Cloud SQL

Appeler le proxy d'authentification Cloud SQL

Tous les exemples d'appels du proxy démarrent le proxy Cloud SQL en arrière-plan, ce qui implique qu'une invite est renvoyée. Réservez ce terminal Cloud Shell au proxy d'authentification Cloud SQL afin d'éviter que sa sortie ne soit mélangée à celle d'autres programmes. La sortie du proxy d'authentification Cloud SQL peut vous aider à diagnostiquer les problèmes de connexion et il peut donc être utile de l'enregistrer dans un fichier journal. Si vous ne démarrez pas le proxy d'authentification Cloud SQL en arrière-plan, la sortie est transmise à stdout à moins d'être redirigée.

Vous n'avez pas besoin d'utiliser /cloudsql comme répertoire pour les sockets du proxy d'authentification Cloud SQL. (Ce nom de répertoire a été choisi de façon à réduire au minimum les différences avec les chaînes de connexion App Engine.) Toutefois, si vous modifiez le nom du répertoire, limitez-en au maximum la longueur totale. En effet, ce nom est incorporé dans une chaîne plus longue présentant une limite de longueur imposée par le système d'exploitation. Cela dépend du système, mais il comporte généralement entre 91 et 108 caractères. Sous Linux, la longueur est généralement définie sur 108 caractères, et vous pouvez la vérifier à l'aide de la commande suivante :

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Utiliser le proxy d'authentification Cloud SQL pour se connecter à plusieurs instances

Vous pouvez utiliser un client proxy Cloud SQL local pour vous connecter à plusieurs instances Cloud SQL. La marche à suivre varie selon que vous utilisez des sockets Unix ou TCP.

Sockets Unix

Pour connecter le proxy d'authentification Cloud SQL à plusieurs instances, vous devez indiquer chaque nom de connexion d'instance en tant qu'argument au proxy d'authentification Cloud SQL, dans une liste d'éléments séparés par des espaces. Le proxy Cloud SQL se connecte à chaque instance au démarrage.

Vous vous connectez à chaque instance à l'aide de son socket, dans le répertoire spécifié.

Exemple :

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

Sockets TCP

Lorsque vous vous connectez à l'aide de TCP, vous devez spécifier un port sur votre machine via lequel le proxy d'authentification Cloud SQL doit écouter pour chaque instance Cloud SQL. Lorsque vous vous connectez à plusieurs instances Cloud SQL, chaque port spécifié doit être unique et disponible sur votre machine.

Par exemple :

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Appels du proxy d'authentification Cloud SQL et chaînes de connexion au client psql

Vous pouvez utiliser les appels du proxy d'authentification Cloud SQL et les chaînes de connexion, par exemple dans les commandes pour un utilisateur PostgreSQL myUser pour l'instance myInstance située dans us-central1 dans le projet myProject.

En utilisant la détection automatique d'instances avec des identifiants gcloud CLI :
    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
 
En utilisant la détection de projets avec des identifiants gcloud CLI :
    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Pour une instance Compute Engine, avec spécification explicite d'instances :
    ./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Pour Unix, en utilisant TCP :
    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" &
    psql -U myUser -h 127.0.0.1
Pour Windows (à l'invite de ligne de commande) :
    cloud-sql-proxy.exe "myProject:us-central1:myInstance?port=5432"
    psql -U myUser -h 127.0.0.1

Pour en savoir plus sur les chaînes de connexion et les options du proxy d'authentification Cloud SQL, consultez la page GitHub relative au proxy d'authentification Cloud SQL.

Résoudre les problèmes de connexion via le proxy d'authentification Cloud SQL

L'image Docker du proxy d'authentification Cloud SQL est basée sur une version spécifique du proxy d'authentification Cloud SQL. Lorsqu'une nouvelle version du proxy d'authentification Cloud SQL est disponible, vous devez extraire la nouvelle version de l'image Docker du proxy afin de maintenir votre environnement à jour. Pour savoir quelle est la version actuelle du proxy d'authentification Cloud SQL, consultez la page GitHub relative aux versions du proxy d'authentification Cloud SQL.

Si vous ne parvenez pas à vous connecter à votre instance Cloud SQL à l'aide du proxy d'authentification Cloud SQL, voici quelques conseils qui pourraient vous permettre de trouver la cause du problème.

  • Vérifiez la sortie du proxy d'authentification Cloud SQL.

    Souvent, la sortie du proxy d'authentification Cloud SQL peut vous aider à déterminer la source du problème et à le résoudre. Dirigez la sortie vers un fichier, ou surveillez le terminal Cloud Shell dans lequel vous avez démarré le proxy d'authentification Cloud SQL.

  • Si vous obtenez une erreur 403 notAuthorized et que vous authentifiez le proxy Cloud SQL à l'aide d'un compte de service, assurez-vous que celui-ci dispose des autorisations appropriées.

    Pour vérifier le compte de service, recherchez son ID sur la page IAM. Il doit disposer de l'autorisation cloudsql.instances.connect. Les rôles prédéfinis Cloud SQL Admin, Client et Editor disposent de cette autorisation.

  • Si vous vous connectez à partir d'App Engine et que vous obtenez une erreur 403 notAuthorized, recherchez un nom de connexion d'instance mal orthographié ou incorrect dans la valeur app.yamlcloud_sql_instances. Les noms de connexion d'instance sont toujours au format PROJECT:REGION:INSTANCE.

    Vérifiez également que le compte de service App Engine (par exemple, $PROJECT_ID@appspot.gserviceaccount.com) dispose du rôle IAM du client Cloud SQL.

    Si le service App Engine se trouve dans un projet (projet A) et que la base de données se trouve dans un autre (projet B), cette erreur signifie que le rôle IAM du client Cloud SQL n'a pas été attribué au compte de service App Engine dans le projet avec la base de données (projet B).

  • Assurez-vous d'avoir activé l'API Cloud SQL Admin.

    Si ce n'est pas le cas, une sortie semblable à Error 403: Access Not Configured s'affiche dans les journaux du proxy d'authentification Cloud SQL.

  • Si la liste d'instances comprend plusieurs instances, veillez à les séparer par une virgule, sans inclure d'espaces. Si vous utilisez le protocole TCP, assurez-vous de spécifier des ports différents pour chaque instance.

  • Si vous vous connectez à l'aide de sockets UNIX, vérifiez qu'ils ont été créés en utilisant le répertoire que vous avez fourni lors du démarrage du proxy d'authentification Cloud SQL.

  • Si vous disposez de règles de pare-feu sortantes, assurez-vous qu'elles autorisent les connexions au port 3307 sur l'instance Cloud SQL cible.

  • Vous pouvez vérifier que le proxy d'authentification Cloud SQL a démarré correctement en consultant les journaux dans la section Opérations > Journalisation > Explorateur de journaux de Google Cloud Console. Une opération réussie ressemble à ce qui suit :

    2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
    2021/06/14 15:47:56 Ready for new connections
    
  • Problèmes de quotas : lorsque le quota de l'API Cloud SQL Admin est dépassé, le proxy d'authentification Cloud SQL démarre avec le message d'erreur suivant :

    There was a problem when parsing a instance configuration but ignoring due
    to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
    metric 'Queries' and limit 'Queries per minute per user' of service
    'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
    rateLimitExceeded
    

    Une fois qu'une application se connecte au proxy, celui-ci signale l'erreur suivante :

    failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
    googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
    'Queries per minute per user' of service 'sqladmin.googleapis.com' for
    consumer 'project_number:$PROJECT_ID., rateLimitExceeded
    

    Solution : identifiez l'origine du problème de quota. Par exemple, une application utilise de manière abusive le connecteur et crée inutilement des connexions. Vous pouvez également contacter l'assistance pour demander une augmentation du quota de l'API Cloud SQL Admin. Si l'erreur de quota apparaît au démarrage, vous devez redéployer l'application pour redémarrer le proxy. Si l'erreur de quota apparaît après le démarrage, un redéploiement est inutile.

Étapes suivantes