Guide de configuration manuelle

Le flux de provisionnement automatique permet de déployer le serveur de taggage sur 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 à l'intérieur d'une image Docker.

Le provisionnement manuel du serveur de taggage nécessite de provisionner séparément le cluster de taggage côté serveur (SST) et un serveur d'aperçu. Le cluster SST est le point d'entrée pour toutes les requêtes adressées au serveur de taggage. Il gère les requêtes comme décrit dans Présentation du taggage côté serveur. Le serveur d'aperçu 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.

Diagramme du flux de données des serveurs de taggage et 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 d'aperçu à l'aide de l'image Docker SST.
  • Provisionnez manuellement un cluster SST à l'aide de l'image Docker SST.
  • Vérifiez que le serveur d'aperçu et le cluster SST sont correctement configurés.
  • Après avoir provisionné le serveur, veillez à ce que la version de votre serveur de taggage soit à jour.

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'adresse 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 vous montrer 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) Incluez les identifiants Google Cloud.

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

  1. Suivez ce guide pour créer un compte de service avec le rôle Éditeur de données BigQuery pour l'accès BigQuery ou le rôle Utilisateur Cloud Datastore pour l'accès Firestore, puis exportez ses identifiants JSON avec 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 monter les identifiants dans l'image.
  3. Faites pointer la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS vers les identifiants.
  4. Vous pouvez également spécifier l'ID de votre projet Google Cloud dans la variable d'environnement GOOGLE_CLOUD_PROJECT pour permettre au serveur de taggage de choisir implicitement le projet.

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

    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 pour gérer les secrets. Pour en savoir plus, consultez le guide de votre système.

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 d'aperçu, 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 de serveur. Dans Tag Manager, accédez à l'espace de travail de votre 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 Configuration du conteneur.

  • RUN_AS_PREVIEW_SERVER : définissez cette valeur sur true pour provisionner le serveur en tant que serveur d'aperçu.

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

Pour provisionner un serveur d'aperçu en local, 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 obtenir une réponse 200 à une requête envoyée à http://localhost:8080/healthy. Vous pouvez également utiliser la variable d'environnement PORT pour modifier le port.

Bonnes pratiques

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

Provisionner manuellement un cluster d'ajout de tags côté serveur

Le cluster SST sert de point d'entrée, transmet les requêtes d'aperçu au serveur d'aperçu et gère toutes les autres requêtes, comme décrit dans Présentation du taggage côté serveur. Utilisez les paramètres requis 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 de serveur. Dans Tag Manager, accédez à l'espace de travail de votre 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 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. Il n'est pas nécessaire pour le provisionnement du serveur d'aperçu. Pour savoir comment configurer le serveur d'aperçu, consultez la section ci-dessus.

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

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

Bonnes pratiques

  • Les serveurs d'insertion de balises 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 de meilleures performances. Veuillez noter 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 régulièrement les serveurs pour vous assurer qu'ils disposent des dernières mises à jour du code pour SST. À défaut, les nouvelles fonctionnalités SST risquent d'être incompatibles. Pour savoir quand le serveur doit redémarrer, vous pouvez configurer des vérifications d'activité, comme expliqué plus loin. Notez également que toutes les mises à jour publiées de votre conteneur de serveur seront toujours appliquées sans redémarrage.
  • Utilisez le point de terminaison /healthy existant (par exemple, https://analytics.example.com/healthy) sur vos serveurs de taggage pour configurer des vérifications de l'état. Une réponse non opérationnelle 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 le point de terminaison /healthy de manière périodique. Si vous dépendez de la vérification de l'état Docker, vous pouvez modifier les paramètres en suivant les instructions Docker.
  • Si le serveur d'aperçu et le serveur de taggage se trouvent sur la même origine, hébergez le serveur d'aperçu 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 processeur virtuel. Les vCPU supplémentaires ne sont pas utilisés et ont un impact négatif sur l'autoscaling.

Validation

Configurer l'URL du conteneur de serveur

Dans Tag Manager, accédez à votre conteneur de 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 Prévisualiser et vérifiez que la page de prévisualisation se charge. Dans un autre onglet de navigateur, accédez à n'importe quel chemin d'accès sur l'URL du conteneur serveur. Si la page d'aperçu affiche la requête qui a été envoyée, cela signifie que tout est configuré correctement.

Si vous avez mappé plusieurs sous-domaines à un seul serveur d'insertion de balises et que vous souhaitez afficher un aperçu sur chaque sous-domaine, ajoutez d'autres URL de conteneur serveur sous Administration > Paramètres du conteneur. Si vous fournissez plusieurs URL, tous leurs chemins doivent correspondre (la chaîne d'informations qui suit le nom de domaine). Par exemple, vous pouvez afficher un aperçu 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 s'affiche à côté du bouton Aperçu. Elle 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 mise à jour régulièrement pour corriger les failles de sécurité et ajouter de nouvelles fonctionnalités. Nous vous recommandons au moins de mettre à jour 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 à l'adresse gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
  2. Déployez votre serveur avec les mêmes paramètres que le déploiement précédent.
  3. Mettez à jour le serveur de prévisualisation unique 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 :

  1. Dans votre conteneur serveur, cliquez sur le bouton Prévisualiser pour démarrer une nouvelle session de débogage et envoyer une requête dans un onglet distinct.
  2. Dans le récapitulatif, 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'à 24 heures après la mise à jour réussie du serveur. Toutefois, la page d'aperçu affichera un message à jour concernant la version du serveur de taggage.