管理资源设置

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

准备工作

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

启用 API

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

Cloud Console

要启用 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。例如 --projects=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 工具请求中使用。

更改局部设置值

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

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。例如 --projects=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_PARAMETERSETTING_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 工具检索给定资源的设置有效值。如需了解详细说明,请参阅查看局部或有效值设置。在以下示例中,为一个组织、该组织中的一个文件夹以及该文件夹的一个子文件夹设置了“首选 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 工具的 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
  }
}