Risolvi i problemi di Cloud Run con SSH

SSH ti consente di stabilire una connessione shell interattiva e sicura alle istanze di container in esecuzione. In questo modo, puoi accedere direttamente al file system e all'ambiente di runtime del container, ispezionare le risorse di sistema, verificare le configurazioni e risolvere i problemi.

SSH per Cloud Run utilizza i seguenti servizi per proteggere le connessioni:

  • L'inoltro TCP di Identity-Aware Proxy funge da proxy per le connessioni SSH, quindi le richieste devono superare i controlli di autenticazione e autorizzazione prima di raggiungere il container. Puoi estendere le policy di accesso di IAP con l'accesso sensibile al contesto per limitare l'accesso in base ad attributi come l'indirizzo IP e il dispositivo dell'utente finale.
  • OS Login utilizza l'autenticazione del certificato SSH per autenticare gli utenti. Quando ti connetti, gcloud CLI genera un certificato SSH di breve durata che scade dopo cinque minuti. Il certificato viene convalidato all'interno del container. Google controlla le autorizzazioni IAM per ogni tentativo di accesso.

SSH per Cloud Run aggiunge automaticamente i file binari gestiti da Google richiesti, tra cui sshd e i file binari che convalidano il certificato, al file system del container. Questi file binari sono accessibili solo per la durata della sessione SSH e vengono rimossi al termine della sessione. Le configurazioni SSH esistenti, incluse le voci /etc/passwd, vengono ignorate da SSH di Cloud Run a favore delle configurazioni gestite da Google.

Le note sul copyright open source di terze parti per le dipendenze SSH gestite da Google vengono montate all'interno del container quando viene stabilita una sessione SSH nel seguente percorso: /usr/share/licenses/google_ssh/THIRD_PARTY_NOTICES.

Sessioni SSH e istanze di servizio

Quando ti connetti a un servizio tramite SSH, tieni presente quanto segue:

  • Se non è in esecuzione alcuna istanza del servizio, Cloud Run avvia una nuova istanza per la sessione SSH.
  • Cloud Run mira a mantenere attiva l'istanza del servizio per la durata della sessione SSH. L'istanza ti viene fatturata come di consueto mentre è attiva.

Limitazioni

A SSH si applicano le seguenti limitazioni:

  • Le sessioni SSH durano al massimo 24 ore. Dopo 24 ore, la sessione viene disconnessa e devi riconnetterti.
  • IAP disconnette le sessioni SSH dopo un'ora di inattività. Per saperne di più, consulta Limitazioni note dell'inoltro TCP di IAP.
  • SSH è disponibile solo per i servizi eseguiti nell'ambiente di seconda generazione di Cloud Run e nelle istanze Cloud Run.
  • Quando utilizzi SSH, le chiavi host nell'immagine vengono sovrascritte. Le chiavi rimangono sovrascritte dopo la fine della sessione SSH, fino al riavvio dell'istanza del servizio.
  • Windows: PuTTY non è supportato. Utilizza il client OpenSSH.
  • Quando utilizzi SSH, devi prestare particolare attenzione alla protezione del container. Prendi in considerazione le best practice di sicurezza, ad esempio l'esecuzione del codice dell'applicazione come utente non root.
  • Quando una connessione SSH avvia a freddo un servizio multi-container con l'ordine di avvio dei container (container-dependencies), la richiesta viene instradata prima che l'ambiente del container sia pronto. Cloud Run restituisce un errore HTTP 500 e arresta immediatamente la nuova istanza. Se ti connetti utilizzando Google Cloud CLI, il comando non va a buon fine. Per risolvere il problema, connettiti tramite SSH solo quando un'istanza è già in esecuzione. Ad esempio, invia prima una richiesta al servizio per avviare un'istanza o configura il numero minimo di istanze.

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 l'API Cloud Run Admin, l'API Cloud Resource Manager, l'API Identity-Aware Proxy e le API Cloud OS Login: 
      gcloud services enable run.googleapis.com \
      cloudresourcemanager.googleapis.com \
      iap.googleapis.com \
      oslogin.googleapis.com
  7. Installa e inizializza gcloud CLI.
  8. Aggiorna i componenti: 
    gcloud components update
  9. Windows: assicurati che il client OpenSSH sia installato.

    Il client OpenSSH è in genere installato per impostazione predefinita su Windows 10 e versioni successive. Se non è installato, puoi installarlo eseguendo il seguente comando in PowerShell come amministratore:

    Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

    Per saperne di più, consulta Installa OpenSSH.

  10. Consulta la pagina dei prezzi di Cloud Run. Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. SSH fattura i byte in uscita dalla rete. Inoltre, ti verrà addebitato il costo dell'istanza come di consueto mentre è attiva per una sessione SSH.
  11. Se il tuo progetto utilizza i Controlli di servizio VPC (VPC-SC), tieni presente che il processo di tunneling controlla iaptunnel.googleapis.com come nome del servizio, anziché run.googleapis.com.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare questi passaggi, chiedi all'amministratore di concederti i seguenti ruoli IAM:

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.

Se non sei un membro dell'organizzazione di cui fa parte il progetto, Cloud Run blocca l'accesso SSH. Per ottenere l'accesso SSH, aggiungi il ruolo roles/compute.osLoginExternalUser o utilizza un ruolo personalizzato con l'autorizzazione compute.oslogin.updateExternalUser.

Puoi concedere il ruolo Utente tunnel protetto da IAP a livello di progetto. Per limitare questo ruolo a un servizio o un'istanza Cloud Run specifico, esegui questo comando:

Per un servizio specifico 

gcloud beta iap tcp add-iam-policy-binding \
    --resource-type=cloud-run \
    --service=SERVICE \
    --region=REGION \
    --member=MEMBER \
    --role=roles/iap.tunnelResourceAccessor

Sostituisci quanto segue:

  • SERVICE: il nome del servizio.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.
  • MEMBER: l'identità a cui concedere l'accesso.

Per un'istanza specifica 

gcloud beta iap tcp add-iam-policy-binding \
    --resource-type=cloud-run \
    --instance=INSTANCE \
    --region=REGION \
    --member=MEMBER \
    --role=roles/iap.tunnelResourceAccessor

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.
  • MEMBER: l'identità a cui concedere l'accesso.

Per concedere il ruolo roles/iap.tunnelResourceAccessor a livello di progetto e regione, consulta Configura le policy di accesso di IAP.

Utilizza SSH con i servizi Cloud Run

Configura l'accesso SSH a livello di servizio e connettiti al servizio tramite SSH.

Configura l'accesso SSH a livello di servizio

Puoi consentire l'accesso in ispezione a un servizio specifico utilizzando gcloud CLI o YAML:

gcloud

Per abilitare l'accesso a un servizio esistente, utilizza il seguente comando:

gcloud beta run services update SERVICE --ssh

Puoi anche consentire l'accesso di ispezione a un servizio utilizzando il flag --ssh durante il deployment del servizio.

YAML

  1. Se stai creando un nuovo servizio, salta questo passaggio. Se stai aggiornando un servizio esistente, scarica la relativa configurazione YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. L'esempio seguente contiene la configurazione YAML:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "true"
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
        image: IMAGE_URL

    Sostituisci quanto segue:

    • SERVICE: il nome del tuo servizio Cloud Run.
    • REGION: la regione Google Cloud , ad esempio us-central1.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  3. Crea o aggiorna il servizio utilizzando il seguente comando:

    gcloud run services replace service.yaml

    Il comando gcloud run services replace utilizza per impostazione predefinita il file service.yaml, se presente.

Puoi disattivare l'accesso SSH per ogni servizio utilizzando gcloud CLI o YAML:

gcloud

Per disattivare l'accesso al servizio, utilizza il seguente comando:

gcloud beta run services update SERVICE --no-ssh

YAML

  1. Se stai creando un nuovo servizio, salta questo passaggio. Se stai aggiornando un servizio esistente, scarica la relativa configurazione YAML:

    gcloud run services describe SERVICE --format export > service.yaml

  2. L'esempio seguente contiene la configurazione YAML:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "false"
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
        image: IMAGE_URL

    Sostituisci quanto segue:

    • SERVICE: il nome del tuo servizio Cloud Run.
    • REGION: la regione Google Cloud , ad esempio us-central1.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  3. Crea o aggiorna il servizio utilizzando il seguente comando:

    gcloud run services replace service.yaml

    Il comando gcloud run services replace utilizza per impostazione predefinita il file service.yaml, se presente.

Connettiti al servizio con SSH

Per connetterti a un servizio utilizzando SSH, utilizza gcloud CLI:

Console

  1. Nella console Google Cloud , vai alla pagina Servizi di Cloud Run:

    Vai a Cloud Run

  2. Fai clic su un servizio per aprire la pagina Dettagli servizio.

  3. Seleziona SSH. Viene aperto Cloud Shell con il comando SSH gcloud.

  4. Premi Invio.

  5. Se ti viene chiesto di inserire una passphrase per la chiave SSH, puoi lasciare il campo vuoto. Tuttavia, se inserisci una passphrase, assicurati di utilizzare la stessa passphrase per tutte le sessioni SSH successive dalla stessa area di lavoro.

  6. Al termine della sessione SSH, Cloud Run visualizza il seguente messaggio:

    Project: PROJECT_ID
Region: REGION
Service: SERVICE
Revision: REVISION
Instance: INSTANCE_ID
Container: CONTAINER
Image: IMAGE

  7. Per terminare la sessione SSH, digita exit. Tutte le modifiche apportate al container persistono per tutto il tempo in cui il container viene mantenuto attivo. L'uscita dalla sessione non riavvia né interrompe il container.

gcloud

Per connetterti a un servizio tramite SSH, utilizza il seguente comando di Google Cloud CLI:

gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID

Sostituisci quanto segue:

  • SERVICE: il nome del servizio.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.
  • PROJECT_ID: l'ID progetto Google Cloud .

Se ti viene chiesto di inserire una passphrase per la chiave SSH, puoi lasciare il campo vuoto. Tuttavia, se inserisci una passphrase, assicurati di utilizzare la stessa passphrase per tutte le sessioni SSH successive dalla stessa area di lavoro.

Al termine della sessione SSH, Cloud Run visualizza il seguente messaggio:

Project: PROJECT_ID
Region: REGION
Service: SERVICE
Revision: REVISION
Instance: INSTANCE_ID
Container: CONTAINER
Image: IMAGE

Per terminare la sessione SSH, digita exit. Tutte le modifiche apportate al container persistono per tutto il tempo in cui il container viene mantenuto attivo. L'uscita dalla sessione non riavvia né interrompe il container.

Specifica un'istanza di servizio

Per connetterti a un'istanza di servizio specifica utilizzando SSH, utilizza Google Cloud CLI.

Console

  1. Nella console Google Cloud , vai alla pagina Servizi di Cloud Run:

    Vai a Cloud Run

  2. Fai clic sul servizio che ti interessa per aprire la pagina Dettagli servizio.

  3. Seleziona Log.

  4. Fai clic sulla voce di log dell'istanza di servizio per espanderla.

  5. Seleziona Accedi a questa istanza tramite SSH. Viene aperto Cloud Shell con il comando SSH gcloud.

  6. Premi Invio.

gcloud

Per connetterti a un'istanza di servizio Cloud Run utilizzando SSH, utilizza il seguente comando Google Cloud CLI:

gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID \
  --revision=REVISION \
  --instance=INSTANCE_ID

Sostituisci quanto segue:

  • SERVICE: il nome del servizio.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • REVISION: il nome della revisione.
  • INSTANCE_ID: l'ID istanza. Per trovare l'ID istanza di servizio, vai alla pagina Log nella sezione Osservabilità. L'ID istanza si trova nel campo labels di una voce di log. Non puoi trovare l'ID istanza se termini l'istanza specifica prima di connetterti.

Specifica una revisione

Per connetterti a una revisione specifica utilizzando SSH, utilizza Google Cloud CLI.

Console

  1. Nella console Google Cloud , vai alla pagina Servizi di Cloud Run:

    Vai a Cloud Run

  2. Fai clic sul servizio che ti interessa per aprire la pagina Dettagli servizio.

  3. Seleziona Cronologia delle revisioni.

  4. Fai clic sull'icona con i puntini di sospensione a destra della revisione a cui vuoi connetterti tramite SSH.

  5. Seleziona Accedi alle revisioni tramite SSH. Viene aperto Cloud Shell con il comando SSH gcloud.

  6. Premi Invio.

gcloud

Per connetterti a una revisione del servizio Cloud Run utilizzando SSH, utilizza il seguente comando Google Cloud CLI:

gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID --revision=REVISION

Sostituisci quanto segue:

  • SERVICE: il nome del servizio.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • REVISION: il nome della revisione.

Utilizza SSH con le istanze Cloud Run

Configura l'accesso SSH a livello di istanza e connettiti all'istanza tramite SSH.

Configura l'accesso SSH a livello di istanza

SSH è abilitato per impostazione predefinita per le istanze.

Puoi disattivare l'accesso SSH per singola istanza utilizzando gcloud CLI o YAML:

gcloud

Per disattivare l'accesso nell'istanza, utilizza il seguente comando:

gcloud beta run instances update INSTANCE --no-ssh

YAML

  1. Se stai creando una nuova istanza, salta questo passaggio. Se stai aggiornando un'istanza esistente, scarica la relativa configurazione YAML:

    gcloud beta run instances describe INSTANCE --format export > instance.yaml

  2. L'esempio seguente contiene la configurazione YAML:

    apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "false"
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
    image: IMAGE_URL

    Sostituisci quanto segue:

    • INSTANCE: il nome dell'istanza Cloud Run.
    • REGION: la regione Google Cloud , ad esempio us-central1.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.

  3. Crea o aggiorna l'istanza utilizzando il seguente comando:

    gcloud beta run instances replace instance.yaml

Puoi consentire l'accesso per l'ispezione a un'istanza specifica utilizzando gcloud CLI o YAML.

gcloud

Per attivare l'accesso su un'istanza esistente, utilizza il seguente comando:

gcloud beta run instances update INSTANCE --ssh

Puoi anche consentire l'accesso di ispezione a un'istanza utilizzando il flag --ssh durante il deployment dell'istanza.

YAML

  1. Se stai creando una nuova istanza, salta questo passaggio. Se stai aggiornando un'istanza esistente, scarica la relativa configurazione YAML:

    gcloud beta run instances describe INSTANCE --format export > instance.yaml

  2. L'esempio seguente contiene la configurazione YAML:

    apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "true"
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
    image: IMAGE_URL

    Sostituisci quanto segue:

    • INSTANCE: il nome dell'istanza Cloud Run.
    • REGION: la regione Google Cloud , ad esempio us-central1.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.

  3. Crea o aggiorna l'istanza utilizzando il seguente comando:

    gcloud beta run instances replace instance.yaml

Connettiti all'istanza con SSH

Per connetterti a un'istanza tramite SSH, utilizza il seguente comando di Google Cloud CLI:

  gcloud beta run instances ssh INSTANCE --region=REGION --project=PROJECT_ID

Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.
  • PROJECT_ID: l'ID progetto Google Cloud .

Se ti viene chiesto di inserire una passphrase per la chiave SSH, puoi lasciare il campo vuoto. Tuttavia, se inserisci una passphrase, assicurati di utilizzare la stessa passphrase per tutte le sessioni SSH successive dalla stessa area di lavoro.

Al termine della sessione SSH, Cloud Run visualizza il seguente messaggio:

  Project: PROJECT_ID
  Region: REGION
  Instance: INSTANCE
  Revision: REVISION
  Container: CONTAINER
  Image: IMAGE

Per terminare la sessione SSH, digita exit.

Utilizza il client OpenSSH per connetterti

Per connetterti utilizzando il client OpenSSH:

  1. Esegui il comando gcloud beta run services ssh sul servizio di destinazione. In questo modo viene avviato il tunnel SSH e generato il certificato.

  2. Aggiungi quanto segue alla configurazione SSH:

    Host cloud-run-ssh
    HostName cloud-run-default
    User root
    IdentityFile /Users/USER/.ssh/google_compute_engine
    CertificateFile /Users/USER/.ssh/google_compute_engine_cert/PROJECT_ID_REGION_SERVICE-cert.pub
    CheckHostIP no
    HashKnownHosts no
    HostKeyAlias cloud-run-default
    IdentitiesOnly yes
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    ProxyUseFdpass no
    ProxyCommand /usr/local/bin/python3 -S /Users/USER/google-cloud-sdk/lib/gcloud.py beta run start-iap-tunnel --project_number=PROJECT_NUMBER --project_id=PROJECT_ID --workload_type=service --deployment_name=SERVICE --region=REGION

    Sostituisci quanto segue:

    • USER: il nome utente sulla tua macchina locale.
    • PROJECT_ID: l'ID progetto Google Cloud .
    • PROJECT_NUMBER: il numero di progetto Google Cloud .
    • REGION: la regione in cui è stato eseguito il deployment del servizio.
    • SERVICE: il nome del servizio.

    Se gcloud CLI è installata in un'altra cartella, potresti dover aggiornare la posizione nell'ultima riga.

  3. Esegui questo comando:

    ssh cloud-run-ssh

Il certificato SSH scade dopo cinque minuti. Se provi a stabilire una connessione SSH con il tuo servizio dopo cinque minuti, devi eseguire nuovamente gcloud beta run services ssh per generare di nuovo il certificato.

Log di accesso SSH

Per acquisire gli audit log per la gestione delle chiavi SSH, devi attivare gli audit log per l'API Cloud OS Login. Consulta Visualizza gli audit log di OS Login. Per accedere ai log SSH delle risorse Cloud Run, devi avere accesso a Cloud Audit Logs per quel progetto.

L'esempio seguente esegue una query su tutti i servizi Cloud Run per il giorno precedente:

gcloud logging read '
  logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access" AND
  protoPayload.serviceName="oslogin.googleapis.com" AND
  protoPayload.request.instance:"run.googleapis.com"
' --project=PROJECT_ID \
  --freshness=1d \
  --format="table(timestamp, protoPayload.authenticationInfo.principalSubject:label=USER, protoPayload.request.instance:label=CLOUD_RUN_SERVICE)"

Proteggi e controlla l'accesso SSH

Puoi controllare chi può utilizzare SSH e come viene limitato nel tuo ambiente.

Disattiva l'accesso SSH con le policy dell'organizzazione

Per impostare una policy dell'organizzazione per disattivare SSH, utilizza il vincolo personalizzato che limita l'attivazione dell'accesso di debug SSH ai servizi Cloud Run.

Passaggi successivi