Labeling Instances

Labels are a lightweight way to group together instances that are related or associated with each other. For example, you could label your instances according to whether you are using them as test or production, or you could add your own billing code to an instance. You can use the labels to search for instances or to track instance charges.

You always add labels as key/value pairs:

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

Restrictions

  • You can assign up to 64 labels to each instance.
  • Label keys and values must conform to the following restrictions:

    • Keys and values cannot be longer than 63 characters each.
    • Keys and values can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed.
    • Label keys must start with a lowercase letter.
    • Label keys cannot be empty.

Creating instances with labels

When creating a new instance using the gcloud command-line tool or the API, you can apply labels to the instance.

gcloud

When creating your instance, include the --labels flag, followed by a comma-separated list of key value pairs of labels. You must use the beta version of the create command to include labels.

For example:

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

curl

In the API, during the POST request to add a new instance, add the userLabels property in the request body to apply labels to the new instance. For example, your request body for creating an instance has the following labels:

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

Adding or updating labels on an existing instance

console

  1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

    Go to the Cloud SQL Instances page

  2. Select the checkboxes next to the resources you want to label.

  3. Click Show Info Panel in the upper righthand corner to expand the labels column.

  4. Update or add new labels as desired.

  5. Save your changes.

gcloud

Use the patch subcommand (beta version) to update or add labels on an existing instance:

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

For example:

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

If you provide a label key that already exists, the tool updates the existing key with the new label value. If you provide a new key, the tool adds the new key to the list of labels. Only the labels you specify are affected; existing labels not included in the command remain unchanged.

curl

To add or update labels, use the PATCH method:

ACCESS_TOKEN="$(gcloud auth application-default 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>

If you provide a label key that already exists, the tool updates the existing key with the new label value. If you provide a new key, the tool adds the new key to the list of labels. Only the labels you specify are affected; existing labels not included in the request remain unchanged.

Removing a label

console

  1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

    Go to the Cloud SQL Instances page

  2. Select the checkboxes next to the resources for which you want to remove labels.

  3. Click Show info panel to expand the labels column.
  4. Click the X next to all the labels you want to remove.
  5. Save your changes.

gcloud

Using the gcloud command-line tool, run the patch subcommand (beta version) with the --remove-labels flag:

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

If you provide a label name that does not exist, no error is returned.

curl

You remove a label using the API by setting its value to null:

ACCESS_TOKEN="$(gcloud auth application-default 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]

Filtering instance searches using labels

You can filter your instance list results by labels using the gcloud tool or the API.

gcloud

In gcloud, make a list request and use the --filter flag. To filter on labels, use the syntax labels.[KEY]:[VALUE]. For example, if you wanted to filter on a label billing-code with a value of 34802, you can run this command:

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

If you want to filter on whether a label exists, regardless of its value:

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

For complete documentation about the filter syntax in the gcloud tool, see the gcloud topic filters documentation.

curl

In the API, make a list request with a URL encoded filter query parameter:

ACCESS_TOKEN="$(gcloud auth application-default 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]

For example:

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

When two label values are included with an (encoded) space between them, they both must be true for an instance to be returned (an AND operation). You can also explicitly provide AND, OR, and NOT operators. For example:

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

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud SQL for MySQL