更新实例属性

您可以使用通过 Google Cloud CLI 或 Compute Engine API 发出的单个请求，以更新多个实例属性，如有必要，还可以选择重启实例。更新方法会处理验证更新后实例属性的逻辑，并确保成功更新必要的资源。如果请求包含无效的属性，或者请求的资源不可用，则请求将返回错误，并且不对您的实例进行任何更改。这样可以保护实例免于部分更新，并保护实例不会停止并且无法访问资源以重新启动。

准备工作

  • 设置身份验证（如果尚未设置）。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例，您可以按如下方式向 Compute Engine 进行身份验证。

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. 安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI： 

      gcloud init
    2. Set a default region and zone.

      3. REST

      如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

        安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI： 

        gcloud init

      如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

限制

  • 通过 gcloud CLI 或 Compute Engine API 发出的实例更新请求不支持 PATCH 语义。更新请求中的实例资源必须包含实例的所有属性。更新请求中的实例配置内缺少的属性会被视为已从实例中删除。
  • 您只能更新特定属性列表。
  • 不支持将实例更改为唯一租户，也不支持将原本使用唯一租户的实例更改为不使用唯一租户。
  • 您可以将一个实例从一项预留改为转到另一项预留，但是不能通过更新过程将实例附加到预留或者从预留中分离。
  • 如果实例挂接了本地固态硬盘，则无法更新需要实例重启的属性。您必须先删除实例，然后重新创建该实例。在删除虚拟机之前，请务必将您的关键数据从本地固态硬盘迁移到永久性磁盘或其他虚拟机。
  • 如果实例使用 Beta 版 Compute Engine API 中可用的资源，您必须使用正确版本的 instances.update 方法来更新这些属性。例如，如果您使用 Beta 版 Compute Engine API 创建了实例，并为该实例配置了只有 Beta 版 API 才能识别的资源，则还必须使用 instances.update 方法的 Beta 版本来更新这些资源。instances.update 方法的 v1 版本无法识别您的实例使用的 Beta 版资源，因此在更新过程中，它会从实例配置中删除这些 Beta 版资源。这也适用于 Alpha 版 API 中的资源。

权限

您必须具有 compute.instances.update 权限才能更新实例。多个现有 Identity and Access Management (IAM) 角色拥有此权限。您还必须具备使用实例上要修改的资源的权限。例如，如需向实例添加磁盘，您必须拥有以下权限：

  • 您要更新的实例的 compute.instances.update 权限。
  • 现有磁盘的 compute.disks.use 权限，或者要创建新磁盘的项目中的 compute.disks.create 权限。

最佳做法

为确保实例更新界面能最有效地为您效力，请遵循以下最佳做法：

  • 如果可能，请始终使用相同版本的 Compute Engine API 来创建、设置和更新实例。这样，如果任何实例资源仅在一个 API 版本中可用，您就可以更新和修改这些资源资源。
  • 尽管您可以使用 instances.update 方法来更新代管实例组 (MIG) 中的实例，但在大多数情况下，最好更改该组的实例模板，并将更新滚动到 MIG。

您可以更新的属性

您只能通过 update 方法更改一组特定的实例属性。对某些属性的更新要求重启实例。为防止实例意外重启，您的请求必须定义允许对实例执行哪些操作。您的请求可以指定以下操作之一：

  • NO_EFFECT：更新请求会检查请求是否有效以及资源是否可用，但并不会执行更新。可以使用此操作来测试命令，而不启动任何实际更新。
  • REFRESH：仅当修改后的实例属性不需要实例重启时，更新请求才会运行。如果请求有效，但要求重启，则请求会返回 INFEASIBLE 错误。
  • RESTART：如果更新要求实例重启，则系统将重启您的实例。

需要更新 RESTART 的属性：

  • reservationAffinity
  • disks - 启动磁盘
    • disks.deviceName - 所有磁盘
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

仅需要 REFRESH 更新的属性：

  • canIpForward
  • deletionProtection
  • description
  • disks - 非启动磁盘属性，不包括 deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

更新实例属性

使用以下步骤更新您的实例：

  1. 导出现有实例配置属性。
  2. 修改实例配置的属性。
  3. 将 NO_EFFECT 指定为中断性程度最高的操作，以运行测试请求。该响应指示实例配置中的无效字段，并指明要应用更改，需要执行哪些操作。
  4. 如果配置可以接受，则请求实例更新，并指定您的实例可以接受的中断性最高的操作。

只有在您的请求满足以下要求时，系统才会启动更新流程：

  • 请求中的实例 fingerprint 属性必须与您要更新的实例的 fingerprint 一致。这样可以防止针对相同实例的同时更新请求彼此覆盖。
  • 更新请求中的属性必须有效。
  • 您请求的资源必须可用。
  • 如果请求中的属性要求实例重启，则您的请求必须将 RESTART 指定为允许的操作。

如果满足了这些要求，系统就会启动实例更新过程。否则，系统不会更改您的现有实例，也不会更改其配置。

您可以使用 gcloud CLI 或 Compute Engine API 来启动更新。

gcloud

  1. 使用 instances export 命令导出现有实例属性：

    gcloud compute instances export INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --destination=FILE_PATH

    请替换以下内容：

    • INSTANCE_NAME：要导出的实例的名称。
    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • FILE_PATH：要在本地工作站上保存实例配置文件的输出路径。

  2. 使用文本编辑器修改已导出的实例配置文件中的一个或多个属性。如需了解您可以更新的属性，请参阅可更新属性的列表。例如，如需更改实例的机器类型，请更改 machineType 属性：

    ⋮
machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
⋮

    请替换以下内容：

    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • MACHINE_TYPE：实例的机器类型。例如 n1-standard-2。

  3. 使用 instances update-from-file 命令运行目标实例的测试更新。指定 --most-disruptive-allowed-action=NO_EFFECT 标志。该响应会识别出配置错误的属性，并指明是否需要执行 RESTART 或 REFRESH 操作来应用更新。

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action NO_EFFECT

    请替换以下内容：

    • INSTANCE_NAME：要导出的实例的名称。
    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • FILE_PATH：本地工作站上修改后的实例配置文件的路径。

  4. 使用 instances update-from-file 命令更新目标实例。如果要更新需要重启实例的属性，请添加 --most-disruptive-allowed-action=RESTART 标志。如果属性不需要重启，请指定 --most-disruptive-allowed-action=REFRESH 标志。如需了解哪些属性需要重启，请参阅可更新的属性列表。

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action ALLOWED_ACTION

    请替换以下内容：

    • INSTANCE_NAME：要导出的实例的名称。
    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • FILE_PATH：本地工作站上修改后的实例配置文件的路径。
    • ALLOWED_ACTION：定义更新的中断性。指定 RESTART 以允许对实例进行完全重启。仅当修改后的属性不需要实例重启时，才应该指定 REFRESH 以更新实例。

如果更新请求有效且所需资源可用，实例更新过程就会开始。您可以查看审核日志，以监控此操作的状态。如果更新需要重启，并且您的命令允许使用 RESTART，则实例将重启以应用更改。

REST

  1. 在 Compute Engine API 中使用 instances.get 方法导出现有实例属性：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    替换以下内容：

    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • INSTANCE_NAME：要导出的实例的名称。

    该请求返回实例资源定义。

  2. 在响应中，修改实例资源属性。要了解哪些属性可更新，请参阅可更新的属性列表。例如，要更改实例的机器类型，请更改 machineType 属性。您可以更改多项属性。

    {
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
  ⋮
}

    替换以下内容：

    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • MACHINE_TYPE：实例的机器类型。例如 n1-standard-2。

  3. 在 Compute Engine API 中使用 instances.update 方法，然后指定 most_disruptive_allowed_action=NO_EFFECT 以对目标实例运行测试更新。该响应会识别出配置错误的属性，并指明是否需要执行 RESTART 或 REFRESH 操作才能应用更新。

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=NO_EFFECT

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    请替换以下内容：

    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • INSTANCE_NAME：要导出的实例的名称。

  4. 使用 Compute Engine API 中的 instances.update 方法以更新目标实例。如果要更新需要重启实例的属性，请添加 ?most_disruptive_allowed_action=RESTART 查询参数，以指示可以在更新期间重启实例。如果属性不需要重启，请指定 ?most_disruptive_allowed_action=REFRESH 查询参数。如需了解哪些属性需要重启，请参阅可更新的属性列表。为您修改的实例资源包含完整的正文。在以下示例中，正文将机器类型更改为 n1-standard-2：

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=ALLOWED_ACTION

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    请替换以下内容：

    • PROJECT_ID：此请求的项目 ID。
    • ZONE：此实例的可用区。
    • INSTANCE_NAME：要导出的实例的名称。
    • ALLOWED_ACTION：定义更新的中断性。指定 RESTART 以允许对实例进行完全重启。仅当修改后的属性不需要实例重启时，才应该指定 REFRESH 以更新实例。

如果更新请求有效且所需资源可用，实例更新过程就会开始。您可以查看审核日志，以监控此操作的状态。如果更新需要重启，并且您的命令允许使用 RESTART，则实例将重启以应用更改。

后续步骤