Rotular instâncias

Nesta página, explicamos como criar uma instância com rótulos, como adicionar, atualizar e remover rótulos e como usá-los nas pesquisas.

Os rótulos são uma maneira leve de agrupar instâncias relacionadas ou associadas entre si. Por exemplo, você pode marcar suas instâncias de acordo com a maneira como as está usando, seja como teste ou produção, ou você pode adicionar seu próprio código de cobrança a uma instância. Você pode usar os marcadores para procurar instâncias ou rastrear cobranças de instâncias.

Sempre adicione rótulos como pares de chave-valor:

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

A modificação de rótulos não afeta o desempenho da instância do Cloud SQL.

Para mais informações, consulte O que são rótulos? e Requisitos para rótulos.

Restrições

  • Você pode atribuir até 64 rótulos a cada instância.

  • As chaves e os valores dos rótulos precisam estar em conformidade com as seguintes restrições:

    • Chaves e valores não podem ter mais de 63 caracteres.
    • Chaves e valores podem conter apenas letras minúsculas, caracteres numéricos, sublinhados e travessões. Caracteres internacionais são permitidos.
    • As chaves de rótulos precisam começar com letra minúscula.
    • As chaves do rótulo não podem estar vazias.

Criar instâncias com rótulos

Ao criar uma nova instância usando a CLI gcloud ou a API, é possível rotular as instâncias.

gcloud

Ao criar sua instância, inclua a sinalização "--labels", seguida de uma lista separada por vírgulas de pares de chave-valor de marcadores. É necessário usar a versão Beta do comando de criação para incluir rótulos.

Exemplo:

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

Terraform

Ao criar uma instância com um rótulo, use um recurso do 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
}

Aplique as alterações

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

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

    terraform init -upgrade

Aplique as alterações

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

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Excluir as alterações

Para excluir as mudanças, faça o seguinte:

  1. Para desativar a proteção contra exclusão, no arquivo de configuração do Terraform, defina o argumento deletion_protection como false. 
    deletion_protection =  "false"
  2. Para aplicar a configuração atualizada do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

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

    terraform destroy

curl

Na API, durante a solicitação "POST" para adicionar uma nova instância, adicione a propriedade "userLabels" no corpo da solicitação para aplicar rótulos a essa nova instância. Por exemplo, o corpo da solicitação de criação de uma instância tem os seguintes rótulos:

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

Adicionar ou atualizar rótulos em uma instância atual

Console

  1. Acesse a página "Instâncias" do Cloud SQL no Console do Google Cloud.

    Acessar a página "Instâncias" do Cloud SQL

  2. Marque as caixas de seleção referentes aos recursos que receberão marcadores.

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

  4. Atualize ou adicione os novos marcadores conforme necessário.

  5. Salve as alterações.

gcloud

Use o subcomando patch (versão Beta) para atualizar ou adicionar rótulos em uma instância atual:

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

Exemplo:

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

Na ferramenta, quando a chave de marcador fornecida já existe, a chave existente é atualizada com o novo valor. Quando uma nova chave é fornecida, ela é adicionada à lista de marcadores. Somente os marcadores que você especifica são afetados. Os marcadores existentes não incluídos no comando permanecem inalterados.

REST v1

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto
  • instance-id: o ID da instância
  • label-name-1: um nome de rótulo
  • value-1: o valor de label-name-1
  • label-name-2: um nome de rótulo
  • value-2: o valor do label-name-2

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Na ferramenta, quando a chave de rótulo fornecida já existe, a chave é atualizada com o novo valor. Quando uma nova chave é fornecida, ela é adicionada à lista de marcadores. Somente os marcadores que você especifica são afetados. Os marcadores existentes não incluídos na solicitação permanecem inalterados.

rest v1beta4

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto
  • instance-id: o ID da instância
  • label-name-1: um nome de rótulo
  • value-1: o valor de label-name-1
  • label-name-2: um nome de rótulo
  • value-2: o valor do label-name-2

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Na ferramenta, quando a chave de rótulo fornecida já existe, a chave é atualizada com o novo valor. Quando uma nova chave é fornecida, ela é adicionada à lista de marcadores. Somente os marcadores que você especifica são afetados. Os marcadores existentes não incluídos na solicitação permanecem inalterados.

Remover um rótulo

Console

  1. Acesse a página "Instâncias" do Cloud SQL no Console do Google Cloud.

    Acessar a página "Instâncias" do Cloud SQL

  2. Selecione as caixas de seleção ao lado dos recursos que têm marcadores que você quer remover.

  3. Clique em Mostrar painel de informações para expandir a coluna de rótulos.

  4. Clique no X ao lado dos rótulos que você quer remover.

  5. Salve as alterações.

gcloud

Usando a CLI gcloud, execute o subcomando patch (versão beta) com a sinalização --remove-labels:

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

Se você fornecer um nome de rótulo que não existe, nenhum erro será retornado.

REST v1

Para remover um rótulo usando a API, defina o valor dele como null:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

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

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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 um rótulo usando a API, defina o valor dele como null:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

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

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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 pesquisas de instâncias usando rótulos

Você pode filtrar os resultados da lista de instâncias por marcadores usando a gcloud CLI ou a API.

gcloud

Na gcloud, crie uma solicitação list e use a sinalização --filter. Para filtrar rótulos, use a sintaxe labels.[KEY]:[VALUE]. Por exemplo, se você quiser filtrar um rótulo billing-code com um valor de 34802, execute este comando:

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

Se você quiser filtrar a existência de um rótulo, independentemente do valor:

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

Para conseguir a documentação completa sobre a sintaxe do filtro na gcloud CLI, consulte a documentação do gcloud topic filters.

curl

Na API, faça uma solicitação de lista com um parâmetro de consulta filter codificado por 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]

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 dois valores de rótulo estão incluídos com um espaço (codificado) entre eles, ambos precisam ser verdadeiros para que uma instância seja devolvida (uma operação AND). Também é possível fornecer explicitamente operadores AND, OR e NOT. 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

A seguir