管理轉移代理程式

Storage 移轉服務代理程式是執行在 Open Container Initiative (OCI) 容器內的應用程式，可與 Storage 移轉服務協調，處理涉及檔案系統或與 S3 相容的儲存空間的移轉作業。

根據預設，Storage 移轉服務會使用 Docker 建構及執行 OCI 容器。Storage 移轉服務也支援 Podman 來管理容器；您必須使用 podman run 指令安裝代理程式，才能使用 Podman。

如果轉移作業不涉及檔案系統或與 S3 相容的儲存空間，您就不需要設定代理程式。

本文說明如何在伺服器上管理移轉代理程式。

總覽

  • 代理程式程序是動態的，執行轉移作業時，您可以新增代理程式來提升效能。新啟動的代理程式會加入指派的代理程式集區，並執行現有轉移作業的工作。您可以使用這項功能調整執行中的服務專員人數，或是根據變動的轉接需求調整轉接效能。

  • 代理程式處理程序是具備容錯功能的集合。如果某個代理程式停止執行，其餘代理程式會繼續執行工作。如果所有代理程式都停止運作，當您新增代理程式時，系統會從代理程式停止運作的位置繼續執行轉移作業。這樣一來，您就能避免監控代理程式、重試轉移作業或實作復原邏輯。您可以與 Google Kubernetes Engine 協調代理程式，在無轉移停機時間的情況下，對代理程式資源池進行修補、移動及動態調整。

    舉例來說，您在兩個服務專員執行時提交兩次轉移作業。如果其中一個代理程式因機器重新啟動或作業系統修補而停止運作，其他代理程式會繼續運作。兩個轉移作業仍在執行，但速度較慢，因為只有一個代理程式在移動資料。如果剩餘的代理程式也停止運作，則所有轉移作業都會停止進行，因為沒有任何代理程式在執行。重新啟動代理程式後，轉移作業會從上次中斷的地方接續進行。

  • 代理程式程序屬於集區。並同時移動您的資料。因此，集區中的所有代理程式都必須擁有相同的存取權，才能存取您要移轉的所有資料來源。

    舉例來說，如果您要從特定檔案系統轉移資料，就必須將檔案系統掛載至代理程式集區中每部代管代理程式的機器。如果資源池中的部分服務代理人可以存取資料來源，而其他服務代理人無法存取，則無法從該資料來源進行轉移。

事前準備

設定轉移作業前，請確認您已設定以下存取權：使用者和服務帳戶。

如果您要使用 gcloud 指令，請安裝 gcloud CLI。

安裝及執行轉移代理程式

建議您為每個代理程式集區安裝至少三個代理程式，最好是安裝在不同的機器上。如要進一步瞭解如何決定要執行的代理程式數量，請參閱「發揮轉移代理程式最佳效能」。

請勿在服務專員 ID 前置字串中加入個人識別資訊 (PII) 或安全性資料等機密資訊。資源名稱可能會傳播至其他 Google Cloud 資源的名稱，並可能會公開給專案以外的 Google 內部系統。

如何安裝及執行轉移代理程式：

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent pools」頁面。

    前往「代理程式集區」

  2. 選取要新增新代理程式的代理程式集區。

  3. 按一下「安裝代理程式」。

  4. 按照操作說明安裝及執行這個代理程式。

    如要進一步瞭解代理程式指令列選項，請參閱「代理程式指令列選項」。

gcloud CLI

如要使用 gcloud CLI 安裝一或多個代理程式，請執行 gcloud transfer agents install：

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

這項工具會引導您完成安裝代理程式所需的所有步驟。這項指令會在您的電腦上安裝 NUM_AGENTS 代理程式，並將其對應至以 POOL_NAME 指定的資源池名稱，然後使用您的 gcloud 憑證驗證代理程式。集區名稱必須存在，否則系統會傳回錯誤。

--mount-directories 標記為選用，但強烈建議使用。其值是檔案系統中要授予代理程式存取權的目錄清單，以半形逗號分隔。省略此標記會將整個檔案系統掛接至代理程式容器。詳情請參閱 gcloud 參考資料。

與 S3 相容的來源

在安裝與 S3 相容來源搭配使用的代理程式時，您必須提供 AWS 憑證，做為 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 的值使用環境變數，或儲存在系統設定檔中的預設憑證。

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

使用服務帳戶金鑰

如要使用服務帳戶金鑰執行代理程式，請使用 --creds-file 選項：

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

更多資訊

如需完整的選用標記清單，請執行 gcloud transfer agents install --help 或參閱 gcloud transfer 參考資料。

Docker

使用 Docker 安裝代理程式前，請按照操作說明安裝 Docker。

docker run 指令會安裝一個代理程式。如要增加集區中的代理程式數量，請視需要重複執行這個指令。

安裝代理程式時，您可以選擇使用 gcloud 預設憑證或服務帳戶進行驗證。

預設憑證

如要讓 Docker 容器以您的 gcloud 預設憑證進行驗證，請執行以下指令來建立含有應用程式預設憑證檔案的 Docker 磁碟區：

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

接著，請使用下列指令安裝代理程式，並使用 --volumes-from 標記掛載 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

服務帳戶驗證

如要使用服務帳戶憑證安裝及執行轉移代理程式 docker run，請使用 --creds-file 標記指定 JSON 格式服務帳戶金鑰的路徑。

路徑必須以 /transfer_root 字串做為前置字串。

如要進一步瞭解服務帳戶金鑰，請參閱「建立及管理服務帳戶金鑰」。

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

選項和標記

請使用下列資訊取代上述範例中的變數：

  • HOST_DIRECTORY 是主機上要複製的目錄。您可以使用多個 -v 旗標，指定要從中複製的其他目錄。
  • CONTAINER_DIRECTORY 是代理程式容器中對應的目錄。必須與 HOST_DIRECTORY 相同。
  • PROJECT_ID 是託管轉移作業的專案 ID。
  • POOL_NAME 是安裝此服務專員的服務專員集區名稱。如果省略這個旗標，服務專員就會安裝至專案的 transfer_service_default 集區。

docker run 指令支援其他旗標。

  • --enable-mount-directory 會在容器的 /transfer_root 目錄下掛接整個檔案系統。如果指定 --enable-mount-directory，系統就不會套用使用 -v 標記的目錄限制。

  • --creds-file=CREDENTIAL_FILE 會指定 JSON 格式服務帳戶憑證檔案的路徑。除非您使用 --enable_mount_directory，否則必須：

    1. 使用 -v 旗標掛接憑證檔案。
    2. 將 /transfer_root 前置於 --creds-file 的路徑。

    例如：

    -v /tmp/key.json:/tmp/key.json \
--creds-file=/transfer_root/tmp/key.json

  • --enable-s3 會指定此代理程式用於從 S3 相容儲存空間進行移轉。使用這個選項安裝的代理程式無法用於從 POSIX 檔案系統進行傳輸。

  • 如果您要從 AWS S3 或與 S3 相容的儲存空間進行轉移，請使用環境變數傳遞存取金鑰 ID 和私密金鑰：

    -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY

  • --env HTTPS_PROXY=PROXY 會指定網路上的轉送 Proxy。PROXY 的值是 Proxy 伺服器的 HTTP 網址和通訊埠。請務必指定 HTTP 網址 (而非 HTTPS 網址)，以免在傳輸層安全標準 (TLS) 加密中造成雙重包裝要求。雙重包裝要求會阻止 Proxy 伺服器傳送有效的傳出要求。

  • --agent-id-prefix=ID_PREFIX 會指定可選的前置字串，並將其置於代理程式 ID 之前，以便在 Google Cloud 主控台中識別代理程式或其機器。使用前置字串時，代理人 ID 的格式為 prefix + hostname + Docker container ID。

  • --log-dir=LOGS_DIRECTORY 會修改代理程式寫入記錄檔的目錄。預設目錄為 /tmp/。

    如果您未指定 --enable_mount_directory，則必須在路徑前方加上 /transfer_root。例如：/transfer_root/logs。

  • --max-physical-mem=MAX_MEMORY：代理程式預設會使用最多 8 GiB 的系統記憶體。如果預設值不符合您的環境，您可以使用下列格式指定相關的最大記憶體用量：

    max-physical-mem 值 記憶體上限設定
    6g 6 GB
    6gb 6 GB
    6GiB 6 GiB

Podman

使用 Podman 安裝代理程式前，請先安裝 Podman：

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

安裝代理程式時，您可以選擇使用 gcloud 預設憑證或服務帳戶進行驗證。

預設憑證

如要讓代理程式容器以您的 Google Cloud CLI 預設憑證進行驗證，請執行以下指令，建立含有應用程式預設憑證檔案的磁碟區：

  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
  ```

Then use the following command to install an agent, using the
`--volumes-from` flag to mount the `gcloud-config` credentials volume.
The command installs one agent. To increase the number of agents in your
pool, re-run this command as many times as required.

```sh
  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
  ```

服務帳戶驗證

如要使用服務帳戶憑證安裝及執行轉移代理程式，請使用 --creds-file 旗標指定 JSON 格式服務帳戶金鑰的路徑。

路徑必須以 /transfer_root 字串做為前置字串。

如要進一步瞭解服務帳戶金鑰，請參閱「建立及管理服務帳戶金鑰」。

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

選項和標記

請使用下列資訊取代上述範例中的變數：

  • HOST_DIRECTORY 是主機上要複製的目錄。您可以使用多個 -v 旗標，指定要從中複製的其他目錄。
  • CONTAINER_DIRECTORY 是代理程式容器中對應的目錄。必須與 HOST_DIRECTORY 相同。
  • PROJECT_ID 是託管轉移作業的專案 ID。
  • POOL_NAME 是安裝此服務專員的服務專員集區名稱。如果省略這個旗標，服務專員就會安裝至專案的 transfer_service_default 集區。

podman run 指令支援其他旗標。

  • --enable-mount-directory 會在容器的 /transfer_root 目錄下掛接整個檔案系統。如果指定 --enable-mount-directory，系統就不會套用使用 -v 標記的目錄限制。

  • --creds-file=CREDENTIAL_FILE 會指定 JSON 格式服務帳戶憑證檔案的路徑。除非您使用 --enable_mount_directory，否則必須：

    1. 使用 -v 旗標掛接憑證檔案。
    2. 將 /transfer_root 前置於 --creds-file 的路徑。

    例如：

    -v /tmp/key.json:/tmp/key.json \
--creds-file=/transfer_root/tmp/key.json

  • --enable-s3 會指定此代理程式用於從 S3 相容儲存空間進行移轉。使用這個選項安裝的代理程式無法用於從 POSIX 檔案系統進行傳輸。

  • 如果您要從 AWS S3 或與 S3 相容的儲存空間進行轉移，請使用環境變數傳遞存取金鑰 ID 和私密金鑰：

    -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY

  • --env HTTPS_PROXY=PROXY 會指定網路上的轉送 Proxy。PROXY 的值是 Proxy 伺服器的 HTTP 網址和通訊埠。請務必指定 HTTP 網址 (而非 HTTPS 網址)，以免在傳輸層安全標準 (TLS) 加密中造成雙重包裝要求。雙重包裝要求會阻止 Proxy 伺服器傳送有效的傳出要求。

  • --agent-id-prefix=ID_PREFIX 會指定可選的前置字串，並將其置於代理程式 ID 之前，以便在 Google Cloud 主控台中識別代理程式或其機器。使用前置字串時，代理人 ID 的格式為 prefix + hostname + OCI container ID。

  • --log-dir=LOGS_DIRECTORY 會修改代理程式寫入記錄檔的目錄。預設目錄為 /tmp/。

    如果您未指定 --enable_mount_directory，則必須在路徑前方加上 /transfer_root。例如：/transfer_root/logs。

  • --max-physical-mem=MAX_MEMORY：代理程式預設會使用最多 8 GiB 的系統記憶體。如果預設值不符合您的環境，您可以使用下列格式指定相關的最大記憶體用量：

    max-physical-mem 值 記憶體上限設定
    6g 6 GB
    6gb 6 GB
    6GiB 6 GiB

疑難排解

如果 SELinux 設定要求將標籤放在已掛載至容器的磁碟區內容上，請在磁碟區中新增 :Z 標記：

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

如果沒有標籤，安全性系統可能會阻止在容器內執行的程序使用內容。根據預設，Podman 不會變更作業系統設定的標籤。

確認代理程式連線

如要確認代理程式是否已連線，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Agent pools」頁面。

    前往「代理程式集區」

    系統會顯示代理程式集區，以及已連線的代理程式數量。

  2. 選取代理程式集區，即可查看已連線代理程式的詳細資料。

如果新代理程式在建立後 10 分鐘內未顯示在代理程式集區頁面中，請參閱「代理程式未連線」一文。

監控服務專員活動

您可以使用 Cloud Monitoring 監控代理程式活動。

監控功能可沿著 project、agent_pool 和 agent_id 維度使用。

您可以利用這項監控資料設定快訊，在發生可能的轉移問題時收到通知。如要這麼做，請針對下列任一 Google Cloud 指標建立快訊：

指標名稱 說明 建議用途
storagetransfer.googleapis.com/agent/transferred_bytes_count 評估特定代理程式在某個時間點服務所有工作時，移動資料的速度。 發出效能下滑警示。
storagetransfer.googleapis.com/agent/connected 對於 Google Cloud最近收到心跳訊息的每個代理程式，此布林值為 True。
  • 失敗的服務專員快訊
  • 未達到您認為可提供合理效能的必要代理人數
  • 指出代理程式機器發生問題

停止服務專員

如要停止服務專員，請在服務專員的 Docker 容器 ID 上執行 docker stop。如何找出 ID 並停止代理程式：

  1. 前往 Google Cloud 控制台的「Agent pools」頁面。

    前往「代理程式集區」

  2. 選取含有要停止的代理程式的代理程式集區。

  3. 從清單中選取代理人。使用「Filter」欄位搜尋前置字串、操作員狀態、操作員年齡等。

  4. 按一下「停止服務代理」。系統會顯示含有特定容器 ID 的 docker stop 指令。

  5. 在代理程式執行的電腦上執行指令。成功的 docker stop 指令會傳回容器 ID。

停止後，服務專員會在服務專員集區清單中顯示為「已中斷連線」。

重新啟動代理程式

已停止的服務中介程無法重新啟動。請改為在代理程式集區中安裝新的代理程式。

刪除代理程式

如要刪除特定代理程式，請列出機器上執行的代理程式：

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

然後將代理程式 ID 傳遞至 transfer agents delete：

gcloud transfer agents delete --ids=id1,id2,…

如要刪除在電腦上執行的所有代理程式，請使用 --all 旗標或 --uninstall 旗標。這兩個標記都會刪除機器上的所有代理程式；--uninstall 標記還會解除安裝代理程式 Docker 映像檔。

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

檔案系統移轉詳細資料

增量轉移

Storage 移轉服務會先計算來源和目的地中的資料，藉此判斷上次轉移後新增、更新或刪除的來源檔案，然後開始所有轉移作業。這樣做是為了減少從您的機器傳送的資料量、有效使用頻寬，以及縮短傳輸時間。

為了偵測檔案是否已變更，我們會檢查來源檔案的上次修改時間和大小，並與檔案上次複製時記錄的上次修改時間和大小進行比較。當我們偵測到新的或已變更的檔案時，會將整個檔案複製到目的地。如要進一步瞭解檔案更新間隔，請參閱「資料一致性詳細資料」。

根據預設，我們會偵測來源檔案的刪除作業，但不會採取任何行動。如果您在建立或編輯時選擇「刪除來源中沒有的目的地檔案」同步選項，系統會在目的地刪除對應的物件。

如果您選擇「刪除來源中沒有的目的地檔案」同步選項，來源中不小心刪除的檔案也會從目的地刪除。為避免資料因誤刪而遺失，如果您選擇使用這個選項，建議您在目的地值區中啟用物件版本管理功能。這樣一來，如果您不小心刪除檔案，就能將 Cloud Storage 中的物件還原為舊版本。

資料一致性詳細資料

成功的轉移作業會轉移所有已存在且在整個作業執行期間未經修改的原始檔案。在傳輸期間建立、更新或刪除的來源檔案，可能會或不會反映在目的地資料集。

Storage 轉移服務會使用檔案的上次修改時間和大小，判斷檔案是否已變更。如果檔案更新時未變更上次修改時間或大小，且您啟用了 delete-objects-from-source 選項，則可能會因這項變更而遺失資料。

使用 delete-objects-from-source 功能時，強烈建議您在轉移期間凍結對來源的寫入作業，以免資料遺失。

如要凍結對來源的寫入作業，請執行下列任一操作：

  • 複製要轉移的目錄，然後使用複製的目錄做為轉移來源。
  • 停止寫入來源目錄的應用程式。

如果您需要擷取傳輸期間發生的變更，可以重新執行傳輸作業，或是在作業執行期間將來源檔案系統設為唯讀。

由於 Cloud Storage 沒有目錄概念，因此不會傳輸空白來源目錄。