Instâncias de etiquetas

Esta página explica as etiquetas. Descreve como criar uma instância com etiquetas; como adicionar, atualizar e remover etiquetas; e como usar etiquetas em pesquisas.

As etiquetas são uma forma simples de agrupar instâncias relacionadas ou associadas entre si. Por exemplo, pode etiquetar as suas instâncias de acordo com a utilização como teste ou produção, ou pode adicionar o seu próprio código de faturação a uma instância. Pode usar as etiquetas para pesquisar instâncias ou para acompanhar os custos das instâncias.

Adiciona sempre etiquetas como pares de chave/valor:

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

A modificação de etiquetas não tem impacto no desempenho da instância do Cloud SQL.

Para mais informações, consulte os artigos O que são as etiquetas? e Requisitos para etiquetas.

Restrições

  • Pode atribuir até 64 etiquetas a cada instância.

  • As chaves e os valores das etiquetas têm de estar em conformidade com as seguintes restrições:

    • As chaves e os valores não podem ter mais de 63 carateres cada.
    • As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. São permitidos carateres internacionais.
    • As chaves de etiquetas têm de começar com uma letra minúscula.
    • As chaves de etiquetas não podem estar vazias.

Crie instâncias com etiquetas

Quando cria uma nova instância através da CLI gcloud ou da API, pode aplicar etiquetas à instância.

gcloud

Quando criar a instância, inclua a flag `--labels`, seguida de uma lista separada por vírgulas de pares de chave-valor de etiquetas. Tem de usar a versão beta do comando create para incluir etiquetas.

Por exemplo:

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

Terraform

Quando criar uma instância com uma etiqueta, use um recurso do 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
}

Aplique as alterações

Para aplicar a configuração do Terraform num Trusted Cloud projeto, conclua os passos nas secções seguintes.

Prepare o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o Trusted Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

    Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

  1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

    Copie o exemplo de código para o ficheiro main.tf criado recentemente.

    Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

  3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
  4. Guarde as alterações.
  5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas: 
    terraform plan

    Faça correções à configuração conforme necessário.

  2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando: 
    terraform apply

    Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

  3. Abra o seu Trusted Cloud projeto para ver os resultados. Na Trusted Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

Eliminar as alterações

Para eliminar as alterações, faça o seguinte:

  1. Para desativar a proteção contra eliminação, no ficheiro de configuração do Terraform, defina o argumento deletion_protection como false. 
    deletion_protection =  "false"
  2. Aplique a configuração do Terraform atualizada executando o seguinte comando e introduzindo yes no comando: 
    terraform apply

  1. Remova os recursos aplicados anteriormente com a sua configuração do Terraform executando o seguinte comando e introduzindo yes no comando:

    terraform destroy

curl

Na API, durante o pedido `POST` para adicionar uma nova instância, adicione a propriedade `userLabels` no corpo do pedido para aplicar etiquetas à nova instância. Por exemplo, o corpo do pedido para criar uma instância tem as seguintes etiquetas:

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

Adicione ou atualize etiquetas numa instância existente

consola

  1. Aceda à página Instâncias do Cloud SQL na Trusted Cloud consola.

    Aceda à página Instâncias do Cloud SQL

  2. Selecione as caixas de verificação junto aos recursos que quer etiquetar.

  3. Clique em Mostrar painel de informações no canto superior direito para expandir a coluna de etiquetas.

  4. Atualize ou adicione novas etiquetas conforme desejado.

  5. Guarde as alterações.

gcloud

Use o subcomando patch (versão beta) para atualizar ou adicionar etiquetas numa instância existente:

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

Por exemplo:

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

Se fornecer uma chave de etiqueta que já exista, a ferramenta atualiza a chave existente com o novo valor da etiqueta. Se fornecer uma nova chave, a ferramenta adiciona a nova chave à lista de etiquetas. Apenas as etiquetas que especificar são afetadas. As etiquetas existentes não incluídas no comando permanecem inalteradas.

rest v1

Para adicionar ou atualizar etiquetas, use o método PATCH:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do projeto
  • instance-id: o ID da instância
  • label-name-1: o nome de uma etiqueta
  • value-1: o valor de label-name-1
  • label-name-2: o nome de uma etiqueta
  • value-2: o valor de label-name-2

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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 fornecer uma chave de etiqueta que já exista, a ferramenta atualiza a chave existente com o novo valor da etiqueta. Se fornecer uma nova chave, a ferramenta adiciona a nova chave à lista de etiquetas. Apenas as etiquetas que especificar são afetadas. As etiquetas existentes não incluídas no pedido permanecem inalteradas.

rest v1beta4

Para adicionar ou atualizar etiquetas, use o método PATCH:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do projeto
  • instance-id: o ID da instância
  • label-name-1: o nome de uma etiqueta
  • value-1: o valor de label-name-1
  • label-name-2: o nome de uma etiqueta
  • value-2: o valor de label-name-2

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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 fornecer uma chave de etiqueta que já exista, a ferramenta atualiza a chave existente com o novo valor da etiqueta. Se fornecer uma nova chave, a ferramenta adiciona a nova chave à lista de etiquetas. Apenas as etiquetas que especificar são afetadas. As etiquetas existentes não incluídas no pedido permanecem inalteradas.

Remova uma etiqueta

consola

  1. Aceda à página Instâncias do Cloud SQL na Trusted Cloud consola.

    Aceda à página Instâncias do Cloud SQL

  2. Selecione as caixas de verificação junto aos recursos dos quais quer remover etiquetas.

  3. Clique em Mostrar painel de informações para expandir a coluna de etiquetas.

  4. Clique em X junto a todas as etiquetas que quer remover.

  5. Guarde as alterações.

gcloud

Com a CLI gcloud, execute o subcomando patch (versão beta) com a flag --remove-labels:

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

Se fornecer um nome de etiqueta que não existe, não é devolvido nenhum erro.

rest v1

Para remover uma etiqueta através da API, defina o respetivo valor como null:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do projeto
  • instance-id: o ID da instância
  • label-name: o nome da etiqueta

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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 remover uma etiqueta através da API, defina o respetivo valor como null:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do projeto
  • instance-id: o ID da instância
  • label-name: o nome da etiqueta

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

Filtre pesquisas de instâncias através de etiquetas

Pode filtrar os resultados da lista de instâncias por etiquetas através da CLI gcloud ou da API.

gcloud

Em gcloud, faça um pedido list e use a flag --filter. Para filtrar por etiquetas, use a sintaxe labels.[KEY]:[VALUE]. Por exemplo, se quiser filtrar por uma etiqueta billing-code com um valor de 34802, pode executar este comando:

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

Se quiser filtrar se existe uma etiqueta, independentemente do respetivo valor:

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

Para aceder à documentação completa sobre a sintaxe de filtros na CLI gcloud, consulte a documentação do gcloud topic filters.

curl

Na API, faça um pedido de lista com um parâmetro de consulta filter com codificação 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 exemplo:

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 são incluídos dois valores de etiquetas com um espaço (codificado) entre eles, ambos têm de ser verdadeiros para que seja devolvida uma instância (uma operação AND). Também pode fornecer explicitamente os operadores AND, OR e NOT. Por exemplo:

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

O que se segue?