Gestire gli agenti di trasferimento

Gli agenti di Storage Transfer Service sono applicazioni in esecuzione all'interno di un container Open Container Initiative (OCI) che si coordinano con Storage Transfer Service per i trasferimenti che coinvolgono file system o spazio di archiviazione compatibile con S3.

Per impostazione predefinita, Storage Transfer Service utilizza Docker per creare ed eseguire container OCI. Storage Transfer Service supporta anche Podman per la gestione dei container. Per utilizzare Podman, devi installare gli agenti utilizzando il comando podman run.

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

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

Panoramica

  • I processi dell'agente sono dinamici. Durante il trasferimento, puoi aggiungere agenti per migliorare il rendimento. Gli agenti appena avviati si uniscono al pool di agenti assegnato ed eseguono il lavoro dai trasferimenti esistenti. Puoi utilizzare questo valore per regolare il numero di agenti in esecuzione o per adattare il rendimento dei trasferimenti alla variazione della domanda di trasferimento.

  • I processi dell'agente sono un insieme a tolleranza di errore. Se un agente smette di funzionare, gli altri continuano a lavorare. Se tutti gli agenti si fermano, quando aggiungi nuovi agenti, il trasferimento riprende da dove si erano interrotti. In questo modo puoi evitare agenti di monitoraggio, nuovi tentativi di trasferimento o l'implementazione della logica di recupero. Puoi applicare 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 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 corso, ma più lenti perché un singolo agente sta spostando i dati. Se anche l'agente rimanente si interrompe, tutti i trasferimenti smettono di avanzare, poiché non sono in esecuzione agenti. Quando riavvii i processi dell'agente, i trasferimenti riprendono da dove 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 trasferisci dati da un file system specifico, devi montare il file system su ogni macchina che ospita gli agenti nel pool di agenti. Se alcuni agenti del tuo 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 service account.

Se utilizzerai i comandi gcloud, installa gcloud CLI.

Installa ed esegui gli agenti di trasferimento

Ti consigliamo di installare almeno tre agenti per pool di agenti, idealmente su macchine separate. Per ulteriori informazioni su come determinare il numero di agenti da eseguire, vedi Massimizzare il rendimento dell'agente di trasferimento.

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

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 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 guida 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, altrimenti 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 gli 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 memorizzate 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

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 la documentazione di riferimento di gcloud transfer.

Docker

Prima di utilizzare Docker 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 credenziali predefinite di gcloud o 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 comando riportato di seguito:

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 del service account

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 dei account di servizio, vedi Creare e gestire le chiavi dei service account.

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

Opzioni e flag

Sostituisci le variabili negli esempi riportati sopra 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 flag aggiuntivi.

  • --enable-mount-directory monta l'intero file system nella directory /transfer_root del container. Se viene specificato --enable-mount-directory, non vengono applicate restrizioni alle directory utilizzando il flag -v.

  • --creds-file=/etc/gcloud/key.json specifica il percorso del file delle credenziali dell'account di servizio in formato JSON sul container. Questo file è montato dal flag -v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro nel comando.

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

  • Se il trasferimento avviene da AWS S3 o da un archivio compatibile con S3, trasmetti 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 aiutare 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 anteporre /transfer_root a questo percorso. 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 della memoria massima
    6g 6 gigabyte
    6gb 6 gigabyte
    6GiB 6 gibibyte

  • --network=DOCKER_NETWORK: specifica la rete Docker per questo container. La specifica di --network=host può migliorare le prestazioni riducendo il sovraccarico di rete, ma consente al container l'accesso completo alla rete dell'host.

Podman

Prima di utilizzare Podman per installare gli agenti, installa Podman:

sudo apt-get update
sudo apt-get -y install podman

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

Credenziali predefinite

Per consentire l'autenticazione del container dell'agente con le credenziali predefinite di Google Cloud CLI, crea un volume contenente un file con le credenziali predefinite dell'applicazione eseguendo il seguente comando:

gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin gcr.io
sudo podman pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
sudo podman run -ti --replace --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable 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. Il comando installa un agente. Per aumentare il numero di agenti nel pool, esegui di nuovo questo comando tutte le volte necessarie.

sudo podman 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 del service account

Per installare ed eseguire gli agenti di trasferimento utilizzando le credenziali dell'account di servizio, devi rendere disponibile la chiave dell'account di servizio in formato JSON sul container. Ecco come fare:

  1. Monta la posizione dell'host della chiave su qualsiasi percorso del container. Ad esempio: -v $HOME/.config/gcloud/credentials.json:/key.json:ro. Questo specifica che la chiave si trova sulla macchina host in $HOME/.config/gcloud/credentials.json e deve essere montata come /key.json sul container. Il simbolo ro indica che il file è reso disponibile come di sola lettura per il container.
  2. Specifica il percorso del contenitore della chiave come valore di --creds-file. Nell'esempio del passaggio precedente, specifica --creds-file=/key.json.

Per ulteriori informazioni sulle chiavi dei account di servizio, vedi Creare e gestire le chiavi dei service account.

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opzioni e flag

Sostituisci le variabili negli esempi riportati sopra 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 podman run supporta flag aggiuntivi.

  • --enable-mount-directory monta l'intero file system nella directory /transfer_root del container. Se viene specificato --enable-mount-directory, non vengono applicate restrizioni alle directory utilizzando il flag -v.

  • --creds-file=/etc/gcloud/key.json specifica il percorso del file delle credenziali dell'account di servizio in formato JSON sul container. Questo file è montato dal flag -v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro nel comando.

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

  • Se il trasferimento avviene da AWS S3 o da un archivio compatibile con S3, trasmetti 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 aiutare 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 + OCI 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 anteporre /transfer_root a questo percorso. 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 della memoria massima
    6g 6 gigabyte
    6gb 6 gigabyte
    6GiB 6 gibibyte

  • --network=DOCKER_NETWORK: specifica la rete Docker per questo container. La specifica di --network=host può migliorare le prestazioni riducendo il sovraccarico di rete, ma consente al container l'accesso completo alla rete dell'host.

Risoluzione dei problemi

Se la tua configurazione di SELinux richiede che le etichette vengano posizionate sul volume contenuto montato in un contenitore, aggiungi il flag :Z al volume:

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json:ro \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Senza un'etichetta, il sistema di sicurezza potrebbe impedire ai processi in esecuzione all'interno del container di utilizzare i contenuti. Per impostazione predefinita, Podman non modifica le etichette impostate dal sistema operativo.

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 tuoi 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 sua creazione, consulta Gli agenti non sono connessi.

Monitorare l'attività degli agenti

Puoi utilizzare Cloud Monitoring per monitorare l'attività dell'agente.

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

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

Nome metrica Cosa descrive 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 di rendimento.
storagetransfer.googleapis.com/agent/connected Un valore booleano True per ogni agente da cui Google Cloud è stato ricevuto un messaggio heartbeat recente.
  • Avviso per gli agenti che non superano il test
  • Valore inferiore al numero di agenti che consideri necessario per prestazioni ragionevoli
  • Segnalare un problema con le macchine degli agenti

Interrompere un agente

Per arrestare un agente, esegui docker stop sull'ID del 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 Filtra 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 contenitore specifico.

  5. Esegui il comando sul computer 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.

Riavvia un agente

Gli agenti arrestati non possono essere riavviati. Installa nuovi agenti nel pool di agenti.

Eliminare un agente

Per eliminare agenti specifici, elenca quelli in esecuzione sul tuo computer:

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 il flag --uninstall. Entrambi i flag eliminano tutti gli agenti sulla macchina; il flag --uninstall disinstalla anche l'immagine Docker dell'agente.

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

Dettagli del trasferimento del 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 facciamo per ridurre la quantità di dati che inviamo dalle 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 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 durante l'ultima copia del file. Quando rileviamo un file nuovo o modificato, copiamo l'intero file nella 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 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 anche nell'origine, i file eliminati accidentalmente nell'origine vengono eliminati anche nella destinazione. Per evitare la perdita di dati dovuta a eliminazioni accidentali, ti consigliamo di abilitare il controllo delle versioni degli oggetti nel bucket di destinazione se scegli di utilizzare questa opzione. In questo modo, 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 trasferirà tutti i file di origine esistenti e non modificati durante l'intero periodo di esecuzione dell'operazione. I file di origine creati, aggiornati o eliminati durante un trasferimento potrebbero o meno riflettere queste modifiche nel set di dati di destinazione.

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

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

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

  • Clona la directory che intendi trasferire, quindi utilizza la directory clonata 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 il concetto di directory, le directory di origine vuote non vengono trasferite.