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.

Para aprovisionar el servidor de etiquetado de forma manual, debes aprovisionar 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 manejará las solicitudes como se describe en Introducción al etiquetado del servidor. Se necesita el servidor de vista previa para obtener una vista previa de un contenedor.

Consulta la figura 1 para ver una ilustración de 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 de los servidores de vista previa

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

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

  • Consulta todos los parámetros de configuración disponibles para la imagen de Docker.
  • Incluye credenciales de BigQuery (opcional)
  • Aprovisionar de forma manual un servidor de vista previa con la imagen de Docker de SST
  • Aprovisionar de forma manual 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 del servidor de etiquetado después de aprovisionar el servidor.

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

Ver 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, veremos 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 lo siguiente 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

Cómo incluir credenciales de Google Cloud (opcional)

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 exportar sus credenciales JSON con el nombre de archivo local_service_account_key.json.
  2. Activa la credencial JSON en un volumen al que la imagen pueda acceder. Con docker run, puedes especificar -v local_service_account_key.json:/app/service_account_key.json para activar las credenciales en la imagen.
  3. Apuntar la variable de entorno GOOGLE_APPLICATION_CREDENTIALS a la credencial
  4. De manera opcional, especifica el ID de tu 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, puede haber diferentes maneras de activar las credenciales. Por ejemplo, Kubernetes y Docker Swarm proporcionan guías para administrar secretos. Consulta la guía de tu sistema correspondiente 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 pasadas al entorno de Docker.

Configuración obligatoria

  • CONTAINER_CONFIG: Es la cadena de configuración del contenedor del servidor. En Tag Manager, navega a tu lugar de trabajo del 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: Configura esto como true para aprovisionar el servidor como 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 lo siguiente:

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/healthz. 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, proxy de 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 lugar de trabajo del contenedor del 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 Container Config.

  • 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 la configuración del 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 lo siguiente:

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/healthz. 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 un clúster, cada instancia de 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 entrega 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 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 de SST. De lo contrario, es posible que las funciones de SST nuevas no sean compatibles. Una forma de saber cuándo se debe reiniciar el servidor es configurar las verificaciones de actividad, que se explican a continuación. Además, ten en cuenta que las actualizaciones publicadas en el contenedor del servidor se aplicarán sin necesidad de reiniciarlo.
  • Usa el extremo /healthz existente (p.ej., https://analytics.example.com/healthz) en tus servidores de etiquetado para configurar las verificaciones de actividad. Una respuesta no saludable indica que se debe reiniciar el servidor.
  • 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 /healthz de forma periódica. Si dependes de la verificación de estado de Docker, puedes cambiar la configuración mediante las instrucciones de Docker.
  • Si el servidor de vista previa y el servidor de etiquetado se encuentran en el mismo origen, aloja el servidor de vista previa en una ruta de acceso diferente a la del servidor de etiquetado. Especifica el PREVIEW_SERVER_URL, incluida la ruta de acceso.
  • Los servidores aprovisionados deben tener como máximo 1 vCPU. Las vCPU adicionales no se usan y afectan negativamente el ajuste de escala automático.

Validación

Configura la URL del contenedor del servidor

En Tag Manager, navega a tu contenedor de 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 mediante el 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 verifica que se cargue la página de vista previa. En otra pestaña del navegador, navega a cualquier ruta de acceso en la URL del contenedor del servidor. Si la página de vista previa muestra la solicitud que se envió, significa que 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 de 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 para 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 obtener correcciones de seguridad y funciones nuevas. Te recomendamos que al menos actualices el servidor de etiquetado para cada lanzamiento de 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 el servidor con la misma configuración que la implementación anterior.
  3. Actualiza el único servidor de vista previa y todos los servidores de etiquetado del clúster.
  4. Apaga los servidores anteriores.

Para verificar que la actualización se haya realizado correctamente, sigue estos pasos:

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

Es posible que Tag Manager muestre mensajes en los que se te solicite que actualices tu servidor de etiquetas 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.