Tutorial sulla riga di comando gcloud all'interno di un servizio Cloud Run

In questo tutorial, creerai un inventario dei servizi Cloud Run utilizzando gli strumenti a riga di comando gcloud e gsutil all'interno di un servizio Cloud Run. Puoi applicare ciò che apprendi in questo tutorial agli script delle operazioni Cloud esistenti o per creare un proof of concept prima di utilizzare le librerie client per creare un servizio più solido.

Puoi utilizzare gli strumenti gcloud e gsutil come qualsiasi script shell all'interno di un servizio web, ad esempio, come mostrato nella guida rapida di Shell. Su Cloud Run, entrambi gli strumenti funzionano con i servizi Google Cloud mediante l'autenticazione automatica con l'identità del servizio Cloud Run. Eventuali autorizzazioni concesse all'identità di servizio sono disponibili per gcloud CLI.

Gcloud CLI è talmente in grado di raccogliere informazioni e gestire le risorse in Google Cloud in modo così ampio che la sfida di utilizzarla in un servizio web riduce al minimo il rischio che un chiamante utilizzi queste funzionalità in modo improprio. Senza i controlli di sicurezza, potresti creare rischi per altri servizi o risorse in esecuzione nello stesso progetto consentendo attività dannose accidentali o intenzionali. Esempi di tali rischi includono:

Abilitazione del rilevamento degli indirizzi IP delle macchine virtuali private
Abilitazione dell'accesso ai dati privati da un database nello stesso progetto
Abilitazione dell'eliminazione di altri servizi in esecuzione

Diversi passaggi di questo tutorial mostrano come imporre controlli per ridurre al minimo i rischi, ad esempio specificare il comando gcloud da eseguire nel codice, invece di lasciarlo aperto come input utente.

Lo scripting con lo strumento a riga di comando in un servizio Cloud Run è simile all'utilizzo della riga di comando localmente. La differenza principale sono le limitazioni aggiuntive che dovresti aggiungere riguardo alla logica dello script principale.

Obiettivi

Scrivi e crea un container personalizzato con un Dockerfile
Scrivi, crea ed deploy di un servizio Cloud Run
Usa gli strumenti gcloud e gsutil in sicurezza in un servizio web
Genera un report sui servizi Cloud Run e salvalo in Cloud Storage

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Prima di iniziare

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 gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Abilita le API Artifact Registry, Cloud Build, Cloud Run, and Cloud Storage.
Abilita le API

Installa e inizializza gcloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare il tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo progetto:

Editor Cloud Build (roles/cloudbuild.builds.editor)
Amministratore Cloud Run (roles/run.admin)
Crea account di servizio (roles/iam.serviceAccountCreator)
Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin)
Utente account di servizio (roles/iam.serviceAccountUser)
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
Amministratore Storage (roles/storage.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura le impostazioni predefinite di gcloud

Per configurare gcloud con i valori predefiniti per il tuo servizio Cloud Run:

Imposta il progetto predefinito:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con il nome del progetto che hai creato per questo tutorial.
Configura gcloud per la regione scelta:
```
gcloud config set run/region REGION
```
Sostituisci REGION con un'area geografica Cloud Run supportata a tua scelta.

Località di Cloud Run

Cloud Run è regionale, il che significa che l'infrastruttura che esegue i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google per essere disponibile in modo ridondante in tutte le zone all'interno di quella regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità sono fattori principali per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. In genere, puoi selezionare la regione più vicina ai tuoi utenti, ma ti consigliamo di considerare la località degli altri prodotti Google Cloud utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato di prodotti Google Cloud in più località può influire sulla latenza e sui costi del tuo servizio.

Cloud Run è disponibile nelle seguenti regioni:

Soggetto ai prezzi di Livello 1

asia-east1 (Taiwan)
asia-northeast1 (Tokyo)
asia-northeast2 (Osaka)
europe-north1 (Finlandia) Bassi livelli di CO₂
europe-southwest1 (Madrid)
europe-west1 (Belgio) Bassi livelli di CO₂
europe-west4 (Paesi Bassi)
europe-west8 (Milano)
europe-west9 (Parigi) A basse emissioni di CO₂
me-west1 (Tel Aviv)
us-central1 (Iowa) A basse emissioni di CO₂
us-east1 (Carolina del Sud)
us-east4 (Virginia del Nord)
us-east5 (Colombo)
us-south1 (Dallas)
us-west1 (Oregon) Bassi livelli di CO₂

Soggetto ai prezzi di Livello 2

africa-south1 (Johannesburg)
asia-east2 (Hong Kong)
asia-northeast3 (Seul, Corea del Sud)
asia-southeast1 (Singapore)
asia-southeast2 (Giacarta)
asia-south1 (Mumbai, India)
asia-south2 (Delhi, India)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsavia, Polonia)
europe-west10 (Berlino)
europe-west12 (Torino)
europe-west2 (Londra, Regno Unito) A basse emissioni di CO₂
europe-west3 (Francoforte, Germania) A basse emissioni di CO₂
europe-west6 (Zurigo, Svizzera) A basse emissioni di CO₂
me-central1 (Doha)
me-central2 (Dammam)
northamerica-northeast1 (Montreal) A basse emissioni di CO₂
northamerica-northeast2 (Toronto) A basse emissioni di CO₂
southamerica-east1 (San Paolo, Brasile) A basse emissioni di CO₂
southamerica-west1 (Santiago, Cile) A basse emissioni di CO₂
us-west2 (Los Angeles)
us-west3 (Salt Lake City)
us-west4 (Las Vegas)

Se hai già creato un servizio Cloud Run, puoi visualizzare la regione nella dashboard di Cloud Run nella console Google Cloud.

Recupero dell'esempio di codice

Per recuperare l'esempio di codice da utilizzare:

Clona il repository dell'app di esempio sulla tua macchina locale:
```
git clone https://github.com/GoogleCloudPlatform/cloud-run-samples.git
```
In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice di esempio di Cloud Run:
```
cd cloud-run-samples/gcloud-report/
```

Rivedi il codice

Questa sezione contiene informazioni sull'esempio di codice recuperato.

Generare un report e caricarlo su Cloud Storage

Questo script shell genera un report dei servizi Cloud Run nel progetto e nella regione correnti e carica il risultato in Cloud Storage. Elenca i servizi il cui nome contiene l'argomento di stringa search fornito.

Lo script utilizza il comando gcloud run services list, le opzioni di formato avanzate di gcloud e la modalità di copia per il trasferimento streaminggsutil.

set -eo pipefail

# Check for required environment variables.
requireEnv() {
  test "${!1}" || (echo "gcloud-report: '$1' not found" >&2 && exit 1)
}
requireEnv GCLOUD_REPORT_BUCKET

# Prepare formatting: Default search term to include all services.
search=${1:-'.'}
limits='spec.template.spec.containers.resources.limits.flatten("", "", " ")'
format='table[box, title="Cloud Run Services"](name,status.url,metadata.annotations.[serving.knative.dev/creator],'${limits}')'

# Create a specific object name that will not be overridden in the future.
obj="gs://${GCLOUD_REPORT_BUCKET}/report-${search}-$(date +%s).txt"

# Write a report containing the service name, service URL, service account or user that
# deployed it, and any explicitly configured service "limits" such as CPU or Memory.
gcloud run services list \
  --format "${format}" \
  --filter "metadata.name~${search}" | gsutil -q cp -J - "${obj}"

# /dev/stderr is sent to Cloud Logging.
echo "gcloud-report: wrote to ${obj}" >&2
echo "Wrote report to ${obj}"

Questo script può essere eseguito come servizio perché chiamate ripetute aggiornano il report senza ulteriori costosi tassi di abbandono. Altri script che utilizzano gcloud CLI possono essere più costosi se richiamati ripetutamente, ad esempio la creazione di nuove risorse Cloud o l'esecuzione di attività costose. Gli script idempotenti, che producono lo stesso risultato a chiamate ripetute, sono più sicuri da eseguire come servizio.

Richiama lo script su richiesta HTTP

Questo codice Go configura un servizio web che esegue uno script shell per generare un report. Poiché la query di ricerca è input utente'utente, il codice la convalida per garantire che contenga solo lettere, numeri o trattini per evitare comandi dannosi come input. Questo set di caratteri è sufficientemente ristretto da impedire attacchi di command injection.

Il servizio web passa il parametro di ricerca come argomento allo script shell.


// Service gcloud-report is a Cloud Run shell-script-as-a-service.
package main

import (
	"log"
	"net/http"
	"os"
	"os/exec"
	"regexp"
)

func main() {
	http.HandleFunc("/", scriptHandler)

	// Determine port for HTTP service.
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	// Start HTTP server.
	log.Printf("listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

func scriptHandler(w http.ResponseWriter, r *http.Request) {
	search := r.URL.Query().Get("search")
	re := regexp.MustCompile(`^[a-z]+[a-z0-9\-]*$`)
	if !re.MatchString(search) {
		log.Printf("invalid search criteria %q, using default", search)
		search = "."
	}

	cmd := exec.CommandContext(r.Context(), "/bin/bash", "script.sh", search)
	cmd.Stderr = os.Stderr
	out, err := cmd.Output()
	if err != nil {
		log.Printf("Command.Output: %v", err)
		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		return
	}
	w.Write(out)
}

Un file go.mod dichiara le dipendenze dell'applicazione in un modulo go:

module github.com/GoogleCloudPlatform/cloud-run-samples/gcloud-report

go 1.19

definisci l'ambiente del container

Il Dockerfile definisce il modo in cui l'ambiente viene creato per il servizio. È simile al Dockerfile della guida rapida di helloworld-shell, tranne per il fatto che l'immagine container finale si basa sull'immagine gcloud di Google Cloud CLI. Ciò consente al nostro servizio di utilizzare gcloud e gsutil senza passaggi di installazione e configurazione personalizzati per Google Cloud CLI.


# Use the official golang image to create a binary.
# This is based on Debian and sets the GOPATH to /go.
# https://hub.docker.com/_/golang
FROM golang:1.20-buster as builder

# Create and change to the app directory.
WORKDIR /app

# Retrieve application dependencies.
# This allows the container build to reuse cached dependencies.
# Expecting to copy go.mod and if present go.sum.
COPY go.* ./
RUN go mod download

# Copy local code to the container image.
COPY invoke.go ./

# Build the binary.
RUN go build -mod=readonly -v -o server

# Use a gcloud image based on debian:buster-slim for a lean production container.
# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM gcr.io/google.com/cloudsdktool/cloud-sdk:slim

WORKDIR /app

# Copy the binary to the production image from the builder stage.
COPY --from=builder /app/server /app/server
COPY *.sh /app/
RUN chmod +x /app/*.sh

# Run the web service on container startup.
CMD ["/app/server"]

Crea un repository standard Artifact Registry

Crea un repository standard Artifact Registry per archiviare l'immagine container:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=REGION

Sostituisci:

REPOSITORY con un nome univoco per il repository.
REGION con la regione Google Cloud di Artifact Registry.

configura il bucket Cloud Storage

Crea un bucket Cloud Storage per caricare i report:

gsutil mb gs://REPORT_ARCHIVE_BUCKET

Sostituisci REPORT_ARCHIVE_BUCKET con un nome di bucket univoco a livello globale.

Configura l'identità del servizio

Per limitare i privilegi del servizio ad altre infrastruttura, devi creare un'identità di servizio e personalizzare le autorizzazioni IAM specifiche necessarie per svolgere il lavoro.

In questo caso, i privilegi richiesti sono l'autorizzazione per leggere i servizi Cloud Run e per leggere e scrivere nel bucket Cloud Storage.

Crea un account di servizio:

gcloud iam service-accounts create gcloud-report-identity

Concedi all'account di servizio l'autorizzazione a leggere i servizi Cloud Run:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com \
  --role roles/run.viewer

Concedi all'account di servizio l'autorizzazione di lettura e scrittura nel bucket Cloud Storage:

gsutil iam ch \
  serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com:objectViewer,objectCreator \
  gs://REPORT_ARCHIVE_BUCKET

L'accesso limitato a questa identità di servizio personalizzata impedisce al servizio di accedere ad altre risorse Google Cloud.

Spedisci il servizio

Il codice di spedizione prevede tre passaggi:

crea un'immagine container con Cloud Build
Caricamento dell'immagine container su Artifact Registry
Deployment dell'immagine container in Cloud Run.

Per spedire il tuo codice:

Crea il tuo container e pubblicalo su Artifact Registry:
```
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/gcloud-report
```
Sostituisci:
- PROJECT_ID con l'ID progetto Google Cloud
- REPOSITORY con il nome del repository Artifact Registry.
- REGION con la regione Google Cloud di Artifact Registry.
gcloud-report è il nome del tuo servizio.

Se l'operazione ha esito positivo, viene visualizzato un messaggio di SUCCESSO con l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e può essere riutilizzata, se necessario.
Esegui questo comando per eseguire il deployment del servizio:
```
gcloud run deploy gcloud-report \
   --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/gcloud-report \
   --update-env-vars GCLOUD_REPORT_BUCKET=REPORT_ARCHIVE_BUCKET \
   --service-account gcloud-report-identity \
   --no-allow-unauthenticated
```
Sostituisci:
- PROJECT_ID con il tuo ID progetto Google Cloud.
- REPOSITORY con il nome del repository Artifact Registry.
- REGION con la regione Google Cloud del servizio.
gcloud-report fa parte del nome del container e del nome del servizio. Il deployment dell'immagine container viene eseguito nel servizio e nella regione (Cloud Run) che hai configurato in precedenza in Configurazione di gcloud.

Il flag --no-allow-unauthenticated limita l'accesso non autenticato al servizio. Mantenendo privato il servizio, puoi fare affidamento sull'autenticazione integrata di Cloud Run per bloccare le richieste non autorizzate. Per maggiori dettagli sull'autenticazione basata su Identity and Access Management (IAM), consulta Gestione dell'accesso utilizzando IAM.

Attendi il completamento del deployment. Questa operazione può richiedere circa 30 minuti. Se l'operazione riesce, la riga di comando visualizza l'URL del servizio.
Se vuoi eseguire il deployment di un aggiornamento del codice nel servizio, ripeti i passaggi precedenti. Ogni deployment in un servizio crea una nuova revisione e avvia automaticamente la gestione del traffico quando è pronto.

Per sapere come concedere agli utenti di Google Cloud l'accesso per richiamare questo servizio, consulta Gestire l'accesso utilizzando IAM. Gli editor e i proprietari del progetto dispongono automaticamente di questo accesso.

Generare un report

Per generare un report sui servizi Cloud Run:

Utilizza curl per inviare una richiesta autenticata:
```
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL
```
Sostituisci SERVICE_URL con l'URL fornito da Cloud Run dopo aver completato il deployment.

Se hai creato un nuovo progetto e hai seguito questo tutorial, l'output sarà simile al seguente:
```
Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-.-DATE.txt
```
. nel nome del file è l'argomento di ricerca predefinito, come indicato nel codice sorgente.

Per utilizzare la funzionalità di ricerca, aggiungi un argomento search alla richiesta:
```
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL?search=gcloud
```
Questa query restituirà un output simile al seguente:
```
Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-gcloud-DATE.txt
```
Recupera il file utilizzando lo strumento gsutil in locale:
```
gsutil cp gs://REPORT_FILE_NAME .
```
. nel comando indica la directory di lavoro corrente.

Sostituisci REPORT_FILE_NAME con l'output del nome dell'oggetto Cloud Storage nel passaggio precedente.

Apri il file per visualizzare il report. Dovrebbe avere il seguente aspetto:

Screenshot dell'elenco dei servizi Cloud Run nel progetto con colonne per quattro attributi di servizio. — Le quattro colonne vengono estratte dalla descrizione del servizio. Includono il **nome** del servizio, l'**URL** assegnato al primo deployment, l'**autore** iniziale del servizio e i **limiti** del servizio relativi alla CPU e alla memoria massime.

Migliorare la robustezza per il futuro

Se intendi sviluppare ulteriormente questo servizio, valuta la possibilità di riscrivere questo servizio in un linguaggio di programmazione più solido e utilizzando l'API Cloud Run Admin e la libreria client di Cloud Storage.

Puoi esaminare le chiamate API effettuate (e visualizzare alcuni dettagli di autenticazione) aggiungendo --log-http ai comandi gcloud e -D ai comandi gsutil.

Automatizza questa operazione

Ora che il report dei servizi Cloud Run può essere attivato da una richiesta HTTP, utilizza l'automazione per generare report quando ne hai bisogno:

Esegui questo servizio in base a una pianificazione con Cloud Scheduler
Crea il report come attività o pianificazione in coda in futuro con Google Tasks.

Esegui la pulizia

Se hai creato un nuovo progetto per questo tutorial, elimina il progetto. Se hai utilizzato un progetto esistente e vuoi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività in questo documento, quando lo elimini elimini anche qualsiasi altro lavoro svolto nel progetto.
Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Nella console Google Cloud, vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Eliminazione delle risorse del tutorial

Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial:
```
gcloud run services delete SERVICE-NAME
```
Dove SERVICE-NAME è il nome del servizio che hai scelto.

Puoi anche eliminare i servizi Cloud Run dalla console Google Cloud.
Rimuovi la configurazione della regione predefinita di gcloud aggiunta durante la configurazione del tutorial:
```
 gcloud config unset run/region
```
Rimuovi la configurazione del progetto:
```
 gcloud config unset project
```
Elimina le altre risorse Google Cloud create in questo tutorial:

Passaggi successivi

Riduci le dipendenze del servizio sostituendo gli strumenti gcloud e gsutil con chiamate API: Caricamento di oggetti, Riferimento API Cloud Run
Migliora ulteriormente la sicurezza utilizzando i controlli in entrata nella rete per limitare l'accesso al servizio.
Esplora le architetture di riferimento, i diagrammi e le best practice su Google Cloud. Visita il nostro Cloud Architecture Center.