Tutoriel sur l'utilisation des packages système

Configurer les paramètres par défaut de gcloud

Pour configurer gcloud avec les valeurs par défaut pour votre service Cloud Run, 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 avez créé pour ce tutoriel.

2. Configurez gcloud pour la région choisie :

   gcloud config set run/region REGION

   Remplacez REGION par la région Cloud Run 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 :

   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 :

L'utilisateur adresse une requête HTTP au service Cloud Run, 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.

La page Démarrage rapide : Construire et déployer montre divers fichiers Dockerfiles pouvant être utilisés comme point de départ afin de créer un fichier Dockerfile pour d'autres services.

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.

   Debian/Ubuntu

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

   Alpine

   Alpine nécessite un deuxième package pour la prise en charge des polices.

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

   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.

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

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.

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

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.

Vous pouvez atténuer davantage les failles potentielles en déployant le service avec un compte de service qui n'a pas été autorisé à utiliser les services Google Cloud, plutôt qu'avec le compte par défaut, qui dispose d'autorisations communes. Pour cette raison, les étapes de ce tutoriel créent et utilisent un nouveau compte de service.

Transmettre le code

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

1. Créez un dépôt Artifact Registry :

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

   Remplacez :

   • REPOSITORY par un nom unique pour le dépôt Pour chaque emplacement de dépôt d'un projet, les noms de dépôt doivent être uniques.
   • REGION par la région Google Cloud à utiliser pour le dépôt Artifact Registry.

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

   Node.js

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

   Où PROJECT_ID correspond à votre ID de projet Google Cloud et graphviz au 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. L'image est stockée dans Artifact Registry et peut être réutilisée si vous le souhaitez.

   Python

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

   Où PROJECT_ID correspond à votre ID de projet Google Cloud et graphviz au 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. L'image est stockée dans Artifact Registry et peut être réutilisée si vous le souhaitez.

   Go

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

   Où PROJECT_ID correspond à votre ID de projet Google Cloud et graphviz au 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. L'image est stockée dans Artifact Registry et peut être réutilisée si vous le souhaitez.

   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 :

      # 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

      où PROJECT_ID correspond à l’ID de votre projet Google Cloud.

   2. Utilisez l'assistant d'identification gcloud pour autoriser Docker à transférer du contenu vers Artifact Registry.

      gcloud auth configure-docker

   3. Créez votre conteneur final avec Jib et publiez-le sur 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

      où PROJECT_ID correspond à l’ID de votre projet Google Cloud.

3. Procédez au déploiement à l'aide des éléments suivants :

   gcloud

   1. Créez un compte de service. Votre code, y compris les packages système qu'il utilise, ne peut utiliser que les services Google Cloud autorisés pour ce compte de service.

      gcloud iam service-accounts create SA_NAME

      Où SA_NAME correspond au nom que vous attribuez à ce compte de service. Si le code comporte une erreur ou une faille, celui-ci ne pourra accéder à aucune de vos autres ressources de projet Google Cloud.
   2. Déployez le code en spécifiant le compte de service.

      gcloud run deploy graphviz-web --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com  --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

      Où PROJECT_ID correspond à l'ID de votre projet Google Cloud, SA_NAME correspond au nom du compte de service que vous avez créé, graphviz correspond au nom du conteneur ci-dessus et graphviz-web correspond au nom du service. Répondez Y à l'invite "Autoriser sans authentification". Pour en savoir plus sur l'authentification basée sur IAM, consultez la page Gérer les accès.
   3. Patientez jusqu'à la fin du déploiement. Cette opération peut prendre environ 30 secondes. En cas de réussite, la ligne de commande affiche l'URL du service.

   Terraform

   Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base.

   Le code Terraform suivant crée un service 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
     }
   }

   Remplacez IMAGE_URL par une référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL se présente sous la forme suivante : LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

   Le code Terraform suivant rend votre service Cloud Run public.

   # 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. 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.

   Copiez l’URL dans la barre d'adresse de votre navigateur et mettez à jour [SERVICE_DOMAIN] :

   https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }

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

   <img src="https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" />

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 :

   

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. Envoyez une requête HTTP à votre service.

   Copiez l'URL dans la barre d'adresse de votre navigateur.

   https://SERVICE_DOMAIN/diagram.png?dot=SELECTED DOTFILE CONTENTS