Guia de configuração manual

O fluxo de provisionamento automático pode ser usado para implantar o servidor de tags no Cloud Run com apenas alguns cliques. Você pode provisionar manualmente o servidor em outros ambientes, caso queira. O servidor de tags é do tipo Node.js dentro de uma imagem do Docker.

O provisionamento manual do servidor exige o provisionamento do cluster de inclusão de tags no servidor (SST, na sigla em inglês) e um servidor de visualização separadamente. O cluster SST é o ponto de entrada de todas as solicitações ao servidor de tags e faz o processamento delas, como descrito em Introdução à inclusão de tags no servidor. Esse servidor é necessário para visualizar um contêiner.

Veja na figura 1 uma ilustração da interação de dados entre os servidores de tags e de visualização.

Diagrama do fluxo de dados entre os servidores de tags e de visualização

Figura 1: um diagrama do fluxo de dados entre os servidores de tags e de visualização.

Neste guia, você vai aprender a:

Conferir todas as configurações disponíveis para a imagem do Docker.
(Opcional) Incluir credenciais do BigQuery
Provisionar manualmente um servidor de visualização usando a imagem do SST Docker
Provisionar manualmente um cluster SST usando a imagem do SST Docker.
Verificar se o servidor de visualização e o cluster SST estão configurados da forma certa
Manter a versão do servidor de tags atualizada após o provisionamento do servidor

Para executar os comandos do Docker neste guia, instale primeiro o Docker no seu computador (link em inglês).

Conferir todas as configurações disponíveis para a imagem do Docker

A imagem do Docker do servidor de tags pode ser encontrada neste URL:

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

Os servidores de tags e de visualização usam a mesma imagem do Docker com sinalizações diferentes. Nesta seção, mostraremos como procurar todas as configurações disponíveis que podem ser usadas com a imagem do Docker.

Para acessar todas as configurações disponíveis, execute o código a seguir usando a ferramenta de linha de comando do Docker (link em inglês):

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

(Opcional) Incluir credenciais do Google Cloud

Para usar a API BigQuery ou Firestore fora do Google Cloud, informe uma credencial de conta de serviço autorizada a acessar esses recursos.

Siga este guia para criar uma conta de serviço com o papel Editor de dados do BigQuery e acesso ao BigQuery ou com o papel Usuário do Cloud Datastore e acesso ao Firestore. Além disso, exporte as credenciais JSON com o nome de arquivo local_service_account_key.json.
Ative a credencial JSON em um volume acessível para a imagem. Com docker run, é possível especificar -v local_service_account_key.json:/app/service_account_key.json para ativar as credenciais na imagem.
Direcione a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS à credencial.
Se quiser, especifique o ID do projeto do Google Cloud na variável de ambiente GOOGLE_CLOUD_PROJECT para permitir que o servidor de tags escolha o projeto de forma implícita.

Execute o servidor. O comando a seguir executa o servidor de tags com as credenciais incluídas:

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

Dependendo do sistema em que o servidor de tags foi implantado, há diferentes maneiras de ativar as credenciais. Por exemplo, o Kubernetes e o Docker Swarm (links em inglês) oferecem guias para gerenciar secrets. Consulte o guia de cada sistema para mais informações.

Siga as práticas recomendadas para proteger suas credenciais.

Provisionar manualmente um servidor de visualização

Com o servidor de visualização, você pode analisar o contêiner do servidor. Para executar o servidor de visualização, execute a imagem do Docker com as seguintes variáveis de ambiente transmitidas ao ambiente do Docker.

Configurações obrigatórias

CONTAINER_CONFIG: a string de configuração do contêiner do servidor. No Gerenciador de tags, vá até o espaço de trabalho no contêiner do servidor e clique no ID do contêiner, no canto superior direito da página. Clique em Provisionar manualmente o servidor de tags para encontrar o valor Configuração do contêiner.
RUN_AS_PREVIEW_SERVER: defina como true para provisionar o servidor como "de visualização".

Exemplo de uso: ferramenta de linha de comando do Docker

Para provisionar um servidor de visualização no local, execute o comando a seguir:

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

Você verá uma resposta 200 de uma solicitação para http://localhost:8080/healthz. Também é possível usar a variável de ambiente PORT para mudar a porta.

Práticas recomendadas

Você precisa implantar exatamente um servidor de visualização. Não configure o escalonamento automático além de uma instância.
Depois de configurar um servidor de visualização usando o Docker, defina um URL HTTPS para direcionar a esse servidor. Isso é necessário para configurar o cluster SST.
Seu balanceador de carga ou CDN deve ter um tempo limite maior que 20 segundos; do contrário, o modo de visualização não funciona corretamente.

Provisionar manualmente um cluster de inclusão de tags no servidor

O cluster SST funciona como ponto de entrada, encaminha solicitações de visualização para o servidor e processa todas as outras solicitações como descrito em Introdução à inclusão de tags no servidor. Use as configurações obrigatórias a seguir com a imagem do Docker do servidor de tags para provisionar um cluster SST em qualquer ambiente compatível com o Docker.

Configurações obrigatórias

CONTAINER_CONFIG: a string de configuração do contêiner do servidor. No Gerenciador de tags, vá até o espaço de trabalho no contêiner do servidor e clique no ID do contêiner, no canto superior direito da página. Clique em Provisionar manualmente o servidor de tags para encontrar o valor Configuração do contêiner.
PREVIEW_SERVER_URL: é o URL HTTPS do servidor de visualização. Essa configuração precisa ser definida apenas para provisionar o servidor de tags e não é necessária para provisionar o servidor de visualização. Consulte a seção acima para ver o guia sobre como configurar o servidor de visualização.

Exemplo de uso: ferramenta de linha de comando do Docker

Para provisionar um único servidor de tags no local, execute o seguinte:

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

Você vai notar uma resposta 200 de uma solicitação para http://localhost:8080/healthz. Também é possível usar a variável de ambiente PORT para alterar a porta.

Práticas recomendadas

Os servidores de inclusão de tags podem ser provisionados como um único servidor ou como um cluster. Recomendamos que você o provisione como um cluster para melhorar a disponibilidade, a escalonabilidade e o desempenho. Para provisionar como cluster, cada instância de servidor precisa ser configurada com as mesmas variáveis de ambiente CONTAINER_CONFIG e PREVIEW_SERVER_URL.
Direcione a implantação do cluster SST a um novo subdomínio no seu site, diferente do subdomínio que atende ao aplicativo. Por exemplo, se o app veicula tráfego da Web em example.com, utilize um subdomínio como analytics.example.com para o servidor de tags.
Após configurar um cluster SST usando o Docker, configure um URL HTTPS para direcionar ao cluster SST.
Reinicie os servidores periodicamente para garantir que tenham as atualizações de código mais recentes para a SST. Se isso não for feito, a funcionalidade poderá ficar incompatível com os novos recursos do SST. Uma maneira de saber quando o servidor precisa ser reiniciado é configurar verificações de atividade, o que é explicado depois. Além disso, as atualizações publicadas no contêiner do servidor ainda serão implementadas sem uma reinicialização.
Use o endpoint /healthz atual (por exemplo, https://analytics.example.com/healthz) nos seus servidores de tags para configurar as verificações de atividade. Uma resposta não íntegra indica que o servidor precisa ser reiniciado.
O contêiner do Docker inclui um comando padrão de verificação de integridade (HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]), que consulta o endpoint /healthz periodicamente. Se você usa a verificação de integridade do Docker, é possível mudar as configurações seguindo as instruções do Docker (link em inglês).
Se o servidor de visualização e o de tags estiverem na mesma origem, hospede o primeiro em um caminho diferente do segundo. Especifique o PREVIEW_SERVER_URL, incluindo o caminho.
Os servidores provisionados só podem ter uma vCPU. As vCPUs extras não são usadas e afetam negativamente o escalonamento automático.

Validação

Configurar o URL do contêiner do servidor

No Gerenciador de tags, acesse o contêiner do servidor. Em Administrador > Configurações do contêiner, insira o URL do servidor de tags no campo URL do contêiner do servidor e clique em Salvar.

Verificar usando o modo de visualização

No espaço de trabalho do Gerenciador de tags, clique em Visualizar para acessar o contêiner e confirmar que a página é carregada. Em outra guia do navegador, navegue até qualquer caminho no URL do contêiner do servidor. Se a página de visualização mostrar que a solicitação foi enviada, tudo está configurado corretamente.

Se você tiver mapeado vários subdomínios para um único servidor de tags e quiser fazer a visualização em cada subdomínio, adicione outros URLs do contêiner do servidor em Administrador > Configurações do contêiner. Se vários URLs forem informados, todos os caminhos de URL terão que ser relacionados à string de informações que vem depois do nome de domínio. Por exemplo, é possível visualizar em example.com/abc e example2.com/abc, mas não em example.com/abc e example2.com/def. Se vários URLs tiverem sido adicionados, você vai notar um ícone ao lado do botão Visualizar que permite selecionar o URL a ser mostrado.

Atualizar a versão do servidor de tags

A imagem gtm-cloud-image contém Node.js e as bibliotecas necessárias para o funcionamento do servidor de tags. A imagem do Docker é atualizada periodicamente de acordo com correções de segurança e novos recursos. Recomendamos atualizar seu servidor de tags para cada versão principal (por exemplo, da versão 1.xx para a 2.xx).

Para atualizar a imagem Docker:

Acesse a versão atual da imagem em gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
Implante seu servidor com as mesmas configurações da implantação anterior.
Atualize o único servidor de visualização e todos os servidores de tags no cluster.
Desative os servidores antigos.

Para verificar se a atualização foi concluída:

No contêiner do servidor, clique no botão Prévia para iniciar uma nova sessão de depuração e envie uma solicitação em uma guia separada.
Em Resumo, selecione a guia Console e verifique se não há mensagens solicitando a atualização do servidor de tags.

O Gerenciador de tags pode mostrar mensagens solicitando a atualização do servidor de tags até um dia depois de já ter sido feita. No entanto, a página de prévia mostra uma mensagem atualizada sobre a versão do servidor de tags.