Utiliser des packages système

Ce tutoriel explique comment créer un service Cloud Run for Anthos personnalisé qui transforme un paramètre d'entrée de description de graphe en un schéma au format d'image PNG. Il utilise l'outil de visualisation Graphviz, qui est installé en tant que package système dans l'environnement de conteneur du service. Graphviz est accessible via les utilitaires de ligne de commande pour le traitement des requêtes.

Objectifs

  • Écrire et créer un conteneur personnalisé avec un Dockerfile
  • Écrire, créer et déployer un service Cloud Run for Anthos
  • Utiliser l'utilitaire Graphviz dot pour générer des schémas.
  • Tester le service en publiant un schéma dans la syntaxe DOT à partir de la collection ou de votre création.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

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

    Go to project selector

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

  3. Activez l'API Cloud Run for Anthos
  4. Installez et initialisez la gcloud CLI.
  5. Installez le composant kubectl : 
    gcloud components install kubectl
  6. Mettez à jour les composants : 
    gcloud components update
  7. Installez curl pour tester le service
  8. Créez un cluster en suivant les instructions de la section Configurer Cloud Run for Anthos.

Configurer les paramètres par défaut de gcloud

Pour configurer gcloud avec les valeurs par défaut pour votre service Cloud Run pour Anthos, procédez comme suit :

  1. Définissez le projet par défaut :

    gcloud config set project PROJECT_ID

    Remplacez PROJECT_ID par le nom du projet que vous utilisez pour ce tutoriel.

  2. Configurez gcloud pour votre cluster :

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

    Remplacez :

    • CLUSTER-NAME par le nom que vous avez utilisé pour votre cluster ;
    • REGION par l'emplacement de cluster compatible de votre choix.

Récupérer l'exemple de code

Pour récupérer l’exemple de code à utiliser, procédez comme suit :

  1. Clonez le dépôt de l'exemple d'application sur votre machine locale :

    Node.js 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Python 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Go 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Java 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

  2. Accédez au répertoire contenant l'exemple de code 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/

Visualiser l'architecture

L'architecture de base est semblable à ceci :

Schéma montrant le parcours du flux de requêtes d'un utilisateur vers le service Web et l'utilitaire graphviz dot.
Pour accéder à la source du diagramme, consultez la description du DOT

L'utilisateur adresse une requête HTTP au service Cloud Run for Anthos, lequel exécute un utilitaire Graphviz pour transformer la requête en image. Cette image est transmise à l'utilisateur sous forme de réponse HTTP.

Comprendre le code

Définir la configuration de votre environnement avec le fichier Dockerfile

Le fichier Dockerfile est spécifique au langage et à l'environnement d'exploitation de base que votre service utilisera, par exemple Ubuntu.

Ce service nécessite un ou plusieurs packages système supplémentaires qui ne sont pas disponibles par défaut.

  1. Ouvrez le fichier Dockerfile dans un éditeur.

  2. Recherchez une instruction Dockerfile RUN. Cette instruction permet d'exécuter des commandes de shell arbitraires pour modifier l'environnement. Si le fichier Dockerfile comporte plusieurs étapes, identifiées par plusieurs instructions FROM, vous le trouverez à la dernière étape.

    Les packages spécifiques requis et le mécanisme pour les installer varient en fonction du système d'exploitation déclaré dans le conteneur.

    Pour obtenir les instructions relatives à votre système d'exploitation ou à votre image de base, cliquez sur l'onglet correspondant.

    Pour déterminer le système d'exploitation de votre image de conteneur, vérifiez le nom dans l'instruction FROM ou dans un fichier README associé à votre image de base. Par exemple, en cas d'extension depuis node, vous trouverez la documentation et le fichier Dockerfile parent sur Docker Hub.

  3. Créez l'image pour tester votre personnalisation, en utilisant docker build localement ou Cloud Build.

Traiter les requêtes entrantes

L'exemple de service utilise les paramètres de la requête HTTP entrante pour effectuer un appel système qui exécute la commande appropriée de l'utilitaire dot.

Dans le gestionnaire HTTP ci-dessous, un paramètre d'entrée de description de graphe est extrait de la variable de chaîne de requête dot.

Les descriptions de graphe peuvent inclure des caractères qui doivent être encodés au format URL pour pouvoir être utilisés dans une chaîne de requête.

Node.js

run/system-package/app.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

run/system-package/main.py 
@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 

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

Vous devrez faire la distinction entre les erreurs de serveur internes et les entrées utilisateur non valides. Cet exemple de service renvoie une erreur de serveur interne pour toutes les erreurs de ligne de commande dot, sauf si le message d'erreur contient la chaîne syntax, ce qui indique un problème de saisie de la part de l'utilisateur.

Générer un schéma

La logique de base de la génération de schéma utilise l'outil de ligne de commande dot pour traiter le paramètre d'entrée de description de graphe dans un schéma au format d'image PNG.

Node.js

run/system-package/app.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

run/system-package/main.py 
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 

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

Concevoir un service sécurisé

Toutes les failles de l'outil dot constituent des failles potentielles du service Web. Pour réduire ces risques, utilisez des versions à jour du package graphviz en recréant régulièrement l'image de conteneur.

Si vous étendez l'exemple actuel pour accepter les entrées utilisateur en tant que paramètres de ligne de commande, vous devez fournir une protection contre les attaques par injection de commande. Des moyens existent pour prévenir les attaques par injection, parmi lesquels :

  • Mapper les entrées dans un dictionnaire de paramètres compatibles.
  • Valider les entrées correspondant à une plage de valeurs connues, en utilisant éventuellement des expressions régulières.
  • Échapper les entrées pour s'assurer que la syntaxe du shell n'est pas évaluée.

Transmettre le code

Pour transmettre votre code, créez un conteneur avec Cloud Build, importez-le dans Container Registry, puis déployez-le sur Cloud Run for Anthos :

  1. Exécutez la commande suivante pour créer votre conteneur et publier sur Container Registry.

    Node.js 

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

    Où PROJECT_ID est l'ID de votre projet GCP et graphviz le nom que vous souhaitez attribuer à votre service.

    En cas de réussite, un message SUCCESS apparaît contenant l'ID, l'heure de création et le nom de l'image. Celle-ci est stockée dans Container Registry et peut être réutilisée au besoin.

    Python 

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

    Où PROJECT_ID est l'ID de votre projet GCP et graphviz le nom que vous souhaitez attribuer à votre service.

    En cas de réussite, un message SUCCESS apparaît contenant l'ID, l'heure de création et le nom de l'image. Celle-ci est stockée dans Container Registry et peut être réutilisée au besoin.

    Go 

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

    Où PROJECT_ID est l'ID de votre projet GCP et graphviz le nom que vous souhaitez attribuer à votre service.

    En cas de réussite, un message SUCCESS apparaît contenant l'ID, l'heure de création et le nom de l'image. Celle-ci est stockée dans Container Registry et peut être réutilisée au besoin.

    Java

    Cet exemple utilise Jib pour créer des images Docker à l'aide d'outils Java courants. Jib optimise les builds de conteneurs sans requérir de fichier Dockerfile ni d'installation Docker. Découvrez comment créer des conteneurs Java avec Jib.

    1. À l'aide du fichier Dockerfile, configurez et créez une image de base avec les packages système installés pour remplacer l'image de base par défaut de Jib :

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

      Où PROJECT_ID est l'ID de votre projet GCP.

    2. Créez votre conteneur final avec Jib et publiez-le sur Container Registry :

      run/system-package/pom.xml 
      <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

      Où PROJECT_ID est l'ID de votre projet GCP.

  2. Utilisez la commande suivante pour effectuer le déploiement :

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

    Où PROJECT_ID est l'ID de votre projet GCP, graphviz est le nom du conteneur ci-dessus et graphviz-web est le nom du service.

    Patientez jusqu'à la fin du déploiement, soit environ 30 secondes.

  3. Si vous souhaitez déployer une mise à jour de code sur le service, répétez les opérations précédentes. Chaque déploiement sur un service crée une nouvelle révision et commence automatiquement à acheminer le trafic une fois prêt.

Essayer

Testez votre service en envoyant des requêtes HTTP POST contenant des descriptions de syntaxe DOT dans la charge utile de la requête.

  1. Envoyez une requête HTTP à votre service.

    Le schéma peut être intégré dans une page Web :

    1. Pour obtenir l'adresse IP externe de la passerelle d'entrée Istio, exécutez la commande suivante : 
      kubectl get svc istio-ingress -n gke-system
      où le résultat ressemble à ce qui suit : 
      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
      La valeur EXTERNAL-IP de l'équilibreur de charge est l'adresse IP que vous devez utiliser.

    2. Exécutez une commande curl en utilisant cette adresse EXTERNAL-IP dans l'URL : N'incluez pas le protocole (par exemple, http://) dans 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. Ouvrez le fichier diagram.png obtenu dans une application compatible avec les fichiers PNG, telle que Chrome.

    Elle devrait se présenter comme ceci :

    Schéma montrant le flux des différentes étapes : Coder, Créer, Déployer et Exécuter.
    Source: Description DOT

Vous pouvez explorer une petite collection de descriptions de schéma prêtes à l'emploi.

  1. Copiez le contenu du fichier .dot sélectionné.

  2. Collez-le dans une commande 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

Effectuer un nettoyage

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous souhaitez le conserver sans les modifications du présent tutoriel, supprimez les ressources créées pour ce tutoriel.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  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.

Supprimer les ressources du tutoriel

  1. Supprimez le service Cloud Run pour Anthos que vous avez déployé dans ce tutoriel :

    gcloud run services delete SERVICE-NAME

    Où SERVICE-NAME est le nom de service que vous avez choisi.

    Vous pouvez également supprimer des services Cloud Run for Anthos depuis la console Google Cloud :

    Accéder à Cloud Run pour Anthos

  2. Supprimez les configurations gcloud par défaut que vous avez ajoutées lors de la configuration du tutoriel :

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

  3. Supprimez la configuration du projet :

     gcloud config unset project

  4. Supprimez les autres ressources Google Cloud créées dans ce tutoriel :

Étapes suivantes

  • Testez votre application graphviz :
    • Assurez la compatibilité pour d'autres utilitaires graphviz appliquant différents algorithmes pour générer les schémas.
    • Enregistrez les schémas dans Cloud Storage. Voulez-vous enregistrer l'image ou la syntaxe DOT ?
    • Ajoutez une protection contre les contenus abusifs avec l'API Cloud Natural Language.
    • Découvrez un autre exemple de package système dans la section Traitement des images.
  • Découvrez des architectures de référence, des schémas et des bonnes pratiques concernant Google Cloud. Consultez notre Centre d'architecture cloud.