Organizzare le risorse utilizzando le etichette

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

Le etichette sono coppie chiave-valore che vengono applicate alle risorse da raggruppare e descrivere. Batch ha etichette predefinite, che vengono applicate automaticamente alle risorse ed etichette personalizzate, che puoi definire e applicare quando crei 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:

Chiarire e organizzare l'elenco dei job del progetto.
Distinguere i eseguibili di un job utilizzando le etichette per descrivere il tipo di container o script specificati.
Analizza i costi filtrando i report di fatturazione Cloud per le 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 ancora utilizzato Batch, consulta la Guida introduttiva all'utilizzo di Batch e abilitalo compilando i prerequisiti per progetti e utenti.
Per ottenere le autorizzazioni necessarie per creare un job, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Editor job batch (roles/batch.jobsEditor) sul progetto
- Utente account di servizio (roles/iam.serviceAccountUser) sull'account di servizio del job, che per impostazione predefinita è l'account di servizio Compute Engine predefinito
Per saperne di più sulla concessione dei ruoli, vedi Gestire l'accesso.

Potresti anche ottenere le autorizzazioni richieste tramite 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 presenta le seguenti limitazioni:

Batch supporta solo le etichette per le risorse create utilizzando Batch e dei seguenti tipi:
- Job
- Eseguibili
- Unità di elaborazione grafica (GPU) per un job (se disponibile)
- Dischi permanenti (dischi di avvio ed eventuali volumi di archiviazione) per un job
- Istanze di macchine virtuali (VM) per un job
Dopo aver preso in considerazione le etichette predefinite che il batch applica automaticamente 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 relativi eseguibili.
- Puoi definire un massimo di 61 etichette personalizzate da applicare a ogni GPU, disco permanente e VM creati per il job.
Il batch supporta solo la definizione di etichette personalizzate con nomi univoci. Questo comporta le seguenti conseguenze:
- Il tentativo di ignorare un'etichetta predefinita causa errori.
- La definizione di un'etichetta personalizzata duplicata sostituisce l'etichetta personalizzata esistente.
Il batch supporta solo la definizione delle etichette durante la creazione di un job.
- Le etichette per job ed eseguibili non possono essere aggiunte, aggiornate o rimosse.
- Sebbene sia possibile utilizzare Compute Engine per aggiungere, aggiornare o rimuovere le etichette per i dischi permanenti e le VM create per i job, non è consigliato. Il periodo di tempo in cui esistono le risorse per un job non può essere stimato in modo affidabile ed eventuali modifiche potrebbero non funzionare correttamente con il batch.
Per utilizzare le etichette per filtrare l'elenco dei job, devi visualizzare l'elenco dei job utilizzando l'interfaccia a riga di comando gcloud 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 creato:
- batch-job-id: il valore di questa etichetta è impostato sul nome del job.
A ciascuna GPU, disco permanente e VM creati 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 è null; raggruppa solo tutte le GPU, i dischi permanenti e le VM creati per i job. Ad esempio, utilizza questa etichetta quando visualizza un report di fatturazione Cloud per identificare i costi di tutte le GPU, i dischi permanenti e le VM create da batch.

Definisci 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 etichette personalizzate, seleziona uno o più dei seguenti metodi in questo documento in base allo scopo dell'etichetta:

Definisci le 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 creata 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 create per un job vengono visualizzati solo negli elenchi del progetto 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 i runnable.

Questa sezione spiega come applicare una o più etichette personalizzate a uno o più eseguibili per il job. Dopo aver creato il job, puoi utilizzare queste etichette per filtrare gli elenchi di 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, a ogni GPU (se presente), al disco permanente (tutti i dischi di avvio e ai nuovi volumi di archiviazione) e alla VM creata per il job.

Puoi definire le etichette per un job e le relative risorse durante la creazione di un job utilizzando l'interfaccia a riga di comando gcloud o l'API batch.

gcloud

Ad esempio, per creare un job container di base in us-central1 che definisce due etichette personalizzate applicabili 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 quelle predefinite applicate da batch o da altri servizi Google Cloud, è consigliabile non specificare nomi di etichette che inizino 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 creati nel passaggio precedente.

API

Ad esempio, per creare un job container di base in us-central1 che definisce due etichette personalizzate applicabili al job e le risorse create per il job, invia 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 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 creazione di un job utilizzando l'interfaccia a riga di comando gcloud o l'API batch.

gcloud

Ad esempio, per creare un job container di base in us-central1 che definisca due etichette personalizzate applicabili 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 secondo 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 creati nel passaggio precedente.

API

Ad esempio, per creare un job container in us-central1 che definisce due etichette personalizzate da applicare ai job, 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 secondo della seconda etichetta da applicare al job.
JOB_LABEL_VALUE2: il valore della seconda etichetta da applicare al job.

Definisci etichette personalizzate per i runnable

Le etichette definite nel campo labels per un eseguibile vengono applicate solo a quel dato.

Puoi definire le etichette per uno o più eseguibili quando crei un job utilizzando l'interfaccia a riga di comando gcloud o l'API Batch.

gcloud

Ad esempio, per creare un job in us-central1 che definisce due etichette personalizzate, una per ogni eseguibile dei 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 alla prima eseguibile del job.
RUNNABLE1_LABEL_VALUE1: il valore dell'etichetta da applicare alla prima eseguibile del job.
RUNNABLE2_LABEL_NAME1: il nome dell'etichetta da applicare alla seconda esecuzione del job.
RUNNABLE2_LABEL_VALUE1: il valore dell'etichetta da applicare alla seconda esecuzione 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 creati nel passaggio precedente.

API

Ad esempio, per creare un job in us-central1 che definisca due etichette personalizzate, una per ciascuno dei due eseguibili, esegui una richiesta POST nel metodo jobs.create e specifica i campi runnables.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 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'esecuzione del primo job.
RUNNABLE1_LABEL_VALUE1: il valore dell'etichetta da applicare al eseguibile del primo job.
RUNNABLE2_LABEL_NAME1: il nome dell'etichetta da applicare al secondo job eseguibile.
RUNNABLE2_LABEL_VALUE1: il valore dell'etichetta da applicare al secondo eseguibile del job.

Passaggi successivi

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