Uso delle etichette per l'organizzazione delle risorse

Questo documento spiega come utilizzare le etichette per organizzare le risorse batch.

Le etichette sono coppie chiave-valore applicate alle risorse per raggrupparle e descriverle. Batch ha etichette predefinite, che vengono applicate automaticamente alle risorse, e etichette personalizzate, che puoi definire e applicare durante la creazione di un job.

Le etichette consentono di filtrare i risultati degli elenchi di risorse e dei report di fatturazione Cloud. Ad esempio, puoi utilizzare le etichette per:

Chiarisci e organizza l'elenco dei job del progetto.
Distinguere gli elementi eseguibili di un job utilizzando le etichette per descrivere il tipo di container o script specificato.
Analizza i costi filtrando i report di fatturazione Cloud in base alle risorse create da job batch o specifici.

Per ulteriori informazioni sulle etichette, consulta anche la documentazione di Compute Engine per le etichette

Prima di iniziare

Se non hai mai utilizzato Batch, consulta la Guida introduttiva all'utilizzo di Batch e abilita Batch completando i prerequisiti per progetti e utenti.
Per ottenere le autorizzazioni necessarie per creare un job, chiedi all'amministratore di concederti i ruoli IAM seguenti:
- Editor job batch (roles/batch.jobsEditor) nel progetto
- Utente account di servizio (roles/iam.serviceAccountUser) nell'account di servizio del job, che per impostazione predefinita è l'account di servizio Compute Engine predefinito
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Limitazioni

Oltre ai requisiti per le etichette specificati nella documentazione di Compute Engine, l'applicazione di etichette a un job batch e alle relative risorse prevede le seguenti restrizioni:

Batch supporta solo le etichette per le risorse create mediante Batch e dei seguenti tipi:
- Job
- Elementi eseguibili
- GPU (Graphics Processing Unit) per un job (se presenti)
- Dischi permanenti (dischi di avvio ed volumi di archiviazione) per un job
- Istanze di macchine virtuali (VM) per un job
Dopo aver preso in considerazione le etichette predefinite che vengono applicate automaticamente da batch a un job, puoi definire le seguenti quantità di etichette personalizzate:
- Puoi definire un massimo di 63 etichette personalizzate da applicare al job e ai suoi eseguibili.
- Puoi definire un massimo di 61 etichette personalizzate da applicare a ogni GPU, disco permanente e VM creata per il job.
Batch supporta solo la definizione di etichette personalizzate con nomi univoci. Ciò comporta le seguenti conseguenze:
- Il tentativo di eseguire l'override di un'etichetta predefinita causa errori.
- La definizione di un'etichetta personalizzata duplicata sostituisce l'etichetta personalizzata esistente.
Batch supporta la definizione delle etichette solo durante la creazione di un job.
- Le etichette per job ed elementi eseguibili non possono essere aggiunte, aggiornate o rimosse.
- Sebbene sia possibile utilizzare Compute Engine per aggiungere, aggiornare o rimuovere le etichette dei dischi permanenti e delle VM create per i job, sconsigliamo di farlo. Il periodo di tempo in cui esistono le risorse per un job non può essere stimato in modo affidabile e eventuali modifiche potrebbero non funzionare correttamente con Batch.
Per utilizzare le etichette per filtrare l'elenco dei job, devi visualizzare l'elenco dei job utilizzando gcloud CLI o l'API Batch.

Etichette predefinite

Ogni etichetta predefinita ha una chiave che inizia con il prefisso batch-. Per impostazione predefinita, Batch applica automaticamente le seguenti etichette predefinite:

Per ogni job che crei:
- batch-job-id: il valore di questa etichetta è impostato sul nome del job.
Per ogni GPU, disco permanente e VM creata per un job:
- batch-job-id: il valore di questa etichetta è impostato sul nome del job.
- batch-job-uid: il valore di questa etichetta è impostato sull'identificatore univoco (UID) del job.
- batch-node: il valore di questa etichetta è nullo. Raggruppa tutte le GPU, i dischi permanenti e le VM create per i job. Ad esempio, utilizza questa etichetta quando visualizzi un report di fatturazione Cloud per identificare i costi di tutte le GPU, di tutti i dischi permanenti e le VM create da Batch.

Definisci le etichette personalizzate

Facoltativamente, puoi definire una o più etichette personalizzate durante la creazione di un job. Puoi definire etichette personalizzate con nuove chiavi o chiavi già utilizzate dal progetto. Per definire le etichette personalizzate, seleziona uno o più dei seguenti metodi in questo documento in base allo scopo dell'etichetta:

Definisci etichette personalizzate per il job e le relative risorse.

Questa sezione spiega come applicare una o più etichette personalizzate al job e a ogni GPU, disco permanente e VM creato per il job. Dopo aver creato il job, puoi utilizzare queste etichette per filtrare i report di fatturazione Cloud e gli elenchi di job, dischi permanenti e VM del tuo progetto.

Nota: i dischi permanenti e le VM creati per un job vengono visualizzati negli elenchi del progetto solo durante il tempo di esecuzione del job (dopo la creazione e prima dell'eliminazione).
Definisci etichette personalizzate per il job.

Questa sezione spiega come applicare una o più etichette personalizzate al job. Dopo aver creato il job, puoi utilizzare queste etichette per filtrare gli elenchi di job del progetto.
Definisci etichette personalizzate per gli elementi eseguibili.

Questa sezione spiega come applicare una o più etichette personalizzate a uno o più elementi eseguibili per il job. Dopo aver creato il job, puoi utilizzare queste etichette per filtrare gli elenchi dei job del progetto.

Definisci etichette personalizzate per il job e le relative risorse

Le etichette definite nel campo labels per il criterio di allocazione di un job vengono applicate al job, nonché a ogni GPU (se presente), disco permanente (tutti i dischi di avvio ed eventuali nuovi volumi di archiviazione) e VM creata per il job.

Puoi definire le etichette per un job e le relative risorse durante la creazione di un job mediante gcloud CLI o l'API Batch.

gcloud

Ad esempio, per creare un job di container di base in us-central1 che definisca due etichette personalizzate che si applicano al job e le risorse create per il job, segui questi passaggi:

Crea un file JSON che specifichi i dettagli di configurazione del job e il campo allocationPolicy.labels.
```
{
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4"
        }
      }
    ],
    "labels": {
      "VM_LABEL_NAME1": "VM_LABEL_VALUE1",
      "VM_LABEL_NAME2": "VM_LABEL_VALUE2"
    }
  },
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello world!"
              ]
            }
          }
        ]
      }
    }
  ]
}
```
Sostituisci quanto segue:
- VM_LABEL_NAME1: il nome della prima etichetta da applicare alle VM create per il job.
- VM_LABEL_VALUE1: il valore della prima etichetta da applicare alle VM create per il job.
- VM_LABEL_NAME2: il nome della seconda etichetta da applicare alle VM create per il job.
- VM_LABEL_VALUE2: il valore della seconda etichetta da applicare alle VM create per il job.
Nota: per evitare di confondere le etichette personalizzate con le etichette predefinite applicate da batch o da altri servizi Google Cloud, ti consigliamo di non specificare nomi di etichette che iniziano con batch-, goog- o google-.
Crea il job in us-central1 utilizzando il comando gcloud batch jobs submit.
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
Sostituisci JSON_CONFIGURATION_FILE con il percorso del file JSON con i dettagli di configurazione del job che hai creato nel passaggio precedente.

API

Ad esempio, per creare un job di container di base in us-central1 che definisca due etichette personalizzate che si applicano al job e alle risorse create per il job, effettua una richiesta POST al metodo jobs.create e specifica il campo allocationPolicy.labels.

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4"
        }
      }
    ],
    "labels": {
      "VM_LABEL_NAME1": "VM_LABEL_VALUE1",
      "VM_LABEL_NAME2": "VM_LABEL_VALUE2"
    }
  },
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello world!"
              ]
            }
          }
        ]
      }
    }
  ]
}

Sostituisci quanto segue:

VM_LABEL_NAME1: il nome della prima etichetta da applicare alle VM create per il job.
VM_LABEL_VALUE1: il valore della prima etichetta da applicare alle VM create per il job.
VM_LABEL_NAME2: il nome della seconda etichetta da applicare alle VM create per il job.
VM_LABEL_VALUE2: il valore della seconda etichetta da applicare alle VM create per il job.

Definisci le etichette personalizzate per il job

Le etichette definite nel campo labels per il job vengono applicate solo al job.

Puoi definire le etichette per un job durante la sua creazione utilizzando gcloud CLI o l'API Batch.

gcloud

Ad esempio, per creare un job di container di base in us-central1 che definisca due etichette personalizzate che si applicano al job stesso, segui questi passaggi:

Crea un file JSON che specifichi i dettagli di configurazione del job e il campo labels.

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello World!"
              ]
            }
          }
        ]
      }
    }
  ],
  "labels": {
    "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
    "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
  }
}

Sostituisci quanto segue:

JOB_LABEL_NAME1: il nome della prima etichetta da applicare al job.
JOB_LABEL_VALUE1: il valore della prima etichetta da applicare al job.
JOB_LABEL_NAME2: il nome della seconda etichetta da applicare al job.
JOB_LABEL_VALUE2: il valore della seconda etichetta da applicare al job.

Crea il job in us-central1 utilizzando il comando gcloud batch jobs submit con i seguenti flag:
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
Sostituisci JSON_CONFIGURATION_FILE con il percorso del file JSON con i dettagli di configurazione del job che hai creato nel passaggio precedente.

API

Ad esempio, per creare un job container in us-central1 che definisca due etichette personalizzate da applicare ai job stessi, effettua una richiesta POST al metodo jobs.create e specifica il campo labels.

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello World!"
              ]
            }
          }
        ]
      }
    }
  ],
  "labels": {
    "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
    "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
  }
}

Sostituisci quanto segue:

JOB_LABEL_NAME1: il nome della prima etichetta da applicare al job.
JOB_LABEL_VALUE1: il valore della prima etichetta da applicare al job.
JOB_LABEL_NAME2: il nome della seconda etichetta da applicare al job.
JOB_LABEL_VALUE2: il valore della seconda etichetta da applicare al job.

Definisci etichette personalizzate per gli elementi eseguibili

Le etichette definite nel campo labels per un elemento eseguibile vengono applicate solo a questo elemento eseguibile.

Puoi definire le etichette per uno o più elementi eseguibili durante la creazione di un job mediante gcloud CLI o l'API Batch.

gcloud

Ad esempio, per creare un job in us-central1 che definisce due etichette personalizzate, un'etichetta personalizzata per ciascuno dei due elementi eseguibili del job, segui questi passaggi:

Crea un file JSON che specifichi i dettagli di configurazione del job e i campi runnables.labels.

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello from task ${BATCH_TASK_INDEX}!"
              ]
            },
            "labels": {
              "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
            }
          },
          {
            "script": {
              "text": "echo Hello from task ${BATCH_TASK_INDEX}!"
            },
            "labels": {
              "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
            }
          }
        ]
      }
    }
  ]
}

Sostituisci quanto segue:

RUNNABLE1_LABEL_NAME1: il nome dell'etichetta da applicare al primo eseguibile del job.
RUNNABLE1_LABEL_VALUE1: il valore dell'etichetta da applicare al primo elemento eseguibile del job.
RUNNABLE2_LABEL_NAME1: il nome dell'etichetta da applicare al secondo eseguibile del job.
RUNNABLE2_LABEL_VALUE1: il valore dell'etichetta da applicare al secondo elemento eseguibile del job.

Crea il job in us-central1 utilizzando il comando gcloud batch jobs submit.
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
Sostituisci JSON_CONFIGURATION_FILE con il percorso del file JSON con i dettagli di configurazione del job che hai creato nel passaggio precedente.

API

Ad esempio, per creare un job in us-central1 che definisce due etichette personalizzate, una per ciascuno dei due elementi eseguibili del job, effettua una richiesta POST al metodo jobs.create e specifica i runnables.labels campi.

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello from ${BATCH_TASK_INDEX}!"
              ]
            },
            "labels": {
              "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
            }
          },
          {
            "script": {
              "text": "echo Hello from ${BATCH_TASK_INDEX}!"
            },
            "labels": {
              "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
            }
          }
        ]
      }
    }
  ]
}

Sostituisci quanto segue:

RUNNABLE1_LABEL_NAME1: il nome dell'etichetta da applicare all'elemento eseguibile del primo job.
RUNNABLE1_LABEL_VALUE1: il valore dell'etichetta da applicare all'elemento eseguibile del primo job.
RUNNABLE2_LABEL_NAME1: il nome dell'etichetta da applicare all'elemento eseguibile del secondo job.
RUNNABLE2_LABEL_VALUE1: il valore dell'etichetta da applicare all'elemento eseguibile del secondo job.

Passaggi successivi

Utilizza le etichette come filtri quando esegui le seguenti operazioni:
Scopri come eliminare ed esportare i job.