Etiquetar instancias

En esta página se explican las etiquetas. En él se describe cómo crear una instancia con etiquetas, cómo añadir, actualizar y quitar etiquetas, y cómo usar etiquetas en las búsquedas.

Las etiquetas son una forma ligera de agrupar instancias relacionadas o asociadas entre sí. Por ejemplo, puedes etiquetar tus instancias según si las utilizas como prueba o producción, o puedes agregar tu propio código de facturación a una instancia. Puedes usar las etiquetas para buscar instancias o para rastrear cobros de la instancia.

Las etiquetas siempre se agregan como pares clave/valor:

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

Modificar las etiquetas no afecta al rendimiento de la instancia de Cloud SQL.

Para obtener más información, consulta ¿Qué son las etiquetas? y Requisitos de las etiquetas.

Restricciones

  • Puedes asignar hasta 64 etiquetas a cada instancia.

  • Las claves y valores de etiqueta deben cumplir con las siguientes restricciones:

    • Las claves y los valores no pueden tener más de 63 caracteres cada uno.
    • Las claves y los valores solo pueden contener letras en minúscula, caracteres numéricos, guiones bajos y guiones. Se permite utilizar caracteres internacionales.
    • Las claves de etiqueta deben comenzar con una letra minúscula.
    • Las claves de etiqueta no pueden estar vacías.

Crear instancias con etiquetas

Cuando creas una instancia con la CLI de gcloud o la API, puedes aplicarle etiquetas.

gcloud

Cuando crees la instancia, incluye la marca `--labels`, seguida de una lista de pares clave-valor de etiquetas separados por comas. Para incluir etiquetas, debes usar la versión beta del comando create.

Por ejemplo:

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

Terraform

Cuando crees una instancia con una etiqueta, usa un recurso de Terraform: 

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
}

Aplica los cambios

Para aplicar la configuración de Terraform en un proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

  1. Abre Cloud Shell.

  2. Define el Google Cloud proyecto Google Cloud predeterminado en el que quieras aplicar tus configuraciones de Terraform.

    Solo tiene que ejecutar este comando una vez por proyecto y puede hacerlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

  1. En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

    Copia el código de ejemplo en el archivo main.tf que acabas de crear.

    También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.

  3. Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
  4. Guarda los cambios.
  5. Inicializa Terraform. Solo tienes que hacerlo una vez por directorio. 
    terraform init

    Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade: 

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas: 
    terraform plan

    Haga las correcciones necesarias en la configuración.

  2. Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición: 
    terraform apply

    Espera hasta que Terraform muestre el mensaje "Apply complete!".

  3. Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para asegurarte de que Terraform los ha creado o actualizado.

Eliminar los cambios

Para eliminar los cambios, sigue estos pasos:

  1. Para inhabilitar la protección contra la eliminación, en el archivo de configuración de Terraform, asigna el valor false al argumento deletion_protection. 
    deletion_protection =  "false"
  2. Aplica la configuración de Terraform actualizada ejecutando el siguiente comando e introduciendo yes en la petición: 
    terraform apply

  1. Para quitar los recursos que se hayan aplicado anteriormente con tu configuración de Terraform, ejecuta el siguiente comando e introduce yes en la petición:

    terraform destroy

curl

En la API, durante la solicitud `POST` para añadir una instancia, añada la propiedad `userLabels` al cuerpo de la solicitud para aplicar etiquetas a la nueva instancia. Por ejemplo, el cuerpo de la solicitud para crear una instancia tiene las siguientes etiquetas:

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

Añadir o actualizar etiquetas en una instancia

consola

  1. Ve a la página Instancias de Cloud SQL de la Google Cloud consola.

    Ir a la página Instancias de Cloud SQL

  2. Selecciona las casillas junto a los recursos que quieres etiquetar.

  3. En la esquina superior derecha, haz clic en Mostrar panel de información para desplegar la columna de etiquetas.

  4. Actualiza o añade las etiquetas que quieras.

  5. Guarda los cambios.

gcloud

Usa el subcomando patch (versión beta) para actualizar o añadir etiquetas a una instancia:

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

Por ejemplo:

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

Si proporcionas una clave de etiqueta que ya existe, la herramienta actualiza la clave con el nuevo valor de etiqueta. Si proporcionas una clave nueva, la herramienta agrega la clave nueva a la lista de etiquetas. Solo se verán afectadas las etiquetas que especifiques. Las que ya existan, pero no estén incluidas en la petición permanecen sin cambios.

REST v1

Para añadir o actualizar etiquetas, usa el método PATCH:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • project-id: el ID del proyecto
  • instance-id: el ID de instancia.
  • label-name-1: nombre de la etiqueta
  • value-1: el valor de label-name-1
  • label-name-2: nombre de la etiqueta
  • value-2: el valor de label-name-2

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

Si proporcionas una clave de etiqueta que ya existe, la herramienta actualiza la clave con el nuevo valor de etiqueta. Si proporcionas una clave nueva, la herramienta agrega la clave nueva a la lista de etiquetas. Solo se verán afectadas las etiquetas que especifiques. Las que ya existan, pero no estén incluidas en la petición permanecen sin cambios.

rest v1beta4

Para añadir o actualizar etiquetas, usa el método PATCH:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • project-id: el ID del proyecto
  • instance-id: el ID de instancia.
  • label-name-1: nombre de la etiqueta
  • value-1: el valor de label-name-1
  • label-name-2: nombre de la etiqueta
  • value-2: el valor de label-name-2

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

Si proporcionas una clave de etiqueta que ya existe, la herramienta actualiza la clave con el nuevo valor de etiqueta. Si proporcionas una clave nueva, la herramienta agrega la clave nueva a la lista de etiquetas. Solo se verán afectadas las etiquetas que especifiques. Las que ya existan, pero no estén incluidas en la petición permanecen sin cambios.

Quitar una etiqueta

consola

  1. Ve a la página Instancias de Cloud SQL de la Google Cloud consola.

    Ir a la página Instancias de Cloud SQL

  2. Seleccione las casillas situadas junto a los recursos de los que quiera quitar las etiquetas.

  3. Haz clic en Mostrar panel de información para desplegar la columna de etiquetas.

  4. Haz clic en la X junto a todas las etiquetas que deseas eliminar.

  5. Guarda los cambios.

gcloud

Con gcloud CLI, ejecuta el subcomando patch (versión beta) con la marca --remove-labels:

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

Si proporcionas un nombre de etiqueta que no existe, no se devuelve ningún error.

REST v1

Para quitar una etiqueta con la API, debes definir su valor como null:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • project-id: el ID del proyecto
  • instance-id: el ID de instancia.
  • label-name: nombre de la etiqueta

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

Para quitar una etiqueta con la API, debes definir su valor como null:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • project-id: el ID del proyecto
  • instance-id: el ID de instancia.
  • label-name: nombre de la etiqueta

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

Filtrar búsquedas de instancias mediante etiquetas

Puedes filtrar los resultados de la lista de instancias por etiquetas con la CLI de gcloud o la API.

gcloud

En gcloud, haz una solicitud list y usa la marca --filter. Para filtrar por etiquetas, usa la sintaxis labels.[KEY]:[VALUE]. Por ejemplo, si quieres filtrar por una etiqueta billing-code con el valor 34802, puedes ejecutar este comando:

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

Si quieres filtrar si existe una etiqueta, independientemente de su valor:

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

Para consultar la documentación completa sobre la sintaxis de los filtros en la CLI de gcloud, consulta la documentación de gcloud topic filters.

curl

En la API, haz una solicitud de lista con un parámetro de consulta filter codificado como 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]

Por ejemplo:

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

Si se incluyen dos valores de etiqueta con un espacio (codificado) entre ellos, ambos deben ser verdaderos para que se devuelva una instancia (una operación AND). También puedes proporcionar explícitamente los operadores AND, OR y NOT. Por ejemplo:

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

Siguientes pasos