Package google.cloud.resourcesettings.v1alpha1

  • ResourceSettingsService provides an interface for interacting with resource settings and setting values within the Google Cloud resource hierarchy.

  • Setting values are inherited hierarchically, with values applied to a resource being inherited by all its descendants.

  • The service offers methods to create, delete, get, list, lookup, search, and update setting values.

  • All requests require specific IAM permissions and may return errors like PERMISSION_DENIED, INVALID_ARGUMENT, or NOT_FOUND.

  • Setting values can have different data types, including boolean, string, and string set, and their schema is defined by the corresponding setting.

Index

ResourceSettingsService

An interface to interact with resource settings and setting values throughout the resource hierarchy.

Services may surface a number of settings for users to control how their resources behave. Setting values applied on a given Cloud resource are evaluated hierarchically and inherited by all descendants of that resource.

For all requests, returns a google.rpc.Status with google.rpc.Code.PERMISSION_DENIED if the IAM check fails or the parent resource is not in a Cloud Organization. For all requests, returns a google.rpc.Status with google.rpc.Code.INVALID_ARGUMENT if the request is malformed.

Note: For all alpha stage Settings, the Setting does not exist under any resources in Cloud Organizations that are not in the alpha.

CreateSettingValue

rpc CreateSettingValue(CreateSettingValueRequest) returns (SettingValue)

Creates a setting value.

Returns a google.rpc.Status with google.rpc.Code.NOT_FOUND if the setting does not exist. Returns a google.rpc.Status with google.rpc.Code.ALREADY_EXISTS if the setting value already exists on the given Cloud resource. Returns a google.rpc.Status with google.rpc.Code.FAILED_PRECONDITION if the setting is flagged as read only.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteSettingValue

rpc DeleteSettingValue(DeleteSettingValueRequest) returns (Empty)

Deletes a setting value. If the setting value does not exist, the operation is a no-op.

Returns a google.rpc.Status with google.rpc.Code.NOT_FOUND if the setting or the setting value does not exist. The setting value will not exist if a prior call to DeleteSetting for the setting value already returned a success code. Returns a google.rpc.Status with google.rpc.Code.FAILED_PRECONDITION if the setting is flagged as read only.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetSettingValue

rpc GetSettingValue(GetSettingValueRequest) returns (SettingValue)

Gets a setting value.

Returns a google.rpc.Status with google.rpc.Code.NOT_FOUND if the setting value does not exist.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListSettings

rpc ListSettings(ListSettingsRequest) returns (ListSettingsResponse)

Lists all the settings that are available on the Cloud resource parent.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
LookupEffectiveSettingValue

rpc LookupEffectiveSettingValue(LookupEffectiveSettingValueRequest) returns (SettingValue)

Computes the effective setting value of a setting at the Cloud resource parent. The effective setting value is the calculated setting value at a Cloud resource and evaluates to one of the following options in the given order (the next option is used if the previous one does not exist):

  1. the setting value on the given resource
  2. the setting value on the given resource's nearest ancestor
  3. the setting's default value
  4. an empty setting value, defined as a SettingValue with all fields unset

Returns a google.rpc.Status with google.rpc.Code.NOT_FOUND if the setting does not exist.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
SearchSettingValues

rpc SearchSettingValues(SearchSettingValuesRequest) returns (SearchSettingValuesResponse)

Searches for all setting values that exist on the resource parent. The setting values are not limited to those of a particular setting.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateSettingValue

rpc UpdateSettingValue(UpdateSettingValueRequest) returns (SettingValue)

Updates a setting value.

Returns a google.rpc.Status with google.rpc.Code.NOT_FOUND if the setting or the setting value does not exist. Returns a google.rpc.Status with google.rpc.Code.FAILED_PRECONDITION if the setting is flagged as read only. Returns a google.rpc.Status with google.rpc.Code.ABORTED if the etag supplied in the request does not match the persisted etag of the setting value.

Note: the supplied setting value will perform a full overwrite of all fields.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

CreateSettingValueRequest

The request for CreateSettingValue.

Fields
setting_value

SettingValue

The setting value to create. See SettingValue for field requirements.

Authorization requires the following IAM permission on the specified resource settingValue:

  • resourcesettings.settingvalues.create

DeleteSettingValueRequest

The request for DeleteSettingValue.

Fields
name

string

The name of the setting value to delete. See SettingValue for naming requirements.

Authorization requires the following IAM permission on the specified resource name:

  • resourcesettings.settingvalues.delete
ignore_read_only

bool

A flag that allows the deletion of the value of a read_only setting. WARNING: use at your own risk. Deleting the value of a read only setting is an irreversible action (i.e., it cannot be created again).

GetSettingValueRequest

The request for GetSettingValue.

Fields
name

string

The name of the setting value to get. See SettingValue for naming requirements.

Authorization requires the following IAM permission on the specified resource name:

  • resourcesettings.settingvalues.get

ListSettingsRequest

The request for ListSettings.

Fields
parent

string

The Cloud resource that parents the setting. Must be in one of the following forms:

  • projects/{project_number}
  • projects/{project_id}
  • folders/{folder_id}
  • organizations/{organization_id}

Authorization requires the following IAM permission on the specified resource parent:

  • resourcesettings.settings.list
page_size

int32

Unused. The size of the page to be returned.
page_token

string

Unused. A page token used to retrieve the next page.

ListSettingsResponse

The response from ListSettings.

Fields
settings[]

Setting

A list of settings that are available at the specified Cloud resource.
next_page_token

string

Unused. A page token used to retrieve the next page.

LookupEffectiveSettingValueRequest

The request for LookupEffectiveSettingValue.

Fields
parent

string

The setting for which an effective value will be evaluated. See Setting for naming requirements.

Authorization requires the following IAM permission on the specified resource parent:

  • resourcesettings.settingvalues.get

SearchSettingValuesRequest

The request for SearchSettingValues.

Fields
parent

string

The Cloud resource that parents the setting. Must be in one of the following forms:

  • projects/{project_number}
  • projects/{project_id}
  • folders/{folder_id}
  • organizations/{organization_id}

Authorization requires the following IAM permission on the specified resource parent:

  • resourcesettings.settingvalues.list
page_size

int32

Unused. The size of the page to be returned.
page_token

string

Unused. A page token used to retrieve the next page.

SearchSettingValuesResponse

The response from SearchSettingValues.

Fields
setting_values[]

SettingValue

All setting values that exist on the specified Cloud resource.
next_page_token

string

Unused. A page token used to retrieve the next page.

Setting

The schema for setting values. At a given Cloud resource, a setting can parent at most one setting value.

Fields
name

string

The resource name of the setting. Must be in one of the following forms:

  • projects/{project_number}/settings/{setting_name}
  • folders/{folder_id}/settings/{setting_name}
  • organizations/{organization_id}/settings/{setting_name}

For example, "/projects/123/settings/gcp-enableMyFeature"
display_name

string

The human readable name for this setting.
description

string

A detailed description of what this setting does.
read_only

bool

A flag indicating that values of this setting cannot be modified (see documentation of the specific setting for updates and reasons); however, it may be deleted using DeleteSettingValue if DeleteSettingValueRequest.ignore_read_only is set to true. Using this flag is considered an acknowledgement that the setting value cannot be recreated. See DeleteSettingValueRequest.ignore_read_only for more details.
data_type

DataType

The data type for this setting.
default_value

Value

The value received by LookupEffectiveSettingValue if no setting value is explicitly set.

Note: not all settings have a default value.

DataType

The data type for setting values of this setting. See Value for more details on the available data types.

Enums
DATA_TYPE_UNSPECIFIED Unspecified data type.
BOOLEAN A boolean setting.
STRING A string setting.
STRING_SET A string set setting.

SettingValue

The instantiation of a setting. Every setting value is parented by its corresponding setting.

Fields
name

string

The resource name of the setting value. Must be in one of the following forms:

  • projects/{project_number}/settings/{setting_name}/value
  • folders/{folder_id}/settings/{setting_name}/value
  • organizations/{organization_id}/settings/{setting_name}/value

For example, "/projects/123/settings/gcp-enableMyFeature/value"
value

Value

The value of the setting. The data type of Value must always be consistent with the data type defined by the parent setting.
etag

string

A fingerprint used for optimistic concurrency. See UpdateSettingValue for more details.
read_only

bool

Output only. A flag indicating that this setting value cannot be modified; however, it may be deleted using DeleteSettingValue if DeleteSettingValueRequest.ignore_read_only is set to true. Using this flag is considered an acknowledgement that the setting value cannot be recreated. This flag is inherited from its parent setting and is for convenience purposes. See Setting.read_only for more details.
update_time

Timestamp

Output only. The timestamp indicating when the setting value was last updated.

UpdateSettingValueRequest

The request for UpdateSettingValue.

Fields
setting_value

SettingValue

The setting value to update. See SettingValue for field requirements.

Authorization requires the following IAM permission on the specified resource settingValue:

  • resourcesettings.settingvalues.update

Value

The data in a setting value.

Fields
Union field value. Selects the data type and associated value. value can be only one of the following:
boolean_value

bool

Defines this value as being a boolean value.
string_value

string

Defines this value as being a string value.
string_set_value

StringSet

Defines this value as being a StringSet.

StringSet

A string set value that can hold a set of strings. The maximum length of each string is 60 characters and there can be a maximum of 50 strings in the string set.

Fields
values[]

string

The strings in the set