Guide de configuration manuelle

Le flux de provisionnement automatique permet de déployer le serveur de taggage dans Cloud Run en quelques clics. Si vous souhaitez provisionner le serveur de taggage dans d'autres environnements, vous pouvez le faire manuellement. Le serveur de taggage est un serveur Node.js dans une image Docker.

Le provisionnement manuel du serveur de taggage nécessite de provisionner le cluster de taggage côté serveur (SST) et un serveur de prévisualisation séparément. Le cluster SST est le point d'entrée de toutes les requêtes envoyées au serveur de taggage et gère les requêtes comme décrit dans Présentation du taggage côté serveur. Le serveur de prévisualisation est nécessaire pour prévisualiser un conteneur.

La figure 1 illustre l'interaction des données entre les serveurs de taggage et le serveur d'aperçu.

Schéma de l'ajout de tags aux serveurs et du flux de données du serveur de prévisualisation

Figure 1: Diagramme du flux de données des serveurs de taggage et du serveur d'aperçu.

Ce guide vous explique comment:

  • Affichez tous les paramètres disponibles pour l'image Docker.
  • (Facultatif) Inclure les identifiants BigQuery
  • Provisionnez manuellement un serveur de prévisualisation à l'aide de l'image Docker SST.
  • Provisionnez manuellement un cluster SST à l'aide de l'image Docker SST.
  • Vérifiez que le serveur Preview et le cluster SST sont correctement configurés.
  • Mettez à jour la version de votre serveur de taggage après l'avoir provisionné.

Pour exécuter les commandes Docker de ce guide, vous devez d'abord installer Docker sur votre ordinateur.

Afficher tous les paramètres disponibles pour l'image Docker

L'image Docker du serveur de taggage est disponible à l'URL suivante:

gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Le serveur de taggage et le serveur d'aperçu utilisent la même image Docker avec des indicateurs différents. Dans cette section, nous allons voir comment rechercher tous les paramètres disponibles qui peuvent être utilisés avec l'image Docker.

Pour afficher tous les paramètres disponibles, exécutez la commande suivante à l'aide de l'outil de ligne de commande docker:

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable server_bin.js --help

(Facultatif) Inclure les identifiants Google Cloud

Pour utiliser l'API BigQuery ou Firestore en dehors de Google Cloud, vous devez fournir des identifiants de compte de service autorisés à accéder à ces ressources.

  1. Suivez ce guide pour créer un compte de service doté du rôle Éditeur de données BigQuery pour l'accès BigQuery ou Utilisateur Cloud Datastore pour l'accès Firestore, puis exportez ses identifiants JSON sous le nom de fichier local_service_account_key.json.
  2. Installez les identifiants JSON dans un volume accessible à l'image. À l'aide de docker run, vous pouvez spécifier -v local_service_account_key.json:/app/service_account_key.json pour installer les identifiants dans l'image.
  3. Pointez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS vers les identifiants.
  4. Vous pouvez également spécifier votre ID de projet Google Cloud dans la variable d'environnement GOOGLE_CLOUD_PROJECT pour laisser le serveur de taggage choisir le projet de manière implicite.

  5. Exécutez le serveur. La commande suivante exécute le serveur de taggage en incluant les identifiants:

    docker run -v local_service_account_key.json:/app/service_account_key.json \
-p 8080:8080 \
-e GOOGLE_APPLICATION_CREDENTIALS='/app/service_account_key.json' \
-e GOOGLE_CLOUD_PROJECT='<your project id>' \
-e CONTAINER_CONFIG='<config string>' \
gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Selon le système sur lequel le serveur de taggage est déployé, il peut exister différentes manières de monter les identifiants. Par exemple, Kubernetes et Docker Swarm fournissent des guides de gestion des secrets. Pour en savoir plus, consultez le guide de votre système respectif.

Veillez à suivre les bonnes pratiques pour protéger vos identifiants.

Provisionner manuellement un serveur de prévisualisation

Le serveur de prévisualisation vous permet de prévisualiser le conteneur de serveur. Pour exécuter le serveur Preview, exécutez l'image Docker avec les variables d'environnement suivantes transmises à l'environnement Docker.

Paramètres obligatoires

  • CONTAINER_CONFIG : chaîne de configuration du conteneur serveur. Dans Tag Manager, accédez à votre espace de travail de conteneur serveur, puis cliquez sur l'ID du conteneur en haut à droite de la page. Cliquez sur Provisionner manuellement le serveur de taggage pour trouver la valeur Container Config (Configuration du conteneur).

  • RUN_AS_PREVIEW_SERVER : définissez cette valeur sur true pour provisionner le serveur en tant que serveur Preview.

Exemple avec l'outil de ligne de commande Docker

Pour provisionner un serveur Preview localement, exécutez la commande suivante:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e RUN_AS_PREVIEW_SERVER=true gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Vous devriez voir une réponse 200 à partir d'une requête envoyée à http://localhost:8080/healthz. Vous pouvez également utiliser la variable d'environnement PORT pour modifier le port.

Bonnes pratiques

  • Vous devez déployer exactement un serveur de prévisualisation. Ne configurez pas l'autoscaling au-delà d'une instance.
  • Une fois que vous avez configuré un serveur de prévisualisation à l'aide de Docker, configurez une URL HTTPS pour qu'elle pointe vers le serveur de prévisualisation. Cela est nécessaire pour configurer le cluster SST.
  • Le délai avant expiration de votre équilibreur de charge ou de votre CDN doit être supérieur à 20 secondes, sinon le mode Preview ne fonctionnera pas correctement.

Provisionner manuellement un cluster de taggage côté serveur

Le cluster SST sert de point d'entrée, proxy les requêtes d'aperçu vers le serveur d'aperçu et gère toutes les autres requêtes, comme décrit dans la section Présentation du taggage côté serveur. Utilisez les paramètres obligatoires suivants avec l'image Docker du serveur de taggage pour provisionner un cluster SST dans n'importe quel environnement compatible avec Docker.

Paramètres obligatoires

  • CONTAINER_CONFIG : chaîne de configuration du conteneur serveur. Dans Tag Manager, accédez à votre espace de travail de conteneur serveur, puis cliquez sur l'ID du conteneur en haut à droite de la page. Cliquez sur Provisionner manuellement le serveur de taggage pour trouver la valeur Container Config (Configuration du conteneur).

  • PREVIEW_SERVER_URL : URL HTTPS du serveur de prévisualisation. Ce paramètre ne doit être défini que pour le provisionnement du serveur de taggage et n'est pas nécessaire pour le provisionnement du serveur d'aperçu. Consultez la section ci-dessus pour obtenir un guide de configuration du serveur Preview.

Exemple d'utilisation de l'outil de ligne de commande Docker

Pour provisionner un seul serveur d'insertion de balises en local, exécutez la commande suivante:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e PREVIEW_SERVER_URL='<HTTPS preview server url>' gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

Une réponse 200 doit s'afficher à partir d'une requête envoyée à http://localhost:8080/healthz. Vous pouvez également utiliser la variable d'environnement PORT pour modifier le port.

Bonnes pratiques

  • Les serveurs de taggage côté serveur peuvent être provisionnés en tant que serveur unique ou en tant que cluster. Nous vous recommandons de le provisionner en tant que cluster pour une meilleure disponibilité, évolutivité et performance. Notez que lors du provisionnement en tant que cluster, chaque instance de serveur doit être configurée avec les mêmes variables d'environnement CONTAINER_CONFIG et PREVIEW_SERVER_URL.
  • Assurez-vous d'héberger votre serveur de taggage dans la même origine (bonne pratique) ou en tant que sous-domaine de votre site Web actuel. Par exemple, si votre application génère du trafic Web sur example.com, utilisez un chemin d'accès tel que example.com/analytics pour votre serveur de taggage. En savoir plus sur la configuration des domaines personnalisés
  • Une fois que vous avez configuré un cluster SST à l'aide de Docker, configurez une URL HTTPS pour qu'elle pointe vers le cluster SST.
  • Veillez à redémarrer les serveurs régulièrement pour vous assurer qu'ils disposent des dernières mises à jour de code pour SST. Sinon, des fonctionnalités pourraient être incompatibles avec les nouvelles fonctionnalités SST. Pour savoir quand le serveur doit redémarrer, vous pouvez configurer des vérifications d'activité, comme expliqué ci-dessous. Notez également que toutes les mises à jour publiées pour votre conteneur serveur seront toujours appliquées sans redémarrage.
  • Utilisez le point de terminaison /healthz existant (par exemple, https://analytics.example.com/healthz) sur vos serveurs de taggage pour configurer les vérifications d'activité. Une réponse non saine indique que le serveur doit être redémarré.
  • Le conteneur Docker inclut une commande de vérification de l'état par défaut (HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]) qui interroge régulièrement le point de terminaison /healthz. Si vous dépendez de la vérification de l'état de Docker, vous pouvez modifier les paramètres en suivant les instructions Docker.
  • Si le serveur de prévisualisation et le serveur de taggage se trouvent sur la même origine, hébergez le serveur de prévisualisation sur un chemin différent de celui du serveur de taggage. Spécifiez le PREVIEW_SERVER_URL, y compris le chemin d'accès.
  • Les serveurs provisionnés ne doivent pas comporter plus d'un vCPU. Les vCPU supplémentaires ne sont pas utilisés et ont un impact négatif sur l'autoscaling.

Validation

Configurer l'URL du conteneur serveur

Dans Tag Manager, accédez à votre conteneur serveur. Sous Admin > Paramètres du conteneur, saisissez l'URL du serveur d'insertion de balises dans le champ URL du conteneur de serveur, puis cliquez sur Enregistrer.

Vérifier en mode Aperçu

Dans l'espace de travail Tag Manager, prévisualisez le conteneur en cliquant sur Aperçu et vérifiez que la page d'aperçu se charge. Dans un autre onglet de navigateur, accédez à un chemin d'accès sur l'URL du conteneur serveur. Si la page d'aperçu affiche la requête envoyée, tout est configuré correctement.

Si vous avez mappé plusieurs sous-domaines à un seul serveur de taggage et que vous souhaitez afficher l'aperçu sur chaque sous-domaine, ajoutez des URL de conteneurs de serveur supplémentaires sous Admin > Paramètres du conteneur. Si vous fournissez plusieurs URL, tous leurs chemins doivent correspondre (chaîne d'informations qui suit le nom de domaine). Par exemple, vous pouvez prévisualiser sur example.com/abc et example2.com/abc, mais pas sur example.com/abc et example2.com/def. Si plusieurs URL sont ajoutées, une icône à côté du bouton Aperçu vous permet de sélectionner l'URL à prévisualiser.

Mettre à jour la version du serveur de taggage

L'image gtm-cloud-image contient Node.js et les bibliothèques nécessaires au fonctionnement du serveur de taggage. L'image Docker est régulièrement mise à jour pour intégrer les correctifs de sécurité et les nouvelles fonctionnalités. Nous vous recommandons de mettre à jour au moins votre serveur de taggage pour chaque version majeure (par exemple, passer de la version 1.x.x à la version 2.x.x).

Pour mettre à jour votre image Docker:

  1. Récupérez la version actuelle de l'image sur gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
  2. Déployez votre serveur avec les mêmes paramètres que pour le déploiement précédent.
  3. Mettez à jour le seul serveur de prévisualisation et tous les serveurs de taggage du cluster.
  4. Arrêtez tous les anciens serveurs.

Pour vérifier que la mise à jour a bien été effectuée, procédez comme suit:

  1. Dans votre conteneur serveur, cliquez sur le bouton Preview (Aperçu) pour démarrer une nouvelle session de débogage et envoyer une requête dans un onglet distinct.
  2. Dans "Résumé", sélectionnez l'onglet Console et assurez-vous qu'aucun message ne vous demande de mettre à jour le serveur de taggage.

Tag Manager peut afficher des messages vous demandant de mettre à jour votre serveur de taggage jusqu'à une journée après la mise à jour du serveur. Toutefois, la page d'aperçu affiche un message à jour sur la version du serveur de taggage.