Manage resource settings

This guide describes how to manage resource settings. You can use the Resource Settings to centrally configure settings for your Google Cloud projects, folders, and organization. Each resource setting allows you to control an aspect of a supported service.

Before you begin

For more information about what resource settings are and how they work, see the Resource Settings overview.

Enable the API

The Resource Settings API can be enabled for individual projects.

Google Cloud console

To enable the Resource Settings API, do the following:

Go to APIs & services

  1. Select the project you will use to access the API.
  2. Click the Enable APIs and Service button.
  3. Search for "Resource Settings".
  4. In the search results, click through to "Resource Settings API".
  5. If "API enabled" is displayed, then the API is already enabled. If not, click the Enable button.

gcloud

To enable the Resource Settings API, use the gcloud services enable command:

gcloud services enable resourcesettings.googleapis.com

Required permissions

The permissions you need depend on the action you need to perform.

To gain these permissions, ask your administrator to grant the suggested role at the appropriate level of the resource hierarchy.

View resource settings

To view the resource settings available for use on a resource, as well as the local an effective setting values on a resource, you need the Resource Settings Viewer role (roles/resourcesettings.viewer), or another role that includes the following permissions:

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

Administer resource settings

To create, update, and delete resource setting values on a resource, you need the Resource Settings Administrator role (roles/resourcesettings.admin), or another role that includes the following permissions:

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

List available settings

You can get a list of all available resource settings for a given resource. This list displays all resource settings that can be applied to the resource. Resource settings in preview status are only available to those that have been given explicit permission to use them.

gcloud

To get a list of all settings available for use on a resource, use the following gcloud resource-settings list command:

gcloud resource-settings list --RESOURCE_ID

Where RESOURCE_ID is the ID of the folder, project, or organization for which you want to find available resource settings. For example: --project=7890123456

API

To get a list of all settings available for use on a resource, use one of the following settings.list methods. Use the method that corresponds to the type of resource for which you want to list settings:

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

Replace the following:

  • ACCESS_TOKEN: your OAuth 2.0 access token.

  • RESOURCE_ID: the ID of the folder, project, or organization for which you want to find available resource settings. For example: projects/7890123456

Example response

A response to a list request on folders/4567890123 looks similar to the following:

{
  "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"
        }
      }
    },
    ...
  ]
}

The name field is the short name of the resource setting, which should be used in API and gcloud CLI requests related to that setting.

Change a local setting value

You can change the local setting value of a given resource setting. If you set a local setting value, this overrides any inherited effective value setting. If you unset the local setting value, any local setting value applied to an ancestry resource is inherited, making it the effective value.

gcloud

To change the local setting value for a resource setting on a resource, use the following gcloud resource-settings set-value command:

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

Replace FILE_PATH with the path to a YAML or JSON file that contains the resource setting.

Example JSON file:

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

Replace the following:

  • RESOURCE_ID: the ID of the folder, project, or organization for which you want to update the local resource setting. For example: projects/7890123456

  • SETTING_NAME: the short name of the resource setting you want to update.

To unset a local setting value on a resource, use the gcloud resource-settings unset-value command:

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

Replace the following:

  • SETTING_NAME: the short name of the resource setting for which you want to unset the local value.

  • RESOURCE_ID: the ID of the folder, project, or organization for which you want to find available resource settings. For example: projects/7890123456

API

To change the local setting value for a resource setting on a resource, use the settings.patch method. Use the method that corresponds to the type of resource for which you want to update settings:

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

Replace the following:

  • ACCESS_TOKEN: your OAuth 2.0 access token.

  • RESOURCE_ID: the ID of the folder, project, or organization for which you want to find available resource settings. For example: projects/7890123456

If you make this request with no local value included in the JSON file, you unset the local settings value, and the resource inherits the parent value setting, or uses the Google-managed default.

After you make a successful request, you get a response that includes the local value that was created for this setting and an etag field you must include on subsequent update requests.

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

View the local or effective value setting

You can view the local or effective value of a resource setting at a given resource.

gcloud

To view the local value of a resource setting at a given resource, use the gcloud resource-settings describe command, as follows:

gcloud resource-settings describe SETTING_NAME \
  --RESOURCE_ID

Replace the following:

  • SETTING_NAME: the short name of the resource setting for which you want to find the local or effective value.

  • RESOURCE_ID: the ID of the folder, project, or organization for which you want to find available resource settings. For example: --project=7890123456

If you add the --effective flag, you get the effective value as it is evaluated for this resource instead.

API

To view the local or effective value of a resource setting at a given resource, use the settings.get method. Use the method that corresponds to the type of resource for which you want to list settings:

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

Replace the following:

  • ACCESS_TOKEN: your OAuth 2.0 access token.

  • RESOURCE_ID: the ID of the folder, project, or organization for which you want to find available resource settings. For example: projects/7890123456

  • SETTING_NAME: the short name of the resource setting for which you want return values.

  • VIEW_PARAMETER: SETTING_VIEW_LOCAL_VALUE to return the local setting value, or SETTING_VIEW_EFFECTIVE_VALUE to return the effective value at this resource.

Example response

A response to a get request on folders/4567890123 looks similar to the following:

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

Inheritance

The resource setting that takes effect on a given resource is evaluated based on inheritance. You can override the inherited value on a resource by setting a local value, which also impacts the setting values inherited by that resource's children. For more information about resource setting inheritance, see Effective setting values.

Retrieve effective values

You can retrieve the effective value of a setting on a given resource using the API or gcloud CLI. For detailed instructions, see View the local or effective value setting. Consider the following example, with the values set for the Preferred DNS Servers resource setting on an organization, a folder within that organization, and a subfolder within that folder:

The effective values on each of these resources evaluate as follows:

  • organizations/111 has no local value, and does not have a parent resource to inherit from, and so would use the Google-managed default of 8.8.8.8.

    • If you use the describe method to get the effective value on a resource, and it uses the Google-managed default, that information is included in the response. For example:
    {
  "name": "organizations/111/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8" ] # Google-managed default
    }
  }
}

  • folders/222 has a local value setting of 8.8.4.4, and so it doesn't inherit from its parent resource.

    • If you use the describe method to get the effective value on a resource, and it is a locally-set value, that information is included in the response. For example:
    {
  "name": "folders/222/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # set on folders/222
    }
  }
}

  • folders/333 has no local value, but its parent resource does. It inherits the local setting value from folders/222, and so evaluates to 8.8.4.4.

    • If you use the describe method to get the effective value on a resource, and it inherits that value from a parent resource, that information is included in the response. For example:
    {
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}

Override inherited value

If you change the local setting value of folders/333 for the Preferred DNS Servers setting, that changes the effective value. For example, you use the patch method to update the local setting value of folders/333 to 192.168.1.1. For detailed instructions, see Change a local setting value.

If you use the describe method on the updated folders/333 resource, you see that the effective value is now 192.168.1.1:

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

Revert to inheriting value

To revert this behavior such that a resource inherits the local value from a parent, use the API patch method with no local value set in the query, or by using the gcloud CLI unset-value command. For detailed instructions, see Change a local setting value.

For example, if you unset the local value on folders/333, it would once again inherit the effective value from its nearest parent resource, folders/222. If you use the describe method on the updated folders/333 resource, you see that the effective value is now 8.8.4.4:

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