Using Metadata

This topic describes metadata in Cloud Foundry (Cloud Foundry) and provides instructions for adding, updating, removing, and viewing metadata.

For additional information about metadata, see the Metadata section in the Cloud Foundry API documentation.

About Metadata

Cloud Foundry allows you to add metadata to objects such as orgs, spaces, and apps. You can use metadata to provide additional information about the objects in your Cloud Foundry 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.

Types of Metadata

You can add two types of metadata to objects in Cloud Foundry:

  • Labels: Labels allow you to identify and select Cloud Foundry 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 Cloud Foundry 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.

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.

Annotation Requirements
Part of Annotation Length in characters
Key 1-1000
Value 0-5000

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

The following procedure describes how to add a label:

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

    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

    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 object, run the following command:

    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

    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 an Object

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

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. See Add Metadata to an Object above.

View Metadata for an Object

The following procedure describes how to view metadata:

  1. To view metadata using the list endpoint of an object, run the following command:

    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

    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 Objects by Querying Labels

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

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

    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 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
Create a pull request or raise an issue on the source for this page in GitHub