Autorisation avec le proxy Cloud SQL

Cette page explique comment autoriser une connexion proxy Cloud SQL. Pour en savoir plus sur la connexion aux instances Cloud SQL à l'aide du proxy, consultez la page Présentation de la connexion. Pour en savoir plus sur le fonctionnement du proxy et obtenir des conseils sur son utilisation, consultez la page À propos du proxy Cloud SQL.

Le proxy Cloud SQL gère l'authentification avec Cloud SQL, offrant un accès sécurisé aux instances Cloud SQL sans avoir à gérer les adresses IP autorisées ni configurer les connexions SSL.

Avant de commencer

Installer le proxy Cloud SQL

Le proxy Cloud SQL est disponible en téléchargement gratuit. Des fichiers exécutables précompilés sont disponibles pour les plates-formes Linux, macOS et Windows 32 bits et 64 bits.

Linux 64 bits

  1. Téléchargez le proxy :
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Rendez le proxy exécutable :
    chmod +x cloud_sql_proxy
    

Linux 32 bits

  1. Téléchargez le proxy :
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Rendez le proxy exécutable :
    chmod +x cloud_sql_proxy
    

macOS 64 bits

  1. Téléchargez le proxy :
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Rendez le proxy exécutable :
    chmod +x cloud_sql_proxy
    

macOS 32 bits

  1. Téléchargez le proxy :
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Rendez le proxy exécutable :
    chmod +x cloud_sql_proxy
    

Windows 64 bits

Pour télécharger le proxy, effectuez un clic droit sur https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe, puis sélectionnez Enregistrer le lien sous. Renommez le fichier en cloud_sql_proxy.exe.

Windows 32 bits

Pour télécharger le proxy, effectuez un clic droit sur https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe, puis sélectionnez Enregistrer le lien sous. Renommez le fichier en cloud_sql_proxy.exe.
Si votre système d'exploitation n'apparaît pas ici, vous pouvez également compiler le proxy à partir de la source.

Activer l'API et définir des autorisations

Le proxy Cloud SQL utilise les autorisations IAM d'un utilisateur ou d'un compte de service pour authentifier votre connexion à une instance Cloud SQL.

  1. Activez l'API Cloud SQL Admin.

    Activer l'API

  2. Ajoutez un ou plusieurs rôles IAM requis à votre compte utilisateur ou compte de service :

    • Cloud SQL Client (rôle à privilégier)
    • Cloud SQL Editor
    • Cloud SQL Admin

    Vous pouvez également attribuer manuellement les autorisations IAM suivantes :

    • cloudsql.instances.connect
    • cloudsql.instances.get

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 Contrôle des accès aux projets pour Cloud SQL.

Utiliser des identifiants à partir du proxy Cloud SQL

Avant de pouvoir lancer le proxy Cloud SQL, vous devez fournir des identifiants d'utilisateur ou de compte de service que le proxy peut utiliser pour authentifier une connexion. Il existe plusieurs options pour spécifier les identifiants utilisés, et le proxy vérifie chaque option dans l'ordre suivant :

Toutes ces options utilisent une chaîne de connexion INSTANCE_CONNECTION_NAME pour identifier une instance Cloud SQL. La chaîne de connexion est au format PROJECT_ID:REGION:INSTANCE_ID. La chaîne de connexion d'une l'instance est répertoriée sur la page de présentation de cette instance.

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. Si vous devez créer un fichier d'identifiants, accédez à la page Comptes de service de votre projet dans Cloud Console, cliquez sur Actions pour le compte de service, puis sélectionnez Créez une clé pour télécharger un fichier d'identifiants JSON pour le compte de service.

Fichier d'identifiants sur la ligne de commande

Pour utiliser cette option, appelez la commande cloud_sql_proxy avec l'option -credential_file définie sur le chemin d'accès et le nom 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 -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME

Jeton d'accès sur la ligne de commande

Les jetons d'accès sont généralement utilisés pour autoriser l'accès au nom d'un compte utilisateur. Pour en savoir plus sur la création et l'utilisation de jetons d'accès OAuth 2.0, consultez la page Autoriser les requêtes.

Pour utiliser cette option, appelez le commentaire 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 -instances=INSTANCE_CONNECTION_NAME

Fichier d'identifiants provenant d'une variable d'environnement

Cette option est semblable à l'utilisation de l'indicateur -credential_file, sauf que vous spécifiez le fichier d'identifiants JSON dans la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS au lieu d'utiliser l'argument de ligne de commande -credential_file.

Identifiants utilisateur du SDK Cloud

Si vous avez installé l'outil de ligne de commande gcloud et que vous vous êtes authentifié avec votre compte personnel, le proxy 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. Dans un environnement de production, vous devez vous authentifier à l'aide de l'une des autres méthodes.

Pour authentifier le SDK Cloud, exécutez la commande gcloud auth login, sélectionnez votre compte, puis connectez-vous. Vous pouvez utiliser la commande gcloud auth list pour vérifier le compte actuellement authentifié pour le SDK Cloud.

Si aucun compte n'a été sélectionné pour gcloud auth login, le proxy recherche un compte sélectionné pour gcloud application-default login.

Compte de service par défaut de l'environnement

Si le proxy 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 Activer l'API et définir des autorisations.

Pour en savoir plus sur l'approche de Google Cloud en matière d'authentification, consultez la page Présentation de l'authentification.

Exécuter le proxy Cloud SQL

Le binaire du proxy se connecte à une ou plusieurs 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.

Des exemples d'utilisation de la ligne de commande du proxy Cloud SQL sont fournis ci-dessous.

Configurer TCP

Pour vous connecter à une instance Cloud SQL avec TCP, utilisez l'argument de ligne de commande -instances pour spécifier une liste de chaînes de connexion séparées par une virgule, chaque chaîne de connexion étant suivie d'un numéro de port TCP, comme indiqué dans cet exemple :

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

Pour les connexions TCP, le proxy écoute localhost (127.0.0.1) par défaut. Ainsi, lorsque vous spécifiez =tcp: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 écoute 0.0.0.0:1234 pour la connexion locale :

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

Pour vous connecter à plusieurs instances, vous pouvez utiliser le proxy Cloud SQL en spécifiant une liste de noms de connexion d'instance séparés par des virgules dans l'argument -instances. Chaque instance doit avoir son propre numéro de port, comme indiqué dans l'exemple suivant :

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME_1=tcp:5432,INSTANCE_CONNECTION_NAME_2=tcp:5433

Configurer un socket Unix

Le proxy Cloud SQL peut également écouter sur un socket Unix, un mécanisme standard de Posix 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 et l'application doivent également disposer tous les deux d'un accès en lecture et en écriture. Pour créer un répertoire et définir les autorisations requises, utilisez les commandes suivantes :

sudo mkdir ~/cloudsql
sudo chmod a+rw /cloudsql

Il existe deux options pour spécifier le répertoire de socket lors du lancement du proxy. L'une de ces options consiste à utiliser l'argument de ligne de commande -dir, comme indiqué ci-dessous :

./cloud_sql_proxy -dir=PATH_TO_TARGET_FOLDER -instances=INSTANCE_CONNECTION_NAME

Vous pouvez également ajouter le répertoire de socket à l'argument de chaîne de connexion :

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=unix:/PATH_TO_TARGET_FOLDER

Choisir une adresse IP publique ou privée

Par défaut, les instances Cloud SQL utilisent la connectivité IP publique, mais vous pouvez également configurer une instance pour qu'elle soit compatible avec la connectivité IP privée. L'adresse IP privée utilise des adresses IP internes hébergées dans un réseau VPC, qui ne sont accessibles qu'à partir d'autres ressources du même réseau VPC. Les avantages de l'adresse IP privée incluent une sécurité accrue, car le trafic IP n'est jamais exposé à Internet, et des performances accrues, car l'adresse IP privée offre une latence plus faible que l'adresse IP publique dans certains scénarios.

Pour configurer votre instance Cloud SQL afin qu'elle utilise une adresse IP privée, consultez la page Configurer une adresse IP privée.

L'option de ligne de commande -ip_address_types du proxy spécifie l'ordre préféré des adresses IP lors de la connexion à une instance Cloud SQL. Le paramètre par défaut est -ip_address_types=PUBLIC,PRIVATE, ce qui signifie que le proxy tente de se connecter à une adresse IP publique si l'adresse IP publique est activée sur l'instance, puis à une adresse IP privée si l'adresse IP privée est activée. Pour spécifier que le proxy ne tente de se connecter qu'à une adresse IP privée, utilisez l'option -ip_address_types=PRIVATE comme indiqué dans cet exemple :

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:5432 -ip_address_types=PRIVATE

Autres arguments de ligne de commande

Les exemples ci-dessus couvrent les cas d'utilisation les plus courants, mais le proxy 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 Cloud SQL, consultez le fichier README sur le dépôt GitHub du proxy Cloud SQL.

Informations supplémentaires

Exécuter le proxy dans un processus distinct

L'exécution du proxy Cloud SQL dans un processus de terminal 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 dans un processus distinct.

Linux

Sous Linux ou macOS, utilisez & à la fin de la ligne de commande pour lancer le proxy dans un processus distinct :

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

Dans Windows PowerShell, utilisez la commande Start-Process pour lancer le proxy dans un processus distinct :

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Exécuter le proxy Cloud SQL dans un conteneur Docker

Pour exécuter le proxy Cloud SQL dans un conteneur Docker, utilisez l'image Docker du proxy disponible dans Google Container Registry. Vous pouvez installer l'image Docker du proxy à l'aide de la commande gcloud :

docker pull gcr.io/cloudsql-docker/gce-proxy:1.16

Vous pouvez démarrer le proxy à l'aide de sockets TCP ou Unix, à l'aide des commandes indiquées ci-dessous.

Sockets TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/config \
  -p 127.0.0.1:5432:5432 \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy \
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 \
  -credential_file=/config

Sockets Unix

docker run -d \
  -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
  -v PATH_TO_KEY_FILE:/config \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy -dir=/cloudsql \
  -instances=INSTANCE_CONNECTION_NAME
  -credential_file=/config/PATH_TO_KEY_FILE

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:/config</span>.

Exécuter le proxy Cloud SQL en tant que service

L'exécution du proxy en tant que service d'arrière-plan peut être pratique pour le développement et les tests locaux. 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é.

Windows

Le proxy 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 en tant que service Windows. NSSM surveille le proxy et le redémarre automatiquement s'il cesse de répondre. Pour plus d'informations, consultez la documentation NSSM.

Étapes suivantes