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 le provisionnement du cluster SST (Server-Side Tagging) et d'un serveur de prévisualisation séparément. Le cluster SST est le point d'entrée de toutes les requêtes adressées au serveur de taggage et les traite comme décrit dans la section Présentation du taggage côté serveur. Ce serveur est nécessaire pour prévisualiser un conteneur.

La figure 1 illustre l'interaction de données entre les serveurs de taggage et le serveur de prévisualisation.

Figure 1: Schéma des serveurs d'ajout de tags et du flux de données du serveur de prévisualisation

Ce guide vous explique comment:

• Affichez tous les paramètres disponibles pour l'image Docker.
• (Facultatif) Inclure les identifiants BigQuery
• Provisionner manuellement un serveur de prévisualisation à l'aide de l'image Docker SST
• Provisionner manuellement un cluster SST à l'aide de l'image Docker SST
• Vérifiez que le serveur de prévisualisation 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.

Remarque :Lorsque vous configurez votre serveur de taggage, le propriétaire de l'environnement serveur (qu'il s'agisse d'un fournisseur cloud ou d'un environnement sur site) peut avoir accès à vos données. Pour en savoir plus, consultez les conditions d'utilisation de cette organisation.

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 options différentes. Dans cette section, nous verrons comment rechercher tous les paramètres disponibles pouvant ê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 des 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é à 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 et exporter 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 installer les identifiants dans l'image.
3. Faites pointer la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS vers l'identifiant.
4. Vous pouvez également spécifier votre ID de 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 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 existe différentes manières d'installer les identifiants. Par exemple, Kubernetes et Docker Swarm fournissent des guides pour la gestion des secrets. Pour en savoir plus, consultez le guide de votre système concerné.

Assurez-vous de 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 serveur. Pour exécuter le serveur de prévisualisation, lancez 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 à 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 d'ajout de tags pour trouver la valeur Container Config.

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

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

Pour provisionner un serveur de prévisualisation 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 voir une réponse 200 à la requête envoyée à http://localhost:8080/healthz. Vous pouvez également modifier le port à l'aide de la variable d'environnement PORT.

Bonnes pratiques

• Vous devez déployer exactement 1 serveur d'aperçu. Ne configurez pas d'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 de prévisualisation. Cette opération est nécessaire pour configurer le cluster SST.
• Votre équilibreur de charge ou CDN doit avoir un délai avant expiration 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 de prévisualisation au serveur de prévisualisation 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 d'ajout de tags 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 à 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 d'ajout de tags pour trouver la valeur Container Config.

• 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 de prévisualisation. Consultez la section ci-dessus pour obtenir des instructions sur la configuration du serveur de prévisualisation.

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

Pour provisionner un seul serveur de taggage localement, 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 voir une réponse 200 à la requête envoyée à http://localhost:8080/healthz. Vous pouvez également modifier le port à l'aide de la variable d'environnement 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 afin d'améliorer la disponibilité, l'évolutivité et les performances. 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 de diriger le déploiement de votre cluster SST vers un nouveau sous-domaine de votre site Web, qui est distinct du sous-domaine qui diffuse votre application. Par exemple, si votre application diffuse du trafic Web sur example.com, utilisez un sous-domaine tel que analytics.example.com pour votre serveur de taggage.
• 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 de code pour SST. Sinon, les nouvelles fonctionnalités SST risquent de ne pas fonctionner. Pour savoir quand le serveur doit redémarrer, vous pouvez configurer des vérifications d'activité, comme expliqué ci-dessous. Veuillez également noter que les mises à jour publiées de votre conteneur de serveur continueront d'être 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 opérationnelle indique que le serveur doit être redémarré.
• Le conteneur Docker inclut une commande de vérification d'é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 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 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 processeurs virtuels supplémentaires ne sont pas utilisés et affectent l'autoscaling de manière négative.

Données

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 de taggage dans le champ URL du conteneur de serveur, puis cliquez sur Enregistrer.

Valider via le mode Aperçu

Dans l'espace de travail Tag Manager, cliquez sur Prévisualiser pour prévisualiser le conteneur. La page d'aperçu se charge. Dans un autre onglet du navigateur, accédez à n'importe quel chemin d'accès de l'URL du conteneur serveur. Si la page d'aperçu affiche la requête envoyée, cela signifie que tout est correctement configuré.

Si vous avez mappé plusieurs sous-domaines à un seul serveur de taggage et que vous souhaitez prévisualiser chaque sous-domaine, ajoutez des URL de conteneur de serveur supplémentaires sous Admin > Paramètres du conteneur. Si plusieurs URL sont fournies, tous les chemins d'URL doivent correspondre (la 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 vous ajoutez plusieurs URL, vous verrez une icône à côté du bouton Aperçu, qui vous permet de sélectionner l'URL à utiliser pour l'aperçu.

Mettre à jour la version du serveur de taggage

Remarque :Si vous avez provisionné vos serveurs de taggage à l'aide du guide de configuration Cloud Run ou du guide de configuration App Engine, suivez les instructions qui y sont indiquées.

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 ajouter des correctifs de sécurité et de nouvelles fonctionnalités. Nous vous recommandons au moins de mettre à jour votre serveur de taggage pour chaque version majeure (par exemple, en passant 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 ceux du déploiement précédent.
3. Mettez à jour le serveur d'aperçu 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 Preview (Aperçu) pour démarrer une nouvelle session de débogage et envoyer une requête dans un onglet distinct.
2. Dans la section "Summary" (Résumé), sélectionnez l'onglet Console (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 affichera un message à jour sur la version du serveur de taggage.