管理资源设置

本指南介绍如何管理资源设置。您可以使用资源设置来为 Google Cloud 项目、文件夹和组织集中配置设置。您可以通过每个资源设置控制受支持的服务的一个方面。

准备工作

如需详细了解资源设置及其工作原理，请参阅资源设置概览。

启用 API

您可以为各个项目单独启用 Resource Settings API。

Google Cloud 控制台

要启用 Resource Settings API，请执行以下操作：

转到 API 和服务

  1. 选择您将使用哪个项目访问该 API。
  2. 点击启用 API 和服务按钮。
  3. 搜索“Resource Settings”。
  4. 在搜索结果中，点击“Resource Settings API”。
  5. 如果显示“API 已启用”，则表示此 API 已启用。如未显示，请点击启用按钮。

gcloud

要启用 Resource Settings API，请使用 gcloud services enable 命令：

gcloud services enable resourcesettings.googleapis.com

所需权限

您需要的权限取决于您需要执行的操作。

如需获得这些权限，请让您的管理员在资源层次结构的适当级层授予建议的角色。

查看资源设置

如需查看可用于某个资源的资源设置，以及资源上的局部和有效设置值，您需要 Resource Settings Viewer 角色 (roles/resourcesettings.viewer) 或拥有以下权限的其他角色：

  • resourcesettings.settings.get
  • resourcesettings.settings.list

管理资源设置

如需创建、更新和删除资源的资源设置值，您需要 Resource Settings Administrator 角色 (roles/resourcesettings.admin) 或拥有以下权限的其他角色：

  • resourcesettings.settings.get
  • resourcesettings.settings.list
  • resourcesettings.settings.update

列出可用的设置

您可以获取给定资源所有可用资源设置的列表。此列表显示可应用于该资源的所有资源设置。预览状态的资源设置仅可用于已获得明确使用权限的资源。

gcloud

要获取可用于某个资源的所有设置的列表，请使用以下 gcloud resource-settings list 命令：

gcloud resource-settings list --RESOURCE_ID

其中 RESOURCE_ID 是您要查找其可用资源设置的文件夹、项目或组织的 ID。例如 --project=7890123456

API

要获取可用于某个资源的所有设置的列表，请使用以下 settings.list 方法之一。使用与要为其列出设置的资源类型相对应的方法：

curl -X GET -H "Content-Type: application/json" -H \
  "Authorization: Bearer $ACCESS_TOKEN" \
  https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings

替换以下内容：

  • ACCESS_TOKEN：您的 OAuth 2.0 访问令牌。

  • RESOURCE_ID：您要为其查找可用资源设置的文件夹、项目或组织的 ID。例如 projects/7890123456

示例响应

对 folders/4567890123 的 list 请求的响应如下所示：

{
  "settings" : [
    {
      "name": "folders/4567890123/settings/net-preferredDnsServers",
      "metadata":  {
        "displayName": "Preferred DNS Servers",
        "description": "The DNS servers to be used by VMs associated with this resource.",
        "read_only": false,
        "data_type" : "STRING_SET",
        "default_value" : {
          "string_set_value" : {
            "values" : [ "8.8.8.8" ],
          }
        }
      }
    },
    {
      "name": "folders/4567890123/settings/text-defaultTextColor",
      "metadata":  {
        "displayName": "Default Text Color",
        "description": "The default text color for this resource.",
        "read_only": false,
        "data_type" : "STRING",
        "default_value" : {
          "string_value" : "black"
        }
      }
    },
    ...
  ]
}

name 字段是资源设置的简称，应在与该设置相关的 API 和 gcloud CLI 请求中使用。

更改局部设置值

您可以更改给定资源资源设置的局部设置值。如果您设置局部设置值，此值会替换所有继承的有效值设置。如果您取消设置局部设置值，应用于祖先资源的任何局部设置值将被继承，成为有效值。

gcloud

要更改资源上资源设置的局部设置值，请使用以下 gcloud resource-settings set-value 命令：

gcloud resource-settings set-value --value-file=FILE_PATH

将 FILE_PATH 替换为包含资源设置的 YAML 或 JSON 文件的路径。

示例 JSON 文件：

{
  "localValue" : {
    "stringSetValue": {
      "values": [
        "8.8.8.8",
        "8.8.4.4",
      ]
    }
  },
  "name": "RESOURCE_ID/settings/SETTING_NAME"
}

替换以下内容：

  • RESOURCE_ID：您要为其更新局部资源设置的文件夹、项目或组织的 ID。例如 projects/7890123456

  • SETTING_NAME：您要更新的资源设置的短名称。

要取消设置资源的局部设置值，请使用 gcloud resource-settings unset-value 命令：

gcloud resource-settings unset-value SETTING_NAME \
  --RESOURCE_ID

替换以下内容：

  • SETTING_NAME：您要为其取消设置局部值的资源设置的短名称。

  • RESOURCE_ID：您要为其查找可用资源设置的文件夹、项目或组织的 ID。例如 projects/7890123456

API

要更改资源上资源设置的局部设置值，请使用 settings.patch 方法。使用与要为其更新设置的资源类型相对应的方法：

curl -X PATCH -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -d \
  '{
    "localValue": {
      "stringSetValue": {
        "values": [ "8.8.8.8", "8.8.4.4" ]
      }
    }
  }
  ' https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings/net-preferredDnsServers

替换以下内容：

  • ACCESS_TOKEN：您的 OAuth 2.0 访问令牌。

  • RESOURCE_ID：您要为其查找可用资源设置的文件夹、项目或组织的 ID。例如 projects/7890123456

如果您发出该请求时 JSON 文件中未包含局部值，则会取消设置局部设置值，资源将继承父值设置，或使用 Google 管理的默认值。

发出成功请求后，您会收到一个响应，其中包含为此设置创建的局部值以及必须在后续更新请求中包含的 etag 字段。

{
  "name": "folders/4567890123/settings/net-preferredDnsServers",
  "localValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8", "8.8.4.4" ]
    }
  }
  "etag": "O2VWGxZU01VnAfRU4Mu97w==",
}

查看局部或有效值设置

您可以查看给定资源的资源设置的局部值或有效值。

gcloud

要查看给定资源的资源设置的局部值，请使用 gcloud resource-settings describe 命令，如下所示：

gcloud resource-settings describe SETTING_NAME \
  --RESOURCE_ID

替换以下内容：

  • SETTING_NAME：您要查找其局部值或有效值的资源设置的短名称。

  • RESOURCE_ID：您要为其查找可用资源设置的文件夹、项目或组织的 ID。例如 --project=7890123456

如果添加 --effective 标志，您将获得为该资源评估的有效值。

API

要查看给定资源的资源设置的局部值或有效值，请使用 settings.get 方法。使用与要为其列出设置的资源类型相对应的方法：

curl -X GET -H "Content-Type: application/json" -H \
  "Authorization: Bearer $ACCESS_TOKEN" \
  https://resourcesettings.googleapis.com/v1/RESOURCE_ID \
  /settings/SETTING_NAME?view=VIEW_PARAMETER

替换以下内容：

  • ACCESS_TOKEN：您的 OAuth 2.0 访问令牌。

  • RESOURCE_ID：您要为其查找可用资源设置的文件夹、项目或组织的 ID。例如 projects/7890123456

  • SETTING_NAME：您要为其返回值的资源设置的短名称。

  • VIEW_PARAMETER：SETTING_VIEW_LOCAL_VALUE（返回局部设置值）或 SETTING_VIEW_EFFECTIVE_VALUE（返回此资源上的有效值）。

示例响应

对 folders/4567890123 的 get 请求的响应如下所示：

{
  "name": "folders/4567890123/settings/net-preferredDnsServers",
  "value": {
    "stringSetValue": {
      "values": [ "8.8.8.8", "8.8.4.4" ]
    }
  }
  "etag": "O2VWGxZU01VnAfRU4Mu97w=="
}

继承

对给定资源生效的资源设置是根据继承评估的。您可以通过设置局部值来替换资源的继承值，这也会影响该资源的子资源继承的设置值。如需详细了解资源设置继承，请参阅有效设置值。

检索有效值

您可以使用 API 或 gcloud CLI 检索给定资源上某项设置的有效值。如需了解详细说明，请参阅查看局部值或有效值设置。在以下示例中，为一个组织、该组织中的一个文件夹以及该文件夹的一个子文件夹设置了“首选 DNS 服务器”资源设置的值：

每个资源的有效值评估如下：

  • organizations/111 没有局部值，也没有可以继承的父资源，因此会使用 Google 管理的默认值 8.8.8.8。

    • 如果您使用 describe 方法获取资源的有效值，并且该方法使用 Google 管理的默认值，则该信息将包含在响应中。例如：
    {
  "name": "organizations/111/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8" ] # Google-managed default
    }
  }
}

  • folders/222 的局部值设置为 8.8.4.4，因此它不会继承其父资源。

    • 如果您使用 describe 方法获取资源的有效值，并且该值是局部设置的值，则该信息会包含在响应中。例如：
    {
  "name": "folders/222/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # set on folders/222
    }
  }
}

  • folders/333 没有局部值，但其父资源有。它会继承 folders/222 的局部设置值，因此评估结果为 8.8.4.4。

    • 如果您使用 describe 方法获取资源的有效值，并且该资源从父资源继承该值，则该信息会包含在响应中。例如：
    {
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}

替换继承的值

如果您更改 folders/333 的“首选 DNS 服务器”设置的局部设置值，则会更改有效值。例如，您使用 patch 方法将 folders/333 的局部设置值更新为 192.168.1.1。如需了解详细说明，请参阅更改局部设置值。

如果您对更新后的 folders/333 资源使用 describe 方法，会看到有效值现在为 192.168.1.1：

{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "192.168.1.1" ] # set on folders/333
    }
  }
}

还原为继承值

如需还原此行为，使资源从父项继承本地值，请使用 API patch 方法，并且未设置查询中的本地值，或者使用 gcloud CLI unset-value 命令。如需了解详细说明，请参阅更改本地设置值。

例如，如果取消设置 folders/333 上的局部值，它将再次从其最近的父资源 folders/222 继承有效值。如果您对更新后的 folders/333 资源使用 describe 方法，会看到有效值现在为 8.8.4.4：

{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}