Руководство по ручной настройке

С помощью процедуры автоматической инициализации вы сможете развернуть сервер тегов на платформе Cloud Run всего за несколько кликов. Чтобы инициализировать сервер в другой среде, выполните его настройку вручную. Сервер тегов представляет собой сервер Node.js, который находится в образе Docker.

Чтобы выполнить настройку вручную, вам потребуется отдельно инициализировать кластер серверного добавления тегов и сервер предварительного просмотра. Кластер – это точка входа для всех запросов, отправляемых на сервер тегов. Он отвечает за их обработку. Ознакомьтесь со статьей Добавление тегов на стороне сервера. Для предварительного просмотра контейнера вам потребуется специальный сервер.

Серверы тегов активно взаимодействуют с сервером предварительного просмотра (см. рис. 1).

Рис 1. Схема обмена данными между серверами тегов и сервером предварительного просмотра

В этом руководстве рассматриваются следующие темы:

• Как посмотреть все доступные настройки для образа Docker.
• Как включить учетные данные BigQuery (необязательно).
• Как вручную инициализировать сервер предварительного просмотра с помощью образа Docker для серверного добавления тегов.
• Как вручную инициализировать кластер серверного добавления тегов с помощью образа Docker для серверного добавления тегов.
• Как проверить настройки сервера предварительного просмотра и кластера серверного добавления тегов.
• Как обеспечить регулярное обновление сервера тегов после его инициализации.

Чтобы запускать команды, установите программное обеспечение Docker на компьютер.

Примечание. Во время настройки сервера тегов доступ к вашим данным может получить владелец серверной среды (поставщик облачных или локальных услуг). Дополнительную информацию вы найдете в Условиях использования организации.

Как посмотреть все доступные настройки для образа Docker

Воспользуйтесь следующим URL для доступа к образу Docker:

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

Для сервера тегов и сервера предварительного просмотра используется один образ Docker, но с разными настройками. В этом разделе содержится обзор всех доступных настроек, которые вы можете использовать с образом Docker.

Чтобы посмотреть их, в командной строке Docker введите следующий текст:

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

Как включить учетные данные Google Cloud (необязательно).

Чтобы использовать BigQuery или Firestore API за пределами Google Cloud, необходимо предоставить учетные данные сервисного аккаунта, у которого есть разрешение на доступ к этим ресурсам.

1. Выполните приведенные в этом руководстве инструкции – создайте сервисный аккаунт с ролью BigQuery Data Editor (Редактор BigQuery) для доступа к BigQuery или Cloud Datastore User (пользователь Cloud Datastore) для доступа к Firestore и экспортируйте учетные данные в виде файла JSON с именем local_service_account_key.json.
2. Подключите файл учетных данных JSON в томе, который доступен для образа. Задать -v local_service_account_key.json:/app/service_account_key.json можно с помощью docker run.
3. Назначьте для учетных данных переменную среды GOOGLE_APPLICATION_CREDENTIALS.
4. Вы также можете указать идентификатор проекта Google Cloud для переменной среды GOOGLE_CLOUD_PROJECT, чтобы сервер тегов выбирал конкретный проект.

5. Запустите сервер. Будет выполнена следующая команда с добавленными учетными данными:

   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
   

Существует несколько способов подключения учетных данных в зависимости от типа системы, в которой развернут сервер тегов. Например, системы Kubernetes и Docker Swarm используют алгоритмы управления секретами. Более подробную информацию можно найти в руководствах по этим системам.

Следуйте рекомендациям, чтобы защитить свои учетные данные.

Как вручную инициализировать сервер предварительного просмотра

Сервер предварительного просмотра позволяет просматривать серверный контейнер. Чтобы инициировать этот сервер, запустите образ Docker с приведенными ниже переменными среды.

Обязательные настройки

• CONTAINER_CONFIG – строка конфигурации для серверного контейнера. В Менеджере тегов откройте рабочую область контейнера тегов. Нажмите на идентификатор контейнера в правом верхнем углу страницы. Выберите Добавить сервер тегов вручную, чтобы получить значение Настройка контейнера.

• RUN_AS_PREVIEW_SERVER – установите для этой настройки значение true, чтобы инициализировать сервер предварительного просмотра.

Пример использования инструмента командной строки Docker

Чтобы инициализировать локальный сервер предварительного просмотра, запустите следующую команду:

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

Вы должны получать код статуса 200 в ответе на запрос http://localhost:8080/healthz. При необходимости воспользуйтесь переменной среды PORT, чтобы изменить порт.

Рекомендации

• Вам нужно развернуть только один сервер предварительного просмотра. Не настраивайте автомасштабирование для нескольких экземпляров.
• После того как вы настроите сервер предварительного просмотра с помощью Docker, сконфигурируйте URL-адрес HTTPS. Он должен указывать на этот сервер. Этот адрес потребуется для настройки кластера серверного добавления тегов.
• Время ожидания балансировщика нагрузки или CDN должно составлять более 20 секунд. В противном случае режим предварительного просмотра будет работать некорректно.

Как вручную инициализировать кластер серверного добавления тегов

Кластер выполняет роль точки входа для всех прокси-запросов, отправляемых на сервер предварительного просмотра. Он отвечает за их обработку. Подробная информация приведена в статье о добавлении тегов на стороне сервера. Вы можете инициализировать кластер серверного добавления тегов в любой среде, поддерживающей Docker. Чтобы это сделать, при запуске образа Docker для сервера тегов используйте обязательные настройки. Они приведены ниже.

Обязательные настройки

• CONTAINER_CONFIG – строка конфигурации для серверного контейнера. В Менеджере тегов откройте рабочую область контейнера тегов. Нажмите на идентификатор контейнера в правом верхнем углу страницы. Выберите Добавить сервер тегов вручную, чтобы получить значение Настройка контейнера.

• PREVIEW_SERVER_URL – URL-адрес HTTPS сервера предварительного просмотра. Эта настройка требуется только при инициализации сервера тегов. Не используйте ее для сервера предварительного просмотра. Инструкции по настройке сервера предварительного просмотра приведены в этом разделе.

Пример использования инструмента командной строки Docker

Чтобы инициализировать отдельный локальный сервер тегов, выполните следующую команду:

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

Вы должны получать код статуса 200 в ответе на запрос http://localhost:8080/healthz. При необходимости воспользуйтесь переменной среды PORT, чтобы изменить порт.

Рекомендации

• Серверы добавления тегов можно инициализировать в качестве отдельного сервера или кластера. Мы рекомендуем использовать кластер. Такое решение поможет вам увеличить доступность, масштабируемость и эффективность. Если вы выбрали кластер, убедитесь, что для каждого сервера используются одинаковые переменные среды CONTAINER_CONFIG и PREVIEW_SERVER_URL.
• Для кластера серверного добавления тегов и для приложения должны использоваться разные субдомены на вашем сайте. Например, если сетевой трафик из приложения поступает в домен example.com, то для сервера тегов следует использовать отдельный субдомен, такой как analytics.example.com.
• После того, как вы настроите кластер серверного добавления тегов с помощью Docker, сконфигурируйте URL-адрес HTTPS. Он должен указывать на этот кластер.
• Периодически перезапускайте серверы, чтобы обновлять код. Если вы не будете этого делать, ваша система не сможет использовать новые функции серверного добавления тегов. Вы можете настроить проверку работоспособности, чтобы узнавать, когда нужно перезапускать сервер. Эта процедура описана ниже. Обратите внимание, что все опубликованные изменения в серверном контейнере будут применяться без перезапуска.
• Чтобы настроить проверку работоспособности сервера, воспользуйтесь существующей конечной точкой /healthz (например, https://analytics.example.com/healthz) на сервере тегов. Следите за состоянием системы, чтобы узнать, когда нужно перезапустить сервер.
• Контейнер Docker содержит команду по умолчанию для проверки состояния: HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]. Она периодически запрашивает конечную точку /healthz. Если вы используете проверку состояния, реализованную в Docker, то можете изменить настройки, следуя этим инструкциям.
• Если у сервера предварительного просмотра и сервера тегов один и тот же источник, используйте для них разные пути. Укажите PREVIEW_SERVER_URL, включая путь.
• На инициализированном сервере должен быть только один ВЦП. Дополнительные ВЦП не будут использоваться и отрицательно скажутся на автомасштабировании.

Проверка

Настройка URL серверного контейнера

В Менеджере тегов перейдите к серверному контейнеру. Откройте раздел Администрирование > Настройки контейнера и укажите URL сервера тегов в поле URL серверного контейнера. Нажмите Сохранить.

Проверка с помощью режима предварительного просмотра

Откройте рабочую область Менеджера тегов, выберите Предварительный просмотр и убедитесь, что страница загружается. Откройте новую вкладку браузера и перейдите на любую страницу (в рамках URL серверного контейнера). Если на странице предварительного просмотра отображается отправленный запрос, настройка выполнена правильно.

Если вы сопоставили с одним сервером тегов несколько субдоменов и хотите посмотреть каждый из них, укажите дополнительные URL серверного контейнера в разделе Администрирование > Настройки контейнера. Пути всех указанных URL (фрагменты после доменного имени) должны совпадать. Например, вы можете посмотреть example.com/abc и example2.com/abc, но не example.com/abc и example2.com/def. Если добавлено несколько URL, то вы увидите значок для их выбора рядом с кнопкой Предварительный просмотр.

Обновление версии сервера тегов

Примечание. Если вы добавили серверы тегов, следуя Руководству по настройке Cloud Run или Руководству по настройке App Engine, воспользуйтесь указанными там инструкциями.

Образ gtm-cloud-image содержит Node.js и библиотеки, необходимые для работы сервера тегов. Мы периодически обновляем образ Docker, исправляя уязвимости безопасности и добавляя новые функции. Рекомендуем обновлять сервер тегов не реже, чем выходят основные версии (например, при переходе с версии 1.x.x на 2.x.x).

Чтобы обновить образ Docker, выполните следующие действия:

1. Получите текущую версию образа на странице gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
2. Разверните сервер с прежними настройками.
3. Обновите отдельный сервер предварительного просмотра и все серверы тегов в кластере.
4. Отключите старые серверы.

Чтобы убедиться, что обновление прошло успешно, выполните следующие действия:

1. В серверном контейнере нажмите кнопку Предварительный просмотр, чтобы начать новый сеанс отладки, и отправьте запрос на отдельной вкладке.
2. В разделе "Сводка" выберите вкладку Консоль и проверьте, нет ли сообщений о том, что нужно обновить сервер тегов.

В течение дня после успешного обновления сервера тегов вы можете по-прежнему видеть сообщения с просьбой обновить его. Однако на странице предварительного просмотра будет актуальная информация о версии сервера тегов.