Guía de configuración manual

El flujo de aprovisionamiento automático se puede usar para implementar el servidor de etiquetado en Cloud Run con solo unos clics. Si deseas aprovisionar el servidor de etiquetado en otros entornos, puedes hacerlo de forma manual. El servidor de etiquetado es un servidor de Node.js dentro de una imagen de Docker.

El aprovisionamiento manual del servidor de etiquetado requiere que se aprovisionen el clúster de etiquetado del servidor (SST) y un servidor de vista previa por separado. El clúster de SST es el punto de entrada para todas las solicitudes al servidor de etiquetado y controlará las solicitudes como se describe en Introducción al etiquetado del servidor. El servidor de vista previa es necesario para obtener una vista previa de un contenedor.

En la figura 1, se ilustra la interacción de datos entre los servidores de etiquetado y el servidor de vista previa.

Diagrama del flujo de datos de los servidores de etiquetado y el servidor de vista previa

Figura 1: Diagrama del flujo de datos de los servidores de etiquetado y el servidor de vista previa.

En esta guía, se explica cómo hacer lo siguiente:

  • Consulta todos los parámetros de configuración disponibles para la imagen de Docker.
  • (Opcional) Incluye credenciales de BigQuery
  • Aprovisiona manualmente un servidor de vista previa con la imagen de Docker de SST.
  • Aprovisiona manualmente un clúster de SST con la imagen de Docker de SST.
  • Verifica que el servidor de vista previa y el clúster de SST estén configurados correctamente.
  • Mantén actualizada la versión de tu servidor de etiquetado después de aprovisionarlo.

Para ejecutar los comandos de Docker en esta guía, primero debes instalar Docker en tu computadora.

Consulta todos los parámetros de configuración disponibles para la imagen de Docker

La imagen de Docker del servidor de etiquetado se puede encontrar en esta URL:

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

El servidor de etiquetado y el servidor de vista previa usan la misma imagen de Docker con diferentes marcas. En esta sección, explicaremos cómo buscar todos los parámetros de configuración disponibles que se pueden usar con la imagen de Docker.

Para ver todos los parámetros de configuración disponibles, ejecuta el siguiente comando con la herramienta de línea de comandos de Docker:

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

(Opcional) Incluye las credenciales de Google Cloud

Para usar la API de BigQuery o Firestore fuera de Google Cloud, debes proporcionar una credencial de cuenta de servicio que esté autorizada para acceder a esos recursos.

  1. Sigue esta guía para crear una cuenta de servicio con el rol de editor de datos de BigQuery para el acceso a BigQuery o el rol de usuario de Cloud Datastore para el acceso a Firestore y exporta sus credenciales JSON con el nombre de archivo local_service_account_key.json.
  2. Activa la credencial JSON en un volumen accesible para la imagen. Con docker run, puedes especificar -v local_service_account_key.json:/app/service_account_key.json para montar las credenciales en la imagen.
  3. Haz que la variable de entorno GOOGLE_APPLICATION_CREDENTIALS apunte a la credencial.
  4. De manera opcional, especifica tu ID del proyecto de Google Cloud en la variable de entorno GOOGLE_CLOUD_PROJECT para permitir que el servidor de etiquetado elija el proyecto de forma implícita.

  5. Ejecuta el servidor. El siguiente comando ejecuta el servidor de etiquetado con las credenciales incluidas:

    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

Según el sistema en el que se implemente el servidor de etiquetado, es posible que haya diferentes formas de activar las credenciales. Por ejemplo, Kubernetes y Docker Swarm proporcionan guías para administrar secretos. Consulta la guía de tu sistema respectivo para obtener más información.

Asegúrate de seguir las prácticas recomendadas para proteger tus credenciales.

Aprovisiona un servidor de vista previa de forma manual

El servidor de vista previa te permite obtener una vista previa del contenedor del servidor. Para ejecutar el servidor de vista previa, ejecuta la imagen de Docker con las siguientes variables de entorno que se pasan al entorno de Docker.

Configuración obligatoria

  • CONTAINER_CONFIG: Es la cadena de configuración del contenedor del servidor. En Tag Manager, navega al espacio de trabajo de tu contenedor de servidor y haz clic en el ID del contenedor en la parte superior derecha de la página. Haz clic en Aprovisionar manualmente el servidor de etiquetado para encontrar el valor de Configuración del contenedor.

  • RUN_AS_PREVIEW_SERVER: Configúralo como true para aprovisionar el servidor como un servidor de vista previa.

Ejemplo con la herramienta de línea de comandos de Docker

Para aprovisionar un servidor de vista previa de forma local, ejecuta el siguiente comando:

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

Deberías poder ver una respuesta 200 de una solicitud a http://localhost:8080/healthy. De manera opcional, usa la variable de entorno PORT para cambiar el puerto.

Prácticas recomendadas

  • Debes implementar exactamente 1 servidor de vista previa. No configures el ajuste de escala automático más allá de 1 instancia.
  • Una vez que hayas configurado un servidor de vista previa con Docker, configura una URL HTTPS para que apunte al servidor de vista previa. Esto es necesario para configurar el clúster de SST.
  • Tu balanceador de cargas o CDN debe tener un tiempo de espera superior a 20 segundos; de lo contrario, el modo de vista previa no funcionará correctamente.

Aprovisiona manualmente un clúster de etiquetado del servidor

El clúster de SST funciona como punto de entrada, reenvía solicitudes de vista previa al servidor de vista previa y controla todas las demás solicitudes como se describe en Introducción al etiquetado del servidor. Usa la siguiente configuración obligatoria con la imagen de Docker del servidor de etiquetado para aprovisionar un clúster de SST en cualquier entorno que admita Docker.

Configuración obligatoria

  • CONTAINER_CONFIG: Es la cadena de configuración del contenedor del servidor. En Tag Manager, navega al espacio de trabajo de tu contenedor de servidor y haz clic en el ID del contenedor en la parte superior derecha de la página. Haz clic en Aprovisionar manualmente el servidor de etiquetado para encontrar el valor de Configuración del contenedor.

  • PREVIEW_SERVER_URL: Es la URL HTTPS del servidor de vista previa. Este parámetro de configuración solo se debe establecer para aprovisionar el servidor de etiquetado y no es necesario para aprovisionar el servidor de vista previa. Consulta la sección anterior para obtener una guía sobre cómo configurar el servidor de vista previa.

Ejemplo con la herramienta de línea de comandos de Docker

Para aprovisionar un solo servidor de etiquetado de forma local, ejecuta el siguiente comando:

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

Deberías ver una respuesta 200 de una solicitud a http://localhost:8080/healthy. De manera opcional, usa la variable de entorno PORT para cambiar el puerto.

Prácticas recomendadas

  • Los servidores de etiquetado del servidor se pueden aprovisionar como un solo servidor o como un clúster. Te recomendamos que lo aprovisiones como un clúster para mejorar la disponibilidad, la escalabilidad y el rendimiento. Ten en cuenta que, cuando se aprovisiona como clúster, cada instancia del servidor debe configurarse con las mismas variables de entorno CONTAINER_CONFIG y PREVIEW_SERVER_URL.
  • Asegúrate de alojar tu servidor de etiquetado en el mismo origen (práctica recomendada) o como un subdominio de tu sitio web actual. Por ejemplo, si tu aplicación publica tráfico web en example.com, usa una ruta de acceso como example.com/analytics para tu servidor de etiquetado. Obtén más información sobre la configuración de dominios personalizados.
  • Una vez que hayas configurado un clúster de SST con Docker, configura una URL de HTTPS para que apunte al clúster de SST.
  • Asegúrate de reiniciar los servidores periódicamente para garantizar que tengan las actualizaciones de código más recientes para SST. De lo contrario, es posible que las funciones nuevas de SST no sean compatibles. Una forma de saber cuándo se debe reiniciar el servidor es configurar comprobaciones de actividad, lo que se explica más adelante. Además, ten en cuenta que las actualizaciones publicadas en tu contenedor del servidor se seguirán aplicando sin necesidad de reiniciar el servidor.
  • Utiliza el extremo /healthy existente (p.ej., https://analytics.example.com/healthy) en tus servidores de etiquetado para configurar verificaciones de actividad. Una respuesta que indica que el servidor no está en buen estado indica que se debe reiniciar.
  • El contenedor de Docker incluye un comando de verificación de estado predeterminado (HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]) que consulta el extremo /healthy de forma periódica. Si dependes de la verificación de estado de Docker, puedes cambiar la configuración siguiendo las instrucciones de Docker.
  • Si el servidor de vista previa y el servidor de etiquetado tienen el mismo origen, aloja el servidor de vista previa en una ruta diferente a la del servidor de etiquetado. Especifica PREVIEW_SERVER_URL, incluida la ruta de acceso.
  • Los servidores aprovisionados deben tener como máximo 1 CPU virtual. No se utilizan las vCPU adicionales y se afecta negativamente el ajuste de escala automático.

Validación

Configura la URL del contenedor del servidor

En Tag Manager, navega a tu contenedor del servidor. En Administrador > Configuración del contenedor, coloca la URL del servidor de etiquetado en el campo URL del contenedor del servidor y haz clic en Guardar.

Verifica a través del modo de vista previa

En el espacio de trabajo de Tag Manager, haz clic en Vista previa para obtener una vista previa del contenedor y ver que se carga la página de vista previa. En otra pestaña del navegador, navega a cualquier ruta de la URL del contenedor del servidor. Si la página de vista previa muestra la solicitud que se envió, todo está configurado correctamente.

Si asignaste varios subdominios a un solo servidor de etiquetado y deseas obtener una vista previa en cada subdominio, agrega URLs de contenedor del servidor adicionales en Administrador > Configuración del contenedor. Si se proporcionan varias URLs, todas las rutas de URL deben coincidir (la cadena de información que aparece después del nombre de dominio). Por ejemplo, puedes obtener una vista previa en example.com/abc y example2.com/abc, pero no en example.com/abc y example2.com/def. Si se agregan varias URLs, verás un ícono junto al botón Vista previa que te permitirá seleccionar la URL en la que deseas obtener una vista previa.

Actualiza la versión del servidor de etiquetado

La imagen gtm-cloud-image contiene Node.js y las bibliotecas necesarias para que funcione el servidor de etiquetado. La imagen de Docker se actualiza periódicamente para incluir correcciones de seguridad y funciones nuevas. Te recomendamos que actualices tu servidor de etiquetado al menos para cada lanzamiento de una versión principal (p.ej., actualizar de la versión 1.x.x a la 2.x.x).

Para actualizar tu imagen de Docker, haz lo siguiente:

  1. Recupera la versión actual de la imagen en gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
  2. Implementa tu servidor con la misma configuración que la implementación anterior.
  3. Actualiza el servidor de vista previa único y todos los servidores de etiquetado del clúster.
  4. Apaga los servidores antiguos.

Para verificar que la actualización se haya realizado correctamente, haz lo siguiente:

  1. En tu contenedor del servidor, haz clic en el botón Vista previa para iniciar una nueva sesión de depuración y enviar una solicitud en una pestaña separada.
  2. En el resumen, selecciona la pestaña Consola y asegúrate de que no haya mensajes que te pidan que actualices el servidor de etiquetado.

Es posible que Tag Manager muestre mensajes en los que se te solicite que actualices tu servidor de etiquetado hasta un día después de que se haya actualizado correctamente. Sin embargo, la página de vista previa mostrará un mensaje actualizado sobre la versión del servidor de etiquetado.