Guida alla configurazione manuale

Il flusso di provisioning automatico può essere utilizzato per eseguire il deployment del server di tagging su 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 accesso 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.

Diagramma del flusso di dati dei server di tagging e di anteprima

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

Questa guida spiega come:

  • Visualizza tutte le impostazioni disponibili per l'immagine Docker.
  • (Facoltativo) Includi le credenziali BigQuery
  • Esegui il provisioning manuale 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 il provisioning del server.

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

Visualizza tutte le impostazioni disponibili per l'immagine Docker

L'immagine Docker del server di tagging è disponibile a questo 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 viene descritto come cercare tutte le impostazioni disponibili che possono essere utilizzate con l'immagine Docker.

Per visualizzare tutte le impostazioni disponibili, esegui quanto segue utilizzando lo strumento a riga di comando docker:

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

(Facoltativo) Includi le credenziali di Google Cloud

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

  1. Segui questa guida per creare un account di servizio con il ruolo Editor di dati BigQuery per l'accesso BigQuery o il ruolo Utente Cloud Datastore per l'accesso Firestore ed esporta le relative credenziali JSON con il nome file local_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. Fai in modo che la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS indichi la credenziale.
  4. Se vuoi, specifica l'ID progetto Google Cloud nella variabile di ambiente GOOGLE_CLOUD_PROJECT per consentire al server di tagging di scegliere implicitamente 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 su cui è implementato il 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 in uso.

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

Esegui manualmente il provisioning di un server di anteprima

Il server di anteprima consente di visualizzare in anteprima il 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 per il contenitore del server. In Tag Manager, vai all'area di lavoro del contenitore del server e fai clic sull'ID contenitore in alto a destra nella 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 di un server di anteprima in locale, esegui quanto segue:

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 visualizzare una risposta 200 da una richiesta a http://localhost:8080/healthz. Se vuoi, utilizza la variabile di ambiente PORT per modificare la porta.

Best practice

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

Esegui manualmente il provisioning di un cluster di tagging lato server

Il cluster SST funge da punto di ingresso, esegue il proxy delle 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 per il contenitore del server. In Tag Manager, vai all'area di lavoro del contenitore del server e fai clic sull'ID contenitore in alto a destra nella 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 impostata 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 quanto segue:

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 200 di una richiesta a http://localhost:8080/healthz. Se vuoi, utilizza la variabile di ambiente PORT per modificare la porta.

Best practice

  • È possibile eseguire il provisioning dei server di tagging lato server come singolo server o come cluster. Ti consigliamo di eseguirne il provisioning come cluster per una maggiore disponibilità, scalabilità e 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 ospitare il server di tagging nella stessa origine (best practice) o come sottodominio del tuo sito web attuale. Ad esempio, se la tua applicazione invia traffico web all'indirizzo example.com, utilizza un percorso come example.com/analytics per il server di tagging. Scopri di più sulla configurazione dei domini personalizzati.
  • Dopo aver configurato un cluster SST utilizzando Docker, configura un URL HTTPS che rimandi al cluster SST.
  • Assicurati di riavviare periodicamente i server per assicurarti che siano installati gli aggiornamenti di codice più recenti per SST. In caso contrario, le nuove funzionalità SST potrebbero essere incompatibili. Un modo per sapere quando è necessario riavviare il server è configurare i controlli di attività, descritti più avanti. Tieni inoltre presente che eventuali aggiornamenti pubblicati al contenitore del server verranno comunque applicati senza un riavvio.
  • Utilizza l'endpoint /healthz esistente (ad es. https://analytics.example.com/healthz) sui server di tagging per configurare i controlli di attivazione. Una risposta non integro indica che il server deve essere riavviato.
  • Il contenitore Docker include un comando di controllo di integrità predefinito (HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]) che esegue query periodicamente sull'endpoint /healthz. Se utilizzi il controllo dell'integrità di Docker, puoi modificare le impostazioni seguendo le istruzioni di Docker.
  • Se il server di anteprima e il server di tagging si trovano nella stessa origine, ospita il server di anteprima su un percorso diverso rispetto al server di tagging. Specifica il PREVIEW_SERVER_URL incluso il percorso.
  • I server di cui è stato eseguito il provisioning devono avere al massimo 1 vCPU. Le vCPU aggiuntive non vengono utilizzate e influiscono negativamente sulla scalabilità automatica.

Convalida

Configura 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.

Verificare tramite la modalità di anteprima

Nell'area di lavoro di Tag Manager, visualizza l'anteprima del contenitore facendo clic su Anteprima e verifica che la pagina di anteprima venga caricata. 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 del 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 puoi visualizzare l'anteprima su example.com/abc e example2.com/def. Se vengono aggiunti più URL, accanto al pulsante Anteprima viene visualizzata un'icona che ti consente di selezionare l'URL di cui visualizzare l'anteprima.

Aggiornare la versione del server di tagging

L'immagine gtm-cloud-image contiene Node.js e le librerie necessarie per il funzionamento del server di tagging. L'immagine Docker viene aggiornata periodicamente per correzioni di sicurezza e nuove funzionalità. Ti consigliamo di aggiornare almeno il server di tagging per ogni release della versione principale (ad es. l'upgrade dalla versione 1.x.x alla 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 tuo 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 vecchi server.

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 su una scheda separata.
  2. In Riepilogo, seleziona la scheda Console e assicurati che non ci siano messaggi che ti chiedono di aggiornare il server di tagging.

Tag Manager potrebbe mostrare messaggi che ti chiedono di aggiornare il server di tagging per un massimo di un giorno dopo l'aggiornamento del server. Tuttavia, la pagina di anteprima mostrerà un messaggio aggiornato sulla versione del server di tagging.