Using Metadata

Page last updated:

This topic describes metadata in Pivotal Application Service and provides instructions for adding, updating, removing, and viewing metadata.

Note: This topic includes references to cf CLI v7 beta commands. Consider the following when using these commands:
  • cf CLI v7 beta and CAPI v3 are both in active development and subject to change.
  • cf CLI v7 beta is developed and tested against the latest CAPI release candidate.
  • cf CLI v7 beta does not yet use CAPI v3 for all commands. Some commands still use CAPI v2 during beta.
For more information, see Upgrading to cf CLI v7 (Beta).

About Metadata

PAS allows you to add metadata to resources such as spaces and apps. You can use metadata to provide additional information about the resources in your PAS deployment. This can help with operating, monitoring, and auditing.

For example, you can tag resources with metadata that describes the type of environment they belong to. You could also use metadata to describe app characteristics, such as front end or back end. Other examples include billing codes, points of contact, resource consumption, and information about security or risk.

Methods of Adding Metadata

You can add metadata to resources using any of the following methods:

Types of Metadata

You can add two types of metadata to resources in PAS:

  • Labels: Labels allow you to identify and select PAS resources. For example, if you have labeled all apps running in production, or all spaces that contain Internet-facing apps, you can then search for them.

  • Annotations: Annotations allow you to add non-identifying metadata to PAS resources. You cannot query based on annotations. Also, there are fewer restrictions for key-value pairs of annotations than there are for labels. For example, you can include contact information of persons responsible for the resource, or tool information for debugging purposes.

Metadata Requirements

The following tables describe requirements for creating metadata.

Requirements for Labels

The following table describes the requirements for creating labels.

Label Requirements
Part of Label Length in characters Allowed characters Other Requirements
(Optional) Key Prefix 0-253
  • Alphanumeric
  • -
  • .
  • DNS subdomain format, with at least one .
  • Must end with /
Key Name 1-63
  • Alphanumeric
  • -
  • _
  • .
Must begin and end with an alphanumeric character
Value 0-63
  • Alphanumeric
  • -
  • _
  • .
  • Must begin and end with an alphanumeric character
  • Empty values allowed

Requirements for Annotations

The following table describes the requirements for creating annotations.

Label Requirements
Part of Annotation Length in characters Allowed characters Other Requirements
(Optional) Key Prefix 0-253
  • Alphanumeric
  • -
  • .
  • DNS subdomain format, with at least one .
  • Must end with /
Key Name 1-63
  • Alphanumeric
  • -
  • _
  • .
Must begin and end with an alphanumeric character
Value 0-5000 n/a n/a

Metadata Key Prefixes

You can ensure a label or annotation key is easily differentiated from other keys by using a prefix. A prefix is a namespacing pattern that helps you more clearly identify resources. Prefixes are in DNS subdomain format: prefix.example.com.

Consider an example in which you have two scanner tools: one for security and one for compliance. Both tools use a scanned label or annotation. You can disambiguate between the two tools using a prefix. The security tool can prefix a label or annotation with security.example.com/scanned and the compliance tool can prefix a label or annotation with compliance.example.com/scanned.

cf CLI Procedures

The following sections describe how to add, update, view, and list metadata using the cf CLI.

Note: At the time of public beta, cf7 beta CLI supports adding labels to apps, orgs, and spaces.

Add Metadata to a Resource

This section describes how to add metadata using the cf CLI.

Add a Label

The following procedure describes how to add a label using the cf7 CLI:

  1. To add a label to an resource, run the following command:

    cf7 set-label RESOURCE RESOURCE-NAME KEY=VALUE
    

    Where:

    • RESOURCE is the type of resource you want to label, such as app or space
    • RESOURCE-NAME is the name of the resource you want to label, such as my-app
    • KEY is the key for the label
    • VALUE is the corresponding value for the label key. You can enter multiple key-value pairs in the same command.

    For example, the following command labels an app as "environment": "production".

    $ cf set-label app my-app environment=production

Update Metadata for a Resource

To update metadata for a resource, follow the procedure for adding metadata and provide a new value for an existing key. See Add Metadata to a Resource above.

Remove Metadata from a Resource

This section describes how to remove metadata using the cf CLI.

Remove a Label

The following procedure describes how to remove a label using the cf CLI:

  1. To remove a label from a resource, run the following command:

    cf7 unset-label RESOURCE RESOURCE-NAME KEY
    

    Where:

    • RESOURCE is the type of resource you want to remove the label from, such as app or space
    • RESOURCE-NAME is the name of the resource you want to remove the label from , such as my-app
    • KEY is the key for the label

    For example, the following command removes the labels "environment": "production" from an app.

    $ cf7 unset-label app my-app environment

View Metadata for a Resource

This section describes how to view metadata with the cf CLI.

View Labels

To view labels, run the following command:

  1. To view labels for a resource, run the following command:

    cf7 labels RESOURCE RESOURCE-NAME
    

    Where:

    • RESOURCE is the type of resource you want to remove the label from, such as app or space
    • RESOURCE-NAME is the name of the resource you want to remove the label from , such as my-app

    For example, the following command lists labels for an app.

    $ cf7 labels app my-app

    Getting labels for app my-app as admin in org my-org…

    Key Value ci_signature_sha2 104cf30d754 env staging

API Procedures

The following sections describe how to add, update, remove, list, and query metadata using CAPI.

Add Metadata to a Resource

The sections below describe how to add labels and annotations to resources.

Add a Label

The following procedure describes how to add a label using CAPI:

  1. To add a label to an resource, run the following command:

    cf curl v3/RESOURCE-ENDPOINT/GUID \
      -X PATCH \
      -d '{
        "metadata": {
          "labels": {
            "LABEL-KEY": "LABEL-VALUE" 
          }
        }
      }'
    

    Where:

    • RESOURCE-ENDPOINT is the CAPI endpoint for the type of resource you want to label, such as apps or organizations
    • GUID is the GUID of the resource you want to label
    • LABEL-KEY is the key for the label
    • LABEL-VALUE is the corresponding value for the label key

    For example, the following command labels an app as "environment": "production".

    $ cf curl v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 \
      -X PATCH \
      -d '{
        "metadata": {
          "labels": {
            "environment": "production" 
          }
        }
      }'
    

Add an Annotation

The following procedure describes how to add an annotation:

  1. To add an annotation to an resource, run the following command:

    cf curl v3/RESOURCE-ENDPOINT/GUID \
      -X PATCH \
      -d '{
        "metadata": {
          "annotations": {
            "ANNOTATION-KEY": "ANNOTATION-VALUE" 
          }
        }
      }'
    

    Where:

    • RESOURCE-ENDPOINT is the CAPI endpoint for the type of resource you want to label, such as apps or organizations
    • GUID is the GUID of the resource you want to label
    • ANNOTATION-KEY is the key for the label
    • ANNOTATION-VALUE is the corresponding value for the annotation key

    For example, the following command provides a contacts annotation for an app.

    $ cf curl v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 \
      -X PATCH \
      -d '{
        "metadata": {
          "annotations": {
            "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)" 
          }
        }
      }'
    

Update Metadata for a Resource

To update metadata for a resource, follow the procedure for adding metadata and provide a new value for an existing key. See Add Metadata to a Resource above.

Remove Metadata from a Resource

To remove metadata from a resource, follow the procedure for adding metadata and provide a null value for an existing key. See Add Metadata to a Resource above.

View Metadata for a Resource

The following procedure describes how to view metadata:

  1. To view metadata using the list endpoint of a resource, run the following command:

    cf curl /v3/RESOURCE-ENDPOINT/GUID
    

    Where:

    • RESOURCE-ENDPOINT is the CAPI endpoint for the type of resource you want to view, such as apps or organizations
    • GUID is the GUID of the resource you want to view

    For example:

    $ cf curl /v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446
    
    {
      "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
      "name": "my_app",
      "state": "STOPPED",
      "created_at": "2016-03-17T21:41:30Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": ["java_buildpack"],
          "stack": "cflinuxfs3"
        }
      },
      "relationships": {
        "space": {
          "data": {
            "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
          }
        }
      },
      "links": {
            . . . 
        }
      },
      "metadata": {
        "labels": {
          "environment": "production"
        },
        "annotations": {
          "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)"
        }
      }
    }
    

List Resources by Querying Labels

The following procedure describes how to list resources by querying label metadata:

  1. To query a resource by using the label_selector parameter on its list endpoint, run the following command:

    cf curl /v3/RESOURCE-ENDPOINT/?label_selector=SELECTOR-REQUIREMENTS
    

    Where:

    • RESOURCE-ENDPOINT is the CAPI endpoint for the type of resource you want to view, such as apps or organizations
    • SELECTOR-REQUIREMENTS is one of requirement types specified in Selector Requirement Reference below. You can add multiple selector requirements using a comma-separated list.

      Note: Ensure that this part of the URL is appropriately escaped.

    For example, the following command selects all apps tagged with a label that has a key environment and value production.

    $ cf curl /v3/apps/?label_selector=environment=production
    

Selector Requirement Reference

The following table describes how to form selector requirements:

Requirement Format Description
existence KEY Returns all resources labeled with the given key
existence !KEY Returns all resources not labeled with the given key
equality KEY==VALUE or KEY=VALUE Returns all resources labeled with the given key and value
inequality KEY!=VALUE Returns all resources not labeled with the given key and value
set inclusion KEY in (VALUE1,VALUE2...) Returns all resources labeled with the given key and one of the specified values
set inclusion KEY notin (VALUE1,VALUE2...) Returns all resources not labeled with the given key and one of the specified values

Example: Label Resources with a Git Commit

This section provides the following:

Labeling your app and related resources with a Git commit SHA allows you to track which version of your code is running on PAS.

For more information about app packages and droplets, see the CAPI documentation.

Manually Label Resources

To label an app, droplet, and package with a Git commit SHA, do the following:

  1. Log in to the Cloud Foundry Command Line Interface (cf CLI).
  2. Run the following command and record the app GUID:

    cf app APP_NAME --guid
    

    Where APP_NAME is the name of the app.

  3. Run the following command to return the GUID of the droplet and package associated with the app:

    cf curl /v3/apps/APP_GUID/droplets/current
    

    Where APP_GUID is the GUID of the app.

  4. Record the GUID of the droplet and package:

    • The droplet GUID is the value for the "guid" key.
    • The package GUID is the end of the "href" URL for the "package" key.

    For example, the droplet and package GUIDs are highlighted in blue in the following output:

    {
      "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
      ...
      "links": {
        "package": {
          "href": "https://api.run.pivotal.io/v3/packages/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
        }
      }    
    
  5. Run the following command to label the app with a Git commit SHA:

    cf curl /v3/apps/APP_GUID -X PATCH -d '{"metadata": { "labels": { "commit": COMMIT_SHA } } }'
    

    Where:

    • APP_GUID is the GUID of the app.
    • COMMIT_SHA is the SHA of the Git commit.
  6. Run the following command to label the app droplet with the same Git commit SHA:

    cf curl /v3/droplets/DROPLET_GUID -X PATCH -d '{"metadata": { "labels": { "commit": COMMIT_SHA } } }'
    

    Where:

    • DROPLET_GUID is the GUID of the droplet.
    • COMMIT_SHA is the SHA of the Git commit.
  7. Run the following command to label the app package with the same Git commit SHA:

    cf curl /v3/packages/PACKAGE_GUID -X PATCH -d '{"metadata": { "labels": { "commit": COMMIT_SHA } } }'
    

    Where:

    • PACKAGE_GUID is the GUID of the package.
    • COMMIT_SHA is the SHA of the Git commit.

Automate Labeling Resources

You can automate labeling resources by running a script either programatically or manually in the app repository.

Prerequisite

To run the following example script, you must install jq. To download jq, see jq.

Example Script

The following script retrieves the GUID of the app, droplet, and package. It then curls CAPI to label each resource with the current Git commit SHA.

Replace APP-NAME with the name of your app.

#!/usr/bin/env bash

set -ex

APP_GUID="$(cf app APP-NAME --guid)"
APP_URI="/v3/apps/${APP_GUID}"

DROPLET_GUID="$(cf curl "/v3/apps/${APP_GUID}/droplets/current" | jq -r .guid)"
DROPLET_URI="/v3/droplets/${DROPLET_GUID}"

PACKAGE_GUID="$(cf curl "/v3/droplets/${DROPLET_GUID}" | jq -r .links.package.href | xargs basename)"
PACKAGE_URI="/v3/packages/${PACKAGE_GUID}"

COMMIT_SHA="$(git rev-parse --short HEAD)"
REQUEST_BODY="$(jq -nc --arg commit "${COMMIT_SHA}" '{"metadata": { "labels": { "commit": $commit } } }')"

cf curl "${APP_URI}" -X PATCH -d "${REQUEST_BODY}"
cf curl "${PACKAGE_URI}" -X PATCH -d "${REQUEST_BODY}"
cf curl "${DROPLET_URI}" -X PATCH -d "${REQUEST_BODY}"