Label für Instanzen

Auf dieser Seite erhalten Sie Informationen zu Labels. Es wird beschrieben, wie Sie eine Instanz mit Labels erstellen. Außerdem erfahren Sie, wie Labels hinzugefügt, aktualisiert, entfernt und in Suchanfragen verwendet werden.

Mit Labels können Sie verwandte oder miteinander verknüpfte Instanzen auf einfache Weise gruppieren. Sie können beispielsweise für Test- oder Produktionszwecke verwendete Instanzen entsprechend beschriften oder Ihren eigenen Abrechnungscode zu einer Instanz hinzuzufügen. Anhand der Labels können Sie Instanzen suchen oder die Kosten für Instanzen überwachen.

Labels werden immer als Schlüssel/Wert-Paare hinzugefügt:

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

Die Änderung von Labels wirkt sich nicht auf die Leistung der Cloud SQL-Instanz aus.

Weitere Informationen finden Sie unter Was sind Labels? und Anforderungen an Labels.

Beschränkungen

  • Sie können jeder Instanz bis zu 64 Labels zuweisen.

  • Labelschlüssel und -werte unterliegen den folgenden Beschränkungen:

    • Schlüssel und Werte dürfen jeweils nicht länger als 63 Zeichen sein.
    • Schlüssel und Werte dürfen nur Kleinbuchstaben, numerische Zeichen, Unterstriche und Bindestriche enthalten. Internationale Zeichen sind erlaubt.
    • Labelschlüssel müssen mit einem Kleinbuchstaben beginnen.
    • Labelschlüssel dürfen nicht leer sein.

Instanzen mit Labels erstellen

Wenn Sie mit der gcloud CLI oder der API eine neue Instanz erstellen, können Sie Labels auf die Instanz anwenden.

gcloud

Geben Sie beim Erstellen der Instanz das Flag --labels gefolgt von einer durch Kommas getrennten Liste mit Schlüssel/Wert-Paaren für Labels an. Um Labels einzubeziehen, müssen Sie die Betaversion des Befehls "create" verwenden.

Beispiel:

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

Terraform

Verwenden Sie beim Erstellen einer Instanz mit einem Label eine Terraform-Ressource: 

resource "google_sql_database_instance" "postgres_instance_labels" {
  name             = "postgres-instance-labels"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    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
}

Änderungen anwenden

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud-Projekt anzuwenden.

Cloud Shell vorbereiten

  1. Rufen Sie Cloud Shell auf.

  2. Legen Sie das Google Cloud-Standardprojekt fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.

    Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).

  1. Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung .tf haben, z. B. main.tf. In dieser Anleitung wird die Datei als main.tf bezeichnet. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.

    Kopieren Sie den Beispielcode in das neu erstellte main.tf.

    Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.

  3. Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
  4. Speichern Sie die Änderungen.
  5. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich. 
    terraform init

    Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden: 

    terraform init -upgrade

Änderungen anwenden

  1. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen: 
    terraform plan

    Korrigieren Sie die Konfiguration nach Bedarf.

  2. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein: 
    terraform apply

    Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

  3. Öffnen Sie Ihr Google Cloud-Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.

Änderungen löschen

So löschen Sie das Projekt:

  1. Um den Löschschutz zu deaktivieren, setzen Sie in der Terraform-Konfigurationsdatei das Argument deletion_protection auf false. 
    deletion_protection =  "false"
  2. Wenden Sie die aktualisierte Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein: 
    terraform apply

  1. Entfernen Sie Ressourcen, die zuvor mit Ihrer Terraform-Konfiguration angewendet wurden, indem Sie den folgenden Befehl ausführen und yes an der Eingabeaufforderung eingeben:

    terraform destroy

curl

Fügen Sie in der API während der "POST"-Anfrage zum Hinzufügen einer neuen Instanz das Attribut "userLabels" in den Anfragetext ein, damit die Labels der neuen Instanz zugewiesen werden. Ihr Anfragetext zum Erstellen einer Instanz kann beispielsweise die folgenden Labels enthalten:

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

Labels in vorhandener Instanz hinzufügen oder aktualisieren

Konsole

  1. Öffnen Sie in der Google Cloud Console die Seite "Cloud SQL-Instanzen".

    Zur Seite "Cloud SQL-Instanzen"

  2. Klicken Sie auf die Kästchen neben den Ressourcen, die Sie mit Labels versehen möchten.

  3. Klicken Sie rechts oben auf Infofeld anzeigen, um die Spalte für Labels zu erweitern.

  4. Aktualisieren Sie Labels oder fügen Sie neue Labels hinzu.

  5. Speichern Sie die Änderungen.

gcloud

Mit dem Unterbefehl patch (Betaversion) können Sie Labels in einer vorhandenen Instanz aktualisieren oder hinzufügen:

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

Beispiel:

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

Aktualisieren Sie den Schlüssel mit dem neuen Labelwert mit einem bestehenden Labelschlüssel. Wenn Sie einen neuen Schlüssel angeben, fügt das Tool diesen Schlüssel der Labelliste hinzu. Dies wirkt sich nur auf die von Ihnen angegebenen Labels aus. Vorhandene Label, die nicht in dem Befehl angegeben sind, bleiben unverändert.

rest v1

So verwenden Sie die Methode PATCH, um Labels hinzuzufügen oder zu aktualisieren:

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • project-id: die Projekt-ID
  • instance-id: die Instanz-ID
  • label-name-1: ein Labelname
  • value-1: der Wert von label-name-1
  • label-name-2: ein Labelname
  • value-2: der Wert von label-name-2

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "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"
}

Aktualisieren Sie den Schlüssel mit dem neuen Labelwert mit einem bestehenden Labelschlüssel. Wenn Sie einen neuen Schlüssel angeben, fügt das Tool diesen Schlüssel der Labelliste hinzu. Dies wirkt sich nur auf die von Ihnen angegebenen Labels aus. Vorhandene Labels, die nicht in der Anfrage angegeben sind, bleiben unverändert.

rest v1beta4

So verwenden Sie die Methode PATCH, um Labels hinzuzufügen oder zu aktualisieren:

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • project-id: die Projekt-ID
  • instance-id: die Instanz-ID
  • label-name-1: ein Labelname
  • value-1: der Wert von label-name-1
  • label-name-2: ein Labelname
  • value-2: der Wert von label-name-2

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "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"
}

Aktualisieren Sie den Schlüssel mit dem neuen Labelwert mit einem bestehenden Labelschlüssel. Wenn Sie einen neuen Schlüssel angeben, fügt das Tool diesen Schlüssel der Labelliste hinzu. Dies wirkt sich nur auf die von Ihnen angegebenen Labels aus. Vorhandene Labels, die nicht in der Anfrage angegeben sind, bleiben unverändert.

Label entfernen

Konsole

  1. Öffnen Sie in der Google Cloud Console die Seite "Cloud SQL-Instanzen".

    Zur Seite "Cloud SQL-Instanzen"

  2. Wählen Sie die Kästchen neben den Ressourcen aus, für die Sie Labels entfernen möchten.

  3. Klicken Sie auf Infofeld anzeigen, um die Spalte mit den Labels zu erweitern.

  4. Klicken Sie auf das X neben den Labels, die Sie entfernen möchten.

  5. Speichern Sie die Änderungen.

gcloud

Führen Sie mit der gcloud CLI den Unterbefehl patch (Betaversion) mit dem Flag --remove-labels aus:

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

Wenn Sie einen nicht vorhandenen Labelnamen angeben, wird keine Fehlermeldung zurückgegeben.

rest v1

Legen Sie den Wert auf null fest, um ein Label über die API zu entfernen:

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • project-id: die Projekt-ID
  • instance-id: die Instanz-ID
  • label-name: der Labelname

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "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"
}

rest v1beta4

Legen Sie den Wert auf null fest, um ein Label über die API zu entfernen:

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • project-id: die Projekt-ID
  • instance-id: die Instanz-ID
  • label-name: der Labelname

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "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"
}

Instanzsuche mit Labels filtern

Sie können die Instanzlistenergebnisse mit der gcloud CLI oder über die API nach Labels filtern.

gcloud

Erstellen Sie in gcloud eine list-Anfrage und verwenden Sie das Flag --filter. Mit der Syntax labels.[KEY]:[VALUE] können Sie nach Labels filtern. Wenn Sie beispielsweise nach dem Label billing-code mit dem Wert 34802 filtern möchten, können Sie diesen Befehl ausführen:

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

So filtern Sie unabhängig vom Wert nach einem vorhandenen Label:

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

Eine vollständige Dokumentation der Filtersyntax in der gcloud CLI finden Sie in der Dokumentation zu gcloud topic filters.

curl

In der API stellen Sie eine Listenanfrage mit dem URL-codierten Abfrageparameter filter.

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]

Beispiel:

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

Wenn zwei Labelwerte mit einem (codierten) Leerzeichen dazwischen enthalten sind, müssen beide den Wert "true" haben, damit eine Instanz zurückgegeben wird. Es handelt sich hierbei um die Operation AND. Sie können die Operatoren AND, OR und NOT auch explizit angeben. Beispiel:

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

Weitere Informationen