Configura i limiti di gestione

Questo documento descrive come configurare e gestire i confini di gestione e le configurazioni delle funzionalità utilizzando Resource Manager. I confini di gestione consentono il rilevamento e la governance delle risorse tra progetti per Agent Registry.

Prima di iniziare

Prima di configurare i limiti e le configurazioni delle funzionalità, ottieni i ruoli richiesti e abilita l'API richiesta.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare confini e funzionalità, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Crea, aggiorna ed elimina i confini e le configurazioni delle funzionalità: Resource Manager Editor (roles/resourcemanager.editor) nella cartella o nell'organizzazione di destinazione (e nel progetto di gestione, se fornisci un progetto di gestione gestito dall'utente)
  • Visualizza i confini e le configurazioni delle funzionalità: Visualizzatore Resource Manager (roles/resourcemanager.viewer) sulla cartella o sull'organizzazione di destinazione
  • Associa i tag ai progetti membri:
    • Tag User (roles/resourcemanager.tagUser) sulla cartella, sull'organizzazione o sui progetti membri di destinazione
    • Tag Administrator (roles/resourcemanager.tagAdmin) sulla cartella o sull'organizzazione di destinazione

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita API

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

    gcloud services enable cloudresourcemanager.googleapis.com \
  --project=PROJECT_ID

    Sostituisci PROJECT_ID con l'ID del tuo progetto.

Configura un confine di gestione

Puoi configurare un confine di gestione su una cartella o un'organizzazione in uno dei seguenti modi:

  • Confine a livello di cartella o di organizzazione (nessun filtro dei tag): include tutti i progetti discendenti nella cartella o nell'organizzazione. Salta i passaggi 1 e 4 e completa solo il Passaggio 2: crea un confine (senza --tag-key e --tag-value) e il Passaggio 3: crea una configurazione delle funzionalità.
  • Confine basato su tag: suddivide i progetti nella cartella o nell'organizzazione in base ai valori dei tag. Completa tutti e quattro i passaggi riportati di seguito.

Passaggio 1: configura la chiave tag di partizionamento

Ignora questo passaggio se stai creando un perimetro a livello di cartella o di organizzazione senza un filtro dei tag. Per impostazione predefinita, per una risorsa BoundaryConfig non è configurata alcuna chiave tag.

Per i confini basati su tag, una risorsa BoundaryConfig stabilisce la chiave tag utilizzata per partizionare i progetti all'interno di una cartella o di un'organizzazione. Configura questa risorsa prima di creare confini basati su tag.

Per impostare la chiave del tag di partizionamento, utilizza il comando gcloud resource-manager boundary-configs update:

gcloud resource-manager boundary-configs update \
  --folder=FOLDER_ID \
  --tag-key=TAG_KEY_NAME

Per configurare la chiave tag su un'organizzazione, specifica --organization=ORGANIZATION_ID anziché --folder. Se in precedenza hai configurato una chiave tag e vuoi passare a un confine non codificato (quando non esistono confini nell'elemento principale), esegui questo comando con --clear-tag-key anziché --tag-key.

Sostituisci quanto segue:

  • FOLDER_ID: l'ID della cartella principale
  • TAG_KEY_NAME: il nome della chiave del tag, formattato come ORGANIZATION_ID/TAG_KEY_SHORT_NAME, ad esempio 123456789012/env

Passaggio 2: crea un confine

Crea una risorsa Boundary nella cartella o nell'organizzazione.

Per creare un confine a livello di cartella senza un filtro dei tag (che include automaticamente tutti i progetti discendenti nella cartella), utilizza il comando gcloud resource-manager boundaries create senza --tag-key e --tag-value:

gcloud resource-manager boundaries create BOUNDARY_ID \
  --folder=FOLDER_ID \
  --display-name="Production Boundary"

Per creare un confine basato su tag dopo aver configurato la chiave tag di partizionamento nel passaggio 1, includi i flag --tag-key e --tag-value:

gcloud resource-manager boundaries create BOUNDARY_ID \
  --folder=FOLDER_ID \
  --display-name="Production Boundary" \
  --tag-key=TAG_KEY_NAME \
  --tag-value=TAG_VALUE_SHORT_NAME

Per creare un perimetro in un'organizzazione, specifica --organization=ORGANIZATION_ID anziché --folder.

Sostituisci quanto segue:

  • BOUNDARY_ID: un ID univoco per il confine, ad esempio prod-boundary
  • FOLDER_ID: l'ID della cartella principale
  • TAG_KEY_NAME: la chiave tag che hai configurato, ad esempio 123456789012/env
  • TAG_VALUE_SHORT_NAME: il valore del tag che i progetti devono avere per unirsi al confine, ad esempio prod

Passaggio 3: crea una configurazione delle funzionalità

Crea una risorsa CapabilityConfig per collegare il confine a un progetto di gestione e dichiara quali servizi vengono gestiti all'interno del confine.

Per creare una configurazione delle funzionalità, utilizza il comando gcloud resource-manager capability-configs create e specifica --types=agent-management per Agent Registry:

gcloud resource-manager capability-configs create \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --types=agent-management \
  --boundaries=folders/FOLDER_ID/boundaries/BOUNDARY_ID \
  --display-name="DISPLAY_NAME"

Per creare la configurazione delle funzionalità in un'organizzazione, specifica --organization=ORGANIZATION_ID anziché --folder.

Sostituisci quanto segue:

  • CAPABILITY_CONFIG_ID: un ID univoco per la configurazione della funzionalità, ad esempio prod-capabilities
  • FOLDER_ID: l'ID della cartella principale
  • BOUNDARY_ID: l'ID del confine che hai creato
  • DISPLAY_NAME: un nome visualizzato leggibile da una persona

Per attivare le funzionalità su un singolo progetto autonomo senza confini, salta i passaggi 1, 2 e 4 ed esegui questo comando con --project=PROJECT_NUMBER e --management-project=projects/PROJECT_NUMBER anziché --folder e --boundaries.

Per utilizzare un progetto esistente come progetto di gestione, passa il flag --management-project=projects/PROJECT_NUMBER. Il progetto specificato deve soddisfare i seguenti requisiti, altrimenti il comando non va a buon fine e viene visualizzato un errore:

  • Risiedere direttamente nello stesso elemento padre (folders/FOLDER_ID o organizations/ORGANIZATION_ID) della risorsa CapabilityConfig.
  • Essere nello stato del ciclo di vita ACTIVE.
  • Non essere già designato come progetto di gestione.

Se ometti --management-project, Resource Manager esegue automaticamente il provisioning di un progetto di gestione dedicato direttamente nella cartella o nell'organizzazione principale.

La creazione di una risorsa CapabilityConfig abilita automaticamente le API di servizio corrispondenti nel progetto di gestione (ad esempio agentregistry.googleapis.com quando specifichi agent-management). Non è necessario abilitare manualmente queste API nel progetto di gestione.

Passaggio 4: associa i tag ai progetti membri

Ignora questo passaggio se hai creato un perimetro a livello di cartella o di organizzazione senza un filtro dei tag, perché tutti i progetti discendenti vengono inclusi automaticamente.

Per i confini basati su tag, i progetti si uniscono dinamicamente al confine di gestione quando associ il valore del tag corrispondente.

Per collegare il tag a ogni progetto che appartiene al confine, utilizza il comando gcloud resource-manager tags bindings create:

gcloud resource-manager tags bindings create \
  --tag-value=TAG_VALUE_NAME \
  --parent=//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER

Sostituisci quanto segue:

  • TAG_VALUE_NAME: il nome del valore del tag, ad esempio 123456789012/env/prod
  • PROJECT_NUMBER: il numero (o l'ID progetto) del progetto che vuoi includere nel perimetro

Gestisci le configurazioni delle funzionalità

Puoi elencare, descrivere, aggiornare ed eliminare le configurazioni delle funzionalità. Gli esempi in questa sezione utilizzano --folder=FOLDER_ID. Per gestire le configurazioni delle funzionalità su un'organizzazione o un progetto, specifica --organization=ORGANIZATION_ID o --project=PROJECT_NUMBER anziché --folder (i confini possono essere collegati solo alle configurazioni delle funzionalità a livello di cartella o di organizzazione).

Elenca le configurazioni delle funzionalità

Per elencare tutte le configurazioni delle funzionalità in una cartella, utilizza il comando gcloud resource-manager capability-configs list:

gcloud resource-manager capability-configs list \
  --folder=FOLDER_ID

Descrivi una configurazione delle funzionalità

Per visualizzare i dettagli della configurazione e il progetto di gestione assegnato, utilizza il comando gcloud resource-manager capability-configs describe:

gcloud resource-manager capability-configs describe \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID

Aggiorna i confini associati

Per aggiornare i limiti collegati a una configurazione delle funzionalità, utilizza il comando gcloud resource-manager capability-configs update:

gcloud resource-manager capability-configs update \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --boundaries=folders/FOLDER_ID/boundaries/BOUNDARY_ID_1,folders/FOLDER_ID/boundaries/BOUNDARY_ID_2

Il comando update accetta anche i flag --types e --display-name per aggiornare i tipi di funzionalità abilitati o il nome visualizzato.

Elimina una configurazione delle funzionalità

Una risorsa CapabilityConfig non può essere eliminata se sono collegati dei confini e una risorsa Boundary non può essere eliminata se è collegata a una risorsa CapabilityConfig.

Per eliminare una configurazione delle funzionalità quando la gestione tra progetti non è più necessaria:

  1. Per scollegare i confini associati, utilizza il comando gcloud resource-manager capability-configs update con il flag --clear-boundaries:

    gcloud resource-manager capability-configs update \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --clear-boundaries

  2. Per eliminare la configurazione della funzionalità, utilizza il comando gcloud resource-manager capability-configs delete:

    gcloud resource-manager capability-configs delete \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID

Passaggi successivi