Ce tutoriel explique comment créer un service Cloud Run 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 fichier Dockerfile.
- Écrire, créer et déployer un service Cloud Run.
- Utiliser l'utilitaire Graphviz dot pour générer des diagrammes.
- 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.
Avant de commencer
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Activez l'API Cloud Run Admin
- Installez et initialisez gcloud CLI.
- Mettez à jour les composants :
gcloud components update
Rôles requis
Pour obtenir les autorisations nécessaires pour suivre le tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :
-
Éditeur Cloud Build (
roles/cloudbuild.builds.editor
) -
Administrateur Cloud Run (
roles/run.admin
) -
Créateur de comptes de service (
roles/iam.serviceAccountCreator
) -
Utilisateur du compte de service (
roles/iam.serviceAccountUser
) -
Consommateur Service Usage (
roles/serviceusage.serviceUsageConsumer
) -
Administrateur de l'espace de stockage (
roles/storage.admin
)
Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
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 :
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.
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.
Emplacements Cloud Run
Cloud Run est régional, ce qui signifie que l'infrastructure qui exécute vos services Cloud Run est située dans une région spécifique et gérée par Google pour être disponible de manière redondante dans toutes les zones de cette région.
Lors de la sélection de la région dans laquelle exécuter vos services Cloud Run, vous devez tout d'abord considérer vos exigences en matière de latence, de disponibilité et de durabilité.
Vous pouvez généralement sélectionner la région la plus proche de vos utilisateurs, mais vous devez tenir compte de l'emplacement des autres produits Google Cloud utilisés par votre service Cloud Run.
L'utilisation conjointe de produits Google Cloud dans plusieurs emplacements peut avoir une incidence sur la latence et le coût de votre service.
Cloud Run est disponible dans les régions suivantes :
Soumis aux tarifs de niveau 1
asia-east1
(Taïwan)asia-northeast1
(Tokyo)asia-northeast2
(Osaka)europe-north1
(Finlande) Faibles émissions de CO2europe-southwest1
(Madrid) Faibles émissions de CO2europe-west1
(Belgique) Faibles émissions de CO2europe-west4
(Pays-Bas) Faibles émissions de CO2europe-west8
(Milan)europe-west9
(Paris) Faibles émissions de CO2me-west1
(Tel Aviv)us-central1
(Iowa) Faibles émissions de CO2us-east1
(Caroline du Sud)us-east4
(Virginie du Nord)us-east5
(Columbus)us-south1
(Dallas) Faibles émissions de CO2us-west1
(Oregon) Faibles émissions de CO2
Soumis aux tarifs de niveau 2
africa-south1
(Johannesburg)asia-east2
(Hong Kong)asia-northeast3
(Séoul, Corée du Sud)asia-southeast1
(Singapour)asia-southeast2
(Jakarta)asia-south1
(Mumbai, Inde)asia-south2
(Delhi, Inde)australia-southeast1
(Sydney)australia-southeast2
(Melbourne)europe-central2
(Varsovie, Pologne)europe-west10
(Berlin) Faibles émissions de CO2.europe-west12
(Turin)europe-west2
(Londres, Royaume-Uni) Faibles émissions de CO2europe-west3
(Francfort, Allemagne) Faibles émissions de CO2europe-west6
(Zurich, Suisse) Faibles émissions de CO2me-central1
(Doha)me-central2
(Dammam)northamerica-northeast1
(Montréal) Faibles émissions de CO2northamerica-northeast2
(Toronto) Faibles émissions de CO2southamerica-east1
(São Paulo, Brésil) Faibles émissions de CO2southamerica-west1
(Santiago, Chili) Faibles émissions de CO2us-west2
(Los Angeles)us-west3
(Salt Lake City)us-west4
(Las Vegas)
Si vous avez déjà créé un service Cloud Run, vous pouvez afficher la région dans le tableau de bord Cloud Run de la console Google Cloud.
Récupérer l'exemple de code
Pour récupérer l’exemple de code à utiliser, procédez comme suit :
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.
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.
Ouvrez le fichier
Dockerfile
dans un éditeur.Recherchez une instruction
Dockerfile
RUN
. Cette instruction permet d'exécuter des commandes de shell arbitraires pour modifier l'environnement. Si le fichierDockerfile
comporte plusieurs étapes, identifiées par plusieurs instructionsFROM
, 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 Alpine Alpine nécessite un deuxième package pour la prise en charge des polices.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 depuisnode
, vous trouverez la documentation et le fichierDockerfile
parent sur Docker Hub.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
Python
Go
Java
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
Python
Go
Java
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 :
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.
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.À 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 :
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base
où PROJECT_ID correspond à l’ID de votre projet Google Cloud.
Utilisez l'assistant d'identification gcloud pour autoriser Docker à transférer du contenu vers Artifact Registry.
gcloud auth configure-docker
Créez votre conteneur final avec Jib et publiez-le sur Artifact Registry :
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.
Procédez au déploiement à l'aide des éléments suivants :
gcloud
- 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.
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.gcloud iam service-accounts create SA_NAME
- Déployez le code en spécifiant le compte de service.
Où PROJECT_ID correspond à l'ID de votre projet Google Cloud, SA_NAME correspond au nom du compte de service que vous avez créé,gcloud run deploy graphviz-web --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
graphviz
correspond au nom du conteneur ci-dessus etgraphviz-web
correspond au nom du service. RépondezY
à l'invite "Autoriser sans authentification". Pour en savoir plus sur l'authentification basée sur IAM, consultez la page Gérer les accès. - 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.
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.
- 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.
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.
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 }" />
Ouvrez le fichier
diagram.png
obtenu dans une application compatible avec les fichiersPNG
, 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.
- Copiez le contenu du fichier
.dot
sélectionné. 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
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 :
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Supprimer les ressources du tutoriel
Supprimez le service Cloud Run 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 à partir de Google Cloud Console.
Supprimez la configuration régionale gcloud par défaut que vous avez ajoutée lors de la configuration du tutoriel :
gcloud config unset run/region
Supprimez la configuration du projet :
gcloud config unset project
Supprimez les autres ressources Google Cloud créées dans ce tutoriel :
Supprimez l'image de conteneur nommée
REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
de Artifact Registry.Supprimez le compte de service SA_NAME.
gcloud iam service-accounts delete SA_NAME@PROJECT_ID.iam.gserviceaccount.com
É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.
- Consultez un autre exemple de package système dans le tutoriel sur le traitement des images avec Cloud Run.
- Découvrez des architectures de référence, des schémas et des bonnes pratiques concernant Google Cloud. Consultez notre Cloud Architecture Center.