Questa pagina descrive come utilizzare il client psql, installato su un'istanza Compute Engine, per connettersi a Cloud SQL.
Puoi utilizzare l'IP privato, l'IP pubblico, il proxy di autenticazione Cloud SQL o l'immagine Docker del proxy di autenticazione Cloud SQL.
Per istruzioni passo passo sull'esecuzione di un'applicazione web di esempio di Compute Engine connessa a Cloud SQL,consulta la guida rapida per la connessione da Compute Engine.
Prima di iniziare
Questa attività non include istruzioni per la configurazione dell'istanza Compute Engine. Se hai bisogno di aiuto per creare e configurare un'istanza Compute Engine, consulta la documentazione di Compute Engine.
IP privato
Per connetterti a Cloud SQL da un'istanza Compute Engine utilizzando l'IP privato, devi configurare l'accesso privato ai servizi per il tuo ambiente e la tua istanza Cloud SQL deve essere configurata per utilizzare l'IP privato. L'istanza Compute Engine deve trovarsi nella stessa regione dell'istanza Cloud SQL e nella rete configurata per una connessione privata. Scopri di più.
1. Configura l'istanza in modo che utilizzi l'IP privato
Segui le istruzioni riportate in Configurazione della connettività IP privato.
2. Apri una connessione terminale Cloud Shell all'istanza Compute Engine.
Utilizza le istruzioni appropriate, a seconda del sistema operativo dell'istanza:
- Per Linux, vedi Connessione alle VM Linux.
- Per Windows, consulta Connessione alle VM Windows.
Se la tua istanza Compute Engine esegue un'immagine pubblica RHEL o CentOS, SELinux potrebbe bloccare la connessione proxy. In questo caso, devi configurare la funzionalità SELinux per consentire la connessione.
Per saperne di più su SELinux per RHEL, consulta la documentazione di RHEL. Per saperne di più su SELinux per CentOS, consulta la documentazione di CentOS.
3. Installa il client psql sull'istanza Compute Engine, se non è già installato.
Debian/Ubuntu
Installa il client psql dal gestore di pacchetti:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Installa il client psql dal gestore di pacchetti:
sudo yum install postgresql
openSUSE
Installa il client psql dal gestore di pacchetti:
sudo zypper install postgresql
Altre piattaforme
- Scarica la distribuzione principale di PostgreSQL per la tua piattaforma dalla
pagina Download di PostgreSQL.
La distribuzione di base include il client psql. - Installa il database PostgreSQL seguendo le istruzioni riportate nella pagina di download.
4. Connettiti al client psql.
psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME
Puoi trovare l'indirizzo IP privato nella
pagina delle istanze Cloud SQL o eseguendo il seguente
comando gcloud
:
gcloud sql instances list
IP pubblico
Per connetterti utilizzando l'IP pubblico:
1. Aggiungi un indirizzo IP statico IPv4 all'istanza Compute Engine, se non ne ha già uno.
Non puoi connetterti a Compute Engine utilizzando IPv6. Per informazioni su come aggiungere un indirizzo IP statico, consulta Prenotare un nuovo indirizzo IP esterno statico nella documentazione di Compute Engine.
2. Autorizza l'indirizzo IP statico dell'istanza Compute Engine come rete che può connettersi all'istanza Cloud SQL.
Per ulteriori informazioni, consulta la pagina Configurazione dell'accesso per connessioni IP pubbliche.
3. Apri una connessione terminale Cloud Shell all'istanza Compute Engine.
Utilizza le istruzioni appropriate, a seconda del sistema operativo dell'istanza:
- Per Linux, vedi Connessione alle VM Linux.
- Per Windows, consulta Connessione alle VM Windows.
Se la tua istanza Compute Engine esegue un'immagine pubblica RHEL o CentOS, SELinux potrebbe bloccare la connessione proxy. In questo caso, devi configurare la funzionalità SELinux per consentire la connessione.
Per saperne di più su SELinux per RHEL, consulta la documentazione di RHEL. Per saperne di più su SELinux per CentOS, consulta la documentazione di CentOS.
4. Installa il client psql sull'istanza Compute Engine, se non è già installato.
Debian/Ubuntu
Installa il client psql dal gestore di pacchetti:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Installa il client psql dal gestore di pacchetti:
sudo yum install postgresql
openSUSE
Installa il client psql dal gestore di pacchetti:
sudo zypper install postgresql
Altre piattaforme
- Scarica la distribuzione principale di PostgreSQL per la tua piattaforma dalla
pagina Download di PostgreSQL.
La distribuzione di base include il client psql. - Installa il database PostgreSQL seguendo le istruzioni riportate nella pagina di download.
5. Connettiti al client psql.
psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME
Puoi trovare l'indirizzo IP pubblico nella
pagina delle istanze Cloud SQL o eseguendo il seguente
comando gcloud
:
gcloud sql instances list
Per un esempio di come connettersi utilizzando SSL, consulta Connessione con SSL.
6. Viene visualizzato il prompt psql.
7. Se devi mantenere attive le connessioni inutilizzate:
Imposta TCP keepalive.
Per ulteriori informazioni, consulta Comunicazione tra le istanze e internet nella documentazione di Compute Engine.
Le connessioni vengono mantenute attive automaticamente per le istanze.
Proxy di autenticazione Cloud SQL
Per connetterti utilizzando il proxy di autenticazione Cloud SQL da Compute Engine:1. Abilita l'API Cloud SQL Admin.
2. Crea un account di servizio.
- Nella Google Cloud console, vai alla pagina Service account.
- Seleziona il progetto che contiene l'istanza Cloud SQL.
- Fai clic su Crea account di servizio.
- Nel campo Nome account di servizio, inserisci un nome descrittivo per l'account di servizio.
- Modifica l'ID service account con un valore univoco e riconoscibile, quindi fai clic su Crea e continua.
-
Fai clic sul campo Seleziona un ruolo e seleziona uno dei seguenti ruoli:
- Cloud SQL > Client Cloud SQL
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Amministratore Cloud SQL
- Fai clic su Fine per completare la creazione del service account.
- Fai clic sul menu delle azioni per il nuovo account di servizio e seleziona Gestisci chiavi.
- Fai clic sul menu a discesa Aggiungi chiave, quindi su Crea nuova chiave.
-
Verifica che il tipo di chiave sia JSON e fai clic su Crea.
Il file della chiave privata viene scaricato sul tuo computer. Puoi spostarlo in un'altra posizione. Proteggi il file di chiave.
Se l'istanza Compute Engine si trova in un progetto diverso dall'istanza Cloud SQL, assicurati che il relativo account di servizio disponga delle autorizzazioni appropriate nel progetto che contiene l'istanza Cloud SQL:
- Vai all'elenco delle istanze Compute Engine nella console Google Cloud .
- Se necessario, seleziona il progetto associato all'istanza di Compute Engine.
- Seleziona l'istanza Compute Engine per visualizzarne le proprietà.
- Nelle proprietà dell'istanza Compute Engine, copia il nome delaccount di serviziot.
- Vai alla pagina IAM e amministrazione > Progetti nella console Google Cloud .
- Seleziona il progetto che contiene l'istanza di Cloud SQL.
- Cerca il nome del account di servizio.
-
Se il account di servizio è già presente e dispone di un ruolo che include l'autorizzazione
cloudsql.instances.connect
, puoi procedere al passaggio 4.I ruoli
Cloud SQL Client
,Cloud SQL Editor
eCloud SQL Admin
forniscono tutti l'autorizzazione necessaria, così come i ruoli di progetto legacyEditor
eOwner
. - In caso contrario, aggiungi il account di servizio facendo clic su Aggiungi.
Nella finestra di dialogo Aggiungi entità, fornisci il nome dell'account di servizio e seleziona un ruolo che includa l'autorizzazione
cloudsql.instances.connect
(qualsiasi ruolo predefinito Cloud SQL diverso da Visualizzatore andrà bene).In alternativa, puoi utilizzare il ruolo Editor di base selezionando Progetto > Editor, ma il ruolo Editor include autorizzazioni per Google Cloud.
Se non vedi questi ruoli, è possibile che il tuo utente non disponga dell'autorizzazione
resourcemanager.projects.setIamPolicy
. Google Cloud Puoi controllare le tue autorizzazioni andando alla pagina IAM nella console Google Cloud e cercando il tuo ID utente.- Fai clic su Aggiungi.
Ora vedi il account di servizio elencato con il ruolo specificato.
3. Apri una connessione terminale all'istanza Compute Engine.
Utilizza le istruzioni appropriate, a seconda del sistema operativo dell'istanza:
- Per Linux, vedi Connessione alle istanze Linux.
- Per Windows, consulta Connessione alle istanze Windows.
Se la tua istanza Compute Engine esegue un'immagine pubblica RHEL o CentOS, SELinux potrebbe bloccare la connessione proxy. In questo caso, devi configurare la funzionalità SELinux per consentire la connessione.
Per saperne di più su SELinux per RHEL, consulta la documentazione di RHEL. Per saperne di più su SELinux per CentOS, consulta la documentazione di CentOS.
4. Installa il client psql sull'istanza Compute Engine, se non è già installato.
Debian/Ubuntu
Installa il client psql dal gestore di pacchetti:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Installa il client psql dal gestore di pacchetti:
sudo yum install postgresql
openSUSE
Installa il client psql dal gestore di pacchetti:
sudo zypper install postgresql
Altre piattaforme
- Scarica la distribuzione principale di PostgreSQL per la tua piattaforma dalla
pagina Download di PostgreSQL.
La distribuzione di base include il client psql. - Installa il database PostgreSQL seguendo le istruzioni riportate nella pagina di download.
5. Installa il proxy di autenticazione Cloud SQL sull'istanza Compute Engine.
Linux a 64 bit
- Scarica il proxy di autenticazione Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.linux.amd64
- Rendi eseguibile il proxy di autenticazione Cloud SQL:
chmod +x cloud-sql-proxy
Linux a 32 bit
- Scarica il proxy di autenticazione Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.linux.386
- Se il comando
curl
non viene trovato, eseguisudo apt install curl
e ripeti il comando di download. - Rendi eseguibile il proxy di autenticazione Cloud SQL:
chmod +x cloud-sql-proxy
Windows a 64 bit
Fai clic con il tasto destro del mouse su https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.x64.exe e seleziona Salva link con nome per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file incloud-sql-proxy.exe
.
Windows a 32 bit
Fai clic con il tasto destro del mouse su https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.x86.exe e seleziona Salva link con nome per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file incloud-sql-proxy.exe
.
Immagine Docker del proxy di autenticazione Cloud SQL
Il proxy di autenticazione Cloud SQL ha immagini container diverse, come distroless
, alpine
e buster
. L'immagine del container del proxy di autenticazione Cloud SQL predefinita utilizza
distroless
, che
non contiene alcuna shell. Se hai bisogno di una shell o di strumenti correlati, scarica un'immagine basata su
alpine
o buster
.
Per maggiori informazioni, vedi
Immagini container del proxy di autenticazione Cloud SQL.
Puoi eseguire il pull dell'ultima immagine sulla tua macchina locale utilizzando Docker con il seguente comando:
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1
Altri sistemi operativi
Per altri sistemi operativi non inclusi qui, puoi compilare il proxy di autenticazione Cloud SQL dal codice sorgente.6. Avvia il proxy di autenticazione Cloud SQL.
A seconda della lingua e dell'ambiente, puoi avviare il proxy di autenticazione Cloud SQL utilizzando i socket TCP, i socket Unix o l'immagine Docker del proxy di autenticazione Cloud SQL. Il binario del proxy di autenticazione Cloud SQL si connette a una o più istanze Cloud SQL specificate nella riga di comando e apre una connessione locale come TCP o socket Unix. Altre applicazioni e servizi, come il codice dell'applicazione o gli strumenti client di gestione del database, possono connettersi alle istanze Cloud SQL tramite queste connessioni TCP o socket Unix.
Socket TCP
Per le connessioni TCP, il proxy di autenticazione Cloud SQL rimane in ascolto sulla porta localhost
(127.0.0.1
) per impostazione predefinita.
Pertanto, quando specifichi --port PORT_NUMBER
per un'istanza, la connessione locale
si trova all'indirizzo 127.0.0.1:PORT_NUMBER
.
In alternativa, puoi specificare un indirizzo diverso per la connessione locale.
Ad esempio, ecco come fare in modo che il proxy di autenticazione Cloud SQL ascolti all'indirizzo 0.0.0.0:1234
per la connessione locale:
./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME
Copia il tuo INSTANCE_CONNECTION_NAME. Puoi trovarlo nella pagina Panoramica della tua istanza nella consoleGoogle Cloud o eseguendo il seguente comando:
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Ad esempio: myproject:myregion:myinstance.
- Se l'istanza ha configurato sia l'IP pubblico che quello privato e vuoi che
il proxy di autenticazione Cloud SQL utilizzi l'indirizzo IP privato,
devi fornire la seguente opzione quando avvii il proxy di autenticazione Cloud SQL:
--private-ip
- Se utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, annotati la posizione sul computer client del file della chiave privata creato durante la creazione del account di servizio.
- Avvia il proxy di autenticazione Cloud SQL.
Alcune possibili stringhe di invocazione del proxy di autenticazione Cloud SQL:
- Utilizzo dell'autenticazione Cloud SDK:
La porta specificata non deve essere già in uso, ad esempio da un server di database locale../cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
- Utilizzo di un account di servizio e inclusione esplicita del nome della connessione all'istanza
(consigliato per gli ambienti di produzione):
./cloud-sql-proxy \ --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Per ulteriori informazioni sulle opzioni del proxy di autenticazione Cloud SQL, consulta Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL.
- Utilizzo dell'autenticazione Cloud SDK:
Socket Unix
Il proxy di autenticazione Cloud SQL può rimanere in ascolto su un socket Unix, che è un meccanismo standard Posix per utilizzare una cartella per gestire la comunicazione tra due processi in esecuzione sullo stesso host. I vantaggi dell'utilizzo dei socket Unix sono una maggiore sicurezza e una latenza inferiore, tuttavia non puoi accedere a un socket Unix da una macchina esterna.
Per creare e utilizzare un socket Unix, la directory di destinazione deve esistere e sia Cloud SQL Auth Proxy sia l'applicazione devono disporre dell'accesso in lettura e scrittura.
Copia il tuo INSTANCE_CONNECTION_NAME. Puoi trovarlo nella pagina Panoramica della tua istanza nella consoleGoogle Cloud o eseguendo il seguente comando:
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Ad esempio: myproject:myregion:myinstance.
- Crea la directory in cui risiederanno i socket del proxy di autenticazione Cloud SQL:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- Se utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, annotati la posizione sul computer client del file della chiave privata creato durante la creazione del account di servizio.
- Apri una nuova finestra del terminale Cloud Shell e avvia il proxy di autenticazione Cloud SQL.
Alcune possibili stringhe di invocazione del proxy di autenticazione Cloud SQL:
- Utilizzo dell'autenticazione Google Cloud SDK:
./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
- Utilizzo di un account di servizio:
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Avvia il proxy di autenticazione Cloud SQL nel proprio terminale Cloud Shell in modo da poter monitorare il suo output senza che si mescoli con l'output di altri programmi.
Per ulteriori informazioni sulle opzioni del proxy di autenticazione Cloud SQL, consulta Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL.
- Utilizzo dell'autenticazione Google Cloud SDK:
Docker
Per eseguire il proxy di autenticazione Cloud SQL in un container Docker, utilizza l'immagine Docker del proxy di autenticazione Cloud SQL disponibile in Google Container Registry.
Puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP o Unix, con i comandi mostrati di seguito. Le opzioni utilizzano INSTANCE_CONNECTION_NAME come stringa di connessione per identificare un'istanza Cloud SQL. Puoi trovare INSTANCE_CONNECTION_NAME nella pagina Panoramica della tua istanza nella consoleGoogle Cloud o eseguendo il seguente comando:
gcloud sql instances describe INSTANCE_NAME
Ad esempio: myproject:myregion:myinstance
.
A seconda della lingua e dell'ambiente, puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP o Unix. I socket Unix non sono supportati per le applicazioni scritte nel linguaggio di programmazione Java o per l'ambiente Windows.
Utilizzo dei socket 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.17.1 \\ --address 0.0.0.0 --port 5432 \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se utilizzi le credenziali fornite dall'istanza Compute Engine,
non includere il parametro --credentials-file
e la riga
-v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Specifica sempre il prefisso 127.0.0.1
in -p in modo che il proxy di autenticazione Cloud SQL non sia
esposto all'esterno dell'host locale. Il valore "0.0.0.0" nel parametro instances
è necessario per rendere la porta accessibile dall'esterno del container Docker.
Utilizzo dei socket 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.17.1 --unix-socket=/cloudsql \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se utilizzi le credenziali fornite dall'istanza Compute Engine,
non includere il parametro --credentials-file
e la riga
-v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Se utilizzi un'immagine ottimizzata per i container, utilizza una directory scrivibile
al posto di /cloudsql
, ad esempio:
-v /mnt/stateful_partition/cloudsql:/cloudsql
Puoi specificare più di un'istanza, separata da virgole. Puoi anche utilizzare i metadati di Compute Engine per determinare dinamicamente le istanze a cui connetterti. Scopri di più sui parametri del proxy di autenticazione Cloud SQL.
7. Avvia la sessione psql.
La stringa di connessione che utilizzi dipende dal fatto che tu abbia avviato il proxy di autenticazione Cloud SQL utilizzando un socket TCP o un socket UNIX o Docker.
Socket TCP
- Avvia il client psql:
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Anche se il parametro
sslmode
è impostato sudisable
, il proxy di autenticazione Cloud SQL fornisce una connessione criptata.Quando ti connetti utilizzando i socket TCP, si accede al proxy di autenticazione Cloud SQL tramite
127.0.0.1
. - Se richiesto, inserisci la password.
- Viene visualizzato il prompt psql.
Utilizzo dei socket Unix
- Avvia il client psql:
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
Anche se il parametro
sslmode
è impostato sudisable
, il proxy di autenticazione Cloud SQL fornisce una connessione criptata. - Inserisci la password.
- Viene visualizzato il prompt psql.
Serve aiuto? Per assistenza nella risoluzione dei problemi relativi al proxy, consulta Risoluzione dei problemi relativi alle connessioni del proxy di autenticazione Cloud SQL o la nostra pagina Assistenza Cloud SQL.
Passaggi successivi
- Ricevi assistenza per la risoluzione dei problemi di connessione per il proxy di autenticazione Cloud SQL.
- Crea utenti e database.
- Scopri di più sull'IP privato.
- Scopri le opzioni per connetterti alla tua istanza dalla tua applicazione.
- Scopri di più sul client psql.
- Scopri di più sulle opzioni di assistenza.