Risolvere i problemi relativi ai trasferimenti del file system

Questo documento descrive come risolvere i problemi relativi ad agenti e trasferimenti e dove trovare i log degli agenti per aiutarti a risolvere i problemi.

Errori

La tabella seguente descrive i messaggi di errore di trasferimento e come risolverli:

Messaggio di errore Tipo di errore Significato dell'errore Come risolvere l'errore
Modificato durante il trasferimento FILE_MODIFIED_FAILURE Il file di origine è stato modificato durante il trasferimento ogni volta che Storage Transfer Service ha tentato di copiarlo. Impedisci le scritture nel file specificato durante la successiva operazione di Storage Transfer Service.
Impossibile trasferire PRECONDITION_FAILURE L'oggetto Cloud Storage associato al file di origine è stato modificato ogni volta che Storage Transfer Service ha tentato di caricare il file. Impedisci a più job di trasferimento di scrivere lo stesso file nello stesso bucket Cloud Storage utilizzando prefissi univoci degli oggetti Cloud Storage quando crei i job di trasferimento.
Directory di origine non trovata SOURCE_DIR_NOT_FOUND Il percorso di origine specificato non è corretto oppure il percorso è corretto, ma non tutti gli agenti hanno accesso al percorso. Controlla la configurazione del job di trasferimento e verifica che:
Impossibile trovare la directory di origine o di destinazione del job ROOT_DIR_NOT_FOUND Il percorso di origine/destinazione specificato non è corretto oppure il percorso è corretto, ma non tutti gli agenti hanno accesso al percorso. Controlla la configurazione del job di trasferimento e verifica che:
File non trovato FILE_NOT_FOUND_FAILURE Il file di origine è stato trovato, ma è stato eliminato prima di essere trasferito su Cloud Storage. Se il file è stato eliminato per errore, ripristinalo in modo che il job di trasferimento successivo possa caricarlo.
Impossibile trovare il bucket di destinazione BUCKET_NOT_FOUND Il bucket di destinazione non esiste in Cloud Storage. Verifica che il nome del bucket di destinazione sia stato digitato correttamente e che il bucket esista.
Impossibile trovare un oggetto di metadati interno METADATA_OBJECT_
NOT_FOUND_FAILURE		 Storage Transfer Service archivia i metadati nel bucket di destinazione con il prefisso storage-transfer. Questo errore viene visualizzato se i file di metadati vengono eliminati prima del completamento delle operazioni di trasferimento corrispondenti. Evita di eliminare gli oggetti con il prefisso storage-transfer/ nel bucket di destinazione fino al completamento di tutti i job di trasferimento.
Operazione non riuscita a causa di un nome file non valido INVALID_FILE_NAME Il percorso di un file di origine non è valido. Verifica e correggi il percorso file specificato. Verifica che il percorso utilizzi caratteri supportati da Cloud Storage.
Operazione non riuscita a causa di una classe di archiviazione non valida INVALID_FILE_STORAGE_CLASS La classe di archiviazione per l'origine specificata non consente le letture. Consulta la documentazione del tuo cloud provider per determinare come trasferire i dati in una classe di archiviazione che ne consenta la copia.
Operazione non riuscita a causa di un URI della sessione di caricamento ripristinabile non valido SESSION_URI_INVALID L'ID caricamento ripristinabile o l'URI della sessione è scaduto o è stato annullato. Il nuovo tentativo di correzione dell'errore non viene eseguito correttamente. Contatta l'assistenza.
Operazione non riuscita a causa di dimensioni file non valide INVALID_FILE_SIZE Le dimensioni del file non sono valide. Verifica che le dimensioni del file siano >= 0 e <= 5 TiB (dimensioni massime dell'oggetto Cloud Storage) per i trasferimenti a Cloud Storage.
Operazione non riuscita a causa delle autorizzazioni PERMISSION_FAILURE e UNAUTHENTICATED Un agente di trasferimento non disponeva di autorizzazioni sufficienti per eseguire un'operazione. Esistono due possibilità per questo errore:
  • Un agente non disponeva di autorizzazioni Google Cloud sufficienti.
  • Un agente non è stato in grado di leggere un file o una directory a causa di autorizzazioni insufficienti nel file system di origine.

Verifica quanto segue:
L'oggetto è soggetto alla policy di conservazione del bucket e non può essere eliminato, sovrascritto o archiviato PERMISSION_FAILURE Il bucket ha un criterio di conservazione attivo e l'oggetto esiste già nel bucket. Storage Transfer Service non può sovrascrivere gli oggetti esistenti nel bucket. Questo errore può essere visualizzato se il file è stato modificato nell'origine o se Storage Transfer Service tenta il caricamento due volte a causa delle condizioni della rete e il primo caricamento è riuscito. Verifica che i dati nel bucket Cloud Storage corrispondano alle tue aspettative. Puoi verificare che le dimensioni e l'ora di modifica (mtime) dei file di origine corrispondano alle controparti degli oggetti Cloud Storage eseguendo nuovamente il job e verificando che non siano presenti errori.
Il servizio non disponeva di autorizzazioni sufficienti SERVICE_PERMISSION_FAILURE Storage Transfer Service non disponeva di autorizzazioni sufficienti per eseguire un'operazione. Storage Transfer Service utilizza un service agent, in genere nel formato project-PROJECT_NUMBER@storage-transfer-service., per accedere alle risorse. Per determinare il tuo PROJECT_NUMBER specifico, utilizza la chiamata API googleserviceaccounts.get. Verifica che il account di servizio disponga dei seguenti ruoli:
  • roles/storagetransfer.serviceAgent per il progetto.
  • roles/storage.objectCreator, roles/storage.objectViewer e roles/storage.legacyBucketReader per tutti i bucket di destinazione o intermedi (consulta Configura l'accesso a un sink: Cloud Storage).
Agente non supportato AGENT_UNSUPPORTED_VERSION La versione dell'agente non è più compatibile con Storage Transfer Service. Si tratta di un errore temporaneo, correlato a un aggiornamento dell'agente non riuscito. Se si verifica, procedi nel seguente modo:
  1. Arresta tutti gli agenti.
  2. Esegui il pull dell'immagine Docker più recente eseguendo: sudo docker pull gcr.io/cloud-ingest/tsop-agent
  3. Esegui il comando Docker run per avviare tutti i container dell'agente.
Se il problema persiste, contatta il team di assistenza.
Operazione non riuscita a causa di una mancata corrispondenza dell'hash HASH_MISMATCH_FAILURE Ogni volta che Storage Transfer Service ha tentato di caricare questo file, i byte caricati erano danneggiati. Di conseguenza, l'hash del file on-premise non corrispondeva all'hash dell'oggetto Cloud Storage risultante. Questo errore può essere causato da una serie di potenziali problemi. Se riscontri una piccola percentuale di errori di mancata corrispondenza degli hash (meno dell'1%) in un trasferimento di grandi dimensioni, riprova a trasferire i file non riusciti. Se riscontri un'elevata percentuale di errori di mancata corrispondenza degli hash (1% o superiore), ti consigliamo di esaminare potenziali errori di memoria, CPU o altri errori hardware sulla macchina dell'agente.
Operazione non riuscita a causa di una modalità file non supportata UNSUPPORTED_FILE_MODE Storage Transfer Service ha rilevato un file con una modalità non supportata, ad esempio un dispositivo, un socket, una named pipe o un file irregolare. Rimuovi questi tipi di file speciali dalla directory di origine.
Operazione non riuscita a causa di un errore nel file system FILESYSTEM_ERROR Un agente ha riscontrato un errore del file system o del sistema operativo durante l'esecuzione di un'operazione del file system, ad esempio lettura, ricerca o stato. Leggi la descrizione dell'errore per capire quale operazione del file system non è riuscita. Assicurati che il file system sia accessibile all'agente on-prem e che risponda alle operazioni su file di base.
Operazione non riuscita a causa di spazio esaurito nel file system FILESYSTEM_NO_SPACE_ON_DEVICE Un agente ha esaurito lo spazio durante l'esecuzione di un'operazione del file system, ad esempio l'apertura o la scrittura. Leggi la descrizione dell'errore per capire quale operazione del file system non è riuscita. Assicurati che il file system disponga di spazio sufficiente per eseguire le operazioni sui file.
Operazione non riuscita a causa di un errore sconosciuto UNKNOWN_FAILURE Si è verificato un errore imprevisto. Leggi la descrizione dell'errore. Se la descrizione dell'errore non contiene informazioni sufficienti per risolvere il problema, contatta l'assistenza.
Operazione non riuscita a causa di una specifica non valida INVALID_SPEC L'agente ha ricevuto una specifica interna danneggiata. Verifica la presenza di dati danneggiati sugli host degli agenti e contatta l'assistenza se non ne trovi.
Operazione non riuscita a causa di un file manifest vuoto o non valido CONFORMANCE_FAILURE L'agente non può leggere o ottenere byte CSV validi a causa di formattazione o voci CSV non valide. Assicurati che le voci del manifest siano percorsi file validi. Se la descrizione dell'errore non contiene informazioni sufficienti per risolvere il problema, contatta l'assistenza.
Utilizzo dei caricamenti ripristinabili anziché dei caricamenti multiparte a causa di un errore di autorizzazione negata PERMISSION_FAILURE I caricamenti multiparte sono stati abilitati per questo trasferimento, ma non sono state impostate le autorizzazioni corrette per il bucket. Per le autorizzazioni necessarie, consulta Configura l'accesso a un sink: Cloud Storage.
Voci elencate non in ordine INCOMPATIBLE_LIST_ORDER_FAILURE Il file system di origine ha restituito un elenco di file in un ordine non compatibile con Storage Transfer Service. Storage Transfer Service richiede che il file system di origine restituisca i file in ordine lessicografico. Verifica che il file system restituisca i file in ordine lessicografico.

Visualizzazione dei log dell'agente

I log dell'agente contengono informazioni pertinenti ai processi dell'agente e possono aiutarti a risolvere i problemi di connessione dell'agente. Se i tuoi agenti sono elencati come connessi nella console Google Cloud e riscontri errori di trasferimento, consulta Visualizzazione degli errori per visualizzare un esempio di errori di trasferimento. Per visualizzare i log che contengono un record di ogni file considerato da Storage Transfer Service durante un trasferimento, consulta Visualizzazione dei log di trasferimento.

Per impostazione predefinita, i log dell'agente vengono archiviati in /tmp. Puoi modificare la località con l'opzione della riga di comando --log-dir=logs-directory.

I log sono denominati:

agent.hostname.username.log.log-level.timestamp

I componenti del nome del log sono i seguenti:

  • hostname: il nome host su cui è in esecuzione l'agente.
  • username: il nome utente che esegue l'agente.
  • log-level è uno dei seguenti:
    • INFO: messaggi informativi
    • ERROR: errori riscontrati durante il trasferimento, ma che non impediscono la continuazione del job di trasferimento.
    • FATAL: errori riscontrati che impediscono la continuazione del job di trasferimento.
  • timestamp: timestamp nel formato YYYYMMDD-hhmmss.thread-id.

La directory dei log contiene collegamenti simbolici ai log più recenti per ciascuno dei livelli di priorità:

  • agent.ERROR
  • agent.FATAL
  • agent.INFO

Bassa velocità di trasferimento

Se il trasferimento dei dati richiede molto tempo, controlla quanto segue:

  1. La velocità effettiva di lettura del file system deve essere circa 1,5 volte la velocità di caricamento desiderata. Puoi utilizzare FIO per testare il throughput di lettura del file system.

    Installa fio:

     sudo apt install -y fio

    Crea una nuova directory fiotest:

     TEST_DIR=/mnt/mnt_dir/fiotest
 sudo mkdir -p $TEST_DIR

    Testa il throughput di lettura:

     sudo fio --directory=$TEST_DIR --direct=1
    --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
    --time_based=1 --runtime=180 --name=read_test --size=1G

    Dopo aver eseguito i comandi riportati sopra, Fio genera un report. La riga con l'etichetta "bw" rappresenta la larghezza di banda aggregata totale di tutti i thread e può essere utilizzata come proxy per il throughput di lettura.

  2. Utilizza iPerf3 per controllare la larghezza di banda internet disponibile per Storage Transfer Service.

  3. Assicurati che ogni agente di trasferimento abbia almeno 4 vCPU e 8 GB di RAM.

Se hai verificato le condizioni riportate sopra e i tempi di trasferimento continuano a essere lunghi, puoi aggiungere altri agenti per aumentare il numero di connessioni simultanee al file system dei tuoi dati.

Per saperne di più su come massimizzare le prestazioni degli agenti di trasferimento, consulta Best practice per gli agenti.

Risoluzione dei problemi dell'agente

Le sezioni seguenti descrivono come risolvere i problemi e gli errori dell'agente di trasferimento:

Gli agenti non sono connessi

Se gli agenti di trasferimento non vengono visualizzati come connessi nella console Google Cloud :

  1. Verifica che gli agenti possano connettersi alle API Storage di Cloud Storage:

    1. Esegui questo comando dalla stessa macchina dell'agente di trasferimento per testare la connessione dell'agente alle API Cloud Storage:

      gcloud storage cp test.txt gs://my-bucket

      Sostituisci:

      my-bucket con il nome del tuo bucket Cloud Storage.

  2. Se il tuo progetto utilizza i Controlli di servizio VPC, visualizza i log dell'agente per verificare la presenza di errori. Se i Controlli di servizio VPC non sono configurati correttamente, i log dell'agente INFO conterranno il seguente errore:

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    In questo output:

Gli agenti sono connessi, ma i job non vanno a buon fine

Se gli agenti vengono visualizzati come connessi, ma i job di trasferimento non vanno a buon fine, controlla i dettagli degli errori dei job non riusciti.

Il proxy rifiuta gli indirizzi IP

Se utilizzi un proxy come Squid e una lista consentita, potresti notare che le richieste vengono rifiutate perché vengono utilizzati indirizzi IP anziché nomi host.

Per risolvere il problema, utilizza il comando docker run per eseguire gli agenti e aggiungi il seguente flag:

--transfer-service-endpoint=storagetransfer.googleapis.com:443

Se utilizzi un endpoint alternativo per raggiungere googleapis.com (ad esempio per Private Service Connect), sostituisci googleapis.com con l'endpoint alternativo.

L'agente non riesce a connettersi a un endpoint HTTPS utilizzando un certificato autofirmato

Se l'agente non riesce a connettersi a un endpoint HTTPS utilizzando un certificato autofirmato, utilizza un'opzione -v aggiuntiva per montare il bundle di certificati personalizzati nella località predefinita del container (/etc/ssl/certs).

Per farlo, modifica il comando docker run aggiungendo il seguente flag:

-v PATH_TO_LOCAL_CERT:/etc/ssl/certs/ca-certificates.crt

Sostituisci:

  • PATH_TO_LOCAL_CERT con il percorso del file del certificato personalizzato.

Avvio dell'agente non riuscito: il KDC non ha risposto in modo appropriato alla negoziazione FAST

Se, quando provi ad avviare l'agente di trasferimento per un trasferimento HDFS, l'agente non si avvia e restituisce un errore simile al seguente:

Failed to start the agent, err = failed to create HDFS client: Couldn't find the hdfs client: no available namenodes: SASL handshake: [Root cause: KRBMessage_Handling_Error] KRBMessage_Handling_Error: AS Exchange Error: AS_REP is not valid or client password/keytab incorrect < KRBMessage_Handling_Error: KDC did not respond appropriately to FAST negotiation

Questo errore si verifica quando il tuo Kerberos Key Distribution Center (KDC) non supporta la negoziazione FAST, che l'agente tenta di utilizzare per impostazione predefinita per i trasferimenti HDFS.

Per risolvere il problema, impedisci all'agente di utilizzare la negoziazione FAST aggiungendo il flag --kerberos-disable-pa-fx-fast quando avvii l'agente.

Questo flag è supportato solo quando l'agente viene eseguito utilizzando Docker o Podman. Non è supportato quando utilizzi il comando gcloud transfer agents install.

Aggiungi il flag al comando docker run o podman run come segue:

docker run --rm -v /usr/local/transfer_agent:/tmp/transfer_agent \
  gcr.io/cloud-ingest/tsop-agent:latest \
  --project-id=PROJECT_ID \
  --hostname=$(hostname) \
  --kerberos-disable-pa-fx-fast

Per ulteriori dettagli sui comandi docker e podman, consulta Installa ed esegui gli agenti di trasferimento.