在檔案系統之間轉移資料

本頁面說明如何在兩個 POSIX 檔案系統之間移轉資料。常見用途包括:

  • 高載至雲端和混合式 HPC:快速將大型資料集從地端部署環境轉移至雲端進行處理。
  • 遷移及同步至 Filestore:將資料從地端部署檔案系統遷移或同步至 Filestore。
  • 代管檔案傳輸:在資料中心之間或兩個雲端檔案系統之間,安全可靠地傳輸資料。

轉移效能指南

下列指南有助於在檔案系統之間移轉時,發揮最大效能。

部署代理

一般來說,建議在來源和目的地代理程式集區中,各使用三個代理程式。監控移轉作業,並視需要新增更多代理程式。每個代理程式需要 4 個 vCPU 和 8 GiB RAM。

如要遷移至 Filestore 執行個體,Filestore 建議為每個代理程式使用 n2-standard-8 執行個體類型。將執行個體掛接至 Compute Engine VM 時,請指定 nconnect=2。如要進一步瞭解如何最佳化調整及測試執行個體效能,請參閱 Filestore 的效能指南。

轉移大量小型檔案

如要在移轉大量小型檔案時提升效能,建議您將檔案分割至多個目錄,並避免單一目錄中含有數百萬個檔案。

事前準備

您必須先完成必要步驟並設定必要權限,才能執行本頁所述的工作:

建立代理集區並安裝代理

如要執行檔案系統對檔案系統的移轉作業,您必須為來源和目的地檔案系統建立代理程式集區和代理程式。來源代理集區的代理必須安裝在可存取來源檔案系統的機器或 VM 上。目的地代理程式集區的代理程式,必須安裝在可存取目的地檔案系統的機器或 VM 上。

建立來源代理程式集區

使用下列任一方法建立來源代理程式集區:

gcloud CLI

執行下列指令,建立來源代理程式集區:

gcloud transfer agent-pools create SOURCE_AGENT_POOL

將 SOURCE_AGENT_POOL 替換為要指派給來源代理程式集區的名稱。

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent pools」(代理程式集區) 頁面。

    前往「Agent pools」(代理程式集區) 頁面

    系統會顯示「Agent pools」(代理程式集區) 頁面,列出您現有的代理程式集區。

  2. 按一下「建立其他集區」。

  3. 輸入集區名稱。

  4. 點選「建立」。

為來源代理程式集區安裝代理程式

在可存取來源檔案系統的機器或 VM 上,安裝來源代理程式集區的代理程式:

gcloud CLI

執行下列指令,為來源代理程式集區安裝代理程式:

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

更改下列內容:

  • 將 SOURCE_AGENT_POOL 替換為來源代理程式集區的名稱。
  • NUMBER_OF_AGENTS:要為來源代理程式集區安裝的代理程式數量。如要判斷環境的最佳代理程式數量,請參閱「代理程式需求和最佳做法」。
  • MOUNT_DIRECTORIES:來源檔案系統上要複製的目錄,以逗號分隔的清單。如果省略這個旗標,系統會掛接整個檔案系統,這可能造成安全性風險。

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent pools」(代理程式集區) 頁面。

    前往「Agent pools」(代理程式集區) 頁面

    系統會顯示「Agent pools」(代理程式集區) 頁面,列出您現有的代理程式集區。

  2. 按一下您剛建立的來源代理程式集區名稱。

  3. 在「代理程式」分頁中,點選「安裝代理程式」。

  4. 請按照 Google Cloud 控制台中的操作說明安裝 Docker 並啟動代理程式。

建立目的地代理程式集區並安裝代理程式

重複上述步驟,建立目的地代理程式集區並安裝代理程式。

建立 Cloud Storage bucket 做為中介

檔案系統之間的移轉作業需要 Cloud Storage bucket 做為資料移轉的中介。

  1. 建立 Cloud Storage Standard 級別 bucket,並採用下列設定:

    • 加密:您可以指定客戶自行管理的加密金鑰 (CMEK)。否則,系統會使用Google-owned and Google-managed encryption key 。
    • 物件版本管理、Bucket Lock 和預設物件保留:請勿啟用這些功能。
  2. 將中繼 bucket 的必要角色,授予 Storage 移轉服務代理,以及來源和目的地移轉代理帳戶。請按照「中繼 bucket 權限」中的指示操作。

建立移轉工作

gcloud CLI

如要建立從來源檔案系統到目的地檔案系統的移轉作業,請執行

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

請替換下列變數:

  • SOURCE_DIRECTORY:來源目錄的路徑。
  • DESTINATION_DIRECTORY:目的地目錄的路徑。
  • 將 SOURCE_AGENT_POOL 替換為來源代理程式集區的名稱。
  • DESTINATION_AGENT_POOL:目的地代理程式集區的名稱。
  • STORAGE_BUCKET:Cloud Storage bucket 的名稱。
  • FOLDER:要將資料移轉至的資料夾名稱。

啟動移轉工作時,系統會先計算來源和目的地中的資料,判斷自上次移轉以來,來源資料是否有新增或更新。系統只會轉移新資料。

用戶端程式庫

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

管理中介 bucket

移轉工作完成後,Storage 移轉服務會儲存移轉記錄,列出 bucket 中已移轉和未移轉的資料。移轉作業完成後,系統會自動啟動清理工作,刪除中繼資料。在某些情況下,清理工作無法刪除 bucket 中的所有資料。如要刪除清理期間未清除的資料,請按照下列操作說明手動刪除資料,或設定生命週期規則自動刪除資料。

手動清理

根據要刪除的資料類型,執行下列指令,從中介 bucket 刪除資料。

  • 如要清除中介 bucket 中未在清理期間刪除的資料,請執行下列指令:

    gcloud storage rm gs://STORAGE_BUCKET/PREFIX**
    
  • 如要刪除所有資料 (包括移轉記錄),請使用 ** 萬用字元指定 bucket 的根目錄:

    gcloud storage rm gs://STORAGE_BUCKET/**
    
  • 如要刪除 bucket,請執行下列指令:

    gcloud storage rm --recursive gs://STORAGE_BUCKET
    

請替換下列變數:

  • STORAGE_BUCKET:中介 bucket 的名稱。

  • PREFIX:中繼 bucket 內,資料移轉至的資料夾名稱。

設定生命週期規則

如要刪除自動清理週期未清除的資料,請為 Cloud Storage bucket 設定生命週期規則。使用 age 條件,指定比使用值區做為中介的最長移轉工作更長的時間,藉此清除值區中的中介資料。如果指定的保留時間條件短於從中繼 bucket 下載檔案至目的地所需的時間,檔案移轉作業就會失敗。

您可以視需要使用 matchesPrefix 條件,清除您為中繼 bucket 指定的資料夾中的資料。如要刪除移轉記錄和 bucket 中的資料,則不需要 matchesPrefix 條件。

保留檔案中繼資料

如要保留檔案中繼資料,包括數字 UID、GID、MODE 和符號連結,請按照下列步驟操作:

gcloud CLI

使用 --preserve-metadata 欄位,指定這項移轉作業的保留行為。適用於檔案系統移轉作業的選項包括:gid、mode、symlink、uid。

REST API

在 metadataOptions 物件中指定適當選項。

詳情請參閱「保留選用的 POSIX 屬性」。

使用 gcloud CLI 轉移的範例

在這個範例中,我們會將資料從 VM1 上的 /tmp/datasource 目錄移轉至 VM2 上的 /tmp/destination。

  1. 設定移轉作業的來源。

    1. 建立來源代理程式集區:

      gcloud transfer agent-pools create source_agent_pool
      
    2. 在 VM1 執行下列指令,安裝 source_agent_pool 的代理程式:

      gcloud transfer agents install --pool=source_agent_pool \
          --count=1 \
          --mount-directories="/tmp/datasource"
      
  2. 設定移轉作業的目的地。

    1. 建立目的地代理程式集區:

      gcloud transfer agent-pools create destination_agent_pool
      
    2. 在 VM2 執行下列指令,安裝 destination_agent_pool 的代理程式:

      gcloud transfer agents install --pool=destination_agent_pool \
          --count=3 \
          --mount-directories="/tmp/destination"
      
  3. 建立中介 Cloud Storage bucket。

    1. 在 bucket 位置建立名為 my-intermediary-bucket 的 bucket:

      gcloud storage buckets create gs://my-intermediary-bucket --location=LOCATION
      

      將 LOCATION 替換為 bucket 的位置。

    2. 按照「中繼 bucket 權限」一節的說明,將 gs://my-intermediary-bucket 的必要角色授予服務代理和移轉代理帳戶。

  4. 執行下列指令,建立移轉工作:

    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
    

後續步驟