Tutorial sull'utilizzo dei pacchetti di sistema

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 che hai creato per questo tutorial.

2. Configura gcloud per la regione scelta:

   gcloud config set run/region REGION

   Sostituisci REGION con la regione Cloud Run supportata che preferisci.

Recupero dell'esempio di codice

Per recuperare l'esempio di codice da utilizzare:

1. Clona il repository dell'app di esempio sulla tua macchina locale:

   Node.js

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

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Python

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

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Vai

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

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

   Java

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

   In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

2. Passa alla directory che contiene il codice campione di Cloud Run:

   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 ha questo aspetto:

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 restituita all'utente come risposta HTTP.

Nozioni di base sul codice

Definizione della configurazione dell'ambiente con Dockerfile

Il tuo Dockerfile è specifico per la lingua e l'ambiente operativo di base, come Ubuntu, che verrà utilizzato dal tuo servizio.

La guida rapida Build and Deploy 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 il Dockerfile in un editor.

2. Cerca un estratto conto Dockerfile RUN. Questa istruzione consente di eseguire comandi shell arbitrari per modificare l'ambiente. Se il Dockerfile ha più fasi, identificate dalla presenza di più istruzioni FROM, verrà trovato nell'ultima fase.

   I pacchetti specifici richiesti e il meccanismo per installarli variano in base al sistema operativo dichiarato all'interno del container.

   Per visualizzare le istruzioni per il tuo sistema operativo o immagine di base, fai clic sulla scheda appropriata.

   Debian/Ubuntu

   RUN apt-get update -y && apt-get install -y \
     graphviz \
     && apt-get clean

   Alpine

   Alpine richiede un secondo pacchetto per il supporto dei caratteri.

   RUN apk --no-cache add graphviz

   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 esegui l'estensione da node, puoi trovare la documentazione e il parent Dockerfile su Docker Hub.

3. Testa la personalizzazione creando l'immagine utilizzando docker build localmente o Cloud Build.

Gestione delle richieste in arrivo

Il servizio di esempio utilizza i parametri della richiesta HTTP in entrata per richiamare una chiamata di sistema che esegue il comando dell'utilità dot appropriato.

Nel gestore HTTP riportato di seguito, un parametro di input della descrizione del grafico viene estratto dalla variabile della stringa di query dot.

Le descrizioni dei grafici possono includere caratteri che devono essere codificati come URL per essere utilizzati in una stringa di query.

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');
    }
  }
});

@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

// 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)
		}
	}
}

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 input utente non validi. Questo servizio di esempio restituisce un errore interno del server per tutti gli errori della riga di comando a meno che il messaggio di errore non contenga la stringa syntax, che indica un problema di input utente'utente.

Generare un diagramma

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

// 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;
};

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

// 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
}

// 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;
}

Progettare un servizio sicuro

Eventuali vulnerabilità dello strumento dot sono potenziali vulnerabilità del servizio web. Puoi risolvere questo problema utilizzando versioni aggiornate del pacchetto graphviz ricreando regolarmente l'immagine container.

Se estendi l'esempio attuale per accettare l'input utente'utente come parametri della riga di comando, devi proteggerti dagli attacchi di command injection. Alcuni modi per prevenire gli attacchi di iniezione includono:

• Mappatura degli input a un dizionario di parametri supportati
• Convalida che gli input corrispondano a un intervallo di valori noti e sicuri, magari utilizzando espressioni regolari
• Escape degli input per garantire che la sintassi della shell non venga valutata

Puoi ridurre ulteriormente le potenziali vulnerabilità eseguendo il deployment del servizio con unaccount di serviziot a cui non sono state concesse autorizzazioni per utilizzare i servizi Google Cloud, anziché utilizzare l'account predefinito, che dispone di autorizzazioni di uso comune. Per questo motivo, i passaggi di questo tutorial creano e utilizzano un nuovoaccount di serviziot.

Invio del codice in corso…

Per spedire il codice, esegui la build con Cloud Build, caricalo in Artifact Registry ed esegui il deployment in 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 il repository Artifact Registry.

2. Esegui il comando seguente 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 è il nome che vuoi dare al servizio.

   In caso di esito positivo, vedrai un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se lo desideri, può essere riutilizzata.

   Python

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

   dove PROJECT_ID è l'ID progetto Google Cloud e graphviz è il nome che vuoi dare al servizio.

   In caso di esito positivo, vedrai un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se lo desideri, può essere riutilizzata.

   Vai

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

   dove PROJECT_ID è l'ID progetto Google Cloud e graphviz è il nome che vuoi dare al servizio.

   In caso di esito positivo, vedrai un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se lo desideri, può essere riutilizzata.

   Java

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

   1. Utilizzando 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:

      # 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.15_6-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 l'assistente per le credenziali gcloud per autorizzare Docker a eseguire il push su 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 quanto segue:

   gcloud

   1. Crea un nuovo account di servizio. Il tuo codice, inclusi i pacchetti di sistema che utilizza, può utilizzare solo i servizi Google Cloud che sono stati concessi a questo account di servizio.

      gcloud iam service-accounts create SA_NAME

      dove SA_NAME è un nome che assegni a questo account di servizio. Se nel codice è presente un errore o una vulnerabilità, il codice non potrà accedere a nessuna delle altre risorse del progetto Google Cloud .
   2. Esegui il deployment del codice, specificando il 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 del account di servizio che hai creato, graphviz è il nome del container di cui sopra e graphviz-web è il nome del servizio. Rispondi Y alla richiesta "consenti non autenticato". Per ulteriori dettagli sull'autenticazione basata su IAM, consulta la pagina Gestione dell'accesso.
   3. Attendi il completamento del deployment. Questa operazione può richiedere circa 30 secondi. 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 seguente codice Terraform 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"
   
     deletion_protection = false # set to "true" in production
   
     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, 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 ha la forma LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

   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 i passaggi precedenti. Ogni deployment in un servizio crea una nuova revisione e inizia automaticamente a pubblicare il traffico quando è pronto.

Fai una prova

Prova il tuo servizio inviando richieste HTTP POST con descrizioni della 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 i file PNG, ad esempio Chrome.

   Dovrebbe avere il seguente aspetto:

   

Puoi esplorare una piccola raccolta di descrizioni di 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