Gerenciar configurações de recursos

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:

Acessar APIs e serviços

  1. Selecione o projeto que você usará para acessar a API.
  2. Clique no botão Ativar APIs e serviço.
  3. Pesquise "Configurações de recursos".
  4. Nos resultados da pesquisa, clique em "Resource Settings API".
  5. 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 ver uma lista de todas as configurações disponíveis para uso em um recurso, use o seguinte comando gcloud resource-settings list:

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 curto da configuração do recurso, que precisa ser usado nas solicitações da 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 uma configuração em um recurso, use o seguinte 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 desativar a definição de um valor de configuração local em um recurso, use o comando gcloud resource-settings unset-value:

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 visualizar 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 ou SETTING_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

É possível recuperar o valor efetivo de uma configuração em um determinado recurso usando a API ou a CLI gcloud. Para instruções detalhadas, consulte Visualizar a configuração do 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ão 8.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
    }
  }
}

  • folders/222 tem uma configuração de valor local de 8.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
    }
  }
}

  • folders/333 não tem um valor local, mas o recurso pai sim. Ele herda o valor da configuração local de folders/222 e, portanto, é avaliado como 8.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
    }
  }
}

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 Mudar 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
    }
  }
}