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 che coinvolgono file system o archiviazione compatibile con S3.

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

I trasferimenti da Amazon S3 non richiedono agenti. L'archiviazione compatibile con S3 si riferisce a sistemi di archiviazione che utilizzano l'API S3 ma non sono ospitati direttamente da Amazon.

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

Panoramica

• I processi dell'agente sono dinamici. Mentre esegui 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. Puoi utilizzarlo per regolare il numero di agenti in esecuzione o per adattare le prestazioni del trasferimento alla domanda di trasferimento mutevole.

• I processi dell'agente sono un collettivo a tolleranza di errore. Se un agente interrompe l'esecuzione, gli agenti rimanenti continuano a lavorare. Se tutti gli agenti si interrompono, quando riavvii gli agenti, il trasferimento riprende dal punto in cui gli agenti erano stati arrestati. In questo modo puoi evitare gli agenti di monitoraggio, ritentare i trasferimenti o implementare la logica di ripristino. Puoi applicare le patch, spostare e scalare dinamicamente i pool di agenti senza tempi di inattività del trasferimento 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ù lenta perché un singolo agente sta spostando i dati. Se anche l'agente rimanente si arresta, tutti i trasferimenti smetteranno di fare progressi poiché non ci sono agenti in esecuzione. Quando riavvii i processi dell'agente, i trasferimenti riprenderanno da dove erano stati interrotti.

• I processi dell'agente appartengono a un pool. Insieme, spostano 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 trasferisci dati da un determinato file system, devi montare il file system su ogni macchina che ospita agenti nel pool di agenti. Se alcuni agenti nel tuo pool possono raggiungere un'origine dati e altri non possono raggiungere un'origine dati, i trasferimenti da quell'origine dati non avranno esito positivo.

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 gcloud CLI.

Installa ed esegui gli agenti di trasferimento

Importante: gli utenti in grado di creare job di trasferimento possono recuperare e scaricare i dati da qualsiasi directory del file system accessibile dall'agente. Se gli agenti vengono eseguiti come root e gli viene concesso l'accesso all'intero file system, un utente malintenzionato potrebbe assumere il controllo dell'host. Ti consigliamo vivamente di limitare l'accesso degli agenti solo alle directory necessarie.

Ti consigliamo di installare almeno tre agenti per pool di agenti, idealmente su macchine separate. Per saperne di più su come determinare il numero di agenti da eseguire, consulta Massimizzare le prestazioni dell'agente di trasferimento.

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

Per installare ed eseguire gli agenti di trasferimento:

12 aprile 2023: gli agenti utilizzati per i trasferimenti da uno spazio di archiviazione compatibile con S3 devono autenticarsi con una chiave dell'account di servizio. Utilizza il flag --creds-file per specificare il percorso di un file di chiavi dell'account di servizio. Il mancato utilizzo di un account di servizio provoca trasferimenti bloccati; il job viene visualizzato come in corso, ma non vengono trasferiti dati.

Questa notifica verrà rimossa una volta risolto il problema.

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 ti guiderà attraverso i passaggi necessari per installare gli agenti. Questo comando installa gli agenti NUM_AGENTS sulla tua macchina, mappati al nome del pool specificato come POOL_NAME e autentica l'agente utilizzando le tue credenziali gcloud. Il nome del pool deve esistere oppure viene restituito un errore.

Il flag --mount-directories è facoltativo, ma è vivamente consigliato. Il suo valore è un elenco separato da virgole di directory del 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.

Origini compatibili con S3

Quando installi agenti da utilizzare con un'origine compatibile con S3, devi fornire le credenziali AWS come variabili di ambiente come valori di AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY oppure archiviate come credenziali predefinite nei file di configurazione del 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

Usa una chiave dell'account di servizio

Nota: le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per maggiori informazioni, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.

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

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

Credenziali predefinite

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

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

Quindi utilizza il comando seguente 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

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

Nota: le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per maggiori informazioni, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.

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 usare più di un flag -v per specificare ulteriori directory da cui eseguire la copia.
• 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 l'agente. Se ometti questo flag, l'agente viene installato nel pool transfer_service_default del progetto.

Il comando docker run supporta flag aggiuntivi.

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

  Attenzione: se gli agenti vengono eseguiti come root e ricevono l'accesso all'intero file system, un utente malintenzionato potrebbe assumere il controllo dell'host. Ti consigliamo vivamente di limitare l'accesso dell'agente alle directory necessarie.

• --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. Fai precedere il percorso --creds-file da /transfer_root.

  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 dallo spazio di archiviazione compatibile con S3. Gli agenti installati con questa opzione non possono essere utilizzati per i trasferimenti da file system POSIX.

• Se il trasferimento proviene da uno spazio di archiviazione compatibile con AWS S3 o S3, passa l'ID della 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 corrisponde all'URL HTTP e alla 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 identificare l'agente o la relativa 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 precedere questo percorso con /transfer_root. Ad esempio, /transfer_root/logs.

• --max-physical-mem=MAX_MEMORY: gli agenti utilizzano per impostazione predefinita un massimo di 8 GiB di memoria di sistema. Se il valore predefinito non è adatto 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

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 compare nella pagina del pool di agenti entro 10 minuti dalla sua creazione, consulta Agenti non sono connessi.

Monitora l'attività degli agenti

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

Il monitoraggio è disponibile in combinazione con le dimensioni project, agent_pool e agent_id.

Utilizzando questi dati di monitoraggio, puoi configurare avvisi per informarti di potenziali problemi relativi al trasferimento. A questo scopo, 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 in tutti i job che gestisce in un determinato momento.	Avviso per cali delle prestazioni.
storagetransfer.googleapis.com/agent/connected	Un valore booleano True per ogni agente da cui Google Cloud ha ricevuto un messaggio Heartbeat recente.	Avviso per gli agenti in errore Non inferiore a un numero di agenti che consideri necessario per prestazioni ragionevoli Segnalare un problema con le macchine degli agenti

Arresta un agente

Per arrestare un agente, esegui docker stop sull'ID container Docker dell'agente. Per trovare l'ID e interrompere 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 Interrompi 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 Disconnetti.

Elimina un agente

Per eliminare agenti specifici, elenca quali agenti sono in esecuzione sulla tua 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 inizia tutti i trasferimenti calcolando 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 che inviamo dalle tue 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: verifichiamo 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 al momento dell'ultima copia del file. Quando rileviamo un file nuovo o modificato, copio l'intero file nella sua destinazione. Per saperne di più sull'aggiornamento dei file, consulta Dettagli sulla coerenza dei dati.

Per impostazione predefinita, rileviamo i file eliminati nell'origine, ma non interveniamo. Se scegli l'opzione di sincronizzazione Elimina 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 file di destinazione che non sono anche nell'origine, i file eliminati per errore all'origine vengono eliminati anche nella destinazione. Per evitare perdite di dati a seguito di 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 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. Nei file di origine creati, aggiornati o eliminati durante un trasferimento le modifiche potrebbero riflettersi o meno nel set di dati di destinazione.

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

Quando utilizzi la funzionalità delete-objects-from-source, ti consigliamo vivamente di bloccare le scritture sull'origine per l'intera durata del trasferimento per evitare la perdita di dati.

Per bloccare le scritture sull'origine, esegui una delle seguenti operazioni:

• Clona la directory che intendi trasferire, quindi utilizza la directory clonata come origine di trasferimento.
• Arresta le applicazioni che scrivono nella directory di origine.

Se è importante acquisire le modifiche che si sono verificate durante un trasferimento, puoi eseguire nuovamente il trasferimento o impostare il file system di origine come di sola lettura mentre l'operazione è in esecuzione.

Poiché Cloud Storage non prevede le directory, le directory di origine vuote non vengono trasferite.

Importante: ti consigliamo vivamente di verificare la riuscita del trasferimento prima di eliminare i dati di origine. Questo servizio non ha la capacità di ripristinare i dati in Cloud Storage.