Etiqueta instancias

En esta página, se explican las etiquetas. Se describe cómo crear una instancia con etiquetas, cómo agregar, actualizar y quitar etiquetas, y cómo usarlas en las búsquedas.

Las etiquetas son una forma rápida de agrupar instancias relacionadas o asociadas entre sí. Por ejemplo, puedes etiquetar tus instancias según se usen 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 realizar un seguimiento de los cargos de instancia.

Las etiquetas siempre se agregan en pares clave-valor:

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

La modificación de etiquetas no tiene ningún impacto en el rendimiento de las instancias de Cloud SQL.

Para obtener más información, consulta las páginas ¿Qué son las etiquetas? y Requisitos para 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, números, guiones y guiones bajos. Se permite el uso de caracteres internacionales.
    • Las claves de etiquetas deben comenzar con una letra en minúscula.
    • Las claves de etiquetas no pueden estar vacías.

Crea instancias con etiquetas

Cuando creas una instancia nueva con la CLI de gcloud o la API, puedes aplicar etiquetas a la instancia.

gcloud

Cuando creas tu instancia, incluye la marca --labels, seguida de una lista separada por comas de los pares clave-valor de las etiquetas. Debes usar la versión Beta del comando create para incluir las etiquetas.

Por ejemplo:

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

Terraform

Cuando crees una instancia con una etiqueta, usa un recurso 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 tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

  1. Inicia Cloud Shell

  2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

Prepara 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 dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

    Copia el código de muestra en el main.tf recién creado.

    De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicializa Terraform. Solo debes hacerlo una vez por directorio. 
    terraform init

    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google: 

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas: 
    terraform plan

    Corrige la configuración según sea necesario.

  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite: 
    terraform apply

    Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

  3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Borra los cambios

Para borrar tus cambios, haz lo siguiente:

  1. Para inhabilitar la protección contra la eliminación, en tu archivo de configuración de Terraform, establece el argumento deletion_protection en false. 
    deletion_protection =  "false"
  2. Para aplicar la configuración actualizada de Terraform, ejecuta el siguiente comando y, luego, ingresa yes cuando se te solicite: 
    terraform apply

  1. Quita los recursos que se aplicaron antes con tu configuración de Terraform mediante la ejecución del siguiente comando y, luego, ingresa yes cuando se te solicite:

    terraform destroy

curl

En la API, durante la solicitud POST para agregar una instancia nueva, agrega la propiedad userLabels en el cuerpo de la solicitud a fin de aplicar etiquetas a esa instancia nueva. Por ejemplo, tu cuerpo de solicitud para crear una instancia tiene las siguientes etiquetas:

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

Agrega o actualiza las etiquetas en una instancia existente

Console

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

    Ir a la página de instancias de Cloud SQL

  2. Selecciona las casillas de verificación que aparecen junto a los recursos que deseas etiquetar.

  3. Haz clic en Mostrar panel de información en la esquina superior derecha para expandir la columna de etiquetas.

  4. Actualiza o agrega etiquetas nuevas como desees.

  5. Guarda los cambios.

gcloud

Usa el subcomando patch (versión Beta) para actualizar o agregar etiquetas en una instancia existente:

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 existente con el valor de etiqueta nuevo. Si proporcionas una clave nueva, la herramienta la agrega a la lista de etiquetas. Solo están afectadas las claves que específicas. Las etiquetas existentes que no están incluidas en el comando permanecen sin cambios.

rest v1

Para agregar o actualizar etiquetas, usa el método PATCH:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID del proyecto
  • instance-id: El ID de la instancia
  • label-name-1: Un nombre de etiqueta
  • value-1: El valor de label-name-1
  • label-name-2: Un nombre de 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, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 existente con el valor de etiqueta nuevo. Si proporcionas una clave nueva, la herramienta la agrega a la lista de etiquetas. Solo están afectadas las claves que específicas. Las etiquetas existentes que no están incluidas en la solicitud permanecen sin cambios.

rest v1beta4

Para agregar o actualizar etiquetas, usa el método PATCH:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID del proyecto
  • instance-id: El ID de la instancia
  • label-name-1: Un nombre de etiqueta
  • value-1: El valor de label-name-1
  • label-name-2: Un nombre de 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, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 existente con el valor de etiqueta nuevo. Si proporcionas una clave nueva, la herramienta la agrega a la lista de etiquetas. Solo están afectadas las claves que específicas. Las etiquetas existentes que no están incluidas en la solicitud permanecen sin cambios.

Quita una etiqueta

Console

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

    Ir a la página de instancias de Cloud SQL

  2. Selecciona las casillas de verificación que aparecen junto a los recursos cuyas etiquetas deseas quitar.

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

  4. Haz clic en la X que aparece junto a las etiquetas que deseas quitar.

  5. Guarda los cambios.

gcloud

Con la CLI de gcloud, 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 muestra ningún error.

rest v1

Puedes quitar una etiqueta con la API si configuras su valor como null:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID del proyecto
  • instance-id: El ID de la instancia
  • label-name: El 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, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Puedes quitar una etiqueta con la API si configuras su valor como null:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID del proyecto
  • instance-id: El ID de la instancia
  • label-name: El 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, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 búsquedas de instancias mediante etiquetas

Puedes filtrar tus resultados de la lista de instancias con la CLI de gcloud o con la API.

gcloud

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

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

Si deseas filtrar para saber si una etiqueta existe, sin importar su valor, ejecuta este comando:

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

Para obtener la documentación completa sobre la sintaxis de 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 en 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

Cuando dos valores de etiqueta están incluidos con un espacio (codificado) entre sí, ambos deben ser verdaderos para que se muestre una instancia (una operación AND). También puedes proporcionar de manera explícita 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

Pasos siguientes