Istanze di etichette

Questa pagina illustra le etichette. Descrive come creare un'istanza con etichette, aggiungere, aggiornare e rimuovere etichette e come usare le etichette nelle ricerche.

Le etichette sono un modo semplice per raggruppare le istanze correlate o associate tra loro. Ad esempio, puoi etichettare le istanze in base al loro utilizzo come test o produzione, oppure puoi aggiungere il tuo codice di fatturazione a un'istanza. Puoi usare le etichette per cercare istanze o monitorare i costi delle istanze.

Aggiungi sempre le etichette come coppie chiave/valore:

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

La modifica delle etichette non influisce sulle prestazioni delle istanze Cloud SQL.

Per ulteriori informazioni, vedi Che cosa sono le etichette? e Requisiti per le etichette.

Limitazioni

  • Puoi assegnare fino a 64 etichette a ogni istanza.

  • Le chiavi e i valori delle etichette devono essere conformi alle seguenti restrizioni:

    • Le chiavi e i valori non possono contenere più di 63 caratteri ciascuno.
    • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Sono consentiti caratteri internazionali.
    • Le chiavi delle etichette devono iniziare con una lettera minuscola.
    • Le chiavi delle etichette non possono essere vuote.

Creare istanze con etichette

Quando crei una nuova istanza utilizzando gcloud CLI o l'API, puoi applicare etichette all'istanza.

gcloud

Quando crei l'istanza, includi il flag "--labels", seguito da un elenco separato da virgole di coppie chiave-valore di etichette. Devi utilizzare la versione beta del comando create per includere le etichette.

Ad esempio:

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

Quando crei un'istanza con un'etichetta, utilizza una risorsa Terraform: 

resource "google_sql_database_instance" "mysql_instance_labels" {
  name             = "mysql-instance-labels"
  region           = "us-central1"
  database_version = "MYSQL_8_0"
  settings {
    tier = "db-n1-standard-2"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Applica le modifiche

Per applicare la tua configurazione Terraform a un progetto Google Cloud, completa i passaggi nelle sezioni seguenti.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud predefinito a cui vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome del file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel nuovo oggetto main.tf.

    Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata se lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Facoltativamente, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà soddisfino le tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione Terraform eseguendo questo comando e inserendo yes al prompt: 
    terraform apply

    Attendi finché in Terraform non viene visualizzato il messaggio "Applicazione completata!".

  3. Apri il progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nella UI per assicurarti che Terraform le abbia create o aggiornate.

Elimina le modifiche

Per eliminare le modifiche:

  1. Per disabilitare la protezione dall'eliminazione, imposta l'argomento deletion_protection nel file di configurazione di Terraform su false. 
    deletion_protection =  "false"
  2. Applica la configurazione Terraform aggiornata eseguendo questo comando e inserendo yes al prompt: 
    terraform apply

  1. Per rimuovere le risorse applicate in precedenza con la tua configurazione Terraform, esegui questo comando e inserisci yes al prompt:

    terraform destroy

curl

Nell'API, durante la richiesta "POST" per aggiungere una nuova istanza, aggiungi la proprietà "userEtichette" nel corpo della richiesta per applicare le etichette alla nuova istanza. Ad esempio, il corpo della richiesta per la creazione di un'istanza ha le seguenti etichette:

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},

Aggiungi o aggiorna le etichette su un'istanza esistente

console

  1. Vai alla pagina Istanze Cloud SQL nella console Google Cloud.

    Vai alla pagina Istanze Cloud SQL

  2. Seleziona le caselle di controllo accanto alle risorse che vuoi etichettare.

  3. Fai clic su Mostra riquadro informazioni nell'angolo in alto a destra per espandere la colonna delle etichette.

  4. Aggiorna o aggiungi nuove etichette in base alle tue esigenze.

  5. Salva le modifiche.

gcloud

Utilizza il sottocomando patch (versione beta) per aggiornare o aggiungere etichette su un'istanza esistente:

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

Ad esempio:

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

Se fornisci una chiave di etichetta già esistente, lo strumento aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento aggiunge la nuova chiave all'elenco di etichette. Sono interessate solo le etichette specificate; le etichette esistenti non incluse nel comando rimangono invariate.

riposo v1

Per aggiungere o aggiornare le etichette, utilizza il metodo PATCH:

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • project-id: l'ID progetto
  • instance-id: l'ID istanza
  • label-name-1: il nome di un'etichetta
  • value-1: il valore di label-name-1
  • label-name-2: il nome di un'etichetta
  • value-2: il valore di label-name-2

Metodo HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corpo JSON della richiesta: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Se fornisci una chiave di etichetta già esistente, lo strumento aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento aggiunge la nuova chiave all'elenco di etichette. Sono interessate solo le etichette specificate; le etichette esistenti non incluse nella richiesta rimangono invariate.

riposo v1beta4

Per aggiungere o aggiornare le etichette, utilizza il metodo PATCH:

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • project-id: l'ID progetto
  • instance-id: l'ID istanza
  • label-name-1: il nome di un'etichetta
  • value-1: il valore di label-name-1
  • label-name-2: il nome di un'etichetta
  • value-2: il valore di label-name-2

Metodo HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corpo JSON della richiesta: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Se fornisci una chiave di etichetta già esistente, lo strumento aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento aggiunge la nuova chiave all'elenco di etichette. Sono interessate solo le etichette specificate; le etichette esistenti non incluse nella richiesta rimangono invariate.

Rimuovere un'etichetta

console

  1. Vai alla pagina Istanze Cloud SQL nella console Google Cloud.

    Vai alla pagina Istanze Cloud SQL

  2. Seleziona le caselle di controllo accanto alle risorse per cui vuoi rimuovere le etichette.

  3. Fai clic su Mostra riquadro informazioni per espandere la colonna delle etichette.

  4. Fai clic sulla X accanto a tutte le etichette da rimuovere.

  5. Salva le modifiche.

gcloud

Utilizzando gcloud CLI, esegui il sottocomando patch (versione beta) con il flag --remove-labels:

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

Se fornisci un nome di etichetta che non esiste, non verrà restituito alcun errore.

riposo v1

Per rimuovere un'etichetta utilizzando l'API, imposta il valore su null:

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • project-id: l'ID progetto
  • instance-id: l'ID istanza
  • label-name: il nome dell'etichetta

Metodo HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corpo JSON della richiesta: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

riposo v1beta4

Per rimuovere un'etichetta utilizzando l'API, imposta il valore su null:

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • project-id: l'ID progetto
  • instance-id: l'ID istanza
  • label-name: il nome dell'etichetta

Metodo HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corpo JSON della richiesta: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Filtra le ricerche di istanze utilizzando le etichette

Puoi filtrare i risultati dell'elenco di istanze in base alle etichette utilizzando gcloud CLI o l'API.

gcloud

In gcloud, effettua una richiesta list e usa il flag --filter. Per filtrare in base alle etichette, utilizza la sintassi labels.[KEY]:[VALUE]. Ad esempio, se vuoi filtrare in base a un'etichetta billing-code con valore 34802, puoi eseguire questo comando:

gcloud beta sql instances list --filter='labels.billing-code:34802'

Se vuoi applicare un filtro in base all'esistenza di un'etichetta, indipendentemente dal suo valore:

gcloud beta sql instances list --filter='labels:billing-code'

Per la documentazione completa sulla sintassi dei filtri in gcloud CLI, consulta la documentazione di gcloud topic filters.

curl

Nell'API, effettua una richiesta di elenco con un parametro di query filter codificato nell'URL:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

Ad esempio:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

Quando vengono inclusi due valori di etichetta separati da uno spazio (codificato), devono essere entrambi veri affinché venga restituita un'istanza (un'operazione AND). Puoi anche fornire esplicitamente gli operatori AND, OR e NOT. Ad esempio:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

Passaggi successivi