使用副本複製磁碟

本文說明磁碟複製的運作方式，以及如何建立磁碟副本。磁碟複製功能可讓您在相同位置 (可用區或區域) 建立現有磁碟的可用副本。在需要現有磁碟副本並立即連接至 VM 的情況下，建立磁碟副本，例如：

  • 複製正式環境資料來建立測試環境，以便在不影響正式環境的情況下進行偵錯
  • 對磁碟執行不中斷的惡意軟體掃描，且不影響生產工作負載的效能
  • 建立副本以驗證資料庫備份
  • 將非開機磁碟資料移至新專案
  • 在擴充 VM 時複製磁碟

如要啟用資料的災難復原功能，請使用標準快照備份磁碟，而不是使用磁碟副本。如要定期擷取磁碟內容，但不想建立新磁碟，請使用即時快照，因為這類快照比副本更節省儲存空間。如需其他磁碟保護選項，請參閱「資料保護選項」。

事前準備

  • 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：

    選取這個頁面上的分頁，瞭解如何使用範例：

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。

    gcloud

    1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

      gcloud init

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  • 設定預設地區和區域。

    • Terraform

    如要在本機開發環境中使用本頁的 Terraform 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

    1. 安裝 Google Cloud CLI。

    2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

      gcloud auth application-default login

      如果您使用 Cloud Shell，則不需要執行這項操作。

      如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

    詳情請參閱 這篇文章，瞭解如何設定本機開發環境的驗證機制。

    Go

    如要在本機開發環境中使用本頁的 Go 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

    1. 安裝 Google Cloud CLI。

    2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

      gcloud auth application-default login

      如果您使用 Cloud Shell，則不需要執行這項操作。

      如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

    詳情請參閱 這篇文章，瞭解如何設定本機開發環境的驗證機制。

    Java

    如要在本機開發環境中使用本頁面的 Java 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

    1. 安裝 Google Cloud CLI。

    2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

      gcloud auth application-default login

      如果您使用 Cloud Shell，則不需要執行這項操作。

      如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

    詳情請參閱 這篇文章，瞭解如何設定本機開發環境的驗證機制。

    Python

    如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

    1. 安裝 Google Cloud CLI。

    2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

      gcloud auth application-default login

      如果您使用 Cloud Shell，則不需要執行這項操作。

      如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

    詳情請參閱 這篇文章，瞭解如何設定本機開發環境的驗證機制。

    REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

用途摘要

除了複製磁碟以進行快速測試和偵錯外，您也可以從可用區磁碟建立區域性副本，為可用區磁碟啟用高可用性。從區域磁碟建立地區磁碟時，地區磁碟會在同一地區內的兩個區域中，建立磁碟副本。建立地區磁碟後，請使用新的地區磁碟，而非區域磁碟。萬一某個可用區發生服務中斷，您仍可從其他可用區的副本存取資料。

下表摘要說明 Compute Engine 支援的不同類型複製作業。

複製類型 使用時機 支援的磁碟類型
從區域磁碟建立區域副本 在同一個可用區中建立磁碟的相同副本，以執行下列任一工作：
  • 複製現有磁碟，供新 VM 使用，藉此擴充工作負載。
  • 使用正式版資料的測試、偵錯或測試環境。
  • 掃描製作中的磁碟是否含有惡意軟體。
  • 將磁碟移至新專案。
  • 永久磁碟：標準、平衡和 SSD 永久磁碟
  • Hyperdisk：所有 Hyperdisk 類型，但 Hyperdisk Balanced High Availability 除外
區域磁碟的區域性副本
  • 在另一個可用區中新增資料副本，讓可用區工作負載具備高可用性。
  • 掃描製作中的磁碟是否含有惡意軟體。
  • 永久磁碟：標準、平衡和 SSD 永久磁碟
  • Hyperdisk：Hyperdisk Extreme 和 Hyperdisk Balanced
區域性磁碟的區域性副本 在相同區域中建立地區磁碟的相同副本，用於：
  • 測試或擴充區域性高可用性 (HA) 工作負載。
  • 執行管理工作或測試時，在兩個可用區之間維持資料備援。
  • 建立 HA 資料庫磁碟區副本以供驗證。
  • 永久磁碟：區域平衡型、SSD 和標準永久磁碟
  • Hyperdisk：Hyperdisk Balanced High Availability

磁碟複製的運作方式

複製磁碟時，系統會建立新磁碟，其中包含來源磁碟上的所有資料。即使現有磁碟已連接至 VM 執行個體，您仍可建立磁碟副本。複製磁碟後，您可以刪除來源磁碟，不必擔心會連帶刪除副本。

根據預設，磁碟的副本會沿用磁碟的大小、效能限制、類型，以及確切的可用區或區域。你可以變更部分屬性，方法如下：

  • 大小：您可以建立比來源磁碟大的副本，但無法建立比來源磁碟小的副本。

  • 效能：您可以為 Hyperdisk 磁碟區的副本指定不同的效能限制。區域性本機副本的可用區 Hyperdisk 磁碟區是 Hyperdisk Balanced High Availability 磁碟區，效能限制可能有所不同。

  • 位置：根據預設，系統會為區域磁碟在相同區域中建立磁碟副本，並為地區磁碟在相同地區中建立副本。不過，如要建立可用區磁碟的區域性副本，可以指定第二個可用區，該可用區必須與可用區磁碟位於同一區域。新副本也稱為區域副本，在來源磁碟的區域和您指定的第二個區域中，各有一個副本。

  • 類型：區域性本機副本的區域性 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區是 Hyperdisk Balanced High Availability 磁碟區。

從可用區 Hyperdisk 磁碟區複製的區域 Hyperdisk 磁碟區

現有可用區 Hyperdisk 磁碟區的區域性本機副本一律是新的 Hyperdisk Balanced High Availability 磁碟區。這是因為 Hyperdisk Balanced High Availability 是唯一支援的區域性 Hyperdisk。從區域 Hyperdisk 建立地區 Hyperdisk 的方式取決於其類型。

  • 對於區域性 Hyperdisk ML 和 Hyperdisk Throughput 磁碟區，您無法透過複製來源磁碟建立區域性磁碟。您必須從區域磁碟的快照建立新的 Hyperdisk Balanced High Availability 磁碟區。

  • 如要建立可用區 Hyperdisk Balanced 和 Hyperdisk Extreme 磁碟區，請建立可用區 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區的區域性本機副本，藉此建立新的 Hyperdisk Balanced High Availability 磁碟區。

從可用區磁碟複製的 Hyperdisk Balanced High Availability 磁碟區效能

從 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區建立新的 Hyperdisk Balanced High Availability 磁碟區時，新磁碟會沿用來源磁碟的大小，但您可以指定不同的大小。

新磁碟的佈建效能上限可能低於來源磁碟，因為如以下表格所示，Hyperdisk Extreme 和 Hyperdisk Balanced 的效能上限高於 Hyperdisk Balanced High Availability。

Hyperdisk 類型 每秒最大 I/O 作業數 (IOPS) 最大總處理量 ( MiB/秒)
Hyperdisk Balanced High Availability 100,000 2,400
Hyperdisk Balanced 160,000 2,400
Hyperdisk Extreme 350,000 5,000

您可以為新的區域磁碟指定限制，但不得超過 Hyperdisk Balanced High Availability 提供的效能上限，也就是 100,000 IOPS 和 2,400 MiB/s。

如未指定新磁碟的效能限制，Compute Engine 會根據 Hyperdisk Balanced High Availability 磁碟區的大小，為磁碟佈建預設 IOPS 和總處理量。如需預設限制，請參閱「Hyperdisk Balanced High Availability 的預設大小和效能限制」。

如要達到 100,000 IOPS，Hyperdisk Balanced High Availability 磁碟區的大小必須至少為 200 GiB，因此您可能也需要增加區域性本機副本的佈建大小。

範例

假設您佈建了 180,000 IOPS，150 GiB 的 Hyperdisk Extreme 磁碟區 hdx-1。

如果您建立 hdx-1 的區域性本機副本，但未指定新的大小或效能限制，Compute Engine 會建立 150 GiB 的 Hyperdisk Balanced High Availability 磁碟區，並套用該大小的預設 IOPS 限制：3,900 IOPS。

如未增加大小，區域複製磁碟最多可指定 75,000 IOPS。

從區域性 Persistent Disk 磁碟區複製的區域性 Persistent Disk 磁碟區

從區域永久磁碟複製的地區永久磁碟磁碟區，與複製來源的類型相同。舉例來說，如果您複製區域標準永久磁碟，就會建立區域標準永久磁碟磁碟區。

不過，永久磁碟卷宗的區域性副本大小和效能限制，可能與區域來源磁碟不同，如下所示。

  • 效能上限較低：永久磁碟的區域性副本的 IOPS 和總處理量效能上限，可能低於來源磁碟。這是因為區域永久磁碟提供較高的執行個體效能上限。舉例來說，區域性平衡型永久磁碟的寫入 IOPS 上限為 80,000，但區域平衡型永久磁碟的上限為 60,000。

    如需詳細效能限制，請比較區域永久磁碟的效能限制和地區永久磁碟的效能限制。

  • 地區標準永久磁碟的大小下限為 200 GiB：地區標準永久磁碟的大小下限為 200 GiB。因此，如要建立 10 到 199 GiB 區域標準永久磁碟磁碟區的地區複製磁碟，您必須為地區磁碟指定至少 200 GiB 的大小。

支援的磁碟類型

如果副本與來源磁碟位於相同位置 (區域或地區)，您可以複製所有永久磁碟和 Hyperdisk 類型。

將區域磁碟複製到地區磁碟時，僅支援下列磁碟類型：

  • Google Cloud Hyperdisk：

    • Hyperdisk Balanced
    • Hyperdisk Extreme

    如要從 Hyperdisk ML 或 Hyperdisk Throughput 磁碟區建立地區磁碟，請先建立快照，然後從快照建立 Hyperdisk Balanced High Availability 磁碟區。

  • Persistent Disk：

    • 平衡型永久磁碟
    • SSD 永久磁碟
    • 標準永久磁碟

限制

磁碟副本有下列限制：

  • 您無法透過複製可用區 Hyperdisk ML 或 Hyperdisk Throughput 磁碟區，建立 Hyperdisk Balanced High Availability 磁碟區。 如要為這些 Hyperdisk 類型建立 Hyperdisk Balanced High Availability 磁碟區，請完成「將可用區磁碟變更為區域性 Hyperdisk Balanced High Availability 磁碟區」一文中的步驟。
  • 您無法複製儲存空間集區中的磁碟。
  • 您無法在不同可用區中，建立現有可用區磁碟的可用區磁碟副本。
  • 複製的磁碟大小必須至少與來源磁碟相同。如果您使用 Google Cloud 控制台建立副本，則無法指定磁碟大小，副本會與來源磁碟大小相同。
  • 如果從 Google Cloud 控制台複製 Hyperdisk 或 Persistent Disk 磁碟區，則無法為複製的磁碟指定佈建的效能。
  • 如果使用客戶提供的加密金鑰 (CSEK) 或客戶自行管理的加密金鑰 (CMEK) 加密來源磁碟，則必須使用相同金鑰加密副本。詳情請參閱「建立加密來源磁碟的副本」。
  • 建立來源磁碟的副本時，無法刪除來源磁碟。
  • 建立複製磁碟時，來源磁碟所連線的運算執行個體無法開機。
  • 如果來源磁碟已標示為要與所連 VM 一併刪除，則在建立副本時，您無法刪除 VM。
  • 每 30 秒最多可建立一個來源磁碟或其副本的副本。
  • 特定來源磁碟或其副本最多可同時複製 1,000 次。如果超出這項限制，系統會傳回 internalError。 不過，如果您建立磁碟副本，然後刪除副本，則刪除的磁碟副本不會計入這項限制。
  • 磁碟複製完成後，該磁碟或其副本的後續副本會計入原始來源磁碟的 1,000 個同步磁碟副本上限，以及每 30 秒最多建立一個副本的上限。
  • 如果您是透過複製區域磁碟來建立區域磁碟，則每 15 分鐘最多可複製 1 TiB 的容量，爆量要求上限為 257 TiB。
  • 您無法從區域性磁碟建立區域磁碟副本。
  • 如要從區域來源磁碟建立區域磁碟副本，區域磁碟副本的其中一個副本可用區必須與來源磁碟的可用區相符。
  • 建立完成後，平均 3 分鐘內即可使用地區磁碟副本。不過，磁碟可能需要數十分鐘才能完成複製，並達到復原點目標 (RPO) 接近零的狀態。
  • 如果您是從映像檔建立區域磁碟，就無法使用該區域磁碟建立地區磁碟副本。

錯誤訊息

如果超過複製頻率限制，要求會失敗並顯示下列錯誤：

RATE LIMIT: ERROR: (gcloud.compute.disks.create) Could not fetch resource:
 - Operation rate exceeded for resource RESOURCE. Too frequent operations from the source resource.

建立磁碟副本

本節說明如何複製現有磁碟並建立磁碟副本。

如需詳細步驟，請根據建立的磁碟副本類型，參閱本文的下列任一節：

在與來源相同的位置建立磁碟副本

您可以使用Google Cloud 控制台、Google Cloud CLI、REST 或 Cloud 用戶端程式庫，分別複製與來源磁碟位於相同可用區或區域的現有可用區或區域磁碟。

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Disks」(磁碟) 頁面。

    前往「Disks」(磁碟) 頁面

  2. 在磁碟清單中，找出要複製的磁碟。

  3. 在「Actions」(動作) 欄中，按一下 選單按鈕，然後選取「Clone disk」(複製磁碟)。

    建立本機副本。

    在隨即顯示的「Clone disk」(複製磁碟) 面板中，執行下列操作：

    1. 在「Name」(名稱) 欄位中，指定複製磁碟的名稱。
    2. 選用：如果是可用區磁碟，請在「位置」下方確認已選取「單一可用區」。
    3. 在「屬性」下方，查看複製磁碟的其他詳細資料。
    4. 如要完成複製磁碟的建立程序，請按一下「Create」(建立)。

Google Cloud CLI

如要複製區域來源磁碟並建立新的區域磁碟，請執行 disks create 指令，並指定 --source-disk 旗標：

gcloud compute disks create TARGET_DISK_NAME \
    --description="cloned disk" \
    --source-disk=projects/PROJECT_ID/zones/ZONE/disks/SOURCE_DISK_NAME

更改下列內容：

  • TARGET_DISK_NAME：新磁碟的名稱。
  • PROJECT_ID：您要複製磁碟的專案 ID。
  • ZONE：來源磁碟和新磁碟的可用區。
  • SOURCE_DISK_NAME：來源磁碟的名稱。

Terraform

如要建立磁碟副本，請使用 google_compute_disk 資源。

resource "google_compute_disk" "default" {
  name  = "disk-name1"
  type  = "pd-ssd"
  zone  = "us-central1-a"
  image = "debian-11-bullseye-v20220719"
  labels = {
    environment = "dev"
  }
  physical_block_size_bytes = 4096
}

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

Go

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Compute Engine Go API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// createDiskFromDisk creates a new disk with the contents of
// an already existitng disk. Type, and size and zone may differ.
func createDiskFromDisk(
	w io.Writer,
	projectID, zone, diskName, diskType, sourceDiskLink string,
	diskSizeGb int64,
) error {
	// projectID := "your_project_id"
	// zone := "us-west3-b" // should match diskType below
	// diskName := "your_disk_name"
	// diskType := "zones/us-west3-b/diskTypes/pd-ssd"
	// sourceDiskLink := "projects/your_project_id/global/disks/disk_name"
	// diskSizeGb := 120

	ctx := context.Background()
	disksClient, err := compute.NewDisksRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewDisksRESTClient: %w", err)
	}
	defer disksClient.Close()

	req := &computepb.InsertDiskRequest{
		Project: projectID,
		Zone:    zone,
		DiskResource: &computepb.Disk{
			Name:       proto.String(diskName),
			Zone:       proto.String(zone),
			Type:       proto.String(diskType),
			SourceDisk: proto.String(sourceDiskLink),
			SizeGb:     proto.Int64(diskSizeGb),
		},
	}

	op, err := disksClient.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create disk: %w", err)
	}

	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}

	fmt.Fprintf(w, "Disk created\n")

	return nil
}

Java

Java

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Compute Engine Java API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。


import com.google.cloud.compute.v1.Disk;
import com.google.cloud.compute.v1.DisksClient;
import com.google.cloud.compute.v1.Operation;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateFromSource {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String project = "YOUR_PROJECT_ID";

    // Name of the zone in which you want to create the disk.
    String zone = "europe-central2-b";

    // Name of the disk you want to create.
    String diskName = "YOUR_DISK_NAME";

    // The type of disk you want to create. This value uses the following format:
    // "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
    // For example: "zones/us-west3-b/diskTypes/pd-ssd"
    String diskType = String.format("zones/%s/diskTypes/pd-ssd", zone);

    // Size of the new disk in gigabytes.
    int diskSizeGb = 10;

    // A link to the disk you want to use as a source for the new disk.
    // This value uses the following format:
    // "projects/{project_name}/zones/{zone}/disks/{disk_name}"
    String diskLink = String.format("projects/%s/zones/%s/disks/%s", "PROJECT_NAME", "ZONE",
        "DISK_NAME");

    createDiskFromDisk(project, zone, diskName, diskType, diskSizeGb, diskLink);
  }

  // Creates a disk in a project in a given zone.
  public static void createDiskFromDisk(String project, String zone, String diskName,
      String diskType, int diskSizeGb, String diskLink)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // 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 `disksClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (DisksClient disksClient = DisksClient.create()) {

      // Create the disk.
      Disk disk = Disk.newBuilder()
          .setZone(zone)
          .setSizeGb(diskSizeGb)
          .setSourceDisk(diskLink)
          .setType(diskType)
          .setName(diskName)
          .build();

      // Wait for the insert instance operation to complete.
      Operation operation = disksClient.insertAsync(project, zone, disk)
          .get(3, TimeUnit.MINUTES);

      if (operation.hasError()) {
        System.out.println("Disk creation failed!");
        throw new Error(operation.getError().toString());
      }
      System.out.println(
          "Disk created from source. Operation Status: " + operation.getStatus());
    }
  }
}

Python

Python

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Compute Engine Python API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

from __future__ import annotations

import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def create_disk_from_disk(
    project_id: str,
    zone: str,
    disk_name: str,
    disk_type: str,
    disk_size_gb: int,
    disk_link: str,
) -> compute_v1.Disk:
    """
    Creates a disk in a project in a given zone.

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        zone: name of the zone in which you want to create the disk.
        disk_name: name of the disk you want to create.
        disk_type: the type of disk you want to create. This value uses the following format:
            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
            For example: "zones/us-west3-b/diskTypes/pd-ssd"
        disk_size_gb: size of the new disk in gigabytes
        disk_link: a link to the disk you want to use as a source for the new disk.
            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"

    Returns:
        An attachable disk.
    """
    disk_client = compute_v1.DisksClient()
    disk = compute_v1.Disk()
    disk.zone = zone
    disk.size_gb = disk_size_gb
    disk.source_disk = disk_link
    disk.type_ = disk_type
    disk.name = disk_name
    operation = disk_client.insert(project=project_id, zone=zone, disk_resource=disk)

    wait_for_extended_operation(operation, "disk creation")

    return disk_client.get(project=project_id, zone=zone, disk=disk_name)

REST

如要複製區域來源磁碟並建立新的區域磁碟，請向 compute.disks.insert 方法提出 POST 要求。在要求主體中，指定 name 和 sourceDisk 參數。磁碟副本會從來源磁碟繼承所有省略的屬性。

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks

{
  "name": "TARGET_DISK_NAME"
  "sourceDisk": "projects/PROJECT_ID/zones/ZONE/disks/SOURCE_DISK_NAME"
}

更改下列內容：

  • PROJECT_ID：您要複製磁碟的專案 ID。
  • ZONE：來源磁碟和新磁碟的可用區。
  • TARGET_DISK_NAME：新磁碟的名稱。
  • SOURCE_DISK_NAME：來源磁碟的名稱

從區域磁碟建立地區磁碟副本

您可以複製現有的可用區磁碟，建立新的區域性磁碟，但僅限下列類型：

  • Hyperdisk Balanced
  • Hyperdisk Extreme
  • 標準、平衡和 SSD 永久磁碟

如果來源磁碟是 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區，區域性磁碟一律為 Hyperdisk Balanced High Availability 磁碟區，不會沿用區域性磁碟的相同佈建效能。如要設定區域磁碟的佈建效能，您必須使用 Google Cloud CLI 或 REST 複製磁碟。如果使用 Google Cloud 控制台複製磁碟，您無法指定效能上限，系統會根據磁碟大小佈建預設上限。

控制台

  1. 前往 Google Cloud 控制台的「Disks」(磁碟) 頁面。

    前往「Disks」(磁碟) 頁面

  2. 在磁碟清單中，找出要複製的區域永久磁碟磁碟區。

  3. 在「Actions」(動作) 欄中，按一下 選單按鈕，然後選取「Clone disk」(複製磁碟)。

    建立本機副本。

    在隨即顯示的「Clone disk」(複製磁碟) 面板中，執行下列操作：

    1. 在「Name」(名稱) 欄位中，指定複製磁碟的名稱。
    2. 在「位置」下方選取「區域」，然後為新的區域複製磁碟選取次要副本可用區。
    3. 在「屬性」下方，查看複製磁碟的其他詳細資料。
    4. 如要完成複製磁碟的建立程序，請按一下「Create」(建立)。

gcloud

如要從區域磁碟建立地區磁碟副本，請執行 gcloud compute disks create 指令，並指定 --region 和 --replica-zones 參數。

如果可用區磁碟是 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區，請指定 --disk-type=hyperdisk-balanced-high-availability 旗標，因為區域性磁碟必須是 Hyperdisk Balanced High Availability 磁碟區。

如要複製 Persistent Disk 磁碟區，請省略 --disk-type 旗標。

gcloud compute disks create TARGET_DISK_NAME \
  --description="zonal to regional cloned disk" \
  --region=CLONED_REGION \
  --source-disk=SOURCE_DISK_NAME \
  --source-disk-zone=SOURCE_DISK_ZONE \
  --replica-zones=SOURCE_DISK_ZONE,REPLICA_ZONE_2 \
  --project=PROJECT_ID \
  [ --disk-type=hyperdisk-balanced-high-availability ] \
  [ --provisioned-iops=IOPS_LIMIT ] \
  [ --provisioned-throughput=THROUGHPUT_LIMIT ]

更改下列內容：

  • TARGET_DISK_NAME：新區域磁碟副本的名稱。
  • CLONED_REGION：來源和複製磁碟的區域。
  • SOURCE_DISK_NAME：要複製的區域磁碟名稱。
  • SOURCE_DISK_ZONE：來源磁碟的可用區。這也會是地區磁碟副本的第一個副本可用區。
  • REPLICA_ZONE_2：新地區磁碟副本的第二個副本區域。
  • PROJECT_ID：您要複製磁碟的專案 ID。
  • IOPS_LIMIT：選用：如要建立區域 Hyperdisk Balanced High Availability 磁碟，您可以指定磁碟可處理的 IOPS 數量，最多為 100,000 IOPS。
  • THROUGHPUT_LIMIT：選用：如要建立區域性 Hyperdisk Balanced High Availability 磁碟，您可以指定磁碟可提供的最大處理量 (單位為 MiB/秒)，上限為 2,400 MiB/秒。

Terraform

如要從區域磁碟建立地區磁碟副本，請使用下列資源。如果來源磁碟是 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區，請將 type 引數設為 hyperdisk-balanced-high-availability。

resource "google_compute_region_disk" "regiondisk" {
  name                      = "region-disk-name"
  snapshot                  = google_compute_snapshot.snapdisk.id
  type                      = "pd-ssd"
  region                    = "us-central1"
  physical_block_size_bytes = 4096
  size                      = 11

  replica_zones = ["us-central1-a", "us-central1-f"]
}

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

Go

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Compute Engine Go API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// createRegionalDiskFromDisk creates a new regional disk with the contents of
// an already existitng zonal disk. Disk type and size may differ.
func createRegionalDiskFromDisk(
	w io.Writer,
	projectID, region string, replicaZones []string,
	diskName, diskType, sourceDiskLink string,
	diskSizeGb int64,
) error {
	// projectID := "your_project_id"
	// region := "us-west3" // should match diskType below
	// diskName := "your_disk_name"
	// diskType := "regions/us-west3/diskTypes/pd-ssd"
	// sourceDiskLink := "projects/your_project_id/global/disks/disk_name"
	// diskSizeGb := 120

	// Exactly two replica zones must be specified
	replicaZoneURLs := []string{
		fmt.Sprintf("projects/%s/zones/%s", projectID, replicaZones[0]),
		fmt.Sprintf("projects/%s/zones/%s", projectID, replicaZones[1]),
	}

	ctx := context.Background()
	disksClient, err := compute.NewRegionDisksRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewRegionDisksRESTClient: %w", err)
	}
	defer disksClient.Close()

	req := &computepb.InsertRegionDiskRequest{
		Project: projectID,
		Region:  region,
		DiskResource: &computepb.Disk{
			Name:         proto.String(diskName),
			Region:       proto.String(region),
			Type:         proto.String(diskType),
			SourceDisk:   proto.String(sourceDiskLink),
			SizeGb:       proto.Int64(diskSizeGb),
			ReplicaZones: replicaZoneURLs,
		},
	}

	op, err := disksClient.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create disk: %w", err)
	}

	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}

	fmt.Fprintf(w, "Disk created\n")

	return nil
}

Java

Java

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Compute Engine Java API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。


import com.google.cloud.compute.v1.Disk;
import com.google.cloud.compute.v1.Operation;
import com.google.cloud.compute.v1.RegionDisksClient;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RegionalCreateFromSource {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String project = "YOUR_PROJECT_ID";

    // Name of the zone in which you want to create the disk.
    String region = "europe-central2";

    // An iterable collection of zone names in which you want to keep
    // the new disks' replicas. One of the replica zones of the clone must match
    // the zone of the source disk.
    List<String> replicaZones = new ArrayList<>();

    // Name of the disk you want to create.
    String diskName = "YOUR_DISK_NAME";

    // The type of disk you want to create. This value uses the following format:
    // "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
    // For example: "zones/us-west3-b/diskTypes/pd-ssd"
    String diskType = String.format("zones/%s/diskTypes/pd-ssd", "ZONE_NAME");

    // Size of the new disk in gigabytes.
    int diskSizeGb = 10;

    // A link to the disk you want to use as a source for the new disk.
    // This value uses the following format:
    // "projects/{project_name}/zones/{zone}/disks/{disk_name}"
    String diskLink = String.format("projects/%s/zones/%s/disks/%s", "PROJECT_NAME", "ZONE",
        "DISK_NAME");

    // A link to the snapshot you want to use as a source for the new disk.
    // This value uses the following format:
    // "projects/{project_name}/global/snapshots/{snapshot_name}"
    String snapshotLink = String.format("projects/%s/global/snapshots/%s", "PROJECT_NAME",
        "SNAPSHOT_NAME");

    createRegionalDisk(project, region, replicaZones, diskName, diskType, diskSizeGb,
        Optional.ofNullable(diskLink), Optional.ofNullable(snapshotLink));
  }

  // Creates a regional disk from an existing zonal disk in a given project.
  public static void createRegionalDisk(
      String project, String region, List<String> replicaZones, String diskName, String diskType,
      int diskSizeGb, Optional<String> diskLink, Optional<String> snapshotLink)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // 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 `regionDisksClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (RegionDisksClient regionDisksClient = RegionDisksClient.create()) {

      Disk.Builder diskBuilder = Disk.newBuilder()
          .addAllReplicaZones(replicaZones)
          .setName(diskName)
          .setType(diskType)
          .setSizeGb(diskSizeGb)
          .setRegion(region);

      // Set source disk if diskLink is not empty.
      diskLink.ifPresent(diskBuilder::setSourceDisk);

      // Set source snapshot if the snapshot link is not empty.
      snapshotLink.ifPresent(diskBuilder::setSourceSnapshot);

      // Wait for the operation to complete.
      Operation operation = regionDisksClient.insertAsync(project, region, diskBuilder.build())
          .get(3, TimeUnit.MINUTES);

      if (operation.hasError()) {
        System.out.println("Disk creation failed!");
        throw new Error(operation.getError().toString());
      }
      System.out.println(
          "Regional disk created. Operation Status: " + operation.getStatus());
    }
  }
}

Python

Python

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Compute Engine Python API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

from __future__ import annotations

from collections.abc import Iterable
import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def create_regional_disk(
    project_id: str,
    region: str,
    replica_zones: Iterable[str],
    disk_name: str,
    disk_type: str,
    disk_size_gb: int,
    disk_link: str | None = None,
    snapshot_link: str | None = None,
) -> compute_v1.Disk:
    """
    Creates a regional disk from an existing zonal disk in a given project.

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        region: name of the region in which you want to create the disk.
        replica_zones: an iterable collection of zone names in which you want to keep
            the new disks' replicas. One of the replica zones of the clone must match
            the zone of the source disk.
        disk_name: name of the disk you want to create.
        disk_type: the type of disk you want to create. This value uses the following format:
            "regions/{region}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
            For example: "regions/us-west3/diskTypes/pd-ssd"
        disk_size_gb: size of the new disk in gigabytes
        disk_link: a link to the disk you want to use as a source for the new disk.
            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
        snapshot_link: a link to the snapshot you want to use as a source for the new disk.
            This value uses the following format: "projects/{project_name}/global/snapshots/{snapshot_name}"

    Returns:
        An attachable regional disk.
    """
    disk_client = compute_v1.RegionDisksClient()
    disk = compute_v1.Disk()
    disk.replica_zones = replica_zones
    disk.size_gb = disk_size_gb
    if disk_link:
        disk.source_disk = disk_link
    if snapshot_link:
        disk.source_snapshot = snapshot_link
    disk.type_ = disk_type
    disk.region = region
    disk.name = disk_name
    operation = disk_client.insert(
        project=project_id, region=region, disk_resource=disk
    )

    wait_for_extended_operation(operation, "disk creation")

    return disk_client.get(project=project_id, region=region, disk=disk_name)

REST

如要從區域磁碟建立地區磁碟副本，請向 compute.disks.insert 方法提出 POST 要求，並指定 sourceDisk 和 replicaZone 參數。

如果可用區磁碟是 Hyperdisk Balanced 或 Hyperdisk Extreme 磁碟區，請加入 type 欄位，建立 Hyperdisk Balanced High Availability 磁碟區。

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/CLONED_REGION/disks

{
  "name": "TARGET_DISK_NAME",
  "sourceDisk": "projects/PROJECT_ID/zones/SOURCE_DISK_ZONE/disks/SOURCE_DISK_NAME",
  "replicaZone": "SOURCE_DISK_ZONE,REPLICA_ZONE_2",
  "type": "projects/PROJECT_ID/regions/CLONED_REGION/diskTypes/hyperdisk-balanced-high-availability",
  "provisionedIops": "IOPS_LIMIT",
  "provisionedThroughput": "THROUGHPUT_LIMIT"
}

更改下列內容：

  • PROJECT_ID：您要複製磁碟的專案 ID。
  • TARGET_DISK_NAME：新區域磁碟副本的名稱。
  • CLONED_REGION：來源和複製磁碟的區域。
  • SOURCE_DISK_NAME：要複製的區域磁碟名稱。
  • SOURCE_DISK_ZONE：來源磁碟的可用區。這也會是地區磁碟副本的第一個副本可用區。
  • REPLICA_ZONE_2：新地區磁碟副本的第二個副本區域。
  • IOPS_LIMIT：選用：如要建立區域 Hyperdisk Balanced High Availability 磁碟，您可以指定磁碟可處理的 IOPS 數量，最多為 100,000 IOPS。
  • THROUGHPUT_LIMIT：選用：如要建立區域性 Hyperdisk Balanced High Availability 磁碟，您可以指定磁碟可提供的最大處理量 (單位為 MiB/秒)，上限為 2,400 MiB/秒。

建立以 CMEK 或 CSEK 加密來源磁碟的磁碟副本

如要建立以 CSEK 或 CMEK 加密的磁碟的區域或地區複製磁碟，請按照上述各節所述程序操作。不過，您也必須提供用來加密來源磁碟的金鑰。

為 CSEK 加密磁碟建立磁碟副本

如果您使用 CSEK 加密來源磁碟，也必須使用相同金鑰加密副本。

控制台

  1. 前往 Google Cloud 控制台的「Disks」(磁碟) 頁面。

    前往「Disks」(磁碟) 頁面

  2. 在區域永久磁碟清單中，找出要複製的磁碟。

  3. 在「Actions」(動作) 欄中，按一下 選單按鈕，然後選取「Clone disk」(複製磁碟)。

    建立本機副本。

    在隨即顯示的「Clone disk」(複製磁碟) 面板中，執行下列操作：

    1. 在「Name」(名稱) 欄位中，指定複製磁碟的名稱。
    2. 在「解密和加密」欄位中，提供來源磁碟加密金鑰。
    3. 在「屬性」下方，查看複製磁碟的其他詳細資料。
    4. 如要完成複製磁碟的建立程序，請按一下「Create」(建立)。

gcloud

如要為 CSEK 加密來源磁碟建立磁碟副本，請執行 gcloud compute disks create 指令，並使用 --csek-key-file 旗標提供來源磁碟加密金鑰。如果您使用的是 RSA 包裝金鑰，請使用gcloud beta compute disks create 指令。

gcloud compute disks create TARGET_DISK_NAME \
  --description="cloned disk" \
  --source-disk=projects/PROJECT_ID/zones/ZONE/disks/SOURCE_DISK_NAME \
  --csek-key-file example-key-file.json

更改下列內容：

  • TARGET_DISK_NAME：新磁碟的名稱。
  • PROJECT_ID：您要複製磁碟的專案 ID。
  • ZONE：來源磁碟和新磁碟的可用區。
  • SOURCE_DISK_NAME：來源磁碟的名稱

Go

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Compute Engine Go API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// Creates a zonal non-boot persistent disk in a project with the copy of data from an existing disk.
// The encryption key must be the same for the source disk and the new disk.
// The disk type and size may differ.
func createDiskFromCustomerEncryptedDisk(
	w io.Writer,
	projectID, zone, diskName, diskType string,
	diskSizeGb int64,
	diskLink, encryptionKey string,
) error {
	// projectID := "your_project_id"
	// zone := "us-west3-b" // should match diskType below
	// diskName := "your_disk_name"
	// diskType := "zones/us-west3/diskTypes/pd-ssd"
	// diskSizeGb := 120
	// diskLink := "projects/your_project_id/global/disks/disk_name"
	// encryptionKey := "SGVsbG8gZnJvbSBHb29nbGUgQ2xvdWQgUGxhdGZvcm0=" // in base64

	ctx := context.Background()
	disksClient, err := compute.NewDisksRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewDisksRESTClient: %w", err)
	}
	defer disksClient.Close()

	req := &computepb.InsertDiskRequest{
		Project: projectID,
		Zone:    zone,
		DiskResource: &computepb.Disk{
			Name:       proto.String(diskName),
			Zone:       proto.String(zone),
			Type:       proto.String(diskType),
			SizeGb:     proto.Int64(diskSizeGb),
			SourceDisk: proto.String(diskLink),
			DiskEncryptionKey: &computepb.CustomerEncryptionKey{
				RawKey: &encryptionKey,
			},
		},
	}

	op, err := disksClient.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create disk: %w", err)
	}

	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}

	fmt.Fprintf(w, "Disk created\n")

	return nil
}

Java

Java

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Compute Engine Java API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。


import com.google.cloud.compute.v1.CustomerEncryptionKey;
import com.google.cloud.compute.v1.Disk;
import com.google.cloud.compute.v1.DisksClient;
import com.google.cloud.compute.v1.InsertDiskRequest;
import com.google.cloud.compute.v1.Operation;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CloneEncryptedDisk {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String project = "YOUR_PROJECT_ID";

    // Name of the zone in which you want to create the disk.
    String zone = "europe-central2-b";

    // Name of the disk you want to create.
    String diskName = "YOUR_DISK_NAME";

    // The type of disk you want to create. This value uses the following format:
    // "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
    // For example: "zones/us-west3-b/diskTypes/pd-ssd"
    String diskType = String.format("zones/%s/diskTypes/pd-ssd", zone);

    // Size of the new disk in gigabytes.
    int diskSizeGb = 10;

    // A link to the disk you want to use as a source for the new disk.
    // This value uses the following format:
    // "projects/{project_name}/zones/{zone}/disks/{disk_name}"
    String diskLink = String.format("projects/%s/zones/%s/disks/%s", "PROJECT_NAME", "ZONE",
        "DISK_NAME");

    // Customer-supplied encryption key used for encrypting data in the source disk.
    // The data will be encrypted with the same key in the new disk.
    byte[] encryptionKey = null;

    createDiskFromCustomerEncryptedKey(project, zone, diskName, diskType, diskSizeGb, diskLink,
        encryptionKey);
  }

  // Creates a zonal non-boot persistent disk in a project with the copy of data
  // from an existing disk.
  // The encryption key must be the same for the source disk and the new disk.
  public static void createDiskFromCustomerEncryptedKey(String project, String zone,
      String diskName, String diskType, int diskSizeGb, String diskLink, byte[] encryptionKey)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // 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 `disksClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (DisksClient disksClient = DisksClient.create()) {

      // Create a disk and set the encryption key.
      Disk disk = Disk.newBuilder()
          .setZone(zone)
          .setName(diskName)
          .setType(diskType)
          .setSizeGb(diskSizeGb)
          .setSourceDisk(diskLink)
          .setDiskEncryptionKey(CustomerEncryptionKey
              .newBuilder()
              .setRawKeyBytes(ByteString.copyFrom(encryptionKey))
              .build())
          .build();

      // Wait for the insert disk operation to complete.
      Operation operation = disksClient.insertAsync(
          InsertDiskRequest.newBuilder()
              .setProject(project)
              .setZone(zone)
              .setDiskResource(disk)
              .build()).get(3, TimeUnit.MINUTES);

      if (operation.hasError()) {
        System.out.println("Disk creation failed!");
        throw new Error(operation.getError().toString());
      }
      System.out.println(
          "Disk cloned with customer encryption key. Operation Status: " + operation.getStatus());
    }
  }
}

Python

Python

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Compute Engine Python API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

from __future__ import annotations

import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def create_disk_from_customer_encrypted_disk(
    project_id: str,
    zone: str,
    disk_name: str,
    disk_type: str,
    disk_size_gb: int,
    disk_link: str,
    encryption_key: bytes,
) -> compute_v1.Disk:
    """
    Creates a zonal non-boot persistent disk in a project with the copy of data from an existing disk.

    The encryption key must be the same for the source disk and the new disk.

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        zone: name of the zone in which you want to create the disk.
        disk_name: name of the disk you want to create.
        disk_type: the type of disk you want to create. This value uses the following format:
            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
            For example: "zones/us-west3-b/diskTypes/pd-ssd"
        disk_size_gb: size of the new disk in gigabytes
        disk_link: a link to the disk you want to use as a source for the new disk.
            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
        encryption_key: customer-supplied encryption key used for encrypting
            data in the source disk. The data will be encrypted with the same key
            in the new disk.

    Returns:
        An attachable copy of an existing disk.
    """
    disk_client = compute_v1.DisksClient()
    disk = compute_v1.Disk()
    disk.zone = zone
    disk.size_gb = disk_size_gb
    disk.source_disk = disk_link
    disk.type_ = disk_type
    disk.name = disk_name
    disk.disk_encryption_key = compute_v1.CustomerEncryptionKey()
    disk.disk_encryption_key.raw_key = encryption_key
    operation = disk_client.insert(project=project_id, zone=zone, disk_resource=disk)

    wait_for_extended_operation(operation, "disk creation")

    return disk_client.get(project=project_id, zone=zone, disk=disk_name)

REST

如要為 CSEK 加密來源磁碟建立磁碟副本，請向 compute.disks.insert 方法提出 POST 要求，並使用 diskEncryptionKey 屬性提供來源磁碟加密金鑰。如果您使用的是 RSA 包裝金鑰，請使用方法的 beta 版本。

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks

{
  "name": "TARGET_DISK_NAME"
  "sourceDisk": "projects/PROJECT_ID/zones/ZONE/disks/SOURCE_DISK_NAME"
  "diskEncryptionKey": {
    "rsaEncryptedKey": "ieCx/NcW06PcT7Ep1X6LUTc/hLvUDYyzSZPPVCVPTVEohpeHASqC8uw5TzyO9U+Fka9JFHz0mBibXUInrC/jEk014kCK/NPjYgEMOyssZ4ZINPKxlUh2zn1bV+MCaTICrdmuSBTWlUUiFoDD6PYznLwh8ZNdaheCeZ8ewEXgFQ8V+sDroLaN3Xs3MDTXQEMMoNUXMCZEIpg9Vtp9x2oeQ5lAbtt7bYAAHf5l+gJWw3sUfs0/Glw5fpdjT8Uggrr+RMZezGrltJEF293rvTIjWOEB3z5OHyHwQkvdrPDFcTqsLfh+8Hr8g+mf+7zVPEC8nEbqpdl3GPv3A7AwpFp7MA=="
  },
}

更改下列內容：

  • PROJECT_ID：您要複製磁碟的專案 ID。
  • ZONE：來源磁碟和新磁碟的可用區。
  • TARGET_DISK_NAME：新磁碟的名稱。
  • SOURCE_DISK_NAME：來源磁碟的名稱

為 CMEK 加密磁碟建立磁碟副本

如果您使用 CMEK 加密來源磁碟，也必須使用相同的金鑰加密副本。

控制台

Compute Engine 會自動使用來源磁碟加密金鑰來加密副本。

gcloud

如要為 CMEK 加密來源磁碟建立磁碟副本，請執行 gcloud compute disks create 指令，並使用 --kms-key 旗標提供來源磁碟加密金鑰。如果您使用的是 RSA 包裝金鑰，請使用gcloud beta compute disks create 指令。

gcloud compute disks create TARGET_DISK_NAME \
  --description="cloned disk" \
  --source-disk=projects/PROJECT_ID/zones/ZONE/disks/SOURCE_DISK_NAME \
  --kms-key projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

更改下列內容：

  • TARGET_DISK_NAME：新磁碟的名稱。
  • PROJECT_ID：您要複製磁碟的專案 ID。
  • ZONE：來源磁碟和新磁碟的可用區。
  • SOURCE_DISK_NAME：來源磁碟的名稱。
  • KMS_PROJECT_ID：加密金鑰的專案 ID。
  • REGION：加密金鑰的區域。
  • KEY_RING：加密金鑰的金鑰環。
  • KEY：加密金鑰的名稱。

Go

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Compute Engine Go API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// Creates a zonal non-boot persistent disk in a project with the copy of data from an existing disk.
// The encryption key must be the same for the source disk and the new disk.
// The disk type and size may differ.
func createDiskFromKmsEncryptedDisk(
	w io.Writer,
	projectID, zone, diskName, diskType string,
	diskSizeGb int64,
	diskLink, kmsKeyLink string,
) error {
	// projectID := "your_project_id"
	// zone := "us-west3-b" // should match diskType below
	// diskName := "your_disk_name"
	// diskType := "zones/us-west3/diskTypes/pd-ssd"
	// diskSizeGb := 120
	// diskLink := "projects/your_project_id/global/disks/disk_name"
	// kmsKeyLink := "projects/your_kms_project_id/locations/us-central1/keyRings/your_key_ring/cryptoKeys/your_key"

	ctx := context.Background()
	disksClient, err := compute.NewDisksRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewDisksRESTClient: %w", err)
	}
	defer disksClient.Close()

	req := &computepb.InsertDiskRequest{
		Project: projectID,
		Zone:    zone,
		DiskResource: &computepb.Disk{
			Name:       proto.String(diskName),
			Zone:       proto.String(zone),
			Type:       proto.String(diskType),
			SizeGb:     proto.Int64(diskSizeGb),
			SourceDisk: proto.String(diskLink),
			DiskEncryptionKey: &computepb.CustomerEncryptionKey{
				KmsKeyName: &kmsKeyLink,
			},
		},
	}

	op, err := disksClient.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create disk: %w", err)
	}

	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}

	fmt.Fprintf(w, "Disk created\n")

	return nil
}

Java

Java

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Compute Engine Java API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。


import com.google.cloud.compute.v1.CustomerEncryptionKey;
import com.google.cloud.compute.v1.Disk;
import com.google.cloud.compute.v1.DisksClient;
import com.google.cloud.compute.v1.InsertDiskRequest;
import com.google.cloud.compute.v1.Operation;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CloneEncryptedDiskManagedKey {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String project = "YOUR_PROJECT_ID";

    // Name of the zone in which you want to create the disk.
    String zone = "europe-central2-b";

    // Name of the disk you want to create.
    String diskName = "YOUR_DISK_NAME";

    // The type of disk you want to create. This value uses the following format:
    // "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
    // For example: "zones/us-west3-b/diskTypes/pd-ssd"
    String diskType = String.format("zones/%s/diskTypes/pd-ssd", zone);

    // Size of the new disk in gigabytes.
    int diskSizeGb = 10;

    // A link to the disk you want to use as a source for the new disk.
    // This value uses the following format:
    // "projects/{project_name}/zones/{zone}/disks/{disk_name}"
    String diskLink = String.format("projects/%s/zones/%s/disks/%s", "PROJECT_NAME", "ZONE",
        "DISK_NAME");

    // URL of the key from KMS. The key might be from another project, as
    // long as you have access to it. The data will be encrypted with the same key
    // in the new disk. This value uses following format:
    // "projects/{kms_project_id}/locations/{region}/keyRings/{key_ring}/cryptoKeys/{key}"
    String kmsKeyName = "kms-key-name";

    createDiskFromKmsEncryptedDisk(project, zone, diskName, diskType, diskSizeGb, diskLink,
        kmsKeyName);
  }

  // Creates a zonal non-boot disk in a project with the copy of data from an existing disk.
  // The encryption key must be the same for the source disk and the new disk.
  public static void createDiskFromKmsEncryptedDisk(String project, String zone, String diskName,
      String diskType, int diskSizeGb, String diskLink, String kmsKeyName)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // 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 `disksClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (DisksClient disksClient = DisksClient.create()) {

      // Create a disk and set the KMS encryption key name.
      Disk disk = Disk.newBuilder()
          .setZone(zone)
          .setName(diskName)
          .setType(diskType)
          .setSizeGb(diskSizeGb)
          .setSourceDisk(diskLink)
          .setDiskEncryptionKey(CustomerEncryptionKey.newBuilder()
              .setKmsKeyName(kmsKeyName)
              .build())
          .build();

      // Wait for the insert disk operation to complete.
      Operation operation = disksClient.insertAsync(
          InsertDiskRequest.newBuilder()
              .setProject(project)
              .setZone(zone)
              .setDiskResource(disk)
              .build()).get(3, TimeUnit.MINUTES);

      if (operation.hasError()) {
        System.out.println("Disk creation failed!");
        throw new Error(operation.getError().toString());
      }
      System.out.println(
          "Disk cloned with KMS encryption key. Operation Status: " + operation.getStatus());
    }
  }
}

Python

Python

在試用這個範例之前，請先按照「使用用戶端程式庫的 Compute Engine 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Compute Engine Python API 參考文件。

如要向 Compute Engine 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

from __future__ import annotations

import sys
from typing import Any

from google.api_core.exceptions import BadRequest
from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def create_disk_from_kms_encrypted_disk(
    project_id: str,
    zone: str,
    disk_name: str,
    disk_type: str,
    disk_size_gb: int,
    disk_link: str,
    kms_key_name: str,
) -> compute_v1.Disk:
    """
    Creates a zonal non-boot disk in a project with the copy of data from an existing disk.

    The encryption key must be the same for the source disk and the new disk.

    To run this method, the service-<project_id>@compute-system.iam.gserviceaccount.com
    service account needs to have the cloudkms.cryptoKeyEncrypterDecrypter role,
    as described in documentation:
    https://cloud.google.com/compute/docs/disks/customer-managed-encryption#before_you_begin

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        zone: name of the zone in which you want to create the disk.
        disk_name: name of the disk you want to create.
        disk_type: the type of disk you want to create. This value uses the following format:
            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
            For example: "zones/us-west3-b/diskTypes/pd-ssd"
        disk_size_gb: size of the new disk in gigabytes
        disk_link: a link to the disk you want to use as a source for the new disk.
            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
        kms_key_name: URL of the key from KMS. The key might be from another project, as
            long as you have access to it. The data will be encrypted with the same key
            in the new disk. This value uses following format:
            "projects/{kms_project_id}/locations/{region}/keyRings/{key_ring}/cryptoKeys/{key}"

    Returns:
        An attachable copy of an existing disk.
    """
    disk_client = compute_v1.DisksClient()
    disk = compute_v1.Disk()
    disk.zone = zone
    disk.size_gb = disk_size_gb
    disk.source_disk = disk_link
    disk.type_ = disk_type
    disk.name = disk_name
    disk.disk_encryption_key = compute_v1.CustomerEncryptionKey()
    disk.disk_encryption_key.kms_key_name = kms_key_name
    try:
        operation = disk_client.insert(
            project=project_id, zone=zone, disk_resource=disk
        )
    except BadRequest as err:
        if "Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied" in err.message:
            print(
                f"Please provide the cloudkms.cryptoKeyEncrypterDecrypter role to"
                f"service-{project_id}@compute-system.iam.gserviceaccount.com"
            )
        raise err

    wait_for_extended_operation(operation, "disk creation")

    return disk_client.get(project=project_id, zone=zone, disk=disk_name)

REST

如要為 CMEK 加密來源磁碟建立磁碟副本，請向 compute.disks.insert 方法提出 POST 要求，並使用 kmsKeyName 屬性提供來源磁碟加密金鑰。如果您使用的是 RSA 包裝金鑰，請使用方法的 beta 版本。

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks

{
  "name": "TARGET_DISK_NAME"
  "sourceDisk": "projects/PROJECT_ID/zones/ZONE/disks/SOURCE_DISK_NAME"
  "diskEncryptionKey": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
}

更改下列內容：

  • PROJECT_ID：您要複製磁碟的專案 ID。
  • ZONE：來源磁碟和新磁碟的可用區。
  • TARGET_DISK_NAME：新磁碟的名稱。
  • SOURCE_DISK_NAME：來源磁碟的名稱。
  • KMS_PROJECT_ID：加密金鑰的專案 ID。
  • REGION：加密金鑰的區域。
  • KEY_RING：加密金鑰的金鑰環。
  • KEY：加密金鑰的名稱。

後續步驟