Transferir datos entre sistemas de archivos

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

  • Transferencia a la nube y HPC híbrida: transfiere rápidamente grandes conjuntos de datos de entornos locales a la nube para procesarlos.
  • Migración y sincronización con Filestore: migra o sincroniza datos de un sistema de archivos local a Filestore.
  • Transferencia de archivos gestionada: transfiere datos de forma segura y fiable entre centros de datos o entre dos sistemas de archivos en la nube.

Directrices de rendimiento de las transferencias

Las siguientes directrices pueden ayudarle a maximizar el rendimiento durante las transferencias de un sistema de archivos a otro.

Despliegue de agentes

Por lo general, recomendamos usar tres agentes en cada uno de los grupos de agentes de origen y de destino. Monitoriza la transferencia y añade más agentes si es necesario. Cada agente necesita 4 vCPUs y 8 GiB de RAM.

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

Transferir un gran número de archivos pequeños

Para mejorar el rendimiento al transferir un gran número de archivos pequeños, te recomendamos que dividas los archivos en varios directorios y que evites tener un solo directorio con millones de archivos.

Antes de empezar

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

Crear grupos de agentes e instalar agentes

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

No incluyas información sensible, como información personal identificable (IPI) o datos de seguridad, en el prefijo del 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 de tu proyecto.

Crear un grupo de agentes de origen

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

CLI de gcloud

Crea un grupo de agentes de origen ejecutando el siguiente comando:

gcloud transfer agent-pools create SOURCE_AGENT_POOL

Sustituye SOURCE_AGENT_POOL por el nombre que quieras asignar al grupo de agentes de origen.

Google Cloud consola

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

    Ir a Grupos de agentes

    Se muestra la página Grupos de agentes, con los grupos de agentes que ya tienes.

  2. Haz clic en Crear otro grupo.

  3. Introduce un nombre para el grupo.

  4. Haz clic en Crear.

Instalar agentes para el grupo de agentes de origen

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

CLI de gcloud

Instala agentes para el grupo de agentes de origen ejecutando el siguiente comando:

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

Haz los cambios siguientes:

  • SOURCE_AGENT_POOL con el nombre del grupo de agentes de origen.
  • NUMBER_OF_AGENTS con el número de agentes que quieras instalar en el grupo de agentes de origen. Para determinar el número óptimo de agentes para tu entorno, consulta los requisitos y las prácticas recomendadas para agentes.
  • MOUNT_DIRECTORIES con una lista de directorios separados por comas en el sistema de archivos de origen desde el que se copiarán los archivos. Si se omite esta marca, se monta todo el sistema de archivos, lo que podría suponer un riesgo de seguridad.

Google Cloud consola

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

    Ir a Grupos de agentes

    Se muestra la página Grupos de agentes, con los grupos de agentes que ya tienes.

  2. Haga clic en el nombre del grupo de agentes de origen que acaba de crear.

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

  4. Sigue las instrucciones de la Google Cloud consola para instalar Docker e iniciar el agente.

Crear un grupo de agentes de destino e instalar agentes

Repite los pasos anteriores para crear un grupo de agentes de destino e instalar agentes.

Crear un segmento de Cloud Storage como intermediario

Para transferir datos de un sistema de archivos a otro, se necesita un segmento de Cloud Storage como intermediario.

  1. Crea un segmento de clase Standard de Cloud Storage con los siguientes ajustes:

    • Cifrado: puedes especificar una clave de cifrado gestionada por el cliente (CMEK). De lo contrario, se usaGoogle-owned and Google-managed encryption key .
    • Gestión de versiones de objetos, Bloqueo de segmentos y bloqueos de objetos predeterminados: mantén estas funciones inhabilitadas.
  2. Asigna permisos y roles mediante uno de los siguientes métodos:

    • Asigna a la cuenta de servicio de Servicio de transferencia de Storage el rol Administrador de Storage (roles/storage.admin) del segmento.
    • Usa gcloud transfer authorize para autorizar tu cuenta en todas las funciones de Storage Transfer Service. Este comando concede permisos de administrador de Storage en todo el proyecto:

      gcloud transfer authorize --add-missing
      

Crear una tarea de transferencia

CLI de gcloud

Para crear una transferencia del sistema de archivos de origen al de destino, ejecuta

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/

Sustituye las siguientes variables:

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

Cuando inicias una tarea de transferencia, el sistema primero calcula los datos de origen y de destino para determinar los datos de origen que son nuevos o que se han actualizado desde la transferencia anterior. Solo se transfieren los datos nuevos.

Bibliotecas de 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}")

Gestionar segmentos intermediarios

Una vez que se completa una tarea de transferencia, el Servicio de transferencia de Storage guarda registros de transferencia que muestran los datos transferidos y los que no se han podido transferir en el segmento. Una vez completada la transferencia, se inician automáticamente tareas de limpieza para eliminar los datos intermedios. En algunos casos, las tareas de limpieza no eliminan todos los datos del contenedor. Para eliminar los datos que no se borran durante la limpieza, sigue las instrucciones que se indican a continuación para eliminar los datos manualmente o para definir una regla de ciclo de vida que los elimine automáticamente.

Limpieza manual

Elimina los datos del contenedor intermediario ejecutando los siguientes comandos en función del tipo de datos que quieras eliminar.

  • Para borrar los datos del bucket intermediario que no se hayan eliminado durante la limpieza, ejecuta el siguiente comando:

    gcloud storage rm gs://STORAGE_BUCKET/PREFIX**
    
  • Para eliminar todos los datos, incluidos los registros de transferencia, especifica la raíz del contenedor mediante el comodín que coincide con todo (*).

    gcloud storage rm gs://STORAGE_BUCKET/*
    
  • Para eliminar el bucket, ejecuta el siguiente comando:

    gcloud storage rm gs://STORAGE_BUCKET
    

Sustituye las siguientes variables:

  • STORAGE_BUCKET con el nombre del segmento intermediario.

  • PREFIX con el nombre de la carpeta a la que se transfirieron los datos en el bucket intermediario.

Definir una regla de ciclo de vida

Para eliminar los datos que no se borran durante el ciclo de limpieza automática, define una regla de ciclo de vida para el segmento de Cloud Storage. Usa la condición age para borrar los datos intermedios del segmento. Para ello, especifica un periodo más largo que la tarea de transferencia más larga que use el segmento como intermediario. Si la condición de antigüedad especificada es inferior al tiempo necesario para descargar el archivo del bucket intermediario al destino, la transferencia del archivo fallará.

De forma opcional, puede usar la condición matchesPrefix para borrar los datos de la carpeta que haya especificado para el segmento intermedio. Para eliminar los registros de transferencia junto con los datos del contenedor, no es necesario que se cumpla la condición matchesPrefix.

Conservar los metadatos de los archivos

Para conservar los metadatos de los archivos, incluidos los UID y GID numéricos, el MODE y los enlaces simbólicos, sigue estos pasos:

CLI de gcloud

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 REST

Especifica las opciones adecuadas en un objeto metadataOptions.

Para obtener más información, consulta el artículo sobre cómo conservar atributos POSIX opcionales.

Ejemplo de transferencia con la CLI gcloud

En este ejemplo, transferimos datos del directorio /tmp/datasource de la VM1 al directorio /tmp/destination de la VM2.

  1. Configura la fuente 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 de source_agent_pool ejecutando el 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 de destination_agent_pool ejecutando el siguiente comando:

      gcloud transfer agents install --pool=destination_agent_pool \
          --count=3 \
          --mount-directories="/tmp/destination"
      
  3. Crea un segmento de Cloud Storage intermediario.

    1. Crea un segmento llamado my-intermediary-bucket:

      gcloud storage buckets create gs://my-intermediary-bucket
      
    2. Autoriza tu cuenta para todas las funciones del Servicio de transferencia de Storage ejecutando el siguiente comando:

      gcloud transfer authorize --add-missing
      
  4. Para crear una tarea de transferencia, ejecuta el siguiente comando:

    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
    

Siguientes pasos