Transfiere datos entre sistemas de archivos

En esta página, se muestra cómo transferir datos entre dos sistemas de archivos POSIX. Los casos de uso comunes incluyen los siguientes:

• Aumento de actividad a la nube y HPC híbrido: Transfiere rápidamente grandes conjuntos de datos desde la ubicación local a la nube para su procesamiento.
• Migración y sincronización a Filestore: migra o sincroniza datos de un sistema de archivos local a Filestore.
• Transferencia de archivos administrados: Transfiere datos de forma segura y confiable entre centros de datos o entre dos sistemas de archivos en la nube.

Lineamientos de rendimiento de la transferencia

Los siguientes lineamientos pueden ayudar a maximizar el rendimiento durante las transferencias del sistema de archivos a este.

Implementación del agente

En general, recomendamos usar tres agentes en cada uno de los grupos de agentes de origen y de destino. Supervisa la transferencia y agrega más agentes si es necesario. Cada agente necesita 4 CPU virtuales y 8 GiB de RAM.

Si migras a una instancia de Filestore, Filestore recomienda usar el tipo de instancia n2-standard-8 para cada agente. Especifica nconnect=2 cuando actives la instancia en una VM de Compute Engine. Consulta los lineamientos de rendimiento de Filestore para obtener más información sobre cómo optimizar y probar el rendimiento de las instancias.

Transfiere grandes cantidades de archivos pequeños

Para obtener un mejor rendimiento cuando transfieres una gran cantidad de archivos pequeños, te recomendamos que dividas los archivos en varios directorios y evites uno solo con millones de archivos.

Antes de comenzar

Antes de realizar las tareas descritas en esta página, completa los pasos previos.

Crea grupos de agentes e instala agentes

Para las transferencias de sistema de archivos a sistema de archivos, debes crear grupos de agentes y agentes para los sistemas de archivos de origen y de destino. Los agentes para el grupo de agentes de origen deben instalarse en máquinas o VM que tengan acceso al sistema de archivos de origen. Los agentes del grupo de agentes de destino deben instalarse en máquinas o VM que tengan acceso al sistema de archivos de destino.

No incluyas información sensible, como información de identificación personal (PII) o datos de seguridad, en el prefijo de ID del agente o en el nombre del grupo de agentes. Los nombres de recursos pueden propagarse a los nombres de otros recursos de Google Cloud y pueden exponerse a sistemas internos de Google fuera del proyecto.

Crea un grupo de agentes de origen

Crea un grupo de agentes de origen mediante uno de los siguientes métodos:

gcloud CLI

Para crear un grupo de agentes de origen, ejecuta el siguiente comando:

gcloud transfer agent-pools create SOURCE_AGENT_POOL

Reemplaza SOURCE_AGENT_POOL por el nombre que deseas asignar al grupo de agentes de origen.

Consola de Google Cloud

1. En la consola de Google Cloud, ve a la página Grupos de agentes.

   Ir a los grupos de agentes

   Se mostrará la página Grupos de agentes, que enumera tus grupos de agentes existentes.

2. Haz clic en Crear otro grupo.

3. Ingresa un nombre para el grupo.

4. Haz clic en Crear.

Instala agentes para el grupo de agentes de origen

Instala los agentes para el grupo de agentes de origen en una máquina o VM que tenga acceso al sistema de archivos de origen:

gcloud CLI

Para instalar los agentes del grupo de agentes de origen, ejecuta el siguiente comando:

gcloud transfer agents install --pool=SOURCE_AGENT_POOL --count=NUMBER_OF_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

Reemplaza lo siguiente:

• SOURCE_AGENT_POOL por el nombre del grupo de agentes de origen
• NUMBER_OF_AGENTS por la cantidad de agentes que deseas instalar para el grupo de agentes de origen. Si deseas determinar la cantidad óptima de agentes para tu entorno, consulta Requisitos y prácticas recomendadas de los agentes.
• MOUNT_DIRECTORIES por una lista de directorios separados por comas en el sistema de archivos de origen desde donde se copiará. Si omites esta marca, se activa todo el sistema de archivos, lo que podría presentar un riesgo de seguridad.

Consola de Google Cloud

1. En la consola de Google Cloud, ve a la página Grupos de agentes.

   Ir a los grupos de agentes

   Se mostrará la página Grupos de agentes, que enumera tus grupos de agentes existentes.

2. Haz clic en el nombre del grupo de agentes de origen que acabas de crear.

3. En la pestaña Agentes, haz clic en Instalar agente.

4. Sigue las instrucciones en la consola de Google Cloud para instalar Docker y, luego, iniciar el agente.

Crea un grupo de agentes de destino y, luego, instala agentes

Repite los pasos anteriores para crear un grupo de agentes de destino y, luego, instalar agentes.

Crea un bucket de Cloud Storage como intermediario

Las transferencias de sistema de archivos a sistema de archivos requieren un bucket de Cloud Storage como intermediario para la transferencia de datos.

1. Crea un bucket de clase Estándar de Cloud Storage con la siguiente configuración:

   • Encriptación: Puedes especificar una clave de encriptación administrada por el cliente (CMEK). De lo contrario, se usa una clave de encriptación administrada por Google.
   • Control de versiones de los objetos, bloqueo del bucket y conservaciones de objetos predeterminadas: Mantén estas funciones inhabilitadas.

2. Otorga permisos y funciones mediante uno de los siguientes métodos:

   • Otorga a la cuenta de servicio del Servicio de transferencia de almacenamiento el rol de administrador de almacenamiento (roles/storage.admin) para el bucket.

   • Usa gcloud transfer authorize a fin de autorizar tu cuenta para todas las funciones del Servicio de transferencia de almacenamiento. Este comando otorga permisos de administrador de almacenamiento a nivel de proyecto:

     gcloud transfer authorize --add-missing
     

Crear un trabajo de transferencia

gcloud CLI

Para crear una transferencia desde el sistema de archivos de origen al sistema de archivos de destino, ejecuta lo siguiente:

gcloud transfer jobs create SOURCE_DIRECTORY DESTINATION_DIRECTORY \
    --source-agent-pool=SOURCE_AGENT_POOL \
    --destination-agent-pool=DESTINATION_AGENT_POOL \
    --intermediate-storage-path= gs://STORAGE_BUCKET/FOLDER/

Reemplaza las siguientes variables:

• SOURCE_DIRECTORY por la ruta del directorio fuente
• DESTINATION_DIRECTORY por la ruta de acceso del directorio de destino
• SOURCE_AGENT_POOL por el nombre del grupo de agentes de origen
• DESTINATION_AGENT_POOL por el nombre del grupo de agentes de destino
• STORAGE_BUCKET con el nombre del bucket de Cloud Storage.
• FOLDER por el nombre de la carpeta a la que deseas transferir los datos

Cuando inicias un trabajo de transferencia, el sistema primero calcula los datos en la fuente y el destino para determinar los datos de origen nuevos o actualizados desde la transferencia anterior. Solo se transfieren los datos nuevos.

Bibliotecas cliente

Go

import (
	"context"
	"fmt"
	"io"

	storagetransfer "cloud.google.com/go/storagetransfer/apiv1"
	"cloud.google.com/go/storagetransfer/apiv1/storagetransferpb"
)

func transferFromPosix(w io.Writer, projectID string, sourceAgentPoolName string, rootDirectory string, gcsSinkBucket string) (*storagetransferpb.TransferJob, error) {
	// Your project id
	// projectId := "myproject-id"

	// The agent pool associated with the POSIX data source. If not provided, defaults to the default agent
	// sourceAgentPoolName := "projects/my-project/agentPools/transfer_service_default"

	// The root directory path on the source filesystem
	// rootDirectory := "/directory/to/transfer/source"

	// The ID of the GCS bucket to transfer data to
	// gcsSinkBucket := "my-sink-bucket"

	ctx := context.Background()
	client, err := storagetransfer.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storagetransfer.NewClient: %w", err)
	}
	defer client.Close()

	req := &storagetransferpb.CreateTransferJobRequest{
		TransferJob: &storagetransferpb.TransferJob{
			ProjectId: projectID,
			TransferSpec: &storagetransferpb.TransferSpec{
				SourceAgentPoolName: sourceAgentPoolName,
				DataSource: &storagetransferpb.TransferSpec_PosixDataSource{
					PosixDataSource: &storagetransferpb.PosixFilesystem{RootDirectory: rootDirectory},
				},
				DataSink: &storagetransferpb.TransferSpec_GcsDataSink{
					GcsDataSink: &storagetransferpb.GcsData{BucketName: gcsSinkBucket},
				},
			},
			Status: storagetransferpb.TransferJob_ENABLED,
		},
	}

	resp, err := client.CreateTransferJob(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("failed to create transfer job: %w", err)
	}
	if _, err = client.RunTransferJob(ctx, &storagetransferpb.RunTransferJobRequest{
		ProjectId: projectID,
		JobName:   resp.Name,
	}); err != nil {
		return nil, fmt.Errorf("failed to run transfer job: %w", err)
	}
	fmt.Fprintf(w, "Created and ran transfer job from %v to %v with name %v", rootDirectory, gcsSinkBucket, resp.Name)
	return resp, nil
}

Java

import com.google.storagetransfer.v1.proto.StorageTransferServiceClient;
import com.google.storagetransfer.v1.proto.TransferProto;
import com.google.storagetransfer.v1.proto.TransferTypes.GcsData;
import com.google.storagetransfer.v1.proto.TransferTypes.PosixFilesystem;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferJob;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferSpec;
import java.io.IOException;

public class TransferBetweenPosix {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your project id
    String projectId = "my-project-id";

    // The agent pool associated with the POSIX data source. If not provided, defaults to the
    // default agent
    String sourceAgentPoolName = "projects/my-project-id/agentPools/transfer_service_default";

    // The agent pool associated with the POSIX data sink. If not provided, defaults to the default
    // agent
    String sinkAgentPoolName = "projects/my-project-id/agentPools/transfer_service_default";

    // The root directory path on the source filesystem
    String rootDirectory = "/directory/to/transfer/source";

    // The root directory path on the sink filesystem
    String destinationDirectory = "/directory/to/transfer/sink";

    // The ID of the GCS bucket for intermediate storage
    String bucketName = "my-intermediate-bucket";

    transferBetweenPosix(
        projectId,
        sourceAgentPoolName,
        sinkAgentPoolName,
        rootDirectory,
        destinationDirectory,
        bucketName);
  }

  public static void transferBetweenPosix(
      String projectId,
      String sourceAgentPoolName,
      String sinkAgentPoolName,
      String rootDirectory,
      String destinationDirectory,
      String bucketName)
      throws IOException {

    TransferJob transferJob =
        TransferJob.newBuilder()
            .setProjectId(projectId)
            .setTransferSpec(
                TransferSpec.newBuilder()
                    .setSinkAgentPoolName(sinkAgentPoolName)
                    .setSourceAgentPoolName(sourceAgentPoolName)
                    .setPosixDataSource(
                        PosixFilesystem.newBuilder().setRootDirectory(rootDirectory).build())
                    .setPosixDataSink(
                        PosixFilesystem.newBuilder().setRootDirectory(destinationDirectory).build())
                    .setGcsIntermediateDataLocation(
                        GcsData.newBuilder().setBucketName(bucketName).build())
                    .build())
            .setStatus(TransferJob.Status.ENABLED)
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources,
    // or use "try-with-close" statement to do this automatically.
    try (StorageTransferServiceClient storageTransfer = StorageTransferServiceClient.create()) {

      // Create the transfer job
      TransferJob response =
          storageTransfer.createTransferJob(
              TransferProto.CreateTransferJobRequest.newBuilder()
                  .setTransferJob(transferJob)
                  .build());

      System.out.println(
          "Created and ran a transfer job from "
              + rootDirectory
              + " to "
              + destinationDirectory
              + " with name "
              + response.getName());
    }
  }
}

Node.js

// Imports the Google Cloud client library
const {
  StorageTransferServiceClient,
} = require('@google-cloud/storage-transfer');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// Your project id
// const projectId = 'my-project'

// The agent pool associated with the POSIX data source. Defaults to the default agent
// const sourceAgentPoolName = 'projects/my-project/agentPools/transfer_service_default'

// The agent pool associated with the POSIX data sink. Defaults to the default agent
// const sinkAgentPoolName = 'projects/my-project/agentPools/transfer_service_default'

// The root directory path on the source filesystem
// const rootDirectory = '/directory/to/transfer/source'

// The root directory path on the sink filesystem
// const destinationDirectory = '/directory/to/transfer/sink'

// The ID of the GCS bucket for intermediate storage
// const bucketName = 'my-intermediate-bucket'

// Creates a client
const client = new StorageTransferServiceClient();

/**
 * Creates a request to transfer from the local file system to the sink bucket
 */
async function transferDirectory() {
  const createRequest = {
    transferJob: {
      projectId,
      transferSpec: {
        sourceAgentPoolName,
        sinkAgentPoolName,
        posixDataSource: {
          rootDirectory,
        },
        posixDataSink: {
          rootDirectory: destinationDirectory,
        },
        gcsIntermediateDataLocation: {
          bucketName,
        },
      },
      status: 'ENABLED',
    },
  };

  // Runs the request and creates the job
  const [transferJob] = await client.createTransferJob(createRequest);

  const runRequest = {
    jobName: transferJob.name,
    projectId: projectId,
  };

  await client.runTransferJob(runRequest);

  console.log(
    `Created and ran a transfer job from '${rootDirectory}' to '${destinationDirectory}' with name ${transferJob.name}`
  );
}

transferDirectory();

Python

from google.cloud import storage_transfer

def transfer_between_posix(
    project_id: str,
    description: str,
    source_agent_pool_name: str,
    sink_agent_pool_name: str,
    root_directory: str,
    destination_directory: str,
    intermediate_bucket: str,
):
    """Creates a transfer between POSIX file systems."""

    client = storage_transfer.StorageTransferServiceClient()

    # The ID of the Google Cloud Platform Project that owns the job
    # project_id = 'my-project-id'

    # A useful description for your transfer job
    # description = 'My transfer job'

    # The agent pool associated with the POSIX data source.
    # Defaults to 'projects/{project_id}/agentPools/transfer_service_default'
    # source_agent_pool_name = 'projects/my-project/agentPools/my-agent'

    # The agent pool associated with the POSIX data sink.
    # Defaults to 'projects/{project_id}/agentPools/transfer_service_default'
    # sink_agent_pool_name = 'projects/my-project/agentPools/my-agent'

    # The root directory path on the source filesystem
    # root_directory = '/directory/to/transfer/source'

    # The root directory path on the destination filesystem
    # destination_directory = '/directory/to/transfer/sink'

    # The Google Cloud Storage bucket for intermediate storage
    # intermediate_bucket = 'my-intermediate-bucket'

    transfer_job_request = storage_transfer.CreateTransferJobRequest(
        {
            "transfer_job": {
                "project_id": project_id,
                "description": description,
                "status": storage_transfer.TransferJob.Status.ENABLED,
                "transfer_spec": {
                    "source_agent_pool_name": source_agent_pool_name,
                    "sink_agent_pool_name": sink_agent_pool_name,
                    "posix_data_source": {
                        "root_directory": root_directory,
                    },
                    "posix_data_sink": {
                        "root_directory": destination_directory,
                    },
                    "gcs_intermediate_data_location": {
                        "bucket_name": intermediate_bucket
                    },
                },
            }
        }
    )

    result = client.create_transfer_job(transfer_job_request)
    print(f"Created transferJob: {result.name}")

Administra buckets intermediarios

Cuando se completa un trabajo de transferencia, el Servicio de transferencia de almacenamiento guarda en el bucket los registros de transferencia enumerando los datos transferidos y con errores. Después de la transferencia, las tareas de limpieza se inician automáticamente para borrar los datos intermedios. En algunos casos, las tareas de limpieza no borran todos los datos del bucket. Si quieres borrar los datos que no se borran durante la limpieza, sigue estas instrucciones para borrarlos manualmente o configurar una regla de ciclo de vida para borrarlos de forma automática.

Limpieza manual

Borra los datos del bucket intermediario ejecutando los siguientes comandos gsutil según el tipo de datos que quieras borrar.

• Para borrar los datos del bucket intermedio que no se borraron durante la limpieza, ejecuta el siguiente comando:

  gsutil -m rm gs://STORAGE_BUCKET/PREFIX**
  

• Para borrar todos los datos, incluidos los registros de transferencia, especifica la raíz del bucket con el comodín de coincidencias con todos los (*).

  gsutil -m rm gs://STORAGE_BUCKET/*
  

• Para borrar el bucket, ejecuta el siguiente comando:

  gsutil -m rm gs://STORAGE_BUCKET
  

Reemplaza las siguientes variables:

• STORAGE_BUCKET por el nombre del bucket intermedio

• PREFIX por el nombre de la carpeta a la que se transfirieron los datos dentro del bucket intermediario

Establece una regla de ciclo de vida

Para borrar datos que el ciclo de limpieza automático no borra, configura una regla del ciclo de vida del bucket de Cloud Storage. Usa la condición age para borrar los datos intermedios del bucket mediante la especificación de un período más largo que el trabajo de transferencia más largo que usa el bucket como intermediario. Si la condición de antigüedad especificada es menor que el tiempo necesario para descargar el archivo del bucket intermedio al destino, la transferencia de archivos falla.

De forma opcional, usa la condición matchesPrefix para borrar los datos de la carpeta que especificaste para el bucket intermedio. Para borrar los registros de transferencia junto con los datos del bucket, no se requiere la condición matchesPrefix.

Conserva los metadatos del archivo

Para conservar los metadatos de archivo, incluidos el UID numérico, el GID, el MODE y los vínculos simbólicos:

gcloud CLI

Usa el campo --preserve-metadata para especificar el comportamiento de conservación de esta transferencia. Las opciones que se aplican a las transferencias del sistema de archivos son gid, mode, symlink y uid.

API de REST

Especifica las opciones adecuadas en un objeto metadataOptions.

Consulta Conserva atributos opcionales de POSIX para obtener más información.

Ejemplo de transferencia mediante la CLI de gcloud

En este ejemplo, se transfieren datos del directorio /tmp/datasource en VM1 a /tmp/destination en VM2.

1. Configura el origen de la transferencia.

   1. Crea el grupo de agentes de origen:

      gcloud transfer agent-pools create source_agent_pool
      

   2. En VM1, instala los agentes para source_agent_pool mediante la ejecución del siguiente comando:

      gcloud transfer agents install --pool=source_agent_pool \
          --count=1 \
          --mount-directories="/tmp/datasource"
      

2. Configura el destino de la transferencia.

   1. Crea el grupo de agentes de destino:

      gcloud transfer agent-pools create destination_agent_pool
      

   2. En VM2, instala los agentes para destination_agent_pool mediante la ejecución del siguiente comando:

      gcloud transfer agents install --pool=destination_agent_pool \
          --count=3 \
          --mount-directories="/tmp/destination"
      

3. Crea un bucket intermediario de Cloud Storage.

   1. Crear un bucket llamado my-intermediary-bucket:

      gsutil mb gs://my-intermediary-bucket
      

   2. Autoriza tu cuenta para todas las funciones del Servicio de transferencia de almacenamiento ejecutando el siguiente comando:

      gcloud transfer authorize --add-missing
      

4. Para crear un trabajo de transferencia, ejecuta lo siguiente:

   gcloud transfer jobs create posix:///tmp/datasource posix:///tmp/destination \
       --source-agent-pool=source_agent_pool \
       --destination-agent-pool=destination_agent_pool \
       --intermediate-storage-path=gs://my-intermediary-bucket
   

¿Qué sigue?

• Obtén más información sobre la administración de trabajos.