设置和移除自定义元数据


每个元数据条目以键值对的形式存储在元数据服务器上。元数据键区分大小写。您的键可以是预定义键,也可以是自定义元数据键。

通过自定义元数据,您可以在单个虚拟机或项目中创建和使用自己的元数据键值对。您可以添加新的自定义元数据键,更新现有键的值,以及移除不需要的任何自定义元数据条目。 设置自定义元数据对于将任意值传递给项目中的虚拟机非常有用。它对创建启动关停脚本也有用。

本文档介绍了如何执行以下操作:

准备工作

  • 查看有关如何定义 Compute Engine 的虚拟机元数据、对其进行分类和安排的基础知识。如需了解详情,请参阅虚拟机元数据简介
  • 设置身份验证(如果尚未设置)。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例,您可以按如下方式向 Compute Engine 进行身份验证。

    选择标签页以了解您打算如何使用本页面上的示例:

    控制台

    当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时,无需设置身份验证。

    gcloud

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

      gcloud init
    2. 设置默认区域和可用区

    REST

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

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

      gcloud init

所需的角色

如需获得在虚拟机上设置或移除自定义元数据所需的权限,请让您的管理员向您授予以下 IAM 角色:

如需详细了解如何授予角色,请参阅管理访问权限

这些预定义角色包含在虚拟机上设置或移除自定义元数据所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

如需在虚拟机上设置或移除自定义元数据,您需要具备以下权限:

  • 如果您的虚拟机使用服务账号:针对服务账号或项目的 iam.serviceAccounts.actAs
  • 如需添加、更新或移除自定义项目范围的元数据:
    • 针对项目的 compute.projects.get 权限
    • 针对项目的 compute.projects.setCommonInstanceMetadata 权限
  • 如需添加、更新或移除自定义项目可用区元数据,请执行以下操作:
    • 对项目中所需可用区的实例设置的 compute.instanceSettings.get 权限
    • 对项目中所需可用区的实例设置的 compute.instanceSettings.update 权限
  • 如需添加、更新或移除自定义实例元数据:
    • 针对虚拟机的 compute.instances.get 权限
    • 针对虚拟机的 compute.instances.setMetadata 权限

您也可以使用自定义角色或其他预定义角色来获取这些权限。

限制

Compute Engine 会对所有元数据条目实施总大小限制(即 512 KB)。最大大小限制还通过以下方式应用于每个 keyvalue

  • 每个元数据 key 的大小上限为 128 字节。
  • 每个元数据 key 都区分大小写。

    对于项目可用区元数据,Compute Engine 不允许创建具有相同字符串的两个单独元数据键,即使它们在不同情况下编写也是如此。例如,如果您具有一个名为 project-zonal-metadata-key 的项目可用区元数据键,则无法创建新的项目可用区元数据键,例如 Project-Zonal-Metadata-KeyPROJECT-ZONAL-METADATA-KEY 或同一字符串的任何其他变体。

  • 每个元数据 value 的大小上限为 256 KB。

  • 除了布尔值之外,每个元数据 value 都区分大小写。

例如,SSH 键会以自定义元数据的形式存储在 ssh-keys 键下。如果此键的元数据内容或 value 超过 256 KB 的限制,您将无法添加更多 SSH 键。如果您受到此限制约束,请考虑移除未使用的键以为新键释放元数据空间。

此外,如果您直接提供启动或关停脚本内容,则这些启动和关停脚本内容也可能会存储为自定义元数据,并计入这些大小限制。为了避免出现这种情况,请将启动或关停脚本存储为文件,并将其托管在 Cloud Storage 等外部位置,然后在创建实例时提供启动脚本网址。这样,这些文件就会下载到虚拟机上,而不是存储在元数据服务器中。

布尔值

对于接受布尔值(TRUEFALSE)的字段,还可以使用以下值:

状态 替代值
TRUE YYes1
FALSE NNo0

布尔值不区分大小写。例如,您可以使用 FalsefalseFALSE 停用某项功能。

在虚拟机上设置自定义元数据

本部分介绍如何通过以下任一方式为 Compute Engine 虚拟机添加新的自定义元数据或更新现有自定义元数据值:

设置自定义项目级元数据

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST 为项目中的所有实例添加或更新自定义元数据。

使用以下说明将元数据设置应用于项目中的所有虚拟机。例如,如果您定义了项目级元数据对 baz=bat,则该元数据对将自动应用于项目中的所有虚拟机。

控制台

  1. 在 Google Cloud 控制台中,转到元数据页面。

    转到元数据页面

  2. 点击修改
  3. 添加或修改元数据条目。
  4. 保存更改。

gcloud

使用 project-info add-metadata 命令

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

请替换以下内容:

  • KEY:元数据键的名称
  • VALUE:为此键存储的值

示例

例如,如需在项目上设置两个新条目 foo=barbaz=bat,请运行以下命令:

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

您可以视情况使用 --metadata-from-file 标志指定一个或多个要从中读取元数据的文件。

REST

  1. 可选。如需执行乐观锁定,您可以选择提供指纹。

    指纹是由 Compute Engine 生成的随机字符串。每次请求后指纹都会更改,因此如果您提供的指纹不匹配,请求将被拒绝。

    如果您未提供指纹,则无需执行一致性检查,并且 projects().setCommonInstanceMetadata 请求将会成功。此行为与 instances().setMetadatainstanceSettings().patch 方法不同,后者始终需要指纹。

    要获取项目的当前指纹,请调用 project().get 方法

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
    

    输出内容类似如下:

    {
      "name": "myproject",
      "commonInstanceMetadata": {
        "kind": "compute#metadata",
        "fingerprint": "FikclA7UBC0=",
        ...
      }
    }
    
  2. projects().setCommonInstanceMetadata 方法发出请求,并设置您的自定义元数据键值对:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata
    
    {
      "fingerprint": "FikclA7UBC0=",
      "items": [
        {
        "key": "foo",
        "value": "bar"
        }
      ]
    }
    

PROJECT_ID 替换为项目 ID。

设置自定义项目可用区元数据

您可以通过以下任一方式为您的虚拟机添加或更新项目可用区元数据条目:

  • 您可以在项目可用区级添加新的自定义元数据键,并为项目中的特定可用区中的所有虚拟机设置元数据值。
  • 您可以为项目中特定可用区中的所有虚拟机更新现有自定义项目可用区元数据键的值。
  • 对于已具有项目范围值的项目元数据键,您可以为特定可用区中的所有虚拟机替换这些项目范围值,并指定这些虚拟机以改用项目可用区值。

设置自定义项目可用区元数据之前的注意事项

项目和项目可用区元数据条目存储在同一 project/ 目录中。如果您在项目级和项目可用区级的虚拟机上为同一自定义元数据键设置了不同的值,则这些键的项目可用区元数据值优先于相应可用区中的项目范围元数据。

  • 如果您为已具有项目范围值的元数据键添加项目可用区元数据值,则 Compute Engine 将替换此指定可用区中虚拟机的项目范围值,并使用项目可用区值更新 /project 目录。
  • 如果您为已具有项目可用区值的元数据键添加新的项目范围元数据值,则系统不会进行任何更改。Compute Engine 会将项目可用区值保留在特定可用区的 /project 目录中。
  • 如果您没有为特定可用区中的自定义元数据键指定项目可用区值,但键具有项目范围的值,则您的虚拟机将继续在这些可用区中具有项目范围值。

过程

您可以使用 Google Cloud CLI 或 REST 为项目中特定可用区的所有虚拟机实例添加或更新自定义元数据。

gcloud

  • 如需添加或更新自定义项目可用区元数据,请使用 gcloud beta compute project-zonal-metadata add 命令

    gcloud beta compute project-zonal-metadata add \
      --zone=ZONE \
      --project=PROJECT_ID  \
      --metadata=KEY1=VALUE1,KEY2=VALUE2,...

    替换以下内容:

    • PROJECT_ID:您的项目 ID
    • ZONE:要添加或更新项目可用区元数据的可用区。
    • KEY1KEY2...:要为其添加或更新值的自定义项目可用区元数据键。
    • VALUE1VALUE2...:您要为现有和新的项目可用区元数据键设置的项目可用区元数据值。根据您的自定义元数据键和值,会出现以下情况之一:

    • 如果相应的自定义元数据键是现有的项目范围的键,则 Compute Engine 将替换项目范围元数据值,并为指定可用区中的所有虚拟机使用项目可用区值。指定可用区中的所有虚拟机都会继承新的项目可用区值。如果您对同一键的项目范围值进行任何未来更改,这些更新不会影响此项目可用区值,并且此可用区中的虚拟机将继续将该项目可用区值作为其项目元数据。

    • 如果相应的自定义元数据键是现有的项目可用区元数据键,且指定的元数据值是新值,则 Compute Engine 会更新现有键的可用区可用区值。

    • 如果相应的自定义元数据键是不属于现有项目范围或项目可用区元数据的新键,则 Compute Engine 会创建项目可用区元数据键并添加此元数据值。

    • 如果相应的自定义元数据键是现有的项目可用区元数据键,并且指定的元数据值与现有值相同,则项目可用区元数据条目将保持不变。

示例:添加新的自定义项目可用区元数据条目

举例来说,假设一个名为 my-project 的项目具有以下自定义元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"value-1""key-2":"value-2"

如需将 "key-4":"value-4" 添加为 us-central1-a 可用区中的新自定义项目可用区元数据对,请运行以下命令:

gcloud beta compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

示例:更新现有自定义项目可用区元数据条目的值

考虑同一示例项目 my-project,该项目现在具有以下自定义元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"value-1""key-2":"value-2""key-4":"value-4"

如需使用新值更新 us-cerntral1-a 可用区中 key-1key-4 的项目可用区元数据值,请运行以下命令。

gcloud beta compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

示例:替换元数据键的项目范围值,并使用项目可用区值

考虑同一示例项目 my-project,该项目现在具有以下自定义元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"new-value-1""key-2":"value-2""key-4":"new-value-4"

在此示例项目中,请考虑使用 key-3,其项目范围的元数据值为 value-c。假设您希望为 us-central1-a 可用区中的所有虚拟机为此键设置项目可用区元数据值 value-3。执行该操作时,对于 us-central1-a 可用区中的所有虚拟机,Compute Engine 会替换项目范围的值并使用项目可用区值。项目所有其他可用区中的虚拟机保留了 key-3 的主要项目范围或项目可用区元数据值。

如需替换 key-3 的项目范围值并设置项目可用区值,请运行以下命令:

gcloud beta compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

  1. 获取当前指纹并查看该可用区中项目的任何现有键值对。

    如需执行乐观锁定,您必须提供指纹。指纹是由 Compute Engine 生成的随机字符串。每次您发出添加、更新或移除项目可用区元数据的请求时,指纹都会更改,并且如果您提供的指纹不匹配,Compute Engine 会拒绝您的请求。

    如果您未提供指纹,则系统会执行一致性检查,并且您的更新请求不会成功。这样,一次就只能进行一项请求,以免发生冲突。此行为与 instances().setMetadata 匹配,其中始终需要指纹。

    如需获取项目可用区元数据的当前指纹,请向 instanceSettings().get 方法发出 GET 请求。

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
    

    替换以下内容:

    • PROJECT_ID:您的项目 ID
    • ZONE:您要设置项目可用区元数据的可用区。

    以下是此请求的示例输出:

        {
          "fingerprint": "VlRIl8dx9vk=",
          "metadata": {
            ...
          }
        }
    
  2. 如需添加或更新项目可用区元数据,请向 instanceSettings().patch 方法发出 PATCH 请求。 您必须在请求中提供以下信息:

    • 更新掩码。使用 update_mask 查询参数。更新掩码必须包含以下内容的元数据键:

      • 您要添加的新自定义项目可用区元数据
      • 要为其更新值的现有自定义项目可用区元数据

      您必须添加字符串 metadata.items. 作为每个键的前缀,例如 metadata.items.key1,metadata.items.key3

    • 在请求正文中,提供以下信息:

      • 要添加的新自定义项目可用区元数据的元数据键和值
      • 要更新的现有自定义项目可用区元数据的元数据键和值
      • 当前的指纹值

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
    {
      "fingerprint": "FINGER_PRINT",
      "metadata": {
        "items": {
          "KEY1": "VALUE1",
          "KEY2": "VALUE2",
          ...
        }
      }
    }
    

    替换以下内容:

    • PROJECT_ID:项目的 ID。
    • ZONE:您要设置项目可用区元数据的可用区。
    • PREFIXED_METADATA_KEYS:以下各项的元数据键列表,其中每个键都以字符串 metadata.items. 为前缀 :

      • 您要添加的新自定义项目可用区元数据
      • 要为其更新值的现有自定义项目可用区元数据

      例如,假设您当前的项目可用区元数据键为 key-1key-2。如果您要添加新的元数据键 key-3,同时还更新其中一个当前的元数据键 key-1,则您的更新掩码必须具有以下字符串:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT:当前指纹值。

    • KEY1KEY2...:要为其添加或更新值的自定义项目可用区元数据键。 指定您在更新掩码中指定的所有自定义项目可用区元数据键。

    • VALUE1VALUE2...:您要为现有和新的项目可用区元数据键设置的项目可用区元数据值。根据您的自定义元数据键和值,会出现以下情况之一:

      • 如果相应的自定义元数据键是现有的项目范围的键,则 Compute Engine 将替换项目范围元数据值,并为指定可用区中的所有虚拟机使用项目可用区值。指定可用区中的所有虚拟机都会继承新的项目可用区值。如果您对同一键的项目范围值进行任何未来更改,这些更新不会影响此项目可用区值,并且此可用区中的虚拟机将继续将该项目可用区值作为其项目元数据。
      • 如果相应的自定义元数据键是现有的项目可用区元数据键,且指定的元数据值是新值,则 Compute Engine 会更新现有键的可用区可用区值。
      • 如果相应的自定义元数据键是不属于现有项目范围或项目可用区元数据的新键,则 Compute Engine 会创建项目可用区元数据键并添加此元数据值。
      • 如果相应的自定义元数据键是现有的项目可用区元数据键,并且指定的元数据值与现有值相同,则项目可用区元数据条目将保持不变。

示例:添加新的自定义项目可用区元数据条目

举例来说,假设一个名为 my-project 的项目具有以下自定义元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"value-1""key-2":"value-2"

如需将 "key-4":"value-4" 添加为 us-central1-a 可用区中的新自定义项目可用区元数据对,请发出以下 PATCH 请求:

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

示例:更新现有自定义项目可用区元数据条目的值

考虑同一示例项目 my-project,该项目现在具有以下自定义元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"value-1""key-2":"value-2""key-4":"value-4"

如需使用新值更新 us-cerntral1-a 可用区中 key-1key-4 的项目可用区元数据值,请发出以下 PATCH 请求:

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

示例:替换元数据键的项目范围值,并使用项目可用区值

考虑同一示例项目 my-project,该项目现在具有以下自定义元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"new-value-1""key-2":"value-2""key-4":"new-value-4"

在此示例项目中,请考虑使用 key-3,其项目范围的元数据值为 value-c。假设您希望为 us-central1-a 可用区中的所有虚拟机为此键设置项目可用区元数据值 value-3。执行该操作时,对于 us-central1-a 可用区中的所有虚拟机,Compute Engine 会替换项目范围的值并使用项目可用区值。项目所有其他可用区中的虚拟机保留了 key-3 的主要项目范围或项目可用区元数据值。

如需替换 key-3 的项目范围的元数据值,并改用自定义项目可用区值 value-3,请发出以下 PATCH 请求:

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

设置自定义实例元数据

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST 添加或更新单个虚拟机实例的自定义元数据。

您可以通过以下某种方式设置自定义实例元数据:

在创建虚拟机期间添加自定义实例元数据

使用以下说明在创建虚拟机时添加特定虚拟机实例上的元数据。

控制台

  1. 在 Google Cloud 控制台中,转到创建实例页面。

    转到“创建实例”

  2. 指定虚拟机详情。

  3. 展开高级选项部分,然后执行以下操作:

    1. 展开管理部分。
    2. 如需为自定义元数据添加多个键值对,请点击元数据部分中的添加一项
  4. 如需创建虚拟机,请点击创建

gcloud

如需设置自定义元数据,请使用带有 --metadata 标志的 gcloud compute instances create 命令

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

请替换以下内容:

  • VM_NAME:您的虚拟机的名称
  • KEY:元数据键的名称
  • VALUE:为此键存储的值

示例

例如,如需在名为 example-instance 的虚拟机上设置值为 bar 的新键 foo,请运行以下命令:

gcloud compute instances create example-instance \
    --metadata=foo=bar

REST

使用 instances.insert 方法并在请求中提供自定义元数据作为 metadata 属性的一部分:

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

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

请替换以下内容:

  • PROJECT_ID:您的项目 ID
  • ZONE:要在其中创建虚拟机的可用区
  • MACHINE_TYPE:新虚拟机的预定义自定义机器类型
  • VM_NAME:新虚拟机的名称
  • KEY:元数据键的名称
  • VALUE:为此键存储的值

在现有虚拟机上添加或更新自定义实例元数据

使用以下说明可更新已存在的特定虚拟机实例上的元数据。

控制台

  1. 在 Google Cloud 控制台中,前往虚拟机实例页面。

    转到“虚拟机实例”页面

  2. 点击您想要更新其元数据的实例。
  3. 点击页面顶部的修改按钮。
  4. 自定义元数据下,点击添加一项或修改现有的元数据条目。
  5. 保存更改。

gcloud

使用 gcloud CLI 更新虚拟机元数据是一项附加性操作。请仅指定您要添加或更改的元数据键。如果您提供的键已经存在,则系统将使用新值来更新该键对应的值。

使用 instances add-metadata 命令

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

请替换以下内容:

  • VM_NAME:您的虚拟机的名称
  • KEY:元数据键的名称
  • VALUE:为此键存储的值

示例

如果要添加 foo=bar 条目,请使用以下命令:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

如果您要将 foo=bar 条目更改为 foo=bat,请使用以下命令:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

  1. 获取当前指纹并查看虚拟机的任何现有键值对。为此,请调用 instances().get 方法

    指纹是由 Compute Engine 生成的随机字符串,可用于执行乐观锁定。 如需更新虚拟机,您需要提供匹配的指纹值。每次请求后指纹都会更改,因此如果您提供的指纹不匹配,请求将被拒绝。这样,一次就只能进行一项更新,以免发生冲突。

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

    替换以下内容:

    • PROJECT_ID:您的项目 ID
    • ZONE:虚拟机所在的地区
    • VM_NAME:您的虚拟机的名称

    输出类似于以下内容:

    {
      ...
      "name": "example-instance",
      "metadata": {
        "kind": "compute#metadata",
        "fingerprint": "zhma6O1w2l8="
        "items": [
          {
            "key": "foo",
            "value": "bar"
          }
        ]
        },
      ...
    }
    
  2. instances().setMetadata 方法发出请求。 请提供新元数据值和当前 fingerprint 值的列表。

    如果您想要保留虚拟机的现有键值对,则必须将这些现有键值对和新键值对都加入此请求中。

    示例

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata
    
    {
    "fingerprint": "zhma6O1w2l8=",
    "items": [
      {
        "key": "foo",
        "value": "bar"
      },
      {
        "key": "baz",
        "value": "bat"
      }
    ]
    }
    

    请替换以下内容:

    • PROJECT_ID:您的项目 ID
    • ZONE:虚拟机所在的地区
    • VM_NAME:您的虚拟机的名称

从虚拟机中移除自定义元数据

您可以通过以下方式之一从 Compute Engine 虚拟机中移除自定义元数据:

移除自定义项目范围的元数据

您可以使用 Google Cloud 控制台或 Google Cloud CLI 移除自定义项目范围的元数据。

控制台

  1. 在 Google Cloud 控制台中,转到元数据页面。

    转到元数据页面

  2. 点击页面顶部的修改修改
  3. 元数据部分,针对要移除的每个元数据条目点击删除 删除项
  4. 如需确认您的更改并移除自定义项目范围的元数据,请点击保存

gcloud

如需移除自定义项目范围的元数据,请使用 gcloud compute project-info remove-metadata 命令

  • 如果您想要移除特定键的自定义元数据条目,请使用 --keys 标志指定这些键,并排除这些键的值。
gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...
  • 如果您要移除虚拟机的所有自定义元数据,请指定 --all 标志。
gcloud compute project-info remove-metadata \
    --all

替换以下内容:

  • KEY1KEY2...:要移除的自定义实例元数据键。

移除自定义项目可用区元数据

您可以使用 Google Cloud CLI 或 Compute Engine API 移除自定义项目可用区元数据。

gcloud

如需移除自定义项目可用区元数据,请使用 gcloud beta compute project-zonal-metadata remove 命令,并使用 --keys 标志指定要移除的所有元数据键。

gcloud beta compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

替换以下内容:

  • PROJECT_ID:您的项目 ID
  • ZONE:您要设置项目可用区元数据的可用区。
  • KEY1KEY2...:要移除的自定义项目可用区元数据键。

运行该命令后,如果任何指定的键具有项目范围的元数据值,则指定可用区中的虚拟机将继承这些项目范围的值。如果元数据键仅在项目可用区级设置,并且没有相应的项目范围密钥,则虚拟机会丢失该元数据信息。

示例:

以项目 my-project 为例,该项目具有以下自定义项目元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"new-value-1""key-2":"value-2""key-3":"value-3""key-4":"new-value-4"

如需移除 us-central1-a 可用区的所有项目可用区元数据,请运行以下命令。

gcloud beta compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

运行该命令后,us-central1-a 可用区中的虚拟机具有以下自定义项目元数据:

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-c"

REST

  1. 获取当前指纹并查看该可用区中项目的任何现有键值对。

    如需执行乐观锁定,您必须提供指纹。指纹是由 Compute Engine 生成的随机字符串。每次您发出添加、更新或移除项目可用区元数据的请求时,指纹都会更改,并且如果您提供的指纹不匹配,Compute Engine 会拒绝您的请求。

    如果您未提供指纹,则系统会执行一致性检查,并且您的删除请求不会成功。这样,一次就只能进行一项请求,以免发生冲突。此行为与 instances().setMetadata 匹配,其中始终需要指纹。

    如需获取项目的当前指纹,请调用 instanceSettings().get 方法

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
    

    替换以下内容:

    • PROJECT_ID:您的项目 ID
    • ZONE:要移除项目可用区元数据的可用区。

    以下是此请求的示例输出:

        {
          "fingerprint": "FikclA7UBC0=",
          "metadata": {
            ...
          }
        }
    
  2. 如需移除自定义项目可用区元数据,请向 instanceSettings().patch 方法发出 PATCH 请求,方法是从请求正文中排除要移除其项目可用区元数据的元数据键。您必须在请求中提供以下信息:

    • 更新掩码。使用 update_mask 查询参数。更新掩码必须包含您要移除其元数据的所有现有自定义项目可用区元数据键。您必须添加字符串 metadata.items. 作为每个键的前缀,例如 metadata.items.key1,metadata.items.key3
    • 在请求正文中,仅提供当前指纹值。排除您在更新掩码中指定的所有元数据键。 如果您在更新掩码和请求正文中都包含任何元数据键,则 Compute Engine 不会移除这些键的项目可用区元数据。
    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
    {
      "fingerprint": "FINGER_PRINT",
      "metadata": {
        "items": {
        }
      }
    }
    

    替换以下内容:

    • PROJECT_ID:项目的 ID。
    • ZONE:要移除项目可用区元数据的可用区。
    • PREFIXED_METADATA_KEYS:要移除的所有现有自定义项目可用区元数据键的列表,其中每个键都以字符串 metadata.items. 为前缀。为确保删除请求成功,请从请求正文中排除这些元数据键。 如果您在更新掩码和请求正文中都包含任何元数据键,则 Compute Engine 不会移除这些键的项目可用区元数据。

      例如,假设您当前的项目可用区元数据键为 key-1key-2key-3key-4,并且想要移除 key-1key-2 的项目可用区元数据条目,则更新掩码必须具有以下字符串:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT:当前指纹值。

发出请求后,如果任何指定的键具有项目范围的元数据值,则指定可用区中的虚拟机将继承这些项目范围的值。如果元数据键仅在项目可用区级设置,并且没有相应的项目范围密钥,则虚拟机会丢失该元数据信息。

示例:

以项目 my-project 为例,该项目具有以下自定义项目元数据:

  • 项目范围的元数据:"key-1":"value-a""key-2":"value-b""key-3":"value-c"
  • us-central1-a 可用区中的项目可用区元数据:"key-1":"new-value-1""key-2":"value-2""key-3":"value-3""key-4":"new-value-4"

如需移除 us-central1-a 可用区中 key-1key-2 的项目可用区元数据,请发出以下 PATCH 请求。

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

此请求完成后,us-central1-a 可用区中的虚拟机将具有以下自定义项目元数据。虚拟机会继承 key-1key-2 的项目范围元数据值,但会保留 key-3 的项目可用区值。

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-3"

移除自定义实例元数据

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST 移除自定义实例元数据。

控制台

  1. 在 Google Cloud 控制台中,前往虚拟机实例页面。

    进入“虚拟机实例”页面

  2. 名称列中,点击要移除其元数据的虚拟机的名称。
  3. 点击页面顶部的修改修改
  4. 元数据部分,针对要移除的每个元数据条目点击删除 删除项
  5. 如需确认您的更改并移除自定义实例元数据,请点击保存

gcloud

如需移除自定义实例元数据,请使用 gcloud compute instances remove-metadata 命令

  • 如果您想要移除特定键的自定义元数据条目,请使用 --keys 标志指定这些键,并排除这些键的值。
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...
  • 如果您要移除虚拟机的所有自定义元数据,请指定 --all 标志。
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

替换以下内容:

  • PROJECT_ID:您的项目 ID。
  • ZONE:您的虚拟机所在的可用区。
  • VM_NAME:您的虚拟机的名称
  • KEY1KEY2...:要移除的自定义实例元数据键。

REST

  1. 获取当前指纹并查看虚拟机的任何现有键值对。为此,请调用 instances().get 方法

    指纹是由 Compute Engine 生成的随机字符串,可用于执行乐观锁定。 如需更新虚拟机,您需要提供匹配的指纹值。每次请求后指纹都会更改,因此如果您提供的指纹不匹配,请求将被拒绝。这样,一次就只能进行一项更新,以免发生冲突。

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

    替换以下内容:

    • PROJECT_ID:您的项目 ID。
    • ZONE:您的虚拟机所在的可用区。
    • VM_NAME:您的虚拟机的名称

    输出类似于以下内容:

    {
      ...
      "name": "example-instance",
      "metadata": {
        "kind": "compute#metadata",
        "fingerprint": "zhma6O1w2l8="
        "items": [
        {
          "key": "key-1",
          "value": "value-1"
        }
        {
          "key": "key-2",
          "value": "value-2"
        }
        ]
      },
      ...
    }
    
  2. instances().setMetadata 方法发出请求。 为了确保请求成功,您必须添加当前的元数据指纹值。

    • 如需从虚拟机中移除所有自定义元数据键值对,请在 items 属性中,移除要为其移除元数据值的元数据键。

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata
      
      {
      "fingerprint": "FINGER_PRINT"
      "items": [
        {
          "key": "KEY1"
          "value": "VALUE1"
        }
        {
          "key": "KEY2"
          "value": "VALUE2"
        }
        ...
      ]
      }
      
    • 如需移除虚拟机上的所有自定义实例元数据,请完全排除 items 属性。

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata
      
      {
      "fingerprint": FINGER_PRINT
      }
      

    替换以下内容:

    • PROJECT_ID:您的项目 ID。
    • ZONE:您的虚拟机所在的可用区。
    • VM_NAME:您的虚拟机的名称
    • FINGER_PRINT:当前指纹值。
    • KEY1KEY2...:要移除的自定义实例元数据键。
    • VALUE1VALUE2...:要移除的自定义实例元数据键的值。

后续步骤