Using Metadata

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.5 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

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

About Metadata

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

For example, you can tag objects 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.

The full list of objects to which you can add metadata using the Cloud Foundry API includes:

• Apps
• Builds
• Buildpacks
• Deployments
• Droplets
• Isolation Segments
• Orgs
• Packages
• Processes
• Spaces
• Stacks
• Tasks
• Revisions

You can add metadata to apps and spaces using Apps Manager. For more information about adding metadata to apps using Apps Manager, see Managing Apps and Service Instances Using Apps Manager. For more information about adding metadata to spaces using Apps Manager, see Managing Orgs and Spaces Using Apps Manager

Types of Metadata

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

• Labels: Labels allow you to identify and select PAS objects. 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 objects. 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 object, 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:

Requirements for Annotations

The following table describes the requirements for creating annotations:

Label Prefixes

You can ensure a label key is easily differentiated from other keys by using a prefix. A prefix is a namespacing pattern that helps you more clearly identify objects. Prefixes are in DNS subdomain format. For example, 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. You can disambiguate between the two tools using a prefix. The security tool can prefix a label with security.example.com/scanned and the compliance tool can prefix a label with compliance.example.com/scanned.

Add Metadata to an Object

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

Add a Label

To add a label to an object:

1. Run:

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

   Where:

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

Add an Annotation

To add an annotation:

1. Run:

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

   Where:

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

Update Metadata for an Object

To update metadata for an object, follow the procedure for adding metadata and provide a new value for an existing key. For more information, see Add Metadata to an Object.

Remove Metadata from an Object

To remove metadata from an object, follow the procedure for adding metadata and provide a null value for an existing key. For more information, see Add Metadata to an Object.

View Metadata for an Object

To view metadata using the list endpoint of a resource:

1. Run:

   cf curl /v3/OBJECT-ENDPOINT/GUID
   

   Where:

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

List Objects by Querying Labels

To list resources by querying label metadata:

1. Run:

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

   Where:

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

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

Selector Requirement Reference

The following table describes how to form selector requirements:

Example: Label Objects with a Git Commit

This section provides:

• A procedure for labeling an app, package, and droplet with a Git commit SHA. For more information, see Manually Label Objects.

• A script that automates the procedure. For more information, see Automate Labeling Objects.

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 Objects

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

1. Run:

   cf app APP-NAME --guid
   

   Where APP-NAME is the name of the app.

2. Record the app GUID you retrieved in the previous step,

3. Return the GUID of the droplet and package associated with the app by running:

   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. Label the app with a Git commit SHA by running:

   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. Label the app droplet with the same Git commit SHA by running:

   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. Label the app package with the same Git commit SHA by running:

   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 Objects

You can automate labeling objects by running a script either programmatically 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}"