Neste guia, descrevemos como gerenciar configurações de recursos. É possível usar as configurações de recursos para definir centralmente as configurações dos seus projetos, pastas e organização do Google Cloud. Cada configuração de recursos permite controlar um aspecto de um serviço compatível.
Antes de começar
Para mais informações sobre o que são configurações de recursos e como elas funcionam, consulte Visão geral das configurações de recursos.
Ativar a API
A API Resource Settings pode ser ativada para projetos individuais.
Console do Google Cloud
Para ativar a API Resource Settings, faça o seguinte:
- Selecione o projeto que você usará para acessar a API.
- Clique no botão Ativar APIs e serviço.
- Pesquise "Configurações de recursos".
- Nos resultados da pesquisa, clique em "Resource Settings API".
- Se for exibido "API ativada", a API já está ativada. Caso contrário, clique no botão Ativar.
gcloud
Para ativar a API Resource Settings, use o comando gcloud services enable
:
gcloud services enable resourcesettings.googleapis.com
Permissões necessárias
As permissões necessárias dependem da ação que você precisa realizar.
Para receber essas permissões, peça ao administrador para conceder o papel sugerido no nível apropriado da hierarquia de recursos.
Ver configurações do recurso
Para visualizar as configurações de recursos disponíveis para uso em um recurso, bem como os
valores de configuração efetiva local de um recurso, você precisa do papel
Leitor de configurações do recurso (roles/resourcesettings.viewer
) ), ou outro papel que inclua as seguintes permissões:
resourcesettings.settings.get
resourcesettings.settings.list
Administrar configurações de recursos
Para criar, atualizar e excluir os valores de configuração de um recurso, é necessário ter o papel Administrador de configurações de recursos (roles/resourcesettings.admin
) ou outro papel que inclua as seguintes permissões:
resourcesettings.settings.get
resourcesettings.settings.list
resourcesettings.settings.update
Listar configurações disponíveis
É possível ver uma lista de todas as configurações de recursos disponíveis para um determinado recurso. Essa lista exibe todas as configurações que podem ser aplicadas ao recurso. As configurações de recursos no status de visualização estão disponíveis apenas para aqueles que receberam permissão explícita para usá-las.
gcloud
Para obter uma lista de todas as configurações disponíveis para uso em um recurso, use o método
seguindo
gcloud resource-settings list
comando:
gcloud resource-settings list --RESOURCE_ID
RESOURCE_ID
é o ID da pasta, do projeto
ou da organização em que você quer encontrar as configurações de recursos disponíveis.
Exemplo: --project=7890123456
API
Para ver uma lista de todas as configurações disponíveis para uso em um recurso, use um
dos seguintes métodos settings.list
. Use o método que corresponda ao tipo de recurso para o qual você quer listar as configurações:
curl -X GET -H "Content-Type: application/json" -H \ "Authorization: Bearer $ACCESS_TOKEN" \ https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings
Substitua:
ACCESS_TOKEN
: seu token de acesso OAuth 2.0.RESOURCE_ID
: o ID da pasta, projeto ou organização para a qual você quer encontrar as configurações de recursos disponíveis. Exemplo:projects/7890123456
Exemplo de resposta
Uma resposta a uma solicitação de lista em folders/4567890123
é semelhante a esta:
{ "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" } } }, ... ] }
O campo name
é o nome abreviado da configuração do recurso, que precisa ser usado
em solicitações de API e da CLI gcloud relacionadas a essa configuração.
Alterar um valor de configuração local
É possível mudar o valor da configuração local de uma determinada configuração de recurso. Se você definir um valor de configuração local, ele substituirá qualquer configuração de valor efetivo herdada. Se você não definir o valor da configuração local, qualquer valor de configuração local aplicado a um recurso ancestral será herdado, tornando-o o valor efetivo.
gcloud
Para alterar o valor da configuração local de um recurso,
use o comando
gcloud resource-settings set-value
:
gcloud resource-settings set-value --value-file=FILE_PATH
Substitua FILE_PATH
pelo caminho para um arquivo YAML ou
JSON que contenha a configuração de recurso.
exemplo de arquivo JSON:
{ "localValue" : { "stringSetValue": { "values": [ "8.8.8.8", "8.8.4.4", ] } }, "name": "RESOURCE_ID/settings/SETTING_NAME" }
Substitua:
RESOURCE_ID
: o ID da pasta, do projeto ou da organização em que você quer atualizar a configuração do recurso local. Exemplo:projects/7890123456
SETTING_NAME
: o nome curto da configuração de recursos que você quer atualizar.
Para remover a definição de um valor de configuração local em um recurso, use o
gcloud resource-settings unset-value
comando:
gcloud resource-settings unset-value SETTING_NAME \ --RESOURCE_ID
Substitua:
SETTING_NAME
: o nome curto da configuração do recurso em que você quer desativar o valor local.RESOURCE_ID
: o ID da pasta, projeto ou organização para a qual você quer encontrar as configurações de recursos disponíveis. Exemplo:projects/7890123456
API
Para alterar o valor da configuração local de um recurso,
use o método settings.patch
. Use o método que corresponda ao tipo de recurso para o qual você quer atualizar as configurações:
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
Substitua:
ACCESS_TOKEN
: seu token de acesso OAuth 2.0.RESOURCE_ID
: o ID da pasta, projeto ou organização para a qual você quer encontrar as configurações de recursos disponíveis. Exemplo:projects/7890123456
Se você fizer essa solicitação sem o valor local incluído no arquivo JSON, o valor das configurações locais será desativado, e o recurso herdará a configuração do valor pai ou usará o padrão gerenciado pelo Google.
Depois de fazer uma solicitação bem-sucedida, você receberá uma resposta que inclui o valor local criado para essa configuração e um campo etag
que precisará ser incluído nas solicitações de atualização subsequentes.
{ "name": "folders/4567890123/settings/net-preferredDnsServers", "localValue": { "stringSetValue": { "values": [ "8.8.8.8", "8.8.4.4" ] } } "etag": "O2VWGxZU01VnAfRU4Mu97w==", }
Ver a configuração de valor local ou efetivo
Você pode ver o valor local ou efetivo de uma configuração de recursos em um determinado recurso.
gcloud
Para conferir o valor local de uma configuração de um determinado recurso, use o comando
gcloud resource-settings describe
, da seguinte maneira:
gcloud resource-settings describe SETTING_NAME \ --RESOURCE_ID
Substitua:
SETTING_NAME
: o nome curto da configuração do recurso em que você quer encontrar o valor local ou efetivo.RESOURCE_ID
: o ID da pasta, projeto ou organização para o qual você quer encontrar as configurações de recursos disponíveis. Exemplo:--project=7890123456
Se você adicionar a sinalização --effective
, receberá o valor efetivo à medida que for avaliado para esse recurso.
API
Para ver o valor local ou efetivo de uma configuração de um determinado
recurso, use o método settings.get
. Use o método que corresponda ao tipo de recurso para o qual você quer listar as configurações:
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
Substitua:
ACCESS_TOKEN
: seu token de acesso OAuth 2.0.RESOURCE_ID
: o ID da pasta, projeto ou organização para a qual você quer encontrar as configurações de recursos disponíveis. Exemplo:projects/7890123456
SETTING_NAME
: o nome curto da configuração de recursos para o qual você quer retornar valores.VIEW_PARAMETER
:SETTING_VIEW_LOCAL_VALUE
para retornar o valor da configuração local ouSETTING_VIEW_EFFECTIVE_VALUE
para retornar o valor efetivo nesse recurso.
Exemplo de resposta
A resposta a uma solicitação get em folders/4567890123
é semelhante a esta:
{ "name": "folders/4567890123/settings/net-preferredDnsServers", "value": { "stringSetValue": { "values": [ "8.8.8.8", "8.8.4.4" ] } } "etag": "O2VWGxZU01VnAfRU4Mu97w==" }
Herança
A configuração que entra em vigor em um determinado recurso é avaliada com base na herança. É possível modificar o valor herdado em um recurso definindo um valor local, o que também afeta os valores de configuração herdados pelos filhos desse recurso. Para mais informações sobre a herança de configuração de recursos, consulte Valores de configuração efetivas.
Recuperar valores efetivos
Você pode recuperar o valor efetivo de uma configuração em um determinado recurso usando a propriedade ou a CLI gcloud. Para instruções detalhadas, consulte Visualizar a configuração de valor local ou efetivo. Veja o exemplo a seguir com os valores definidos para a configuração de recursos dos servidores DNS preferidos em uma organização, uma pasta dentro dessa organização e uma subpasta nessa pasta:
Os valores efetivos para cada um desses recursos são avaliados da seguinte maneira:
organizations/111
não tem valor local e não tem um recurso pai para herdar e, portanto, usaria o padrão8.8.8.8
gerenciado pelo Google.- Se você usar o método
describe
para receber o valor efetivo em um recurso e usar o padrão gerenciado pelo Google, essa informação será incluída na resposta. Exemplo:
{ "name": "organizations/111/settings/net-preferredDnsServers", "effectiveValue": { "stringSetValue": { "values": [ "8.8.8.8" ] # Google-managed default } } }
- Se você usar o método
folders/222
tem uma configuração de valor local de8.8.4.4
e, portanto, não herda do recurso pai.- Se você usar o método
describe
para receber o valor efetivo de um recurso e esse for um valor definido localmente, essas informações serão incluídas na resposta. Exemplo:
{ "name": "folders/222/settings/net-preferredDnsServers", "effectiveValue": { "stringSetValue": { "values": [ "8.8.4.4" ] # set on folders/222 } } }
- Se você usar o método
folders/333
não tem um valor local, mas o recurso pai sim. Ele herda o valor da configuração local defolders/222
e, portanto, é avaliado como8.8.4.4
.- Se você usar o método
describe
para receber o valor efetivo em um recurso e ele herdar esse valor de um recurso pai, essa informação será incluída na resposta. Exemplo:
{ "name": "folders/333/settings/net-preferredDnsServers", "effectiveValue": { "stringSetValue": { "values": [ "8.8.4.4" ] # inherited from folders/222 } } }
- Se você usar o método
Substituir valor herdado
Se você alterar o valor da configuração local de folders/333
para a configuração dos Servidores DNS preferidos, isso mudará o valor efetivo. Por exemplo, use o método patch
para atualizar o valor da configuração local de folders/333
para 192.168.1.1
. Para instruções detalhadas, consulte Alterar um valor de configuração local.
Se você usar o método describe
no recurso folders/333
atualizado, verá que o valor efetivo agora é 192.168.1.1
:
{ "name": "folders/333/settings/net-preferredDnsServers", "effectiveValue": { "stringSetValue": { "values": [ "192.168.1.1" ] # set on folders/333 } } }
Reverter para a herança de valor
Para reverter esse comportamento de modo que um recurso herde o valor local de um
pai, use o método patch
da API sem valor local definido na consulta ou
usando o comando unset-value
da CLI gcloud. Para instruções
detalhadas, consulte
Alterar um valor de configuração local.
Por exemplo, se você desativar o valor local em folders/333
, ele herdará novamente o valor efetivo do recurso pai mais próximo, folders/222
. Se
você usar o método describe
no recurso folders/333
atualizado, verá
que o valor efetivo agora é 8.8.4.4
:
{ "name": "folders/333/settings/net-preferredDnsServers", "effectiveValue": { "stringSetValue": { "values": [ "8.8.4.4" ] # inherited from folders/222 } } }