Connettiti utilizzando il proxy di autenticazione AlloyDB

Per stabilire connessioni autorizzate e criptate alle istanze AlloyDB per PostgreSQL, puoi utilizzare il proxy di autenticazione AlloyDB. Per saperne di più, consulta Informazioni sul proxy di autenticazione AlloyDB.

Per utilizzare il proxy di autenticazione AlloyDB, devi eseguire diversi passaggi di configurazione una tantum, quindi avviare il client del proxy di autenticazione e utilizzarlo per connetterti a un database.

Prima di iniziare

L'host client deve soddisfare i seguenti requisiti:

• Il client deve avere un percorso di rete verso l'istanza AlloyDB in base al metodo di connessione:

  • Accesso privato ai servizi (predefinito): il client deve avere visibilità di rete sulla rete Virtual Private Cloud (VPC) in cui risiedono le istanze. Gli host client (come le istanze Compute Engine) in questa rete VPC hanno intrinsecamente questa visibilità di rete. Gli host client in reti esterne (reti on-premise o reti VPC diverse) hanno questa visibilità se la rete VPC dell'istanza AlloyDB è connessa alla rete esterna utilizzando un tunnel Cloud VPN o un collegamento VLAN per Dedicated Interconnect o Partner Interconnect.
  • Private Service Connect: la rete VPC del client deve avere un endpoint Private Service Connect e un record DNS privato corrispondente e devi avviare il client proxy Auth con il flag --psc.
  • IP pubblico: l'istanza deve avere l'IP pubblico abilitato e devi avviare il client proxy di autenticazione con il flag --public-ip. Quando ti connetti utilizzando Auth Proxy, non è necessario aggiungere l'indirizzo IP dell'host client alle reti esterne autorizzate.

• Se l'host client ha una policy del firewall in uscita, deve consentire le connessioni in uscita alla porta 5433 sugli indirizzi IP delle istanze AlloyDB e consentire le connessioni in uscita alla porta 443 (la porta HTTPS standard) a tutti gli indirizzi IP.

• Se utilizzi un'istanza Compute Engine come host client, deve avere l'ambito di accesso https://www.googleapis.com/auth/cloud-platform per poter utilizzare l'API AlloyDB. Se necessario, modifica l'ambito di accesso per includere questo ambito.

Scarica il client proxy di autenticazione

La macchina su cui scarichi il client Auth Proxy dipende dal fatto che tu voglia connetterti alle tue istanze AlloyDB dall'interno o dall'esterno della rete VPC.

Se vuoi connetterti al cluster utilizzando l'accesso privato ai servizi, puoi scaricare il client Auth Proxy su un'istanza di macchina virtuale (VM) Compute Engine in esecuzione all'interno della rete VPC che ha accesso privato ai servizi al tuo cluster.

Se intendi connetterti al cluster dall'esterno del VPC, la macchina su cui lo installi dipende dalla strategia di connessione esterna che utilizzi. Ad esempio, puoi installare il client proxy di autenticazione su una macchina macOS o Windows locale per la tua applicazione, quindi utilizzare un server SOCKS in esecuzione all'interno della tua rete VPC AlloyDB come intermediario della connessione. Per saperne di più, consulta Connettiti a un cluster dall'esterno del relativo VPC.

Nota: assicurati di utilizzare l'ultima versione del client proxy di autenticazione. Google rilascia nuove versioni del client Auth Proxy ogni mese. Puoi trovare la versione corrente controllando la pagina delle release di GitHub del client proxy di autenticazione.

Linux

64 bit (AMD)

1. Scarica il client proxy di autenticazione:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

2. Rendi eseguibile il client proxy di autenticazione:

   chmod +x alloydb-auth-proxy

3. Aggiungi il client proxy di autenticazione al tuo PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Per mantenere queste modifiche tra le sessioni, aggiungi export PATH="$HOME/.local/bin:$PATH" al file ~/.bashrc o ~/.zshrc.

32 bit (AMD)

1. Scarica il client proxy di autenticazione:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

2. Rendi eseguibile il client proxy di autenticazione:

   chmod +x alloydb-auth-proxy

3. Aggiungi il client proxy di autenticazione al tuo PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Per mantenere queste modifiche tra le sessioni, aggiungi export PATH="$HOME/.local/bin:$PATH" al file ~/.bashrc o ~/.zshrc.

64 bit (ARM)

1. Scarica il client proxy di autenticazione:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

2. Rendi eseguibile il client proxy di autenticazione:

   chmod +x alloydb-auth-proxy

3. Aggiungi il client proxy di autenticazione al tuo PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Per mantenere queste modifiche tra le sessioni, aggiungi export PATH="$HOME/.local/bin:$PATH" al file ~/.bashrc o ~/.zshrc.

32 bit (ARM)

1. Scarica il client proxy di autenticazione:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

2. Rendi eseguibile il client proxy di autenticazione:

   chmod +x alloydb-auth-proxy

3. Aggiungi il client proxy di autenticazione al tuo PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Per mantenere queste modifiche tra le sessioni, aggiungi export PATH="$HOME/.local/bin:$PATH" al file ~/.bashrc o ~/.zshrc.

macOS

ARM64

1. Scarica il client proxy di autenticazione:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.arm64

2. Rendi eseguibile il client proxy di autenticazione:

   chmod +x alloydb-auth-proxy

3. Aggiungi il client proxy di autenticazione al tuo PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Per mantenere queste modifiche tra le sessioni, aggiungi export PATH="$HOME/.local/bin:$PATH" al file ~/.bashrc o ~/.zshrc.

AMD64

1. Scarica il client proxy di autenticazione:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.amd64

2. Rendi eseguibile il client proxy di autenticazione:

   chmod +x alloydb-auth-proxy

3. Aggiungi il client proxy di autenticazione al tuo PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Per mantenere queste modifiche tra le sessioni, aggiungi export PATH="$HOME/.local/bin:$PATH" al file ~/.bashrc o ~/.zshrc.

Windows

64 bit

1. Fai clic con il tasto destro del mouse su https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x64.exe e seleziona Salva link con nome per scaricare il client Auth Proxy. Rinomina il file in alloydb-auth-proxy.exe.

2. Aggiungi il client proxy di autenticazione al tuo PATH:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

A 32 bit

1. Fai clic con il tasto destro del mouse su https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x86.exe e seleziona Salva link con nome per scaricare il client Auth Proxy. Rinomina il file in alloydb-auth-proxy.exe.

2. Aggiungi il client proxy di autenticazione al tuo PATH:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

Immagine Docker

Per praticità, in Artifact Registry sono disponibili diverse immagini container che contengono il client proxy di autenticazione.

Puoi eseguire il pull dell'immagine più recente sulla tua macchina locale utilizzando Docker con il seguente comando:

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Altri sistemi operativi

Per altri sistemi operativi non inclusi qui, puoi compilare il client proxy Auth dal codice sorgente.

Scegli l'entità Identity and Access Management (IAM) e preparala per l'autorizzazione

Il proxy di autenticazione AlloyDB supporta l'utilizzo di questi tipi di entità IAM per autorizzare le connessioni tra il client e un'istanza AlloyDB:

• Un service account associato. Se l'host client viene eseguito suGoogle Cloud, ad esempio su un'istanza Compute Engine, puoi autorizzare le connessioni utilizzando il account di servizio collegato alla risorsa.

  Ti consigliamo di utilizzare un account di servizio per l'autorizzazione negli ambienti di produzione. Un account di servizio collegato è l'opzione più sicura perché non richiede il download di una chiave.

• Il tuo account utente. Puoi utilizzare il tuo account utente IAM per autorizzare le connessioni.

  L'utilizzo del tuo account utente è comodo negli ambienti di sviluppo in cui gestisci le risorse AlloyDB utilizzando gcloud CLI, sviluppi il database utilizzando uno strumento come psql e sviluppi il codice dell'applicazione sullo stesso host.

• Un service account gestito dall'utente. Puoi creare un service account IAM per la tua applicazione e poi autorizzare le connessioni utilizzando il account di servizio.

  Utilizza un account di servizio gestito dall'utente quando l'host client viene eseguito al di fuori diGoogle Cloud e non può utilizzare un account di servizio collegato.

Dopo aver scelto l'entità IAM da utilizzare, verifica che disponga delle autorizzazioni IAM richieste e che le sue credenziali siano disponibili sull'host client.

Autorizzazioni IAM obbligatorie

L'entità IAM che utilizzi per autorizzare le connessioni deve disporre delle autorizzazioni fornite dai ruoli predefiniti roles/alloydb.client (AlloyDB Client) e roles/serviceusage.serviceUsageConsumer (Service Usage Consumer).

Nota: anche il ruolo roles/alloydb.admin (AlloyDB Admin) fornisce le autorizzazioni richieste.

Per assegnare il ruolo Client AlloyDB a un'entità IAM:

• L'API Cloud Resource Manager deve essere abilitata nel progetto Google Cloud .

• Devi disporre del ruolo IAM di baseroles/owner (Proprietario) nel progettoGoogle Cloud o di un ruolo che conceda queste autorizzazioni:

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  Per ottenere queste autorizzazioni seguendo il principio del privilegio minimo, chiedi all'amministratore di concederti il ruolo roles/resourcemanager.projectIamAdmin (Project IAM Admin).

Rendi disponibili le credenziali IAM sull'host client

Il client Auth Proxy utilizza le Credenziali predefinite dell'applicazione (ADC) per individuare le credenziali IAM sull'host client. Nella maggior parte degli ambienti queste credenziali sono già presenti, quindi non devi configurare nulla. Il client proxy di autenticazione cerca le seguenti origini delle credenziali, in ordine:

• Il tuo account utente. Quando sviluppi in locale, autenticati con il tuo account utente eseguendo il seguente comando gcloud CLI:

  gcloud auth application-default login
  

  Il client Auth Proxy rileva e utilizza queste credenziali. Non è necessario scaricare una chiave del account di servizio.

• Un service account associato. Quando l'host client viene eseguito su Google Cloud, ad esempio su un'istanza Compute Engine, il server dei metadati dell'ambiente fornisce le credenziali dal account di servizio collegato. Il client Auth Proxy rileva e utilizza queste credenziali senza ulteriori configurazioni.

Altre origini delle credenziali

Utilizza i seguenti metodi solo quando le credenziali predefinite dell'applicazione non sono disponibili, ad esempio quando esegui il client Auth Proxy al di fuori diGoogle Cloudo quando devi eseguire l'override delle credenziali nell'ambiente.

• Una account di servizio account. Utilizza una chiave del account di servizio quando l'host client viene eseguito al di fuori di Google Cloud, ad esempio in un data center on-premise o su un altro cloud provider, e non puoi utilizzare la federazione delle identità per i workload.

  Crea una chiave del account di servizio in formato JSON e scaricala sul tuo host client. Poi, imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave:

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
  

  Facoltativamente, puoi specificare il percorso con il flag --credentials-file quando avvii il client proxy di autenticazione:

  alloydb-auth-proxy --credentials-file /path/to/service-account-key.json INSTANCE_URI
  

  Attenzione :le chiavi dei service account comportano un rischio per la sicurezza se non vengono gestite correttamente. Prima di creare una chiave, valuta un'alternativa più sicura.

• Un token di accesso OAuth 2.0. Utilizza un token di accesso quando un altro sistema emette già token di breve durata per te, ad esempio una pipeline di integrazione continua che ottiene un token prima di avviare il client proxy di autenticazione.

  Se hai già un token di accesso OAuth 2.0 valido, passalo direttamente quando avvii il client proxy di autenticazione:

  alloydb-auth-proxy --token "ACCESS_TOKEN" INSTANCE_URI
  

• Credenziali di gcloud CLI. Utilizza il flag --gcloud-auth solo quando devi riutilizzare una sessione gcloud auth login esistente e non puoi eseguire gcloud auth application-default login.

  Il flag --gcloud-auth fa sì che il client Auth Proxy utilizzi l'account con cui hai eseguito l'autenticazione con gcloud auth login anziché utilizzare le Credenziali predefinite dell'applicazione. Non consigliamo questo flag. Esegui invece gcloud auth application-default login.

Raccogli gli URI di connessione per le istanze AlloyDB

Quando avvii il client Auth Proxy, identifichi l'istanza o le istanze AlloyDB a cui vuoi connetterti utilizzando questo formato di URI di connessione:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Per visualizzare un elenco di tutti gli URI di connessione delle tue istanze, utilizza il comando gcloud CLI alloydb instances list:

gcloud alloydb instances list \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID

Sostituisci quanto segue:

• REGION_ID: la regione in cui si trovano le istanze
• CLUSTER_ID: l'ID del cluster in cui sono posizionate le istanze
• PROJECT_ID: l'ID del progetto in cui si trova il cluster

Raccogli l'URI di connessione all'istanza per ogni istanza a cui vuoi connetterti.

Avvia il client proxy di autenticazione

Quando avvii il client proxy di autenticazione, fornisci informazioni sulle istanze AlloyDB a cui connetterti e, se necessario, informazioni sulle credenziali da utilizzare per autorizzare queste connessioni.

All'avvio, il client proxy di autenticazione:

• Autorizza le connessioni alle istanze AlloyDB utilizzando le credenziali e le autorizzazioni IAM dell'entità IAM che hai configurato. Cerca le credenziali seguendo una sequenza specifica di passaggi.
• Autorizza automaticamente le connessioni IP pubbliche alla rete di origine, se l'istanza ha un IP pubblico abilitato.
• Configura una connessione mTLS 1.3 privata al server proxy di autenticazione di ogni istanza.
• Inizia ad ascoltare le richieste di connessione dei client locali.

Per impostazione predefinita, il client proxy Auth rimane in ascolto delle connessioni TCP sull'indirizzo IP 127.0.0.1, a partire dalla porta 5432 e incrementando di un numero di porta per ogni istanza AlloyDB oltre alla prima. Puoi specificare un indirizzo listener e porte diversi quando avvii il client Auth Proxy.

Avviso: fai attenzione quando associ il client proxy di autenticazione a un'interfaccia esterna. Chiunque abbia accesso a quell'interfaccia o a quella porta è autorizzato a connettersi alla tua istanza.

Nota: Google consiglia di eseguire il client Auth Proxy come servizio persistente negli ambienti di produzione.

Riga di comando

alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

Sostituisci quanto segue:

• INSTANCE_URI: l'URI di connessione dell'istanza di un'istanza AlloyDB a cui connettersi, specificato utilizzando questo formato:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  Puoi eseguire l'override della porta del listener locale predefinita che il client proxy di autenticazione utilizzerà per l'istanza aggiungendo il parametro di query port all'URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• (Facoltativo) PATH_TO_KEY_FILE: il percorso del file della chiave JSON del account di servizio gestito dall'utente da utilizzare per l'autorizzazione della connessione.

• (Facoltativo) OAUTH_ACCESS_TOKEN: un valore del token OAuth2 da utilizzare per l'autorizzazione della connessione.

• (Facoltativo) INITIAL_PORT_NUMBER: il numero di porta iniziale da utilizzare al posto della porta predefinita 5432 durante l'ascolto delle connessioni TCP locali.

• (Facoltativo) LOCAL_LISTENER_ADDRESS: l'indirizzo del listener da utilizzare al posto di quello predefinito 127.0.0.1 durante l'ascolto delle connessioni TCP locali.

Il flag facoltativo --auto-iam-authn consente di eseguire l'autenticazione automatica all'istanza. Questo funziona solo per l'utente del database associato all'account IAM che esegue il client proxy di autenticazione. Per saperne di più, consulta Esegui l'autenticazione automatica utilizzando Auth Proxy.

Il flag facoltativo --psc consente al proxy di autenticazione di connettersi a un'istanza con Private Service Connect abilitato. Per saperne di più sulla configurazione del DNS con Private Service Connect, consulta Configura una zona gestita DNS e un record DNS.

Il flag facoltativo --public-ip consente al proxy di autenticazione di connettersi a un'istanza con IP pubblico abilitato utilizzando l'indirizzo IP pubblico dell'istanza. Per saperne di più sull'IP pubblico, consulta Connettiti utilizzando l'IP pubblico.

Il flag facoltativo --disable-built-in-telemetry disattiva il reporter delle metriche interne utilizzato dal proxy di autenticazione per generare report sullo stato della connessione e della rete. Per impostazione predefinita, il proxy di autenticazione segnala le sue operazioni interne al prefisso della metrica di sistema alloydb.googleapis.com. Queste metriche aiutano AlloyDB a migliorare le prestazioni e a identificare i problemi di connettività dei client. Questa opzione è utile per le applicazioni che operano in ambienti in cui l'esportazione delle metriche in uscita è limitata. Per disattivare questa telemetria, utilizza questo flag.

Container Docker

Avvia il client proxy di autenticazione utilizzando il comando docker run.

Se utilizzi le credenziali fornite dalla tua istanza Compute Engine, puoi utilizzare un comando simile al seguente:

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

Sostituisci quanto segue:

• PORT: la porta da utilizzare per le connessioni locali al client proxy di autenticazione. Il valore predefinito è 5432.

• INSTANCE_URI: l'URI di connessione dell'istanza AlloyDB a cui connettersi, specificato utilizzando il seguente formato:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  Puoi eseguire l'override della porta del listener locale predefinita utilizzata dal client proxy di autenticazione per l'istanza aggiungendo il parametro di query port all'URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Specifica sempre il prefisso 127.0.0.1 nel flag --publish in modo che il client proxy di autenticazione non sia esposto all'esterno dell'host locale.

Il valore 0.0.0.0 nel flag --address è obbligatorio per rendere il listener accessibile dall'esterno del container Docker.

Per fornire le credenziali archiviate in un file JSON locale, includi i flag --volume e --credentials-file quando esegui il comando docker run:

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Sostituisci PATH_TO_KEY_FILE con il percorso del file della chiave JSON del account di servizio gestito dall'utente da utilizzare per l'autorizzazione della connessione.

Esempi di startup

I seguenti esempi mostrano vari modi per avviare il client proxy di autenticazione. Utilizzano questi URI di connessione alle istanze di esempio:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Avvio di base

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

In questo esempio, il client proxy di autenticazione autorizza la connessione seguendo la normale sequenza di passaggi di autorizzazione, quindi inizia ad ascoltare le connessioni locali all'istanza myprimary su 127.0.0.1:5432.

Avvio con un account di servizio gestito dall'utente

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --credentials-file "myappaccount/key.json"

In questo esempio, il client proxy di autenticazione autorizza la connessione utilizzando la chiave JSON del account di servizio gestito dall'utente archiviata in myappaccount/key.json, quindi inizia ad ascoltare le connessioni locali all'istanza myprimary su 127.0.0.1:5432.

Startup che si connette a più istanze

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

In questo esempio, il client proxy di autenticazione autorizza la connessione seguendo la normale sequenza di passaggi di autorizzazione, quindi inizia ad ascoltare le connessioni locali all'istanza myprimary su 127.0.0.1:5432 e all'istanza myreadpool su 127.0.0.1:5433.

Ascolto all'avvio su porte personalizzate

L'utilizzo di porte personalizzate per il client proxy di autenticazione può essere utile quando devi riservare la porta 5432 per altre connessioni PostgreSQL.

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

In questo esempio, il client proxy di autenticazione autorizza la connessione seguendo la normale sequenza di passaggi di autorizzazione, quindi inizia ad ascoltare le connessioni locali all'istanza myprimary su 127.0.0.1:5000 e all'istanza myreadpool su 127.0.0.1:5001.

Poiché queste porte personalizzate sono sequenziali, è possibile ottenere lo stesso effetto utilizzando questo comando di avvio:

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Avvio dell'ascolto su un indirizzo IP personalizzato

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

In questo esempio, il client proxy di autenticazione autorizza la connessione seguendo la normale sequenza di passaggi di autorizzazione, quindi inizia ad ascoltare le connessioni locali all'istanza myprimary su 0.0.0.0:5432.

Connetti un'applicazione a un database utilizzando il proxy di autenticazione AlloyDB

I seguenti esempi mostrano come connettere un'applicazione a un database utilizzando il proxy di autenticazione AlloyDB.

L'esempio psql fornisce un esempio di connessione di uno strumento a riga di comando.

La connessione a un'istanza AlloyDB utilizzando l'Auth Proxy è, per diversi linguaggi di programmazione, identica alla connessione a un'istanza Cloud SQL per PostgreSQL utilizzando il Cloud SQL Auth Proxy, pertanto gli esempi di linguaggio sono gli stessi di quelli per Cloud SQL per PostgreSQL.

Questi esempi si basano su un avvio predefinito del client proxy di autenticazione in modo che sia in ascolto delle connessioni TCP locali su 127.0.0.1:5432.

Nota: con un nuovo cluster, puoi connetterti come utente postgres utilizzando la password specificata durante la creazione del cluster.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Sostituisci DB_USER con l'utente del database con cui vuoi connetterti, ad esempio postgres.

Ti verrà chiesto di inserire la password dell'utente DB_USER.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    INSTANCE_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Vai

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta gli esempi di Go su GitHub.

package alloydb

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %v", err)
	}

	// ...

	return dbPool, nil
}

C#

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);