Utilizzo dei pacchetti di sistema

---

Questo tutorial mostra come creare un servizio Cloud Run for Anthos personalizzato che trasforma un parametro di input della descrizione dei grafici in un diagramma nel formato dell'immagine PNG. Utilizza Graphviz installato come pacchetto di sistema nell'ambiente del container del servizio. Graphviz viene utilizzato tramite le utilità della 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 for Anthos
• Utilizza l'utilità Graphviz dot per generare diagrammi
• Testa il servizio pubblicando un diagramma di sintassi DOT della raccolta o di una tua creazione

Costi

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

• Cloud Build
• Container Registry
• Cloud Run for Anthos

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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

3. Abilita l'API Cloud Run for Anthos
4. Installa e inizializza l'interfaccia alla gcloud CLI.
5. Installa il componente kubectl:

   gcloud components install kubectl

6. Aggiorna i componenti:

   gcloud components update

7. Installa curl per provare il servizio
8. Crea un nuovo cluster utilizzando le istruzioni in Configurazione di Cloud Run for Anthos.

Configurazione dei valori predefiniti gcloud

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

1. Imposta il progetto predefinito:

   gcloud config set project PROJECT_ID

   Sostituisci PROJECT_ID con il nome del progetto che utilizzi per questo tutorial.

2. Configura gcloud per il tuo cluster:

   gcloud config set run/platform gke
   gcloud config set run/cluster CLUSTER-NAME
   gcloud config set run/cluster_location REGION

   Sostituisci:

   • CLUSTER-NAME con il nome utilizzato per il cluster,
   • REGION con la località del cluster supportata di tua scelta.

Recupero dell'esempio di codice

Per recuperare l'esempio di codice da utilizzare:

1. Clona il repository dell'app di esempio nella 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.

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

   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 ha il seguente aspetto:

Per l'origine del diagramma, consulta la descrizione del DOT

L'utente effettua una richiesta HTTP al servizio Cloud Run for Anthos che esegue un'utilità Graphviz per trasformare la richiesta in un'immagine. L'immagine viene inviata all'utente come risposta HTTP.

Nozioni di base sul codice

Definizione della configurazione dell'ambiente con Dockerfile

Punto chiave: utilizza il tuo Dockerfile per personalizzare il tuo ambiente con librerie, utilità, variabili di ambiente, file di configurazione e processi di avvio. Questo è l'approccio basato su container per la "configurazione del server".

Il linguaggio Dockerfile è specifico per il linguaggio e l'ambiente operativo di base, ad esempio Ubuntu, che il servizio utilizzerà.

Nota: la guida rapida, anche se è per Cloud Run for Anthos, mostra vari Dockerfiles che puoi utilizzare come punto di partenza per creare 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 una dichiarazione Dockerfile RUN. Questa istruzione consente di eseguire comandi shell arbitrari per modificare l'ambiente. Se il Dockerfile ha più fasi, individuate individuando più istruzioni FROM, si troverà nell'ultima fase.

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

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

   Debian/Ubuntu

   run/system_package/Dockerfile

   Visualizza su GitHub Feedback

   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/system-package/Dockerfile

   Visualizza su GitHub Feedback

   RUN apk --no-cache add graphviz ttf-ubuntu-font-family

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

3. Verifica la tua 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 di utilità dot appropriato.

Nel gestore HTTP di seguito, 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 in URL per essere utilizzati in una stringa di query.

Node.js

run/system-package/app.js

Visualizza su GitHub Feedback

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

run/system-package/main.py

Visualizza su GitHub Feedback

@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

Go

run/system_package/graphviz.go

Visualizza su GitHub Feedback

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

run/system-package/src/main/java/com/example/cloudrun/App.java

Visualizza su GitHub Feedback

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 a riga di comando del punto, a meno che il messaggio di errore non contenga la stringa syntax, che indica un problema di input utente'utente.

Generazione di un diagramma

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

Node.js

run/system-package/app.js

Visualizza su GitHub Feedback

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

run/system-package/main.py

Visualizza su GitHub Feedback

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

Go

run/system_package/graphviz.go

Visualizza su GitHub Feedback

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

run/system-package/src/main/java/com/example/cloudrun/App.java

Visualizza su GitHub Feedback

// 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à 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 per accettare l'input utente come parametri della riga di comando, dovresti proteggerti dagli attacchi con comando di iniezione. Ecco alcuni modi per prevenire gli attacchi di iniezione:

• Mappatura degli input a un dizionario di parametri supportati
• La convalida degli input corrisponde a una serie di valori noti e sicuri, forse utilizzando espressioni regolari
• Eseguire l'escape degli input per garantire che la sintassi della shell non venga valutata

Spedizione del codice

Per inviare il tuo codice, devi creare con Cloud Build, caricare il file in Container Registry ed eseguire il deployment in Cloud Run for Anthos:

1. 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 GCP e graphviz è il nome che vuoi assegnare al servizio.

   Se l'operazione va a buon fine, verrà visualizzato un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e, se necessario, può essere riutilizzata.

   Python

   gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz

   Dove PROJECT_ID è l'ID progetto GCP e graphviz è il nome che vuoi assegnare al servizio.

   Se l'operazione va a buon fine, verrà visualizzato un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e, se necessario, può essere riutilizzata.

   Go

   gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz

   Dove PROJECT_ID è l'ID progetto GCP e graphviz è il nome che vuoi assegnare al servizio.

   Se l'operazione va a buon fine, verrà visualizzato un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e, se necessario, può essere riutilizzata.

   Java

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

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

      run/system-package/Dockerfile

      Visualizza su GitHub Feedback
      # 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.8_7-jre
      
      RUN apt-get update -y && apt-get install -y \
        graphviz \
        && apt-get clean

      gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz-base

      Dove PROJECT_ID è il tuo ID progetto GCP.

   2. Crea il tuo container finale con Jib e pubblicalo su Container Registry:

      run/system-package/pom.xml

      Visualizza su GitHub Feedback
      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.3.2</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=gcr.io/PROJECT_ID/graphviz \
       -Djib.from.image=gcr.io/PROJECT_ID/graphviz-base

      Dove PROJECT_ID è il tuo ID progetto GCP.

2. Esegui il deployment utilizzando il comando seguente:

   gcloud run deploy graphviz-web --create-if-missing --image gcr.io/PROJECT_ID/graphviz

   Dove PROJECT_ID è l'ID progetto GCP, graphviz è il nome del container dall'alto e graphviz-web è il nome del servizio.

   Attendi il completamento del deployment: questa operazione può richiedere circa mezzo minuto.

3. Se vuoi eseguire il deployment di un aggiornamento del codice al servizio, ripeti i passaggi precedenti. Ogni deployment in un servizio crea una nuova revisione e avvia automaticamente la gestione del traffico quando è pronto.

Fai una prova

Prova il tuo servizio inviando le richieste HTTP POST con descrizioni della sintassi DOT nel payload delle richieste.

1. Invia una richiesta HTTP al servizio.

   Puoi incorporare il diagramma in una pagina web:

   1. Per ottenere l'IP esterno per il gateway in entrata Istio:

      kubectl get svc istio-ingress -n gke-system

      in cui l'output risultante ha il seguente aspetto:

      NAME            TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
      istio-ingress   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

      Il EXTERNAL-IP per il bilanciatore del carico è l'indirizzo IP che devi utilizzare.

   2. Esegui un comando curl utilizzando questo indirizzo EXTERNAL-IP nell'URL. Non includere il protocollo (ad esempio: http://) in SERVICE_DOMAIN.

      curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \
         --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \
         > diagram.png

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

   Dovrebbe avere il seguente aspetto:

   

   Fonte: Descrizione del DOT

Puoi esplorare una piccola raccolta di descrizioni dei diagrammi pronte.

1. Copia i contenuti del file .dot selezionato

2. Incollalo nel comando curl:

   curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \
   --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \
   > diagram.png

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 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à descritte in questo documento, quando lo elimini elimini anche tutto il 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 appspot.com URL, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

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

1. Elimina il servizio Cloud Run for Anthos 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 for Anthos dalla console Google Cloud:

   Vai a Cloud Run for Anthos

2. Rimuovi le configurazioni gcloud predefinite che hai aggiunto durante la configurazione del tutorial:

    gcloud config unset run/platform
    gcloud config unset run/cluster
    gcloud config unset run/cluster_location
   

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 gcr.io/<var>PROJECT_ID</var>/graphviz da Container Registry.
   • Se hai creato un cluster per questo tutorial, elimina il cluster

Passaggi successivi

• Sperimenta con la tua app Graphviz:
  • Aggiungi il supporto per altre utilità chartviz che applicano diversi algoritmi alla generazione del diagramma.
  • Salva i diagrammi in Cloud Storage. Vuoi salvare l'immagine o la sintassi DOT?
  • Implementa la protezione contro gli abusi di contenuti con l'API Cloud Natural Language.
  • Vedi un altro esempio di pacchetto di sistema nella sezione Elaborazione delle immagini.
• Esplora architetture di riferimento, diagrammi e best practice su Google Cloud. Dai un'occhiata al nostro Centro di architettura cloud.