Gestisci agenti di trasferimento

Gli agenti di Storage Transfer Service sono applicazioni in esecuzione all'interno di un container Docker, che si coordinano con Storage Transfer Service per leggere i dati dalle origini del file system POSIX e/o scrivere dati nei sink del file system POSIX.

Se il trasferimento non riguarda un file system POSIX, non è necessario configurare gli agenti.

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

Panoramica

  • I processi dell'agente sono dinamici. Durante l'esecuzione di un trasferimento, puoi aggiungere agenti per aumentare le prestazioni. Gli agenti appena avviati si uniscono al pool di agenti assegnato ed eseguono il lavoro dai trasferimenti esistenti. che ti consente di regolare il numero di agenti in esecuzione o di adattare le prestazioni di trasferimento in base alla variazione della domanda di trasferimento.

  • I processi dell'agente sono un insieme a tolleranza di errore. Se un agente smette di funzionare, gli agenti rimanenti continueranno a funzionare. Se tutti gli agenti si interrompono, al riavvio vengono ripristinati il punto in cui gli agenti si sono arrestati. In questo modo puoi evitare di monitorare gli agenti, riprovare i trasferimenti o implementare la logica di recupero. Puoi applicare patch, spostare e scalare in modo dinamico i tuoi pool di agenti senza tempi di inattività dei trasferimenti coordinando gli agenti con Google Kubernetes Engine.

    Ad esempio, invii due trasferimenti mentre sono in esecuzione due agenti. Se uno degli agenti si interrompe 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 più lenti perché un singolo agente trasferisce i dati. Se anche l'agente rimanente si interrompe, tutti i trasferimenti interrompono l'avanzamento, dato che non ci sono agenti in esecuzione. Quando riavvii i processi dell'agente, i trasferimenti riprendono dal punto in cui erano stati interrotti.

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

    Ad esempio, se stai trasferendo dati da un particolare file system, devi montare il file system su ogni macchina che ospita agenti nel tuo pool di agenti. Se alcuni agenti nel pool possono raggiungere un'origine dati e altri no, i trasferimenti da quella 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 utilizzerai i comandi gcloud, installa l'interfaccia a riga di comando gcloud.

Installa ed esegui gli agenti di trasferimento

Ti consigliamo di installare almeno tre agenti per pool di agenti, possibilmente su macchine separate. Per ulteriori informazioni su come determinare quanti agenti eseguire, consulta Massimizzare le prestazioni dell'agente di trasferimento.

Per installare ed eseguire gli agenti di trasferimento:

console Google Cloud

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

    Vai a 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 della riga di comando dell'agente, consulta Opzioni della 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 illustra i passaggi necessari per l'installazione degli agenti. Questo comando installa NUM_AGENTS agente/i sulla tua macchina, mappato al nome del pool specificato come POOL_NAME e autentica l'agente utilizzando le tue credenziali gcloud. Il nome del pool deve esistere o viene restituito un errore.

Il flag --mount-directories è facoltativo, ma è vivamente consigliato. Il valore è un elenco di directory separate da virgole sul file system a cui concedere l'accesso all'agente. Se questo flag viene omesso, l'intero file system viene montato nel container dell'agente. Per ulteriori dettagli, consulta il riferimento gcloud.

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

Per un elenco completo dei flag facoltativi, esegui gcloud transfer agents install --help o leggi il 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 nuovamente questo comando tutte le volte necessarie.

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

Credenziali predefinite

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

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

Utilizza quindi 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 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 dalla 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 negli esempi precedenti con le seguenti informazioni:

  • HOST_DIRECTORY è la directory sulla macchina host da cui intendi copiare. Puoi utilizzare più di un flag -v per specificare directory aggiuntive da cui copiare.
  • CONTAINER_DIRECTORY è la directory mappata all'interno del 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 nel pool transfer_service_default del tuo progetto.

Il comando docker run supporta ulteriori flag.

  • --enable-mount-directory monta l'intero file system nella directory /transfer_root sul container. Se --enable-mount-directory è specificato, le limitazioni della directory che utilizzano il flag -v non vengono applicate.

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

  • --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. e il percorso --creds-file verso /transfer_root.

    Ad esempio:

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

  • Se il trasferimento proviene da uno spazio di archiviazione compatibile con AWS S3 o S3, trasmetti il tuo 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 che viene anteposto all'ID agente per aiutare a identificare l'agente o la sua macchina nella console Google Cloud. Quando viene utilizzato un prefisso, l'ID agente ha il formato 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 specificare questo percorso per /transfer_root. Ad esempio: /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: agenti predefiniti che utilizzano 8 GiB massimo di memoria di sistema. Se l'impostazione predefinita non si adatta al tuo ambiente, puoi specificare un utilizzo massimo della memoria pertinente nei seguenti formati:

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

Conferma le connessioni dell'agente

Dopo aver installato gli agenti di trasferimento, puoi verificare che siano connessi al pool di agenti.

Per verificare che gli 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 sugli agenti connessi.

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

Monitora l'attività dell'agente

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

Il monitoraggio è disponibile nelle dimensioni project, agent_pool e agent_id.

Puoi utilizzare questi dati di monitoraggio per configurare avvisi per segnalare potenziali problemi relativi al trasferimento. Per farlo, crea un avviso su una delle seguenti metriche di Google Cloud:

Nome metrica Descrizione 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 opera in un determinato momento. Avvisa per cali di rendimento.
storagetransfer.googleapis.com/agent/connected Un valore booleano True per ogni agente da cui Google Cloud ha ricevuto un messaggio heartbeat recente.
  • Avviso per agenti in errore
  • Mancato numero di agenti che ritieni necessari per prestazioni ragionevoli
  • Segnala un problema con le macchine degli agenti

Arresta un agente

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

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

    Vai a Pool di agenti

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

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

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

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

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 macchina:

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

Quindi 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 --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 trasferimento file system

Trasferimenti incrementali

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

Per rilevare se un file è stato modificato, utilizziamo un algoritmo simile a gsutil rsync: controlliamo l'ora e le dimensioni dell'ultima modifica del file di origine e le confrontiamo con l'ora e le dimensioni dell'ultima modifica registrate quando il file è stato copiato l'ultima volta. Quando rileviamo un file nuovo o modificato, lo copiamo nella sua destinazione. Per ulteriori informazioni sull'aggiornamento dei file, consulta i dettagli sulla coerenza dei dati.

Per impostazione predefinita, rileviamo i file eliminati dall'origine, ma non interveniamo. Se scegli l'opzione di sincronizzazione Elimina i file di destinazione che non sono presenti 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 nell'origine, vengono eliminati anche i file che sono stati eliminati all'origine. Per evitare la perdita di dati da eliminazioni accidentali, ti consigliamo di abilitare 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 gli oggetti in Cloud Storage a una versione precedente.

Dettagli sulla coerenza dei dati

Un'operazione di trasferimento riuscita trasferisce tutti i file di origine esistenti e non modificati durante l'intera durata dell'operazione. I file di origine che sono stati creati, aggiornati o eliminati durante un trasferimento potrebbero o meno avere queste modifiche nel set di dati di destinazione.

Storage Transfer Service utilizza l'ora e la dimensione dell'ultima modifica di un file per determinare se è stata modificata. Se un file viene aggiornato senza modificarne la data/l'ora dell'ultima modifica o le dimensioni e attivi l'opzione delete-objects-from-source, potresti perdere i dati relativi alla modifica.

Quando usi la funzionalità delete-objects-from-source, ti consigliamo vivamente di bloccare le scritture all'origine per la durata del trasferimento, in modo da evitare la perdita di dati.

Per bloccare le scritture sulla tua origine, procedi in uno dei seguenti modi:

  • Clonare la directory che intendi trasferire, quindi utilizzare la directory clonata come origine di trasferimento.
  • Interrompi le applicazioni che scrivono nella directory di origine.

Se è importante acquisire le modifiche avvenute durante un trasferimento, puoi ripetere il trasferimento o impostare il file system di origine come di sola lettura mentre l'operazione è in esecuzione.

Poiché Cloud Storage non tiene conto del concetto di directory, le directory di origine vuote non vengono trasferite.