Questo tutorial mostra come creare un servizio Cloud Run personalizzato che trasforma un parametro di input per la descrizione del grafico in un diagramma nel formato immagine PNG
. Utilizza Graphviz ed è installato come pacchetto di sistema nell'ambiente container del servizio.
Graphviz viene utilizzato tramite le utilità a riga di comando per gestire le richieste.
Obiettivi
- Scrivi e crea un container personalizzato con un Dockerfile
- Scrivi, crea ed esegui il deployment di un servizio Cloud Run
- Usa l'utilità Graphviz. per generare diagrammi
- Testa il servizio pubblicando un diagramma della sintassi DOT dalla raccolta o da una tua creazione
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.
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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
- Abilita l'API Cloud Run Admin
- Installa e inizializza gcloud CLI.
- Aggiorna i componenti:
gcloud components update
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
) -
Utente account di servizio (
roles/iam.serviceAccountUser
) -
Consumer Service Usage (
roles/serviceusage.serviceUsageConsumer
) -
Storage Admin (
roles/storage.admin
)
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Configurazione dei valori predefiniti 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 la regione Cloud Run supportata che preferisci.
Località 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 della regione.
Soddisfare i requisiti di latenza, disponibilità o durabilità sono fattori principali per la selezione della regione in cui vengono eseguiti i servizi Cloud Run.
In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi 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 regioni seguenti:
Soggetto ai prezzi di Livello 1
asia-east1
(Taiwan)asia-northeast1
(Tokyo)asia-northeast2
(Osaka)europe-north1
(Finlandia)A basse emissioni di CO2
europe-southwest1
(Madrid)europe-west1
(Belgio)A basse emissioni di CO2
europe-west4
(Paesi Bassi)europe-west8
(Milano)europe-west9
(Parigi)A basse emissioni di CO2
me-west1
(Tel Aviv)us-central1
(Iowa)A basse emissioni di CO2
us-east1
(Carolina del Sud)us-east4
(Virginia del Nord)us-east5
(Colombo)us-south1
(Dallas)us-west1
(Oregon)A basse emissioni di CO2
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 CO2
europe-west3
(Francoforte, Germania)A basse emissioni di CO2
europe-west6
(Zurigo, Svizzera)A basse emissioni di CO2
me-central1
(Doha)me-central2
(Dammam)northamerica-northeast1
(Montreal)A basse emissioni di CO2
northamerica-northeast2
(Toronto)A basse emissioni di CO2
southamerica-east1
(San Paolo, Brasile)A basse emissioni di CO2
southamerica-west1
(Santiago, Cile)A basse emissioni di CO2
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 all'interno della console Google Cloud.
Recupero dell'esempio di codice in corso
Per recuperare l'esempio di codice da utilizzare:
Clona il repository dell'app di esempio nella tua macchina locale:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-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:
Node.js
cd nodejs-docs-samples/run/system-package/
Python
cd python-docs-samples/run/system-package/
Go
cd golang-samples/run/system_package/
Java
cd java-docs-samples/run/system-package/
Visualizzazione dell'architettura
L'architettura di base è simile alla seguente:
![Diagramma che mostra il flusso di richieste dall'utente al servizio web all'utilità Graphviz.](https://cloud.google.com/static/run/docs/tutorials/images/diagram-as-a-service.png?authuser=7&hl=it)
L'utente invia una richiesta HTTP al servizio Cloud Run che esegue un'utilità Graphviz per trasformare la richiesta in un'immagine. L'immagine viene consegnata all'utente come risposta HTTP.
Nozioni di base sul codice
Definisci la configurazione del tuo ambiente con l'Dockerfile
Dockerfile
è specifico per la lingua e l'ambiente operativo di base, ad esempio Ubuntu, che verrà utilizzato dal servizio.
La guida rapida di creazione e deployment mostra vari Dockerfiles
che possono essere utilizzati come punto di partenza per creare una Dockerfile
per altri servizi.
Questo servizio richiede uno o più pacchetti di sistema aggiuntivi non disponibili per impostazione predefinita.
Apri
Dockerfile
in un editor.Cerca un estratto conto
Dockerfile
RUN
. Questa istruzione consente di eseguire comandi shell arbitrari per modificare l'ambiente. SeDockerfile
ha più fasi, identificate trovando più istruzioniFROM
, si troverà nell'ultima fase.I pacchetti specifici richiesti e il meccanismo per installarli variano in base al sistema operativo dichiarato all'interno del container.
Per ricevere istruzioni per il tuo sistema operativo o l'immagine di base, fai clic sulla scheda appropriata.
Debian/Ubuntu Alpine Alpine richiede un secondo pacchetto per il supporto dei caratteri.Per determinare il sistema operativo dell'immagine container, controlla il nome nell'istruzione
FROM
o in un file README associato all'immagine di base. Ad esempio, se estendinode
, puoi trovare la documentazione e l'elemento padreDockerfile
in Docker Hub.Testa la personalizzazione creando l'immagine utilizzando
docker build
in locale o Cloud Build.
Gestione delle richieste in entrata
Il servizio di esempio utilizza i parametri della richiesta HTTP in entrata per richiamare una chiamata di sistema che esegue il comando appropriato dell'utilità dot
.
Nel gestore HTTP in basso, un parametro di input per la descrizione del grafico viene estratto dalla variabile stringa di query dot
.
Le descrizioni dei grafici possono includere caratteri che devono essere codificati nell'URL per essere utilizzati in una stringa di query.
Node.js
Python
Go
Java
Dovrai distinguere tra errori interni del server e input dell'utente non validi. Questo servizio di esempio restituisce un errore interno del server per tutti gli errori della riga di comando dot, a meno che il messaggio di errore non contenga la stringa syntax
, che indica un problema relativo input utente dell'utente.
Generare un diagramma
La logica di base per la generazione dei diagrammi utilizza lo strumento a riga di comando dot per elaborare il parametro di input della descrizione del grafico in un diagramma nel formato dell'immagine PNG.
Node.js
Python
Go
Java
Progettazione di un servizio sicuro
Eventuali vulnerabilità nello strumento dot
sono potenziali vulnerabilità del
servizio web. Puoi mitigare questo problema utilizzando versioni aggiornate del pacchetto graphviz
mediante la creazione regolare dell'immagine container.
Se estendi l'esempio corrente in modo da accettare l'input utente come parametri della riga di comando, dovresti proteggerti dagli attacchi di comando iniezione. Ecco alcuni modi per prevenire gli attacchi di injection:
- Mappatura degli input a un dizionario di parametri supportati
- La convalida degli input corrisponde a un intervallo di valori di sicurezza nota, magari usando espressioni regolari
- Sequenza di escape degli input per garantire che la sintassi della shell non venga valutata
Puoi mitigare ulteriormente le potenziali vulnerabilità eseguendo il deployment del servizio con un account di servizio a cui non sono state concesse autorizzazioni per utilizzare i servizi Google Cloud, anziché utilizzare l'account predefinito, che con autorizzazioni di uso comune. Per questo motivo, i passaggi in questo tutorial creano e usano un nuovo account di servizio.
Spedizione del codice
Per distribuire il codice, crea con Cloud Build, carica in Container Registry ed esegui il deployment in Cloud Run:
Esegui questo comando per creare il container e pubblicarlo su Container Registry.
Node.js
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz
dove PROJECT_ID è l'ID progetto Google Cloud e
graphviz
è il nome che vuoi assegnare al servizio.Se l'operazione riesce, vedrai un messaggio SUCCESS contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e può essere riutilizzata, se necessario.
Python
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz
dove PROJECT_ID è l'ID progetto Google Cloud e
graphviz
è il nome che vuoi assegnare al servizio.Se l'operazione riesce, vedrai un messaggio SUCCESS contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e può essere riutilizzata, se necessario.
Go
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz
dove PROJECT_ID è l'ID progetto Google Cloud e
graphviz
è il nome che vuoi assegnare al servizio.Se l'operazione riesce, vedrai un messaggio SUCCESS contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e può essere riutilizzata, se necessario.
Java
Questo esempio utilizza Jib per creare immagini Docker utilizzando strumenti Java comuni. Jib ottimizza le build di container senza bisogno di un Dockerfile o senza dover installare Docker. Scopri di più sulla creazione di container Java con Jib.Utilizzando il Dockerfile, configura e crea un'immagine di base con i pacchetti di sistema installati per eseguire l'override dell'immagine di base predefinita di Jib:
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz-base
Dove PROJECT_ID è l'ID progetto Google Cloud.
Usa gcloud credentials helper per autorizzare Docker a eseguire il push in Container Registry.
gcloud auth configure-docker
Crea il tuo container finale con Jib e pubblicalo su Container Registry:
mvn compile jib:build \ -Dimage=gcr.io/PROJECT_ID/graphviz \ -Djib.from.image=gcr.io/PROJECT_ID/graphviz-base
Dove PROJECT_ID è l'ID progetto Google Cloud.
Esegui il deployment utilizzando:
gcloud
- Crea un nuovo account di servizio. Il tuo codice, inclusi eventuali pacchetti di sistema
utilizzati, può utilizzare solo i
servizi Google Cloud concessi a questo account di servizio.
gcloud iam service-accounts create SA_NAME
Dove SA_NAME è un nome assegnato a questo account di servizio. Se si verifica un errore o una vulnerabilità nel codice, il codice non sarà in grado di accedere a nessun'altra risorsa del progetto Google Cloud. - Esegui il deployment del codice specificando l'account di servizio.
gcloud run deploy graphviz-web --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com --image gcr.io/PROJECT_ID/graphviz
Dove PROJECT_ID è l'ID progetto Google Cloud, SA_NAME è il nome dell'account di servizio che hai creato, mentregraphviz
è il nome del container indicato sopra egraphviz-web
è il nome del servizio. RispondiY
alla richiesta "Consenti non autenticati". Per ulteriori dettagli sull'autenticazione basata su IAM, consulta Gestione dell'accesso. - Attendi il completamento del deployment. Questa operazione può richiedere circa mezzo minuto. Se l'operazione riesce, la riga di comando visualizza l'URL del servizio.
Terraform
Per scoprire come applicare o rimuovere una configurazione Terraform, vedi Comandi Terraform di base.
Il codice Terraform seguente crea un servizio Cloud Run.
Sostituisci
gcr.io/cloudrun/hello
con un riferimento al contenitore.Il seguente codice Terraform rende pubblico il tuo servizio Cloud Run.
- Crea un nuovo account di servizio. Il tuo codice, inclusi eventuali pacchetti di sistema
utilizzati, può utilizzare solo i
servizi Google Cloud concessi a questo account di 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 inizia automaticamente a gestire il traffico quando è pronto.
Fai una prova
Prova il tuo servizio inviando richieste POST
HTTP con descrizioni della sintassi DOT nel payload delle richieste.
Invia una richiesta HTTP al tuo servizio.
Copia l'URL nella barra degli URL del browser e aggiorna
[SERVICE_DOMAIN]
:https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }
Puoi incorporare il diagramma in una pagina web:
<img src="https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" />
Apri il file
diagram.png
risultante in qualsiasi applicazione che supporti i filePNG
, ad esempio Chrome.Dovrebbe avere il seguente aspetto:
Fonte: Descrizione DOT
Puoi esplorare una piccola raccolta di descrizioni dei diagrammi già pronte.
- Copia i contenuti del file
.dot
selezionato Invia una richiesta HTTP al tuo servizio.
Copia l'URL nella barra degli URL del browser.
https://SERVICE_DOMAIN/diagram.png?dot=SELECTED DOTFILE CONTENTS
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 è quello di eliminare il progetto che hai creato per il tutorial.
Per eliminare il progetto:
- Nella console Google Cloud, vai alla pagina 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 in corso...
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.
I servizi Cloud Run possono essere eliminati anche dalla console Google Cloud.
Rimuovi la configurazione predefinita della regione di gcloud che hai aggiunto durante la configurazione del tutorial:
gcloud config unset run/region
Rimuovi la configurazione del progetto:
gcloud config unset project
Elimina altre risorse Google Cloud create in questo tutorial:
Elimina l'immagine container denominata
gcr.io/<var>PROJECT_ID</var>/graphviz
da Container Registry.Elimina l'account di servizio
<var>SA_NAME</var>
.gcloud iam service-accounts delete SA_NAME@PROJECT_ID.iam.gserviceaccount.com
Passaggi successivi
- Sperimenta con l'app Graphviz:
- È stato aggiunto il supporto per altre utilità di Graphviz che applicano algoritmi diversi alla generazione dei diagrammi.
- Salva i diagrammi in Cloud Storage. Vuoi salvare l'immagine o la sintassi DOT?
- Implementa la protezione dall'abuso dei contenuti con l'API Cloud Natural Language.
- Guarda un altro esempio di pacchetto di sistema nel tutorial sull'elaborazione di immagini con Cloud Run.
- Esplora le architetture di riferimento, i diagrammi e le best practice su Google Cloud. Visita il nostro Cloud Architecture Center.