Instâncias de rótulo, Instâncias de rótulo, Instâncias de rótulo, Instâncias de rótulo

Esta página explica rótulos. Ela descreve como criar uma instância com rótulos; como adicionar, atualizar e remover rótulos; e como usar rótulos em pesquisas.

Os rótulos são uma maneira simples de agrupar instâncias relacionadas ou associadas. Por exemplo, você pode rotular suas instâncias de acordo com o uso, seja como teste ou produção, ou adicionar seu próprio código de cobrança a uma instância. Você pode usar os rótulos para pesquisar instâncias ou rastrear cobranças por elas.

Você sempre adiciona rótulos como pares chave/valor:

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

Modificar rótulos não afeta o desempenho da instância do Cloud SQL.

Para obter 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 devem obedecer às seguintes restrições:

    • Chaves e valores não podem ter mais de 63 caracteres cada.
    • Chaves e valores podem conter apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Caracteres internacionais são permitidos.
    • As chaves de rótulo devem começar com uma letra minúscula.
    • As chaves de rótulo não podem estar vazias.

Criar instâncias com rótulos

Ao criar uma nova instância usando a CLI ou a API do gcloud , você pode aplicar rótulos à instância.

gcloud

Ao criar sua instância, inclua o sinalizador `--labels`, seguido por uma lista separada por vírgulas de pares de valores-chave de rótulos. Você deve usar a versão beta do comando create para incluir rótulos.

Por 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
}

Aplicar as alterações

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

Preparar o Cloud Shell

  1. Inicie o Cloud Shell .

  2. Defina o padrão Google Cloud projeto onde você deseja aplicar suas configurações do Terraform.

    Você só precisa executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    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 deve ter seu 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 deve ter a extensão .tf — por exemplo, main.tf Neste tutorial, o arquivo será chamado de main.tf 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

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

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

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

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve suas 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

Aplicar as alterações

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

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

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

    Aguarde até que o Terraform exiba a mensagem "Aplicação concluída!".

  3. Abra seu Google Cloud projeto para visualizar os resultados. No Google Cloud console, navegue até seus recursos na interface do usuário para garantir que o Terraform os criou ou atualizou.

Excluir as alterações

Para excluir suas alterações, faça o seguinte:

  1. Para desabilitar a proteção contra exclusão, no seu arquivo de configuração do Terraform defina o argumento deletion_protection como false . 
    deletion_protection =  "false"
  2. Aplique a configuração atualizada do Terraform executando o seguinte comando e digitando yes no prompt: 
    terraform apply

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

    terraform destroy

enrolar

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 à nova instância. Por exemplo, o corpo da solicitação para criar 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 existente

console

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

    Acesse a página Instâncias do Cloud SQL

  2. Marque as caixas de seleção ao lado dos recursos que você deseja rotular.

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

  4. Atualize ou adicione novos rótulos conforme desejado.

  5. Salve suas alterações.

gcloud

Use o subcomando patch (versão beta) para atualizar ou adicionar rótulos em uma 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 você fornecer uma chave de rótulo já existente, a ferramenta atualizará a chave existente com o novo valor de rótulo. Se você fornecer uma nova chave, a ferramenta a adicionará à lista de rótulos. Somente os rótulos especificados serão afetados; os rótulos existentes não incluídos no comando permanecerão inalterados.

resto v1

Para adicionar ou atualizar rótulos, use o método PATCH :

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

  • 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 de 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 sua solicitação, expanda uma destas opções:

Você 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": "[email protected]",
  "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 você fornecer uma chave de rótulo já existente, a ferramenta atualizará a chave existente com o novo valor de rótulo. Se você fornecer uma nova chave, a ferramenta a adicionará à lista de rótulos. Somente os rótulos especificados serão afetados; os rótulos existentes não incluídos na solicitação permanecerão inalterados.

resto v1beta4

Para adicionar ou atualizar rótulos, use o método PATCH :

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

  • 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 de 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 sua solicitação, expanda uma destas opções:

Você 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": "[email protected]",
  "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 você fornecer uma chave de rótulo já existente, a ferramenta atualizará a chave existente com o novo valor de rótulo. Se você fornecer uma nova chave, a ferramenta a adicionará à lista de rótulos. Somente os rótulos especificados serão afetados; os rótulos existentes não incluídos na solicitação permanecerão inalterados.

Remover um rótulo

console

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

    Acesse a página Instâncias do Cloud SQL

  2. Marque as caixas de seleção ao lado dos recursos cujos rótulos você deseja remover.

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

  4. Clique no X ao lado de todos os rótulos que você deseja remover.

  5. Salve suas alterações.

gcloud

Usando o gcloud CLI , execute o subcomando patch (versão beta) com o sinalizador --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.

resto v1

Você remove um rótulo usando a API definindo seu valor como null :

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

  • 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 sua solicitação, expanda uma destas opções:

Você 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": "[email protected]",
  "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"
}

resto v1beta4

Você remove um rótulo usando a API definindo seu valor como null :

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

  • 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 sua solicitação, expanda uma destas opções:

Você 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": "[email protected]",
  "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ância usando rótulos

Você pode filtrar os resultados da sua lista de instâncias por rótulos usando a CLI do gcloud ou a API.

gcloud

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

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

Se você quiser filtrar se um rótulo existe, independentemente do seu valor: 

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

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

enrolar

Na API, faça uma solicitação de lista com um parâmetro de consulta filter codificado em 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 dois valores de rótulo são incluídos com um espaço (codificado) entre eles, ambos devem ser verdadeiros para que uma instância seja retornada (uma operação AND ). Você 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 vem a seguir