Über den Cloud SQL Auth-Proxy verbinden

Auf dieser Seite wird beschrieben, wie Sie einen MySQL-Client über den Cloud SQL Auth-Proxy mit einer Cloud SQL-Instanz verbinden.

Informationen zum Herstellen einer Verbindung eines mysql-Clients zu einer Cloud SQL-Instanz über öffentliche IP-Adressen finden Sie unter Verbindung über einen Datenbankclient herstellen.

Weitere Informationen über die Funktionsweise des Proxys finden Sie unter Informationen zum Cloud SQL Auth-Proxy.

Hinweis

Bevor Sie einen MySQL-Client mit einer Cloud SQL-Instanz verbinden können, müssen folgende Bedingungen erfüllt sein:

Authentifizierungsoptionen für Cloud SQL Auth-Proxy

Alle diese Optionen verwenden einen INSTANCE_CONNECTION_NAME als Verbindungsstring, um eine Cloud SQL-Instanz zu identifizieren. Sie finden den INSTANCE_CONNECTION_NAME auf der Seite Übersicht Ihrer Instanz in der Google Cloud Console oder ermitteln ihn über folgenden Befehl:

gcloud sql instances describe INSTANCE_NAME.

Beispiel: myproject:myregion:myinstance.

Einige dieser Optionen verwenden eine JSON-Datei mit Anmeldedaten, die den privaten RSA-Schlüssel für das Konto enthält. Eine Anleitung zum Erstellen einer JSON-Datei mit Anmeldedaten für ein Dienstkonto finden Sie unter Dienstkonto erstellen und Schlüsseldatei generieren.

Der Cloud SQL Auth-Proxy bietet abhängig von der Umgebung mehrere alternative Authentifizierungsoptionen. Der Cloud SQL Auth-Proxy prüft das Vorhandensein der folgenden Elemente in der unten angeführten Reihenfolge und verwendet das erste Element, das er findet, für die Authentifizierung:

  1. Vom Flag credential_file bereitgestellte Anmeldedaten

    Erstellen Sie mit einem Dienstkonto die zugehörige JSON-Datei, laden Sie sie herunter und setzen Sie das Flag -credential_file auf den Pfad der Datei, wenn Sie den Cloud SQL Auth-Proxy starten. Das Dienstkonto muss die erforderlichen Berechtigungen für die Cloud SQL-Instanz haben.

    Wenn Sie diese Option in der Befehlszeile verwenden möchten, rufen Sie den Befehl cloud_sql_proxy auf, wobei das Flag -credential_file auf den Pfad und den Dateinamen einer JSON-Anmeldedatendatei festgelegt ist. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Beispiele:

    ./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME
      

    Eine ausführliche Anleitung zum Hinzufügen von IAM-Rollen zu einem Dienstkonto finden Sie unter Dienstkonten Rollen zuweisen.

    Weitere Informationen zu den von Cloud SQL unterstützten Rollen finden Sie unter Projektzugriffssteuerung für Cloud SQL.

  2. Von einem Zugriffstoken bereitgestellte Anmeldedaten

    Erstellen Sie ein Zugriffstoken und rufen Sie den Befehl cloud_sql_proxy mit dem auf ein OAuth 2.0-Zugriffstoken gesetzten Flag -token auf. Beispiele:
    ./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME
      
  3. Von einer Umgebungsvariable bereitgestellte Anmeldedaten.

    Diese Option ähnelt der Verwendung des Flags -credential_file, mit dem Unterschied, dass Sie die JSON-Anmeldedatendatei angeben, die Sie in der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festgelegt haben, anstatt das Befehlszeilenargument -credential_file zu verwenden.
  4. Anmeldedaten eines authentifizierten Cloud SDK-Clients

    Wenn Sie das Cloud-Befehlszeilentool installiert und sich mit Ihrem privaten Konto authentifiziert haben, kann der Cloud SQL Auth-Proxy dieselben Kontoanmeldedaten verwenden. Diese Methode ist besonders hilfreich, um eine Entwicklungsumgebung einzurichten und auszuführen.

    Wenn kein Konto für gcloud auth login ausgewählt wurde, prüft der Cloud SQL Auth-Proxy, ob für gcloud auth application-default login ein Konto ausgewählt wurde.

  5. Zur Compute Engine-Instanz gehörende Anmeldedaten

    Wenn Sie eine Verbindung zu Cloud SQL von einer Compute Engine-Instanz herstellen, kann der Cloud SQL Auth-Proxy das Dienstkonto verwenden, das mit der Compute Engine-Instanz verknüpft ist. Wenn das Dienstkonto die erforderlichen Berechtigungen für die Cloud SQL-Instanz hat, wird der Cloud SQL Auth-Proxy erfolgreich authentifiziert.

    Wenn sich die Compute Engine-Instanz im selben Projekt wie die Cloud SQL-Instanz befindet, hat das standardmäßige Dienstkonto die erforderlichen Berechtigungen zur Authentifizierung des Cloud SQL Auth-Proxys. Wenn sich die beiden Instanzen in verschiedenen Projekten befinden, müssen Sie das Dienstkonto der Compute Engine-Instanz dem Projekt hinzufügen, das die Cloud SQL-Instanz enthält.

  6. Standarddienstkonto der Umgebung

    Wenn der Cloud SQL Auth-Proxy keine Anmeldedaten an einem der zuvor erwähnten Orte finden kann, folgt er der Vorgehensweise, die unter Authentifizierung für Server-zu-Server-Produktionsanwendungen einrichten dokumentiert ist. Einige Umgebungen (z. B. Compute Engine, App Engine und andere) bieten ein Standarddienstkonto, mit dem sich Ihre Anwendung standardmäßig authentifizieren kann. Wenn Sie ein Standarddienstkonto verwenden, muss es die Berechtigungen enthalten, die unter Rollen und Berechtigungen aufgeführt sind. Weitere Informationen über den Google Cloud-Authentifizierungsansatz finden Sie unter Authentifizierung – Übersicht.

Dienstkonto erstellen

  1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.

    Zur Seite "Dienstkonten"

  2. Wählen Sie das Projekt aus, in dem sich die Cloud SQL-Instanz befindet.
  3. Klicken Sie auf Dienstkonto erstellen.
  4. Geben Sie in das Dialogfeld Dienstkonto erstellen einen aussagekräftigen Namen für das Dienstkonto ein.
  5. Ändern Sie die Dienstkonto-ID in einen eindeutigen, erkennbaren Wert und klicken Sie dann auf Erstellen.
  6. Wählen Sie für Rolle eine der folgenden Rollen aus, klicken Sie auf Weiter und dann auf Fertig:
    • Cloud SQL > Cloud SQL-Client
    • Cloud SQL > Cloud SQL-Bearbeiter
    • Cloud SQL > Cloud SQL-Administrator
  7. Klicken Sie auf das Aktionsmenü für das neue Dienstkonto und wählen Sie Schlüssel verwalten aus.
  8. Klicken Sie auf das Drop-down-Menü Schlüssel hinzufügen und dann auf Neuen Schlüssel erstellen.
  9. Prüfen Sie, ob der Schlüsseltyp JSON ist, und klicken Sie dann auf Erstellen.

    Die Datei mit dem privaten Schlüssel wird auf Ihren Computer heruntergeladen. Sie können die Datei an einen anderen Speicherort verschieben. Bewahren Sie die Schlüsseldatei sicher auf.

Cloud SQL Auth-Proxy installieren

Linux 64-Bit

  1. Laden Sie den Cloud SQL Auth-Proxy herunter:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:
    chmod +x cloud_sql_proxy
    

Linux 32-Bit

  1. Laden Sie den Cloud SQL Auth-Proxy herunter:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:
    chmod +x cloud_sql_proxy
    

macOS 64-Bit

  1. Laden Sie den Cloud SQL Auth-Proxy herunter:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:
    chmod +x cloud_sql_proxy
    

macOS 32-Bit

  1. Laden Sie den Cloud SQL Auth-Proxy herunter:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Machen Sie den Cloud SQL Auth-Proxy ausführbar:
    chmod +x cloud_sql_proxy
    

Windows 64-Bit

Klicken Sie mit der rechten Maustaste auf https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe, wählen Sie Link speichern unter aus und laden Sie den Cloud SQL Auth-Proxy herunter. Benennen Sie die Datei in cloud_sql_proxy.exe um.

Windows 32-Bit

Klicken Sie mit der rechten Maustaste auf https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe, wählen Sie Link speichern unter aus und laden Sie den Cloud SQL Auth-Proxy herunter. Benennen Sie die Datei in cloud_sql_proxy.exe um.

Docker-Image des Cloud SQL Auth-Proxys

Das Cloud SQL-Team verwaltet zur Vereinfachung mehrere Container-Images, die den Cloud SQL Auth-Proxy zur Verwendung durch unsere Kunden enthalten. Weitere Informationen zu diesen Images finden Sie im Cloud SQL Auth-Proxy-Repository auf GitHub. Mit folgendem Befehl können Sie das neueste Image mithilfe von Docker auf Ihren lokalen Computer übertragen:
docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Andere Betriebssysteme

Für andere Betriebssysteme, die hier nicht aufgeführt sind, können Sie den Cloud SQL Auth-Proxy aus der Quelle kompilieren.

Cloud SQL Auth-Proxy starten

Je nach verwendeter Programmiersprache und Umgebung können Sie den Cloud SQL Auth-Proxy entweder mit TCP-Sockets, mit Unix-Sockets oder mit dem Cloud SQL Auth-Docker-Proxy-Image starten. Das Cloud SQL Auth-Proxy-Binärprogramm stellt eine Verbindung zu einer oder mehreren Cloud SQL-Instanzen her, die in der Befehlszeile angegeben sind, und öffnet eine lokale Verbindung als TCP- oder Unix-Socket. Andere Anwendungen und Dienste, z. B. Ihre Anwendungscode- oder Datenbankverwaltungs-Clienttools, können über diese TCP- oder Unix-Socket-Verbindungen eine Verbindung zu Cloud SQL-Instanzen herstellen.

TCP-Sockets

Bei TCP-Verbindungen beobachtet der Cloud SQL Auth-Proxy standardmäßig localhost(127.0.0.1). Wenn Sie also tcp:PORT_NUMBER für eine Instanz angeben, befindet sich die lokale Verbindung auf 127.0.0.1:PORT_NUMBER.

Alternativ können Sie eine andere Adresse für die lokale Verbindung angeben. So können Sie zum Beispiel den Cloud SQL-Auth-Proxy dazu bringen, die lokale Verbindung auf 0.0.0.0:1234 zu beobachten:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234
  1. Kopieren Sie Ihren INSTANCE_CONNECTION_NAME. Sie finden ihn in der Google Cloud Console auf der Seite Übersicht für Ihre Instanz oder über den folgenden Befehl:

    gcloud sql instances describe INSTANCE_NAME
    .

    Beispiel: myproject:myregion:myinstance.

  2. Wenn für die Instanz sowohl eine öffentliche als auch eine private IP-Adresse konfiguriert ist und der Cloud SQL Auth-Proxy die private IP-Adresse verwenden soll, müssen Sie beim Starten des Cloud SQL Auth-Proxys folgende Option angeben:
    -ip_address_types=PRIVATE
  3. Wenn Sie ein Dienstkonto zur Authentifizierung des Cloud SQL Auth-Proxys verwenden, notieren Sie den Speicherort der Datei mit dem privaten Schlüssel, die zusammen mit dem Dienstkonto erstellt wurde, auf Ihrem Clientcomputer.
  4. Starten Sie den Cloud SQL Auth-Proxy.

    Einige mögliche Strings zum Aufrufen des Cloud SQL Auth-Proxys:

    • Mit Cloud SDK-Authentifizierung:
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306
      
      Der angegebene Port darf nicht belegt sein (etwa durch einen lokalen Datenbankserver).
    • Mit einem Dienstkonto und unter expliziter Angabe des Namens der Instanzverbindung (empfohlen für Produktionsumgebungen):
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:3306 \
                        -credential_file=PATH_TO_KEY_FILE &
      

    Weitere Informationen über Cloud SQL Auth-Proxyoptionen finden Sie unter Authentifizierungsoptionen für den Cloud SQL Auth-Proxy sowie Spezifikationsoptionen für Instanzen.

Unix-Sockets

Der Cloud SQL Auth-Proxy kann einen Unix-Socket beobachten. Dies ist ein POSIX-Standardverfahren für die Verwendung eines Ordners zur Verwaltung der Kommunikation zwischen zwei Prozessen, die auf demselben Host ausgeführt werden. Vorteile der Verwendung von Unix-Sockets sind höhere Sicherheit und geringere Latenz. Sie können jedoch nicht von einem externen Computer aus auf einen Unix-Socket zugreifen.

Zum Erstellen und Verwenden eines Unix-Sockets muss das Zielverzeichnis vorhanden sein und sowohl der Cloud SQL Auth-Proxy als auch die Anwendung müssen Lese- und Schreibzugriff darauf haben.

  1. Wenn Sie eine explizite Instanzspezifikation verwenden, kopieren Sie Ihren INSTANCE_CONNECTION_NAME. Sie finden ihn in der Google Cloud Console auf der Seite Übersicht für Ihre Instanz oder ermitteln ihn über folgenden Befehl:

    gcloud sql instances describe INSTANCE_NAME
    .

    Beispiel: myproject:myregion:myinstance.

  2. Erstellen Sie das Verzeichnis für die Cloud SQL Auth-Proxy-Sockets:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. Wenn Sie ein Dienstkonto zur Authentifizierung des Cloud SQL Auth-Proxys verwenden, notieren Sie den Speicherort der Datei mit dem privaten Schlüssel, die zusammen mit dem Dienstkonto erstellt wurde, auf Ihrem Clientcomputer.
  4. Öffnen Sie ein neues Terminalfenster und starten Sie den Cloud SQL Auth-Proxy.

    Einige mögliche Strings zum Aufrufen des Cloud SQL Auth-Proxys:

    • Mit einem Dienstkonto und unter expliziter Angabe des Namens der Instanzverbindung (empfohlen für Produktionsumgebungen):
      ./cloud_sql_proxy -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
      -credential_file=PATH_TO_KEY_FILE &
    • Mit Cloud SDK-Authentifizierung und automatischer Instanzerkennung:
      ./cloud_sql_proxy -dir=/cloudsql &

    Am besten starten Sie den Cloud SQL Auth-Proxy in seinem eigenen Terminal. So können Sie seine Ausgabe überwachen, ohne dass diese mit der Ausgabe anderer Programme vermischt wird.

    Weitere Informationen über Cloud SQL Auth-Proxyoptionen finden Sie unter Authentifizierungsoptionen für den Cloud SQL Auth-Proxy sowie Spezifikationsoptionen für Instanzen.

Docker-Image des Cloud SQL Auth-Proxys

Verwenden Sie zum Ausführen des Cloud SQL Auth-Proxys in einem Docker-Container das Cloud SQL Auth-Proxy-Docker-Image, das in der Google Container Registry verfügbar ist.

Sie können den Cloud SQL Auth-Proxy entweder mit TCP-Sockets oder Unix-Sockets starten. Dabei werden die folgenden Befehle verwendet. Die Optionen verwenden einen INSTANCE_CONNECTION_NAME als Verbindungsstring, um eine Cloud SQL-Instanz zu identifizieren. Sie finden den INSTANCE_CONNECTION_NAME auf der Seite Übersicht Ihrer Instanz in der Google Cloud Console oder ermitteln ihn über folgenden Befehl:

gcloud sql instances describe INSTANCE_NAME
.

Beispiel: myproject:myregion:myinstance.

Je nach Ihrer Programmiersprache und Umgebung können Sie den Cloud SQL Auth-Proxy entweder mit TCP-Sockets oder mit Unix-Sockets starten. Allerdings werden Unix-Sockets nicht für Anwendungen unterstützt, die in der Programmiersprache Java oder für die Windows-Umgebung geschrieben sind.

TCP-Sockets verwenden

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

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, geben Sie den Parameter credential_file und die Zeile -v PATH_TO_KEY_FILE:/config nicht an.

Geben Sie in -p immer das Präfix 127.0.0.1 an, damit der Cloud SQL Auth-Proxy nicht außerhalb des lokalen Hosts bereitgestellt wird. Die Angabe "0.0.0.0" im Instanzparameter ist erforderlich, damit von außerhalb des Docker-Containers auf den Port zugegriffen werden kann.

Unix-Sockets verwenden

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

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, geben Sie den Parameter credential_file und die Zeile -v PATH_TO_KEY_FILE:/config nicht an.

Wenn Sie ein containeroptimiertes Image verwenden, ersetzen Sie /cloudsql durch ein beschreibbares Verzeichnis. Beispiel:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Sie können mehrere durch Kommas getrennte Instanzen angeben. Außerdem haben Sie die Möglichkeit, mithilfe von Compute Engine-Metadaten dynamisch die Instanzen zu bestimmen, zu denen eine Verbindung hergestellt werden soll. Weitere Informationen zu Cloud SQL Auth-Proxyparametern.

Andere Befehlszeilenargumente

Die obigen Beispiele decken die häufigsten Anwendungsfälle ab. Der Cloud SQL Auth-Proxy bietet aber auch weitere Konfigurationsoptionen, die mit Befehlszeilenargumenten festgelegt werden können. Wenn Sie Hilfe zu Befehlszeilenargumenten benötigen, rufen Sie mit dem Flag -help die aktuelle Dokumentation auf:

./cloud_sql_proxy -help

Weitere Beispiele zur Verwendung der Befehlszeilenoptionen des Cloud SQL Auth-Proxys finden Sie in der README-Datei im Cloud SQL Auth-Proxy-GitHub-Repository.

Verbindung zum Cloud SQL Auth-Proxy herstellen

Der verwendete Verbindungsstring hängt davon ab, ob Sie den Cloud SQL Auth-Proxy mit einem TCP-Socket, einem UNIX-Socket oder einem Docker gestartet haben.

TCP-Sockets

  1. Starten Sie den MySQL-Client:
    mysql -u USERNAME -p --host 127.0.0.1
    

    Wenn Sie die Verbindung mithilfe von TCP-Sockets herstellen, greifen Sie über 127.0.0.1 auf den Cloud SQL Auth-Proxy zu.

  2. Geben Sie das Passwort ein, wenn Sie dazu aufgefordert werden.
  3. Die MySQL-Eingabeaufforderung wird angezeigt.

Unix-Sockets verwenden

  1. Starten Sie den MySQL-Client:
    mysql -u USERNAME -p -S /cloudsql/INSTANCE_CONNECTION_NAME
    
  2. Geben Sie das Passwort ein.
  3. Die MySQL-Eingabeaufforderung wird angezeigt.

Benötigen Sie Hilfe? Informationen zur Fehlerbehebung für den Proxy finden Sie unter Fehlerbehebung bei Cloud SQL Auth-Proxyverbindungen. Weitere Informationen erhalten Sie auf der Cloud SQL-Supportseite.

Sprachspezifische Codebeispiele

Sie können eine Verbindung zum Cloud SQL Auth-Proxy mit jeder Sprache herstellen, die eine Verbindung zu Unix- oder TCP-Sockets ermöglicht. Im Folgenden finden Sie einige Code-Snippets aus vollständigen Beispielen auf GitHub, die das Zusammenwirken in der Anwendung veranschaulichen.

Weitere Themen

Proxy mit privater IP-Adresse verwenden

Wenn Sie eine Verbindung zu einer Cloud SQL-Instanz mithilfe einer privaten IP-Adresse herstellen möchten, muss sich der Proxy auf einer Ressource befinden, die Zugriff auf dasselbe VPC-Netzwerk wie die Instanz hat.

Der Proxy verwendet die IP-Adresse, um eine Verbindung mit Ihrer Cloud SQL-Instanz herzustellen. Standardmäßig versucht der Proxy, eine Verbindung mit einer öffentlichen IPv4-Adresse herzustellen. Hat die Cloud SQL-Instanz nur eine private IP-Adresse, verwendet der Proxy diese für die Verbindung.

Wenn für die Instanz sowohl eine öffentliche als auch eine private IP konfiguriert ist und Sie möchten, dass der Proxy die private IP-Adresse verwendet, müssen Sie beim Starten des Proxys die folgende Option angeben:

-ip_address_types=PRIVATE

Cloud SQL Auth-Proxy für ein Datenbanknutzerkonto benötigen

Wenn Sie über den Proxy eine Verbindung zu Ihrer Instanz herstellen, geben Sie ein Nutzerkonto an, mit dem Sie sich in der Instanz anmelden. Für diesen Zweck können Sie ein beliebiges Datenbank-Nutzerkonto verwenden. Da der Proxy eine Verbindung immer von einem Hostnamen aus herstellt, auf den nur mit dem Proxy zugegriffen werden kann, haben Sie auch die Möglichkeit, ein Nutzerkonto zu erstellen, das nur vom Proxy verwendet werden kann. Diese Vorgehensweise hat den Vorteil, dass Sie dieses Konto ohne Passwort angeben können, ohne die Sicherheit Ihrer Instanz und Ihrer Daten zu beeinträchtigen.

Geben Sie den Hostnamen 'cloudsqlproxy~[IP_ADDRESS]' an, um ein Nutzerkonto zu erstellen, das nur mit dem Cloud SQL Auth-Proxy verwendet werden kann. Sie können auch den Platzhalter für die IP-Adresse verwenden, der zu 'cloudsqlproxy~%' führt. Der vollständige Nutzername wäre:

'[USER_NAME]'@'cloudsqlproxy~%'

oder

'[USER_NAME]'@'cloudsqlproxy~[IP_ADDRESS]'

Eine Anleitung zur Erstellung eines Nutzerkontos finden Sie unter Nutzerkonten erstellen und verwalten. Weitere Informationen über die Funktionsweise von Nutzerkonten in Cloud SQL finden Sie unter Nutzer.

Proxy in einem separaten Prozess ausführen

Das Ausführen des Cloud SQL Auth-Proxys in einem separaten Terminalprozess kann nützlich sein, um zu vermeiden, dass die Konsolenausgabe mit der Ausgabe anderer Programme vermischt wird. Verwenden Sie die unten gezeigte Syntax, um den Proxy in einem separaten Prozess aufzurufen.

Linux

Verwenden Sie unter Linux oder macOS ein abschließendes & in der Befehlszeile, um den Proxy in einem separaten Prozess zu starten:

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

Windows

Verwenden Sie in PowerShell unter Windows den Befehl Start-Process, um den Proxy in einem separaten Prozess zu starten:

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

Cloud SQL Auth-Proxy in einem Docker-Container ausführen

Verwenden Sie zum Ausführen des Cloud SQL Auth-Proxys in einem Docker-Container das Proxy-Docker-Image, das in der Google Container Registry verfügbar ist. Sie können das Proxy-Docker-Image mit dem folgenden gcloud-Befehl installieren:

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

Mit den unten aufgeführten Befehlen können Sie den Proxy mit TCP-Sockets oder Unix-Sockets starten.

TCP-Sockets

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

Unix-Sockets

    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.19.1 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

Wenn Sie ein containeroptimiertes Image verwenden, ersetzen Sie /cloudsql durch ein beschreibbares Verzeichnis. Beispiel:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, geben Sie den Parameter credential_file und die Zeile -v PATH_TO_KEY_FILE:/config nicht an.

Cloud SQL Auth-Proxy als Dienst ausführen

Die Ausführung des Proxys als Hintergrunddienst kann für die lokale Entwicklung und das Testen praktisch sein. Wenn Sie auf Ihre Cloud SQL-Instanz zugreifen müssen, können Sie den Dienst im Hintergrund starten und beenden, wenn Sie fertig sind.

  • Der Cloud SQL Auth-Proxy bietet derzeit keine integrierte Unterstützung für die Ausführung als Windows-Dienst. Es können aber Drittanbieter-Dienstmanager verwendet werden, um ihn als Dienst auszuführen. Beispielsweise können Sie NSSM verwenden, um den Proxy als Windows-Dienst zu konfigurieren. NSSM überwacht dann den Proxy und startet ihn automatisch neu, wenn er nicht mehr reagiert. Weitere Informationen finden Sie in der NSSM-Dokumentation.

Tipps für die Arbeit mit dem Cloud SQL Auth-Proxy

Cloud SQL Auth-Proxy aufrufen

Alle Beispiel-Proxyaufrufe starten den Proxy im Hintergrund, sodass eine Meldung ausgegeben wird. Im Idealfall ist dieses Terminal für den Proxy reserviert, um zu vermeiden, dass seine Ausgabedaten mit den Ausgabedaten von anderen Programmen vermischt werden. Die Ausgabe des Proxys kann bei der Diagnose von Verbindungsproblemen hilfreich sein. Darum bietet es sich an, sie in einer Logdatei zu erfassen. Wenn Sie den Proxy nicht im Hintergrund starten, wird die Ausgabe an stdout übergeben, sofern sie nicht weitergeleitet wird.

Sie müssen /cloudsql nicht als Verzeichnis für die Proxy-Sockets verwenden. Dieser Verzeichnisname wurde ausgewählt, um die Unterschiede zu App Engine-Verbindungsstrings so gering wie möglich zu halten. Wenn Sie den Verzeichnisnamen ändern, halten Sie ihn so kurz wie möglich. Er ist Teil eines längeren Strings, der einer Längenbeschränkung durch das Betriebssystem unterliegt. Dieses Limit hängt vom System ab, liegt aber in der Regel zwischen 91 und 108 Zeichen. Unter Linux beträgt die maximale Länge normalerweise 108 Zeichen. Mit folgendem Befehl können Sie die Länge prüfen:

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

Über den Proxy Verbindung zu mehreren Instanzen herstellen

Sie können mithilfe eines einzigen lokalen Proxyclients eine Verbindung zu mehreren Cloud SQL-Instanzen herstellen. Die Vorgehensweise hängt dabei davon ab, ob Sie Unix-Sockets oder TCP verwenden.

Unix-Sockets

Um den Proxy mit mehreren Instanzen zu verbinden, geben Sie die Instanzverbindungsnamen mit dem Parameter „-instances“ in einer durch Kommas getrennten Liste ohne Leerzeichen an. Der Proxy stellt beim Start eine Verbindung zu den einzelnen Instanzen her.

Eine Verbindung zu den einzelnen Instanzen stellen Sie über den jeweiligen Socket im angegebenen Verzeichnis her.

Beispiele:

      ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
      mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance2
  

TCP-Sockets

Wenn Sie eine Verbindung zu einer Instanz über TCP herstellen, geben Sie den Port Ihres Computers an, der dafür verwendet werden soll. Jede Instanz muss einen eigenen Port haben. Das mysql-Tool verwendet standardmäßig den Port 3306, aber Sie können auch einen anderen angeben.

Beispiele:

    # Start the proxy for two instances, each with its own port:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" on port 3306, and "myInstance2" on port 1234

    mysql -u myInstanceUser --host 127.0.0.1  --port 3306
    mysql -u myInstance2User --host 127.0.0.1  --port 1234
  

Proxyaufrufe und mysql Client-Verbindungsstrings

Sie können Proxyaufrufe und Verbindungsstrings verwenden, z. B. in Befehlen für einen MySQL-Nutzer myUser, für die Instanz myInstance, die sich in us-central1 im Projekt myProject befindet.

Automatische Instanzerkennung mit gcloud-Anmeldedaten verwenden:
    ./cloud_sql_proxy -dir=/cloudsql &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance
Projekterkennung mit gcloud-Anmeldedaten verwenden:
    ./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
    mysql -u myUser -S /cloudsql/myProject:us-central1:

Für eine Compute Engine-Instanz mit expliziter Instanzspezifikation:
    ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance
Für Unix mit TCP:
    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306 &
    mysql -u myUser --host 127.0.0.1
Für Windows (in der Eingabeaufforderung):
    cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:3306
    mysql -u myUser --host 127.0.0.1

Weitere Informationen über die Cloud SQL Auth-Proxyoptionen finden Sie auf der GitHub-Seite zum Cloud SQL Auth-Proxy.

Fehlerbehebung bei Cloud SQL Auth-Proxyverbindungen

Das Proxy-Docker-Image basiert auf einer speziellen Version des Cloud SQL Auth-Proxys. Wenn eine neue Version des Cloud SQL Auth-Proxys verfügbar ist, rufen Sie die neue Version des Proxy-Docker-Images ab, damit Ihre Umgebung auf dem neuesten Stand ist. Die aktuelle Version des Cloud SQL Auth-Proxys finden Sie auf der GitHub-Seite mit Cloud SQL Auth-Proxyversionen.

Wenn Sie Probleme damit haben, über den Cloud SQL Auth-Proxy eine Verbindung mit der Cloud SQL-Instanz herzustellen, versuchen Sie Folgendes, um die Problemursache zu ermitteln.

  • Überprüfen Sie die Proxyausgabe.

    Die Proxyausgabe ist oft nützlich, um die Ursache des Problems zu ermitteln und eine Lösung zu finden. Leiten Sie die Ausgabe in eine Datei oder überwachen Sie das Terminal, auf dem Sie den Proxy gestartet haben.

  • Wenn Sie den Fehler 403 notAuthorized erhalten und das Dienstkonto zur Authentifizierung des Proxys verwenden, vergewissern Sie sich, dass das Dienstkonto über die richtigen Berechtigungen verfügt.

    Sie können das Dienstkonto überprüfen. Suchen Sie dazu auf der IAM-Seite nach seiner ID. Das Konto muss die Berechtigung cloudsql.instances.connect haben. Die vordefinierten Rollen Cloud SQL Admin, Client und Editor haben diese Berechtigung.

  • Achten Sie darauf, dass die Cloud SQL Admin API aktiviert ist.

    Ist das nicht der Fall, wird in Ihren Proxylogs die Ausgabe wie Error 403: Access Not Configured angezeigt.

  • Wenn Sie in der Instanzliste mehrere Instanzen angeben, achten Sie darauf, ein Komma als Trennzeichen zu verwenden. Wenn Sie TCP verwenden, geben Sie für alle Instanzen unterschiedliche Ports an.

  • Wenn Sie eine Verbindung über UNIX-Sockets herstellen, achten Sie darauf, dass die Sockets erstellt wurden. Rufen Sie zu diesem Zweck das Verzeichnis auf, das Sie beim Starten des Proxys angegeben haben.

  • Wenn Sie eine Firewallrichtlinie für ausgehende Verbindungen haben, müssen Sie darauf achten, dass sie Verbindungen zu Port 3307 auf der Ziel-Cloud SQL-Instanz zulässt.

Nächste Schritte