Guida alla configurazione manuale

Il flusso di provisioning automatico può essere utilizzato per eseguire il deployment del server di tagging in Cloud Run in pochi clic. Se vuoi eseguire il provisioning del server di tagging in altri ambienti, puoi farlo manualmente. Il server di tagging è un server Node.js all'interno di un'immagine Docker.

Il provisioning manuale del server di tagging richiede il provisioning separato del cluster di tagging lato server (SST) e di un server di anteprima. Il cluster SST è il punto di ingresso per tutte le richieste al server di tagging e gestirà le richieste come descritto in Introduzione al tagging lato server. Il server di anteprima è necessario per visualizzare l'anteprima di un contenitore.

Consulta la Figura 1 per un'illustrazione dell'interazione dei dati tra i server di tagging e il server di anteprima.

Figura 1: diagramma dei server di tagging e del flusso di dati del server di anteprima.

Questa guida spiega come:

• Visualizza tutte le impostazioni disponibili per l'immagine Docker.
• (Facoltativo) Includi le credenziali BigQuery
• Esegui manualmente il provisioning di un server di anteprima utilizzando l'immagine Docker SST.
• Esegui manualmente il provisioning di un cluster SST utilizzando l'immagine Docker SST.
• Verifica che il server di anteprima e il cluster SST siano configurati correttamente.
• Mantieni aggiornata la versione del server di tagging dopo aver eseguito il provisioning del server.

Per eseguire i comandi Docker in questa guida, devi prima installare Docker sul tuo computer.

Nota: quando configuri il server di tagging, il proprietario dell'ambiente server (sia un cloud provider sia on-premise) potrebbe avere accesso ai tuoi dati. Per maggiori dettagli, consulta i Termini di servizio dell'organizzazione.

Visualizza tutte le impostazioni disponibili per l'immagine Docker

L'immagine Docker del server di tagging è disponibile al seguente URL:

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

Il server di tagging e il server di anteprima utilizzano la stessa immagine Docker con flag diversi. In questa sezione illustreremo come cercare tutte le impostazioni disponibili che possono essere utilizzate con l'immagine Docker.

Per vedere tutte le impostazioni disponibili, esegui il comando seguente utilizzando lo strumento a riga di comando di Docker:

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

(Facoltativo) Includi le credenziali Google Cloud

Per utilizzare l'API BigQuery o Firestore al di fuori di Google Cloud, devi fornire una credenziale dell'account di servizio autorizzato ad accedere a queste risorse.

1. Segui questa guida per creare un account di servizio con il ruolo Editor dati BigQuery per l'accesso BigQuery o il ruolo Utente Cloud Datastore per l'accesso Firestore ed esportare le relative credenziali JSON con il nome filelocal_service_account_key.json.
2. Monta la credenziale JSON in un volume accessibile all'immagine. Utilizzando docker run, puoi specificare -v local_service_account_key.json:/app/service_account_key.json per montare le credenziali nell'immagine.
3. Indirizza la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS alla credenziale.
4. (Facoltativo) Specifica l'ID progetto Google Cloud nella variabile di ambiente GOOGLE_CLOUD_PROJECT per consentire al server di tagging di scegliere in modo implicito il progetto.

5. Esegui il server. Il seguente comando esegue il server di tagging con le credenziali incluse:

   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
   

A seconda del sistema in cui viene eseguito il deployment del server di tagging, potrebbero essere disponibili diversi modi per montare le credenziali. Ad esempio, Kubernetes e Docker Swarm forniscono guide per la gestione dei secret. Per ulteriori informazioni, consulta la guida del sistema corrispondente.

Assicurati di seguire le best practice per proteggere le tue credenziali.

Eseguire il provisioning manuale di un server di anteprima

Il server di anteprima consente di visualizzare l'anteprima del contenitore del server. Per eseguire il server di anteprima, esegui l'immagine Docker con le seguenti variabili di ambiente passate all'ambiente Docker.

Impostazioni obbligatorie

• CONTAINER_CONFIG: la stringa di configurazione del contenitore del server. In Tag Manager, accedi all'area di lavoro del contenitore del server e fai clic sull'ID contenitore in alto a destra della pagina. Fai clic su Esegui il provisioning manuale del server di tagging per trovare il valore Configurazione contenitore.

• RUN_AS_PREVIEW_SERVER: imposta questo valore su true per eseguire il provisioning del server come server di anteprima.

Esempio di utilizzo dello strumento a riga di comando Docker

Per eseguire il provisioning locale di un server di anteprima, esegui questo 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

Dovresti essere in grado di vedere una risposta di tipo 200 da una richiesta a http://localhost:8080/healthz. Facoltativamente, utilizza la variabile di ambiente PORT per modificare la porta.

Best practice

• Devi eseguire il deployment di un solo server di anteprima. Non configurare la scalabilità automatica oltre 1 istanza.
• Dopo aver configurato un server di anteprima utilizzando Docker, configura un URL HTTPS in modo che rimandi al server di anteprima. Questa operazione è necessaria per configurare il cluster SST.
• Il bilanciatore del carico o la rete CDN devono avere un timeout superiore a 20 secondi, altrimenti la modalità di anteprima non funzionerà correttamente.

Eseguire il provisioning manuale di un cluster di tagging lato server

Il cluster SST funge da punto di ingresso, trasmette le richieste di anteprima al server di anteprima e gestisce tutte le altre richieste come descritto in Introduzione al tagging lato server. Utilizza le seguenti impostazioni obbligatorie con l'immagine Docker del server di tagging per eseguire il provisioning di un cluster SST in qualsiasi ambiente che supporti Docker.

Impostazioni obbligatorie

• CONTAINER_CONFIG: la stringa di configurazione del contenitore del server. In Tag Manager, accedi all'area di lavoro del contenitore del server e fai clic sull'ID contenitore in alto a destra della pagina. Fai clic su Esegui il provisioning manuale del server di tagging per trovare il valore Configurazione contenitore.

• PREVIEW_SERVER_URL: l'URL HTTPS del server di anteprima. Questa impostazione deve essere configurata solo per il provisioning del server di tagging e non è necessaria per il provisioning del server di anteprima. Consulta la sezione precedente per una guida alla configurazione del server di anteprima.

Esempio di utilizzo dello strumento a riga di comando Docker

Per eseguire il provisioning di un singolo server di tagging localmente, esegui questo 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

Dovresti visualizzare una risposta di tipo 200 per una richiesta inviata a http://localhost:8080/healthz. Facoltativamente, utilizza la variabile di ambiente PORT per modificare la porta.

Best practice

• È possibile eseguire il provisioning dei server di tagging lato server come server singolo o come cluster. Ti consigliamo di eseguire il provisioning come cluster per migliorare la disponibilità, la scalabilità e le prestazioni. Tieni presente che quando esegui il provisioning come cluster, ogni istanza del server deve essere configurata con le stesse variabili di ambiente CONTAINER_CONFIG e PREVIEW_SERVER_URL.
• Assicurati di indirizzare il deployment del cluster SST a un nuovo sottodominio sul tuo sito web separato da quello che gestisce la tua applicazione. Ad esempio, se la tua applicazione gestisce il traffico web in example.com, utilizza un sottodominio come analytics.example.com per il server di tagging.
• Dopo aver configurato un cluster SST utilizzando Docker, configura un URL HTTPS in modo che punti al cluster SST.
• Assicurati di riavviare i server periodicamente per garantire che dispongano degli aggiornamenti del codice più recenti per SST. In caso contrario, le funzionalità delle nuove funzionalità SST potrebbero essere incompatibili. Un modo per sapere quando è necessario riavviare il server è configurare i controlli di attività, come spiegato più dettagliatamente di seguito. Inoltre, tieni presente che eventuali aggiornamenti pubblicati al contenitore del server verranno comunque applicati senza riavvio.
• Utilizza l'endpoint /healthz esistente (ad es. https://analytics.example.com/healthz) sui server di tagging per configurare i controlli di attività. Una risposta non integro indica che il server deve essere riavviato.
• Il container Docker include un comando di controllo di integrità predefinito, HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"], che esegue periodicamente query sull'endpoint /healthz. Se dipendi dal controllo di integrità di Docker, puoi modificare le impostazioni seguendo le istruzioni di Docker.
• Se il server di anteprima e il server di tagging si trovano sulla stessa origine, ospita il server di anteprima su un percorso diverso rispetto al server di tagging. Specifica l'elemento PREVIEW_SERVER_URL, incluso il percorso.
• I server di cui è stato eseguito il provisioning devono avere al massimo 1 vCPU. vCPU aggiuntive non vengono utilizzate e influiscono negativamente sulla scalabilità automatica.

Dati di

Configurare l'URL del contenitore del server

In Tag Manager, vai al contenitore del server. In Amministrazione > Impostazioni contenitore, inserisci l'URL del server di tagging nel campo URL contenitore del server e fai clic su Salva.

Verifica tramite la modalità di anteprima

Nell'area di lavoro di Tag Manager, visualizza l'anteprima del contenitore facendo clic su Anteprima e controlla che venga caricata la pagina di anteprima. In un'altra scheda del browser, vai a un percorso dell'URL del contenitore del server. Se la pagina di anteprima mostra la richiesta inviata, significa che è tutto configurato correttamente.

Se hai mappato più sottodomini a un singolo server di tagging e vuoi visualizzare l'anteprima su ogni sottodominio, aggiungi altri URL contenitore del server in Amministrazione > Impostazioni contenitore. Se vengono forniti più URL, tutti i percorsi degli URL devono corrispondere (la stringa di informazioni che segue il nome di dominio). Ad esempio, puoi visualizzare l'anteprima su example.com/abc e example2.com/abc, ma non su example.com/abc e example2.com/def. Se vengono aggiunti più URL, vedrai un'icona accanto al pulsante Anteprima che ti consente di selezionare l'URL di cui visualizzare l'anteprima.

Aggiorna la versione del server di tagging

Nota: se hai eseguito il provisioning dei server di tagging utilizzando la guida alla configurazione di Cloud Run o la guida alla configurazione di App Engine, segui le istruzioni riportate qui.

L'immagine gtm-cloud-image contiene Node.js e le librerie necessarie al funzionamento del server di tagging. L'immagine Docker viene aggiornata periodicamente per correzioni di sicurezza e nuove funzionalità. Ti consigliamo almeno di aggiornare il server di tagging per ogni release della versione principale (ad es. eseguire l'upgrade dalla versione 1.x.x alla versione 2.x.x).

Per aggiornare l'immagine Docker:

1. Recupera la versione attuale dell'immagine all'indirizzo gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
2. Esegui il deployment del server con le stesse impostazioni del deployment precedente.
3. Aggiorna il singolo server di anteprima e tutti i server di tagging nel cluster.
4. Arresta i server precedenti.

Per verificare che l'aggiornamento sia riuscito:

1. Nel contenitore del server, fai clic sul pulsante Anteprima per avviare una nuova sessione di debug e inviare una richiesta in una scheda separata.
2. In Riepilogo, seleziona la scheda Console e assicurati che non siano presenti messaggi che ti chiedono di aggiornare il server di tagging.

Tag Manager può mostrare messaggi in cui ti viene chiesto di aggiornare il server di tagging fino a un giorno dopo il corretto aggiornamento del server. Tuttavia, la pagina di anteprima mostrerà un messaggio aggiornato sulla versione del server di tagging.