Configura i collegamenti rapidi

I collegamenti rapidi su Ambient Networking ti consentono di connettere un servizio Cloud Run di origine a un servizio Cloud Run di destinazione nello stesso progetto e nella stessa regione senza scrivere codice di autenticazione nell'applicazione o configurare un mesh di servizi.

Quando un servizio Cloud Run chiama un altro servizio Cloud Run protetto da Identity and Access Management (IAM), la richiesta deve includere un token ID OpenID Connect (OIDC) in modo che la destinazione possa verificare l'identità e le autorizzazioni del chiamante. Senza un collegamento rapido, devi scrivere il codice di autenticazione service-to-service nella tua applicazione per recuperare e allegare i token dal server dei metadati oppure configurare le risorse di Cloud Service Mesh come una rete Virtual Private Cloud (VPC), i servizi di backend e le regole di instradamento. Un collegamento rapido trasferisce questo lavoro di autenticazione e routing al container sidecar ambient completamente gestito, mantenendo il codice dell'applicazione portabile e concentrato sulla logica di business.

Casi d'uso

Puoi utilizzare i collegamenti rapidi per i seguenti scenari:

  • Esegui l'offload dell'autenticazione service-to-service dal codice dell'applicazione: connetti un servizio Cloud Run chiamante a un servizio Cloud Run di destinazione protetto da IAM tramite HTTP semplice. Il sidecar ambient recupera e inserisce automaticamente il token ID OIDC del servizio di origine e cripta la richiesta tramite HTTPS.
  • URL di destinazione astratti con nomi host personalizzati: configura un nome host personalizzato sul collegamento rapido utilizzando il flag --matches-hostname in modo che l'applicazione di origine invii richieste a un indirizzo logico, ad esempio http://my-backend, anziché impostare come hardcoded l'URL deterministico della destinazione. Se il servizio di destinazione cambia, puoi ricreare il collegamento rapido in modo che punti alla nuova destinazione senza modificare o rifare il deployment del codice dell'applicazione di origine.
  • Semplifica le chiamate di servizio point-to-point senza un mesh di servizi: ottieni l'inserimento automatico delle credenziali tra i servizi Cloud Run senza eseguire il provisioning di una rete VPC, di gruppi di endpoint di rete, di servizi di backend o di record Cloud DNS richiesti da Cloud Service Mesh.

La tabella seguente confronta i passaggi per configurare la comunicazione autenticata tra servizi con e senza un collegamento rapido:

Passaggio Senza un collegamento rapido Con un collegamento rapido
1. Esegui il deployment del servizio di destinazione Esegui il deployment del servizio Cloud Run di destinazione con l'autenticazione IAM obbligatoria (--no-allow-unauthenticated). Uguale.
2. Concedi l'autorizzazione Invoker Concedi il ruolo Cloud Run Invoker (roles/run.invoker) sul servizio di destinazione al account di servizio del servizio di origine. Uguale.
3. Configura la richiesta in uscita Scrivi il codice nell'applicazione di origine per recuperare un token ID OIDC per l'URL di destinazione e collegalo all'intestazione Authorization: Bearer tramite HTTPS. Invia una richiesta http:// semplice all'URL di destinazione o al nome host personalizzato senza codice di autenticazione nell'applicazione di origine.
4. Esegui il deployment del servizio di origine Esegui il deployment del servizio Cloud Run di origine. Esegui il deployment del servizio Cloud Run di origine con l'Ambient Networking abilitato, quindi crea un collegamento rapido tra i servizi di origine e di destinazione di cui è stato eseguito il deployment.

Architettura

Quando attivi l'Ambient Networking su un servizio Cloud Run di origine e crei un collegamento rapido, Cloud Run configura il container sidecar Envoy completamente gestito in esecuzione insieme al container dell'applicazione in ogni istanza del container.

Quando l'applicazione invia una richiesta HTTP semplice all'URL deterministico del servizio di destinazione o a un nome host personalizzato configurato sul collegamento rapido, il container sidecar ambientale esegue automaticamente le seguenti operazioni:

  1. Intercetta le richieste HTTP in uscita destinate al servizio di destinazione.
  2. Recupera un token ID OIDC per il service account del servizio di origine e lo inserisce nell'intestazione Authorization.
  3. Cripta e inoltra la richiesta tramite HTTPS (TLS unidirezionale) al servizio Cloud Run di destinazione, che verifica le autorizzazioni IAM del chiamante.
Un container dell'applicazione all'interno di un servizio Cloud Run di origine che invia una richiesta HTTP in testo normale al container sidecar ambientale, che intercetta la richiesta, inserisce un token ID OIDC e inoltra il token ID e il payload tramite HTTPS tramite un collegamento rapido a un servizio Cloud Run di destinazione.
Figura 1. Il container sidecar ambient intercetta le richieste in uscita dal servizio di origine, inserisce un token ID OIDC e inoltra la richiesta tramite HTTPS (TLS unidirezionale) al servizio di destinazione.

Connettività di rete e piano dati

Un collegamento rapido configura l'intercettazione delle richieste in uscita e l'inserimento delle credenziali nel sidecar ambientale, ma non sostituisce il percorso di rete sottostante tra i tuoi servizi. Devi comunque assicurarti che il servizio di origine possa raggiungere il percorso di ingresso del servizio di destinazione:

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Abilita le API Cloud Run, Network Services e Traffic Director, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

  7. Assicurati di avere un servizio Cloud Run di origine esistente e un servizio Cloud Run di destinazione esistente nello stesso progetto e nella stessa regione.
  8. Assicurati che Ambient Networking sia abilitato con l'ambito global nel servizio Cloud Run di origine. Ad esempio, esegui gcloud beta run services update SOURCE_SERVICE --ambient-networking --ambient-scope=global --region=REGION, ricordandoti di aumentare prima i limiti di CPU e memoria del servizio.

  9. Leggi la pagina dei prezzi di Cloud Run per l'utilizzo del sidecar di Ambient Networking. La fatturazione per le funzionalità ambient non viene applicata durante l'anteprima.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare i collegamenti rapidi, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Configura il collegamento rapido: Cloud Run Developer (roles/run.developer) e Utente dell'account di servizio (roles/iam.serviceAccountUser) sul progetto
  • Gestisci le risorse di collegamento rapido: Network Services Admin (roles/networkservices.admin) sul progetto

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

L'identità di servizio del servizio Cloud Run di origine deve disporre anche dei seguenti ruoli nel progetto:

  • Client Traffic Director (roles/trafficdirector.client)
  • Cloud Trace Agent (roles/cloudtrace.agent)

Per concedere questi ruoli all'identità di servizio, utilizza gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • RUN_CLIENT_SA: il nome del account di servizio collegato al servizio Cloud Run di origine.

Se l'identità del servizio Cloud Run non dispone di questi ruoli, il servizio Cloud Run viene comunque distribuito, ma le funzionalità che dipendono dal networking ambientale non funzionano. Questo comportamento è diverso da quello di Cloud Service Mesh, in cui il deployment del servizio Cloud Run non riesce se mancano i ruoli richiesti.

Limitazioni

Ai collegamenti rapidi si applicano le seguenti limitazioni:

  • Sono supportati solo i servizi Cloud Run come risorse di origine e di destinazione. I job, i pool di worker e le istanze Cloud Run non sono supportati.
  • Le configurazioni tra progetti e tra regioni non sono supportate. Il servizio Cloud Run di origine e il servizio Cloud Run di destinazione devono trovarsi nello stesso progetto e nella stessa regione.
  • I collegamenti rapidi richiedono l'Ambient Networking con l'ambito global nel servizio di origine. Se il servizio di origine utilizza l'ambito regional, la creazione del collegamento rapido riesce, ma il traffico non viene instradato.
  • Devi creare i servizi Cloud Run di origine e di destinazione prima di creare il collegamento rapido. La creazione fuori ordine non è supportata. Se elimini un servizio di destinazione, il collegamento rapido può continuare a mostrare e pubblicare la configurazione obsoleta finché non elimini o ricrei il collegamento rapido.
  • Non puoi aggiornare il servizio di origine, il servizio di destinazione o il nome host personalizzato di un collegamento rapido esistente. Il comando gcloud beta network-services express-links update aggiorna solo la descrizione del collegamento rapido. Per modificare la configurazione del routing, elimina e ricrea il collegamento rapido.
  • I servizi Cloud Run di destinazione devono avere l'URL run.app predefinito abilitato, anche se utilizzi URL personalizzati, domini personalizzati o configuri un nome host personalizzato con il flag --matches-hostname.
  • Le richieste inviate all'URL non deterministico della destinazione non vengono intercettate e non vanno a buon fine con un errore 403 Forbidden. Se il servizio di destinazione non ha un URL deterministico perché il nome del servizio e il numero di progetto combinati superano i 63 caratteri, devi specificare --matches-hostname, altrimenti la creazione del collegamento rapido non va a buon fine e viene visualizzato un errore Cloud Run Service name is too long.
  • Quando visualizzi lo stato completo di un collegamento rapido, vengono restituite solo le informazioni sul servizio di destinazione. I dettagli sulle revisioni di Cloud Run di origine e sull'autenticazione negoziata potrebbero essere mancanti o mostrare dati obsoleti. Ciò non influisce sul modo in cui il collegamento rapido instrada o autentica il traffico.
  • I servizi Cloud Run di origine configurati con l'identità dell'agente e i token associati a mTLS non sono supportati.
  • I servizi Cloud Run di origine configurati per instradare il traffico in uscita tramite Agent Gateway su Cloud Run e Secure Web Proxy non sono supportati. I collegamenti rapidi richiedono l'ambito di Ambient Networking globale, mentre Agent Gateway richiede l'ambito regionale.
  • Se una richiesta in uscita dal servizio di origine include già un'intestazione Authorization, il collegamento rapido inoltra la richiesta con l'intestazione invariata e non inserisce un token. L'inserimento automatico dei token nell'intestazione X-Serverless-Authorization non è supportato.
  • Il traffico generato dai container di sandbox di Cloud Run non è supportato.
  • Non puoi utilizzare i collegamenti rapidi per inoltrare il traffico ai servizi Cloud Run di destinazione protetti da Identity-Aware Proxy.
  • Ogni collegamento rapido supporta un servizio Cloud Run di destinazione e puoi creare fino a 5000 collegamenti rapidi per progetto.

Per connettere i tuoi servizi Cloud Run, crea un collegamento rapido specificando il servizio di origine e il servizio di destinazione, quindi concedi il ruolo Cloud Run Invoker sul servizio di destinazione.

Connettiti a un altro servizio Cloud Run

Per connettere un servizio Cloud Run di origine a un servizio Cloud Run di destinazione, crea un collegamento rapido utilizzando gcloud o YAML.

gcloud

Utilizza il comando gcloud beta network-services express-links create per creare un collegamento rapido:

gcloud beta network-services express-links create EXPRESS_LINK_NAME \
    --location=global \
    --source-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE \
    --destination-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE

Sostituisci quanto segue:

  • EXPRESS_LINK_NAME: un nome per il collegamento rapido.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione in cui è stato eseguito il deployment dei servizi Cloud Run.
  • SOURCE_SERVICE: il nome del servizio Cloud Run di origine.
  • DESTINATION_SERVICE: il nome del servizio Cloud Run di destinazione.

Al termine del comando, possono essere necessari fino a 2 minuti prima che la configurazione del routing venga propagata alle istanze del servizio di origine in esecuzione.

Per impostazione predefinita, il collegamento rapido intercetta solo le richieste inviate all'URL deterministico del servizio di destinazione, non al suo URL non deterministico. Per utilizzare un nome host personalizzato, passa il nome host senza uno schema nel flag --matches-hostname="HOSTNAME", ad esempio --matches-hostname="DESTINATION_SERVICE", e invia le richieste dalla tua applicazione di origine a http://HOSTNAME. Se specifichi --matches-hostname, l'URL deterministico viene sostituito anziché aggiunto.

YAML

  1. Crea un file di configurazione, ad esempio express-link.yaml:

    name: "projects/PROJECT_ID/locations/global/expressLinks/EXPRESS_LINK_NAME"
source:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE"
destination:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE"

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • REGION: la regione in cui è stato eseguito il deployment dei servizi.
    • EXPRESS_LINK_NAME: un nome per il collegamento rapido.
    • SOURCE_SERVICE: il nome del servizio Cloud Run di origine.
    • DESTINATION_SERVICE: il nome del servizio Cloud Run di destinazione.

  2. Importa il file YAML utilizzando il comando gcloud beta network-services express-links import:

    gcloud beta network-services express-links import EXPRESS_LINK_NAME \
    --location=global \
    --source=YAML_FILENAME.yaml

    Sostituisci quanto segue:

    • EXPRESS_LINK_NAME: un nome per il collegamento rapido.
    • YAML_FILENAME: il nome del file YAML.

Concedi le autorizzazioni Invoker sul servizio di destinazione

Per consentire al servizio di origine di richiamare un servizio di destinazione protetto da IAM, concedi il ruolo Cloud Run Invoker (roles/run.invoker) al account di servizio del servizio di origine nel servizio Cloud Run di destinazione. Questo è necessario per il funzionamento dell'autenticazione nel piano dati.

gcloud run services add-iam-policy-binding DESTINATION_SERVICE \
    --member="serviceAccount:SOURCE_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=REGION

Sostituisci quanto segue:

  • DESTINATION_SERVICE: il nome del servizio Cloud Run di destinazione.
  • SOURCE_SA: il nome del account di servizio collegato al servizio Cloud Run di origine.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione in cui è stato eseguito il deployment del servizio di destinazione.

Verifica lo stato del collegamento rapido

Per visualizzare la configurazione di base del collegamento rapido, utilizza il comando gcloud beta network-services express-links describe:

gcloud beta network-services express-links describe EXPRESS_LINK_NAME \
    --location=global

Per visualizzare lo stato completo del collegamento rapido, tra cui connectionStatus (tipo di route attiva, nomi host corrispondenti e URI della revisione di origine) e cloudRunSourceInfo (metodi di autenticazione configurati e rete VPC), includi ?view=EXPRESS_LINK_VIEW_FULL# nel nome della risorsa:

gcloud beta network-services express-links describe 'EXPRESS_LINK_NAME?view=EXPRESS_LINK_VIEW_FULL#' \
    --location=global

Sostituisci EXPRESS_LINK_NAME con il nome del tuo collegamento rapido. Mantieni gli apici singoli e il carattere # finale quando esegui query sulla visualizzazione completa.

Per rimuovere un collegamento rapido e interrompere l'inserimento automatico delle credenziali e l'intercettazione del traffico dal servizio di origine, utilizza il comando gcloud beta network-services express-links delete:

gcloud beta network-services express-links delete EXPRESS_LINK_NAME \
    --location=global

Sostituisci EXPRESS_LINK_NAME con il nome del tuo collegamento rapido.

Per indirizzare un collegamento rapido esistente a un servizio di destinazione diverso o modificare l'impostazione --matches-hostname, elimina il collegamento rapido con il comando precedente, quindi crea un nuovo collegamento rapido con la configurazione aggiornata.

Passaggi successivi