Tutorial sull'utilizzo dei pacchetti di sistema

Questo tutorial mostra come creare un servizio Cloud Run personalizzato che trasforma un parametro di input per la descrizione del grafico in un diagramma nell'elemento PNG formato dell'immagine. che utilizza Graphviz e viene 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

  • Scrivere e creare un container personalizzato con un Dockerfile
  • Scrivi, crea ed esegui il deployment di un servizio Cloud Run
  • Usa il punto Graphviz per generare diagrammi
  • Testa il servizio pubblicando un diagramma della sintassi DOT dalla raccolta o da una tua creazione

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Make sure 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.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Abilita l'API Cloud Run Admin
  7. Installa e inizializza con gcloud CLI.
  8. 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:

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

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

Configurazione dei valori predefiniti di gcloud

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

  1. Imposta il progetto predefinito:

    gcloud config set project PROJECT_ID

    Sostituisci PROJECT_ID con il nome del progetto per cui hai creato questo tutorial.

  2. Configura gcloud per la regione scelta:

    gcloud config set run/region REGION

    Sostituisci REGION con il Cloud Run supportato regione a tua scelta.

Località Cloud Run

Cloud Run è regionale, il che significa che l'infrastruttura dei tuoi servizi Cloud Run si trova in una regione specifica gestiti da Google in modo che siano disponibili in modo ridondante tutte le zone all'interno di quella regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità è fondamentale i fattori necessari per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. Generalmente puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la località dell'altro account Google Cloud prodotti utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire nonché la latenza del tuo servizio.

Cloud Run è disponibile nelle regioni seguenti:

Soggetto ai prezzi di Livello 1

Soggetto ai prezzi di Livello 2

Se hai già creato un servizio Cloud Run, puoi visualizzare nella dashboard di Cloud Run all'interno Console Google Cloud.

Recupero dell'esempio di codice in corso

Per recuperare l'esempio di codice da utilizzare:

  1. 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 scarica l'esempio . come file ZIP ed estrarlo.

    Python 

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    In alternativa, puoi scarica l'esempio . come file ZIP ed estrarlo.

    Vai 

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    In alternativa, puoi scarica l'esempio . come file ZIP ed estrarlo.

    Java 

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    In alternativa, puoi scarica l'esempio . come file ZIP ed estrarlo.

  2. Passa alla directory che contiene l'esempio di Cloud Run codice:

    Node.js 

    cd nodejs-docs-samples/run/system-package/

    Python 

    cd python-docs-samples/run/system-package/

    Vai 

    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 al grafico utilità.
. Per l'origine del diagramma, consulta Descrizione DOT

L'utente invia una richiesta HTTP al servizio Cloud Run che esegue un'utilità Graphviz per trasformare la richiesta in un'immagine. L'immagine è inviati 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. come Ubuntu, che il tuo servizio utilizzerà.

La guida rapida alla creazione e al deployment mostra vari Dockerfiles che possono essere utilizzati come punto di partenza per creare un Dockerfile per altri servizi.

Questo servizio richiede uno o più pacchetti di sistema aggiuntivi non disponibili per impostazione predefinita.

  1. Apri Dockerfile in un editor.

  2. Cerca un Dockerfile RUN l'Informativa. Questa istruzione consente di eseguire comandi shell arbitrari per modificare dell'ambiente. Se Dockerfile prevede più fasi, identificate da più istruzioni FROM, lo troverai nell'ultima fase.

    I pacchetti specifici richiesti e il meccanismo per installarli variano a seconda il sistema operativo dichiarato all'interno del container.

    Per ricevere istruzioni relative al tuo sistema operativo o all'immagine di base, fai clic sull'icona scheda appropriata.

    Debian/Ubuntu
    RUN apt-get update -y && apt-get install -y \
  graphviz \
  && apt-get clean
    di Gemini Advanced.
    Alpine
    di Gemini Advanced. Alps richiede un secondo pacchetto per il supporto dei caratteri. 
    RUN apk --no-cache add graphviz ttf-ubuntu-font-family

    Per determinare il sistema operativo dell'immagine container, controlla il nome in l'istruzione FROM o un file README associato all'immagine di base. Ad esempio: Se estendi da node, puoi trovare la documentazione e l'istanza principale Dockerfile su Docker Hub.

  3. 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 un che esegue il comando di utilità dot appropriato.

Nel gestore HTTP di seguito, viene estratto un parametro di input per la descrizione del grafico la variabile stringa di query dot.

Le descrizioni dei grafici possono includere caratteri che devono essere Codificato come URL per l'utilizzo in una stringa di query.

Node.js 

app.get('/diagram.png', (req, res) => {
  try {
    const image = createDiagram(req.query.dot);
    res.setHeader('Content-Type', 'image/png');
    res.setHeader('Content-Length', image.length);
    res.setHeader('Cache-Control', 'public, max-age=86400');
    res.send(image);
  } catch (err) {
    console.error(`error: ${err.message}`);
    const errDetails = (err.stderr || err.message).toString();
    if (errDetails.includes('syntax')) {
      res.status(400).send(`Bad Request: ${err.message}`);
    } else {
      res.status(500).send('Internal Server Error');
    }
  }
});

Python 

@app.route("/diagram.png", methods=["GET"])
def index():
    """Takes an HTTP GET request with query param dot and
    returns a png with the rendered DOT diagram in a HTTP response.
    """
    try:
        image = create_diagram(request.args.get("dot"))
        response = make_response(image)
        response.headers.set("Content-Type", "image/png")
        return response

    except Exception as e:
        print(f"error: {e}")

        # If no graphviz definition or bad graphviz def, return 400
        if "syntax" in str(e):
            return f"Bad Request: {e}", 400

        return "Internal Server Error", 500

Vai 


// diagramHandler renders a diagram using HTTP request parameters and the dot command.
func diagramHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		log.Printf("method not allowed: %s", r.Method)
		http.Error(w, fmt.Sprintf("HTTP Method %s Not Allowed", r.Method), http.StatusMethodNotAllowed)
		return
	}

	q := r.URL.Query()
	dot := q.Get("dot")
	if dot == "" {
		log.Print("no graphviz definition provided")
		http.Error(w, "Bad Request", http.StatusBadRequest)
		return
	}

	// Cache header must be set before writing a response.
	w.Header().Set("Cache-Control", "public, max-age=86400")

	input := strings.NewReader(dot)
	if err := createDiagram(w, input); err != nil {
		log.Printf("createDiagram: %v", err)
		// Do not cache error responses.
		w.Header().Del("Cache-Control")
		if strings.Contains(err.Error(), "syntax") {
			http.Error(w, "Bad Request: DOT syntax error", http.StatusBadRequest)
		} else {
			http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		}
	}
}

Java 

get(
    "/diagram.png",
    (req, res) -> {
      InputStream image = null;
      try {
        String dot = req.queryParams("dot");
        image = createDiagram(dot);
        res.header("Content-Type", "image/png");
        res.header("Content-Length", Integer.toString(image.available()));
        res.header("Cache-Control", "public, max-age=86400");
      } catch (Exception e) {
        if (e.getMessage().contains("syntax")) {
          res.status(400);
          return String.format("Bad Request: %s", e.getMessage());
        } else {
          res.status(500);
          return "Internal Server Error";
        }
      }
      return image;
    });

Dovrai distinguere tra errori interni del server e utenti non validi di testo. Questo servizio di esempio restituisce un errore interno del server per tutti i punti errori della riga di comando, a meno che il messaggio di errore non contenga la stringa syntax, che indica un problema di input utente.

Generare un diagramma

La logica di base della generazione di diagrammi utilizza lo strumento a riga di comando. il parametro di input della descrizione del grafico in un diagramma nel formato di immagine PNG.

Node.js 

// Generate a diagram based on a graphviz DOT diagram description.
const createDiagram = dot => {
  if (!dot) {
    throw new Error('syntax: no graphviz definition provided');
  }

  // Adds a watermark to the dot graphic.
  const dotFlags = [
    '-Glabel="Made on Cloud Run"',
    '-Gfontsize=10',
    '-Glabeljust=right',
    '-Glabelloc=bottom',
    '-Gfontcolor=gray',
  ].join(' ');

  const image = execSync(`/usr/bin/dot ${dotFlags} -Tpng`, {
    input: dot,
  });
  return image;
};

Python 

def create_diagram(dot):
    """Generates a diagram based on a graphviz DOT diagram description.

    Args:
        dot: diagram description in graphviz DOT syntax

    Returns:
        A diagram in the PNG image format.
    """
    if not dot:
        raise Exception("syntax: no graphviz definition provided")

    dot_args = [  # These args add a watermark to the dot graphic.
        "-Glabel=Made on Cloud Run",
        "-Gfontsize=10",
        "-Glabeljust=right",
        "-Glabelloc=bottom",
        "-Gfontcolor=gray",
        "-Tpng",
    ]

    # Uses local `dot` binary from Graphviz:
    # https://graphviz.gitlab.io
    image = subprocess.run(
        ["dot"] + dot_args, input=dot.encode("utf-8"), stdout=subprocess.PIPE
    ).stdout

    if not image:
        raise Exception("syntax: bad graphviz definition provided")
    return image

Vai 


// createDiagram generates a diagram image from the provided io.Reader written to the io.Writer.
func createDiagram(w io.Writer, r io.Reader) error {
	stderr := new(bytes.Buffer)
	args := []string{
		"-Glabel=Made on Cloud Run",
		"-Gfontsize=10",
		"-Glabeljust=right",
		"-Glabelloc=bottom",
		"-Gfontcolor=gray",
		"-Tpng",
	}
	cmd := exec.Command("/usr/bin/dot", args...)
	cmd.Stdin = r
	cmd.Stdout = w
	cmd.Stderr = stderr

	if err := cmd.Run(); err != nil {
		return fmt.Errorf("exec(%s) failed (%w): %s", cmd.Path, err, stderr.String())
	}

	return nil
}

Java 

// Generate a diagram based on a graphviz DOT diagram description.
public static InputStream createDiagram(String dot) {
  if (dot == null || dot.isEmpty()) {
    throw new NullPointerException("syntax: no graphviz definition provided");
  }
  // Adds a watermark to the dot graphic.
  List<String> args = new ArrayList<>();
  args.add("/usr/bin/dot");
  args.add("-Glabel=\"Made on Cloud Run\"");
  args.add("-Gfontsize=10");
  args.add("-Glabeljust=right");
  args.add("-Glabelloc=bottom");
  args.add("-Gfontcolor=gray");
  args.add("-Tpng");

  StringBuilder output = new StringBuilder();
  InputStream stdout = null;
  try {
    ProcessBuilder pb = new ProcessBuilder(args);
    Process process = pb.start();
    OutputStream stdin = process.getOutputStream();
    stdout = process.getInputStream();
    // The Graphviz dot program reads from stdin.
    Writer writer = new OutputStreamWriter(stdin, "UTF-8");
    writer.write(dot);
    writer.close();
    process.waitFor();
  } catch (Exception e) {
    System.out.println(e);
  }
  return stdout;
}

Progettazione di un servizio sicuro

Eventuali vulnerabilità nello strumento dot sono potenziali vulnerabilità di servizio web. Puoi mitigare questo problema utilizzando versioni aggiornate del graphviz creando regolarmente l'immagine container.

Se estendi l'esempio corrente in modo da accettare l'input utente come riga di comando occorre proteggere attacchi di tipo command-injection. Alcuni di i modi per prevenire gli attacchi di iniezione includono:

  • Mappatura degli input a un dizionario di parametri supportati
  • Gli input di convalida corrispondono a un intervallo di valori di sicurezza nota, magari utilizzando regolari espressioni
  • 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 le autorizzazioni per utilizzare Google Cloud piuttosto che usare l'account predefinito, che di solito ha usato autorizzazioni aggiuntive. Per questo motivo, i passaggi in questo tutorial creare e utilizzare un nuovo account di servizio.

Spedizione del codice

Per distribuire il codice, devi utilizzare Cloud Build e caricarlo sul Artifact Registry ed eseguire il deployment su Cloud Run:

  1. Crea un Artifact Registry:

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

    Sostituisci:

    • REPOSITORY con un nome univoco per il repository. Per ogni posizione del repository in un progetto, i nomi dei repository devono essere univoci.
    • REGION con la regione Google Cloud da utilizzare per nel repository Artifact Registry.

  2. Esegui questo comando per creare il container e pubblicarlo su Artifact Registry.

    Node.js 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

    Dove PROJECT_ID è l'ID progetto Google Cloud e graphviz è l'ID che vuoi assegnare al servizio.

    Se l'operazione riesce, verrà visualizzato il messaggio SUCCESS contenente l'ID, la creazione ora e nome dell'immagine. L'immagine è archiviata in Artifact Registry e può essere se lo desideri,

    Python 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

    Dove PROJECT_ID è l'ID progetto Google Cloud e graphviz è l'ID che vuoi assegnare al servizio.

    Se l'operazione riesce, verrà visualizzato il messaggio SUCCESS contenente l'ID, la creazione ora e nome dell'immagine. L'immagine è archiviata in Artifact Registry e può essere riutilizzate, se necessario.

    Vai 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

    Dove PROJECT_ID è l'ID progetto Google Cloud e graphviz è l'ID che vuoi assegnare al servizio.

    Se l'operazione riesce, verrà visualizzato il messaggio SUCCESS contenente l'ID, la creazione ora e nome dell'immagine. L'immagine è archiviata in Artifact Registry e può essere riutilizzate, se necessario.

    Java

    Questo esempio utilizza Jib per creare utilizzando strumenti Java comuni. Jib ottimizza le build di container senza la necessità di un Dockerfile o di avere Docker installato. Scopri di più sulla creazione di container Java con Jib.

    1. Utilizzando il Dockerfile, configura e crea un'immagine di base con il sistema pacchetti installati per sostituire l'immagine di base predefinita di Jib:

      # Use the Official eclipse-temurin image for a lean production stage of our multi-stage build.
# https://hub.docker.com/_/eclipse-temurin/
FROM eclipse-temurin:17.0.12_7-jre

RUN apt-get update -y && apt-get install -y \
  graphviz \
  && apt-get clean
       
      gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base

      Dove PROJECT_ID è l'ID progetto Google Cloud.

    2. Utilizza gcloud credentials helper per autorizzare Docker a eseguire il push in Artifact Registry. 

      gcloud auth configure-docker

    3. Crea il container finale con Jib e pubblicalo su Artifact Registry:

      <plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  <version>3.4.0</version>
  <configuration>
    <from>
      <image>gcr.io/PROJECT_ID/graphviz-base</image>
    </from>
    <to>
      <image>gcr.io/PROJECT_ID/graphviz</image>
    </to>
  </configuration>
</plugin>
       
      mvn compile jib:build \
 -Dimage=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz \
 -Djib.from.image=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base

      Dove PROJECT_ID è l'ID progetto Google Cloud.

  3. Esegui il deployment utilizzando:

    gcloud

    1. Crea un nuovo account di servizio. Il tuo codice, inclusi eventuali pacchetti di sistema può usare solo quelle 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 c'è a causa di un errore o una vulnerabilità nel codice, il codice non sarà in grado di accedere ad alcuna delle altre risorse del progetto Google Cloud.
    2. 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 REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
       Dove PROJECT_ID è l'ID progetto Google Cloud, SA_NAME è il nome dell'account di servizio che hai creato, mentre graphviz è del container sopra, mentre graphviz-web è il nome del completamente gestito di Google Cloud. Rispondi Y alla richiesta di autorizzazione per gli utenti non autenticati. . Per ulteriori informazioni, consulta Gestire l'accesso i dettagli sull'autenticazione basata su IAM.
    3. 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, consulta: Comandi Terraform di base.

    Il codice Terraform seguente crea un servizio Cloud Run.

    resource "google_service_account" "graphviz" {
  account_id   = "graphviz"
  display_name = "GraphViz Tutorial Service Account"
}

resource "google_cloud_run_v2_service" "default" {
  name     = "graphviz-example"
  location = "us-central1"

  template {
    containers {
      # Replace with the URL of your graphviz image
      #   gcr.io/<YOUR_GCP_PROJECT_ID>/graphviz
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }

    service_account = google_service_account.graphviz.email
  }
}

    Sostituisci IMAGE_URL con un riferimento all'immagine container, per ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già creati. L'URL ha la forma LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG di Google.

    Il seguente codice Terraform rende pubblico il tuo servizio Cloud Run.

    # Make Cloud Run service publicly accessible
resource "google_cloud_run_service_iam_member" "allow_unauthenticated" {
  service  = google_cloud_run_v2_service.default.name
  location = google_cloud_run_v2_service.default.location
  role     = "roles/run.invoker"
  member   = "allUsers"
}

  4. Se vuoi eseguire il deployment di un aggiornamento del codice nel servizio, ripeti la precedente passaggi. Ogni deployment in un servizio crea una nuova revisione e, e inizia a gestire il traffico quando è pronto.

Fai una prova

Prova il tuo servizio inviando richieste POST HTTP con sintassi DOT nel payload della richiesta.

  1. 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 }" />

  2. Apri il file diagram.png risultante in qualsiasi applicazione che supporti PNG file, come Chrome.

    Dovrebbe avere il seguente aspetto:

    Diagramma che mostra il flusso della fase di codice da creare per il deployment su &quot;Esegui&quot;.
    . Fonte: Descrizione DOT

Puoi esplorare una piccola raccolta di descrizioni dei diagrammi già pronte.

  1. Copia i contenuti del file .dot selezionato

  2. 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 mantenerlo senza l'aggiunta delle modifiche In questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione creato per il tutorial.

Per eliminare il progetto:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Eliminazione delle risorse del tutorial in corso...

  1. 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 Console Google Cloud.

  2. Rimuovi la configurazione predefinita della regione gcloud che hai aggiunto durante il tutorial configurazione:

     gcloud config unset run/region

  3. Rimuovi la configurazione del progetto:

     gcloud config unset project

  4. Elimina altre risorse Google Cloud create in questo tutorial:

    • Elimina l'immagine container denominata REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz da Artifact Registry.

    • Elimina l'account di servizio SA_NAME.

      gcloud iam service-accounts delete SA_NAME@PROJECT_ID.iam.gserviceaccount.com

Passaggi successivi