Como rotular instâncias

Marcadores 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.

Você sempre adiciona marcadores como pares de chave-valor:

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

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 de rótulos não podem estar vazias.

Como criar instâncias com marcadores

Ao criar uma nova instância usando a ferramenta de linha de comando gcloud ou a API, rotule as instâncias.

gcloud

Ao criar sua instância, inclua a sinalização --labels, seguida por uma lista de pares de chave-valor separadas por vírgula. Você precisa usar a versão Beta do comando de criação para incluir marcadores.

Por exemplo:

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

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 marcadores:

  ....
  "settings": {"tier":"db-n1-standard-2",
               "userLabels": {"track": "production",
                              "location": "western-division",
                              "billing-code": "34802"},
  ....

Como adicionar ou atualizar marcadores em uma instância existente

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.

curl

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

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"settings" : {"userLabels" :
                              {"<LABEL1>" : "<VALUE1>", "<LABEL2>" : "<VALUE2>"}}}' \
    -X PATCH \
    https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>

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 na solicitação permanecem inalterados.

Como remover um marcador

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 ferramenta de linha de comando 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.

curl

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

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"settings": {"userLabels": {"[LABEL_NAME]": null}}}' \
     -X PATCH \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/[INSTANCE_NAME]

Como filtrar buscas de instâncias usando marcadores

Filtre os resultados da lista de instâncias por rótulos usando a ferramenta gcloud 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 ferramenta do gcloud, 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 marcador 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