Gestione di Resource Settings

Questa guida descrive come gestire le impostazioni delle risorse. Puoi utilizzare le impostazioni delle risorse per configurare in modo centralizzato le impostazioni per i progetti, le cartelle e l'organizzazione Google Cloud. Ogni impostazione della risorsa consente di controllare un aspetto di un servizio supportato.

Prima di iniziare

Per saperne di più sulle impostazioni delle risorse e sul loro funzionamento, consulta la panoramica di Resource Settings.

Abilita l'API

L'API Resource Settings può essere abilitata per i singoli progetti.

Console Google Cloud

Per abilitare l'API Resource Settings, segui questi passaggi:

Vai ad API e servizi

  1. Seleziona il progetto che utilizzerai per accedere all'API.
  2. Fai clic sul pulsante Abilita API e servizi.
  3. Cerca "Impostazioni risorse".
  4. Nei risultati di ricerca, fai clic su "API Resource Settings".
  5. Se viene visualizzato il messaggio "API abilitata", significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

gcloud

Per abilitare l'API Resource Settings, utilizza il comando gcloud services enable:

gcloud services enable resourcesettings.googleapis.com

Autorizzazioni obbligatorie

Le autorizzazioni necessarie dipendono dall'azione da eseguire.

Per ottenere queste autorizzazioni, chiedi all'amministratore di concedere il ruolo suggerito al livello appropriato della gerarchia delle risorse.

Visualizza le impostazioni delle risorse

Per visualizzare le impostazioni delle risorse disponibili per l'utilizzo in una risorsa, nonché i valori delle impostazioni locali ed efficaci in una risorsa, devi disporre del ruolo Visualizzatore impostazioni risorse (roles/resourcesettings.viewer) o di un altro ruolo che includa le seguenti autorizzazioni:

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

Amministrare le impostazioni delle risorse

Per creare, aggiornare ed eliminare i valori delle impostazioni delle risorse in una risorsa, devi disporre del ruolo Amministratore impostazioni risorse (roles/resourcesettings.admin) o di un altro ruolo che includa le seguenti autorizzazioni:

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

Elenco delle impostazioni disponibili

Puoi ottenere un elenco di tutte le impostazioni delle risorse disponibili per una determinata risorsa. Questo elenco mostra tutte le impostazioni della risorsa che possono essere applicate alla risorsa. Le impostazioni delle risorse in stato di anteprima sono disponibili solo per gli utenti a cui è stata concessa l'autorizzazione esplicita per utilizzarle.

gcloud

Per ottenere un elenco di tutte le impostazioni disponibili per l'utilizzo in una risorsa, utilizza il seguente comando gcloud resource-settings list:

gcloud resource-settings list --RESOURCE_ID

dove RESOURCE_ID è l'ID della cartella, del progetto o dell'organizzazione per cui vuoi trovare le impostazioni delle risorse disponibili. Ad esempio: --project=7890123456

API

Per visualizzare un elenco di tutte le impostazioni disponibili per l'utilizzo in una risorsa, utilizza uno dei seguenti metodi settings.list. Utilizza il metodo corrispondente al tipo di risorsa per cui vuoi elencare le impostazioni:

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

Sostituisci quanto segue:

  • ACCESS_TOKEN: il tuo token di accesso OAuth 2.0.

  • RESOURCE_ID: l'ID della cartella, del progetto o dell'organizzazione per cui vuoi trovare le impostazioni delle risorse disponibili. Ad esempio: projects/7890123456

Risposta di esempio

Una risposta a una richiesta di elenco su folders/4567890123 è simile alla seguente:

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

Il campo name è il nome breve dell'impostazione della risorsa, che deve essere utilizzato nelle richieste dell'API e gcloud CLI relative a quell'impostazione.

Modificare il valore di un'impostazione locale

Puoi modificare il valore dell'impostazione locale di una determinata impostazione della risorsa. Se imposti un valore di impostazione locale, questo sostituisce qualsiasi impostazione del valore effettivo ereditato. Se non imposti il valore dell'impostazione locale, qualsiasi valore dell'impostazione locale applicato a una risorsa di ascendenza viene ereditato e diventa il valore effettivo.

gcloud

Per modificare il valore dell'impostazione locale per un'impostazione della risorsa, utilizza il seguente gcloud resource-settings set-value comando:

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

Sostituisci FILE_PATH con il percorso di un file YAML o JSON contenente l'impostazione della risorsa.

Esempio di file JSON:

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

Sostituisci quanto segue:

  • RESOURCE_ID: l'ID della cartella, del progetto o dell'organizzazione per cui vuoi aggiornare l'impostazione della risorsa locale. Ad esempio: projects/7890123456

  • SETTING_NAME: il nome breve dell'impostazione della risorsa che vuoi aggiornare.

Per annullare l'impostazione di un valore locale in una risorsa, utilizza il comando gcloud resource-settings unset-value:

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

Sostituisci quanto segue:

  • SETTING_NAME: il nome breve dell'impostazione della risorsa per la quale vuoi annullare l'impostazione del valore locale.

  • RESOURCE_ID: l'ID della cartella, del progetto o dell'organizzazione per cui vuoi trovare le impostazioni delle risorse disponibili. Ad esempio: projects/7890123456

API

Per modificare il valore dell'impostazione locale per un'impostazione della risorsa, utilizza il metodo settings.patch. Utilizza il metodo corrispondente al tipo di risorsa per cui vuoi aggiornare le impostazioni:

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

Sostituisci quanto segue:

  • ACCESS_TOKEN: il tuo token di accesso OAuth 2.0.

  • RESOURCE_ID: l'ID della cartella, del progetto o dell'organizzazione per cui vuoi trovare le impostazioni delle risorse disponibili. Ad esempio: projects/7890123456

Se effettui questa richiesta senza includere un valore locale nel file JSON, il valore delle impostazioni locali viene reimpostato e la risorsa eredita l'impostazione del valore padre o utilizza il valore predefinito gestito da Google.

Dopo aver inviato una richiesta andata a buon fine, ricevi una risposta che include il valore locale creato per questa impostazione e un campo etag da includere nelle richieste di aggiornamento successive.

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

Visualizzare l'impostazione del valore locale o effettivo

Puoi visualizzare il valore locale o effettivo di un'impostazione della risorsa in una determinata risorsa.

gcloud

Per visualizzare il valore locale di un'impostazione della risorsa in una determinata risorsa, utilizza il comando gcloud resource-settings describe come segue:

gcloud resource-settings describe SETTING_NAME \
  --RESOURCE_ID

Sostituisci quanto segue:

  • SETTING_NAME: il nome breve dell'impostazione della risorsa per la quale vuoi trovare il valore locale o effettivo.

  • RESOURCE_ID: l'ID della cartella, del progetto o dell'organizzazione per cui vuoi trovare le impostazioni delle risorse disponibili. Ad esempio: --project=7890123456

Se aggiungi il flag --effective, ottieni il valore effettivo così come viene valutato per questa risorsa.

API

Per visualizzare il valore locale o effettivo di un'impostazione della risorsa in una determinata risorsa, utilizza il metodo settings.get. Utilizza il metodo corrispondente al tipo di risorsa per cui vuoi elencare le impostazioni:

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

Sostituisci quanto segue:

  • ACCESS_TOKEN: il tuo token di accesso OAuth 2.0.

  • RESOURCE_ID: l'ID della cartella, del progetto o dell'organizzazione per cui vuoi trovare le impostazioni delle risorse disponibili. Ad esempio: projects/7890123456

  • SETTING_NAME: il nome breve dell'impostazione della risorsa per la quale vuoi restituire i valori.

  • VIEW_PARAMETER: SETTING_VIEW_LOCAL_VALUE per restituire il valore dell'impostazione locale o SETTING_VIEW_EFFECTIVE_VALUE per restituire il valore effettivo in questa risorsa.

Risposta di esempio

Una risposta a una richiesta get su folders/4567890123 è simile alla seguente:

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

Ereditarietà

L'impostazione della risorsa che viene applicata a una determinata risorsa viene valutata in base all'eredità. Puoi sostituire il valore ereditato in una risorsa impostando un valore locale, che influisce anche sui valori delle impostazioni ereditati dai figli della risorsa. Per ulteriori informazioni sull'ereditarietà delle impostazioni delle risorse, consulta Valori delle impostazioni effettivi.

Recuperare i valori effettivi

Puoi recuperare il valore effettivo di un'impostazione in una determinata risorsa utilizzando l'API o gcloud CLI. Per istruzioni dettagliate, consulta Visualizzare l'impostazione del valore locale o effettivo. Considera il seguente esempio, con i valori impostati per l'impostazione della risorsa Server DNS preferiti in un'organizzazione, una cartella all'interno dell'organizzazione e una sottocartella all'interno di quella cartella:

I valori effettivi di ciascuna di queste risorse vengono valutati come segue:

  • organizations/111 non ha un valore locale e non ha una risorsa principale da ereditare, pertanto utilizzerà il valore predefinito gestito da Google di 8.8.8.8.

    • Se utilizzi il metodo describe per ottenere il valore effettivo di una risorsa e questa utilizza il valore predefinito gestito da Google, queste informazioni sono incluse nella risposta. Ad esempio:
    {
  "name": "organizations/111/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8" ] # Google-managed default
    }
  }
}

  • folders/222 ha un'impostazione del valore locale 8.8.4.4, pertanto non eredita dalla risorsa principale.

    • Se utilizzi il metodo describe per ottenere il valore effettivo di una risorsa e si tratta di un valore impostato localmente, queste informazioni sono incluse nella risposta. Ad esempio:
    {
  "name": "folders/222/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # set on folders/222
    }
  }
}

  • folders/333 non ha un valore locale, ma la relativa risorsa principale sì. Eredita il valore dell'impostazione locale da folders/222 e, pertanto, restituisce 8.8.4.4.

    • Se utilizzi il metodo describe per ottenere il valore effettivo di una risorsa e la risorsa eredita questo valore da una risorsa principale, queste informazioni vengono incluse nella risposta. Ad esempio:
    {
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}

Esegui l'override del valore ereditato

Se modifichi il valore dell'impostazione locale folders/333 per l'impostazione Server DNS preferiti, il valore effettivo cambia. Ad esempio, utilizzi il metodo patch per aggiornare il valore dell'impostazione locale da folders/333 a 192.168.1.1. Per istruzioni dettagliate, vedi Modificare il valore di un'impostazione locale.

Se utilizzi il metodo describe sulla risorsa folders/333 aggiornata, vedrai che il valore effettivo ora è 192.168.1.1:

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

Ripristinare il valore ereditato

Per ripristinare questo comportamento in modo che una risorsa erediti il valore locale da un elemento primario, utilizza il metodo patch dell'API senza impostare un valore locale nella query oppure utilizza il comando unset-value di gcloud CLI. Per istruzioni dettagliate, vedi Modificare il valore di un'impostazione locale.

Ad esempio, se reimposti il valore locale su folders/333, questo erediterà nuovamente il valore effettivo dalla risorsa principale più vicina, folders/222. Se utilizzi il metodo describe sulla risorsa folders/333 aggiornata, vedrai che il valore effettivo ora è 8.8.4.4:

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