Gestisci agenti di trasferimento

Gli agenti Storage Transfer Service sono applicazioni in esecuzione all'interno di un container Docker, che si coordinano con Storage Transfer Service per i trasferimenti relativi ai file system o compatibile con S3.

Se il trasferimento non prevede un file system o uno spazio di archiviazione compatibile con S3, non è necessario configurare gli agenti.

Questo documento descrive come amministrare gli agenti di trasferimento sui tuoi server.

Panoramica

  • I processi degli agenti sono dinamici. Mentre esegui un trasferimento, puoi aggiungere agli agenti per aumentare le prestazioni. Gli agenti appena avviati si uniscono al pool di agenti assegnato ed eseguono il lavoro dei trasferimenti esistenti. Puoi usarlo per regolare quanti agenti sono in esecuzione, o di adattare le prestazioni dei trasferimenti all'evoluzione della domanda di trasferimento.

  • I processi dell'agente sono un collettivo tollerante agli errori. Se l'esecuzione di un agente viene interrotta, mentre gli altri agenti continuano a lavorare. Se tutti gli agenti si arrestano, quando li riavvii il trasferimento riprende da dove si erano interrotti. In questo modo, eviterai di monitorare gli agenti, di riprovare i trasferimenti o di implementare la logica di recupero. Puoi applicare patch, spostare e scalare dinamicamente i pool di agenti senza tempi di riposo durante il trasferimento tramite coordinamento degli agenti con Google Kubernetes Engine.

    Ad esempio, invii due trasferimenti mentre sono in esecuzione due agenti. Se uno degli agenti si arresta a causa di un riavvio della macchina o di una patch del sistema operativo, l'agente rimanente continua a funzionare. I due trasferimenti sono ancora in esecuzione, ma sono più lenti perché un solo agente sposta i dati. Se anche l'agente rimanente si arresta, tutti i trasferimenti interrompono l'avanzamento, poiché non ci sono agenti in esecuzione. Quando riavvii i processi dell'agente, i trasferimenti riprendono da dove si erano interrotti.

  • I processi dell'agente appartengono a un pool. Trasferisci insieme i tuoi dati parallelo. Per questo motivo, tutti gli agenti all'interno di un pool devono avere lo stesso e l'accesso a tutte le origini dati che vuoi trasferire.

    Ad esempio, se trasferisci i dati da un determinato file system, devi montare il file system su ogni macchina che ospita agenti nel tuo pool di agenti. Se alcuni agenti del pool possono raggiungere un'origine dati e altri no, i trasferimenti da quell'origine dati non andranno a buon fine.

Prima di iniziare

Prima di configurare i trasferimenti, assicurati di aver configurato l'accesso: per utenti e account di servizio.

Se usi i comandi gcloud, installa gcloud CLI.

Installa ed esegui agenti di trasferimento

Consigliamo di installare un minimo di tre agenti per pool di agenti, idealmente su e macchine separate. Per ulteriori informazioni su come determinare il numero di agenti da eseguire, consulta Ottimizzare il rendimento dell'agente di trasferimento.

Non includere nel prefisso dell'ID agente informazioni sensibili come quelle che consentono l'identificazione personale (PII) o dati di sicurezza. I nomi delle risorse possono essere propagati ai nomi di altre risorse Google Cloud e possono essere esposti ai sistemi interni di Google al di fuori del progetto.

Per installare ed eseguire gli agenti di trasferimento:

Console Google Cloud

  1. Nella console Google Cloud, vai alla pagina Pool di agenti.

    Vai ai pool di agenti

  2. Seleziona il pool di agenti a cui aggiungere il nuovo agente.

  3. Fai clic su Installa agente.

  4. Segui le istruzioni per installare ed eseguire l'agente.

    Per ulteriori informazioni sulle opzioni a riga di comando dell'agente, consulta Opzioni a riga di comando dell'agente.

Interfaccia a riga di comando gcloud

Per installare uno o più agenti utilizzando gcloud CLI, esegui gcloud transfer agents install:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

Lo strumento ti guiderà attraverso tutti i passaggi necessari per installare gli agenti. Questo installa NUM_AGENTS agente sulla tua macchina, mappato a il nome del pool specificato come POOL_NAME e autentica il utilizzando le tue credenziali gcloud. Il nome del pool deve esistere oppure .

Il flag --mount-directories è facoltativo, ma vivamente consigliato. Il suo valore è un elenco separato da virgole di directory sul file system a cui concedere l'accesso all'agente. Se questo flag non viene specificato, l'intero file system viene montato nel contenitore dell'agente. Consulta: il Riferimento gcloud per ulteriori dettagli.

Origini compatibili con S3

Quando installi agenti da usare con un'origine compatibile con S3, devi fornire le credenziali AWS come variabili di ambiente valori di AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY o archiviati come credenziali predefinite nei file di configurazione del tuo sistema.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

Utilizzare una chiave dell'account di servizio

Per eseguire gli agenti utilizzando una chiave dell'account di servizio, utilizza l'opzione --creds-file:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

Scopri di più

Per un elenco completo dei flag facoltativi, esegui gcloud transfer agents install --help o leggi le Riferimento gcloud transfer.

docker run

Prima di utilizzare docker run per installare gli agenti, segui le istruzioni per installare Docker.

Il comando docker run installa un agente. Per aumentare il numero di agenti nel pool, esegui di nuovo questo comando tutte le volte necessarie.

Quando installi gli agenti, puoi scegliere di eseguire l'autenticazione utilizzando le tue gcloud credenziali predefinite o con un account di servizio.

Credenziali predefinite

Per consentire l'autenticazione di un container Docker mediante le credenziali predefinite di gcloud, crea un volume Docker contenente un file con le credenziali predefinite dell'applicazione eseguendo il seguente comando:

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

Quindi, utilizza il seguente comando per installare un agente, utilizzando il flag --volumes-from per montare il volume delle credenziali gcloud-config:

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Autenticazione dell'account di servizio

Per installare ed eseguire gli agenti di trasferimento docker run utilizzando le credenziali dell'account di servizio, specifica il percorso della chiave dell'account di servizio in formato JSON utilizzando il flag --creds-file.

Il percorso deve essere preceduto dal prefisso della stringa /transfer_root.

Per ulteriori informazioni sulle chiavi degli account di servizio, consulta Creare e gestire le chiavi degli account di servizio.

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opzioni e flag

Sostituisci le variabili degli esempi precedenti con le seguenti informazioni:

  • HOST_DIRECTORY è la directory sulla macchina host da cui intendi effettuare la copia. Puoi utilizzare più di un flag -v per specificare altre directory da cui eseguire la copia.
  • CONTAINER_DIRECTORY è la directory mappata all'interno il container dell'agente. Deve essere uguale a HOST_DIRECTORY.
  • PROJECT_ID è l'ID progetto che ospita il trasferimento.
  • POOL_NAME è il nome del pool di agenti in cui installare questo agente. Se ometti questo flag, l'agente viene installato del pool transfer_service_default del progetto.

Il comando docker run supporta flag aggiuntivi.

  • --enable-mount-directory monta l'intero file system sotto la /transfer_root sul container. Se --enable-mount-directory le restrizioni della directory che utilizzano il flag -v non vengono applicate.

  • --creds-file=CREDENTIAL_FILE specifica il percorso di un file delle credenziali dell'account di servizio in formato JSON. A meno che non utilizzi --enable_mount_directory, devi:

    1. Monta il file delle credenziali utilizzando il flag -v.
    2. Anteponi il prefisso /transfer_root al percorso che porta a --creds-file.

    Ad esempio:

    -v /tmp/key.json:/tmp/key.json \
--creds-file=/transfer_root/tmp/key.json

  • --enable-s3 specifica che questo agente è destinato ai trasferimenti da spazi di archiviazione compatibili con S3. Gli agenti installati con questa opzione non possono essere utilizzati per i trasferimenti da file system POSIX.

  • Se il trasferimento avviene da AWS S3 o da uno spazio di archiviazione compatibile con S3, passa l'ID chiave di accesso e la chiave segreta utilizzando le variabili di ambiente:

    -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY

  • --env HTTPS_PROXY=PROXY specifica un proxy di inoltro sulla tua rete. Il valore di PROXY è l'URL HTTP e la porta del server proxy. Assicurati di specificare l'URL HTTP e non un URL HTTPS per evitare il doppio wrapping delle richieste nella crittografia TLS. Le richieste con doppio wrapping impediscono al server proxy di inviare richieste in uscita valide.

  • --agent-id-prefix=ID_PREFIX specifica un prefisso facoltativo anteposto all'ID agente per consentire a identificare l'agente o la relativa macchina nella console Google Cloud. Quando viene utilizzato un prefisso, l'ID agente viene formattato come prefix + hostname + Docker container ID.

  • --log-dir=LOGS_DIRECTORY modifica la directory in cui l'agente scrive i log. La directory predefinita è /tmp/.

    Se non hai specificato --enable_mount_directory, devi premettere questo percorso con /transfer_root. Ad esempio, /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: il valore predefinito degli agenti è utilizzando al massimo 8 GiB di memoria di sistema. Se l'impostazione predefinita non si adatta al tuo ambiente, puoi specificare una memoria massima nei seguenti formati:

    max-physical-mem valore Impostazione della memoria massima
    6g 6 gigabyte
    6gb 6 gigabyte
    6GiB 6 gibibyte

Conferma le connessioni degli agenti

Per verificare che i tuoi agenti siano connessi:

  1. Nella console Google Cloud, vai alla pagina Pool di agenti.

    Vai a Pool di agenti

    Vengono visualizzati i pool di agenti con il numero di agenti connessi.

  2. Seleziona un pool di agenti per visualizzare i dettagli degli agenti connessi.

Se un nuovo agente non viene visualizzato nella pagina del pool di agenti entro 10 minuti dalla sua creazione, consulta Agenti non connessi.

Monitora l'attività dell'agente

Puoi utilizzare gli avvisi di Cloud Monitoring per monitorare l'attività degli agenti.

Il monitoraggio è disponibile per le dimensioni project, agent_pool e agent_id.

Utilizzando questi dati di monitoraggio, puoi configurare avvisi per ricevere notifiche di potenziali problemi con il trasferimento. A tale scopo, crea un avviso su una delle seguenti metriche di Google Cloud:

Nome metrica Che cosa descrive Utilizzi suggeriti
storagetransfer.googleapis.com/agent/transferred_bytes_count Misura la velocità con cui un agente specifico sposta i dati tra tutti i job che in un determinato momento. Avviso in caso di cali nelle prestazioni.
storagetransfer.googleapis.com/agent/connected Un valore booleano che è True per ogni agente che Google Cloud ha ricevuto un messaggio heartbeat recente da.
  • Avviso per gli agenti in stato di errore
  • Numero di agenti inferiore a quello che consideri necessario per un rendimento ragionevole
  • Segnalazione di un problema con le macchine degli agenti

Interrompere un agente

Per arrestare un agente, esegui docker stop sull'ID container Docker dell'agente. Per trovare l'ID e interrompi l'agente:

  1. Nella console Google Cloud, vai alla pagina Pool di agenti.

    Vai ai pool di agenti

  2. Seleziona il pool di agenti contenente l'agente da arrestare.

  3. Seleziona un agente dall'elenco. Utilizza il campo Filtra per cercare prefissi, stato dell'agente, età dell'agente e altro ancora.

  4. Fai clic su Interrompi agente. Il comando docker stop con il container specifico Viene visualizzato l'ID.

  5. Esegui il comando sulla macchina su cui è in esecuzione l'agente. Un comando docker stop riuscito restituisce l'ID contenitore.

Una volta arrestato, l'agente viene visualizzato nell'elenco dei pool di agenti come Disconnesso.

Elimina un agente

Per eliminare agenti specifici, elenca quelli in esecuzione sulla tua macchina:

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

Poi passa gli ID agente a transfer agents delete:

gcloud transfer agents delete --ids=id1,id2,…

Per eliminare tutti gli agenti in esecuzione sulla macchina, utilizza il flag --all o il flag --uninstall. Entrambi i flag eliminano tutti gli agenti sulla macchina. Il flag --uninstall disinstalla inoltre l'immagine Docker dell'agente.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

Dettagli sul trasferimento del file system

Trasferimenti incrementali

Storage Transfer Service avvia tutti i trasferimenti calcolando i dati presenti all'origine e la destinazione per determinare quali file di origine sono nuovi, aggiornati o eliminati dall'ultimo trasferimento. Lo scopo è ridurre la quantità di dati inviati le tue macchine, per utilizzare la larghezza di banda in modo efficace e per ridurre i tempi di trasferimento.

Per rilevare se un file è stato modificato, controlliamo la data e l'ora dell'ultima modifica e le dimensioni del file di origine e le confrontiamo con la data e l'ora dell'ultima modifica e le dimensioni registrate l'ultima volta che il file è stato copiato. Quando rileviamo un file nuovo o modificato, lo copiamo nella sua destinazione. Per ulteriori informazioni l'aggiornamento dei file, consulta Dettagli sulla coerenza dei dati.

Per impostazione predefinita, rileviamo i file eliminati nell'origine, ma non interveniamo. Se scelgo l'opzione di sincronizzazione Elimina i file di destinazione che non sono anche nell'origine durante la creazione o la modifica, il trasferimento eliminerà l'oggetto corrispondente nella destinazione.

Se scegli l'opzione di sincronizzazione Elimina i file di destinazione che non sono presenti anche origine, i file eliminati accidentalmente all'origine vengono eliminati anche la destinazione. Per evitare la perdita di dati a causa di eliminazioni accidentali, ti consigliamo di attivare il controllo delle versioni degli oggetti nel bucket di destinazione se scegli di utilizzare questa opzione. Quindi, se elimini un file per errore puoi ripristinare una versione precedente degli oggetti in Cloud Storage.

Dettagli sulla coerenza dei dati

Un'operazione di trasferimento riuscita trasferirà tutti i file di origine esistenti e non modificati durante l'intero tempo di esecuzione dell'operazione. File sorgente che sono stati creati, aggiornati o eliminati durante un trasferimento potrebbero o meno essere le modifiche riflesse nel set di dati di destinazione.

Storage Transfer Service utilizza la data e l'ora dell'ultima modifica e le dimensioni di un file per determinare se è stato modificato. Se un file viene aggiornato senza modificare la data o le dimensioni dell'ultima modifica e attivi l'opzione delete-objects-from-source, potresti perdere i dati a causa di questa modifica.

Quando utilizzi la funzionalità delete-objects-from-source, ti consigliamo vivamente di blocchi le scritture sull'origine per la durata del trasferimento, per proteggere dalla perdita di dati.

Per bloccare le scritture sull'origine, procedi in uno dei seguenti modi:

  • Clona la directory che intendi trasferire, quindi utilizza il file come origine del trasferimento.
  • Interrompi le applicazioni che scrivono nella directory di origine.

Se è importante acquisire le modifiche apportate durante un trasferimento, puoi eseguire nuovamente il trasferimento o impostare il file system di origine come di sola lettura durante l'esecuzione dell'operazione.

Poiché Cloud Storage non ha la nozione di directory, l'origine vuota vengono trasferite.