metadata.html.md.erb

---
title: Using Metadata
owner: CAPI
---

<style>
.guid {
  color: #5FABFF;
}
</style>


This topic describes metadata in <%= vars.product_full %> and provides instructions for adding, updating, removing, and viewing metadata. 

For additional information about adding metadata with the Cloud Foundry API (CAPI), see the _Metadata_ section in the [CAPI documentation](http://v3-apidocs.cloudfoundry.org). 

## <a id="about"></a> About Metadata

<%= vars.product_short %> 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 <%= vars.product_short %> 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. 

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

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

<%= vars.metadata_ref %>

### <a id="types"></a> Types of Metadata 

You can add two types of metadata to objects in <%= vars.product_short %>:

* **Labels:** Labels allow you to identify and select <%= vars.product_short %> 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 <%= vars.product_short %> 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. 


### <a id="reqs"></a> Metadata Requirements

The following tables describe requirements for creating metadata. 

#### <a id="reqs-labels"></a> Requirements for Labels

The following table describes the requirements for creating labels.

<table>
<tr>
	<th colspan="4" style="text-align: center">Label Requirements</th>
</tr>
<tr>
	<th>Part of Label</th>
	<th>Length in characters</th>
	<th>Allowed characters</th>
	<th>Other Requirements</th>
</tr>
<tr>
	<td>(Optional) Key Prefix</td>
	<td>0-253</td>
	<td>
		<ul>
			<li>Alphanumeric</li>
			<li><code>-</code></li>
			<li><code>.</code></li>
		</ul>
	<td>
		<ul>
			<li>DNS subdomain format, with at least one <code>.</code></li>
			<li>Must end with <code>/</code></li>
		</ul></td>	
</tr>
<tr>
	<td>Key Name</td>
	<td>1-63</td>
	<td><ul>
			<li>Alphanumeric</li>
			<li><code>-</code></li>
			<li><code>_</code></li>
			<li><code>.</code></li>
		</ul></td>
	<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
	<td>Value</td>
	<td>0-63</td>
	<td><ul><li>Alphanumeric</li>
			<li><code>-</code></li>
			<li><code>_</code></li>
			<li><code>.</code></li></ul></td>
	<td>
		<ul>
			<li>Must begin and end with an alphanumeric character</li>
			<li>Empty values allowed</li></td>
</tr>
</table>

#### <a id="reqs-annotations"></a> Requirements for Annotations

The following table describes the requirements for creating annotations.

<table>
<tr>
	<th colspan="4" style="text-align: center">Label Requirements</th>
</tr>
<tr>
	<th>Part of Annotation</th>
	<th>Length in characters</th>
	<th>Allowed characters</th>
	<th>Other Requirements</th>
</tr>
<tr>
	<td>(Optional) Key Prefix</td>
	<td>0-253</td>
	<td>
		<ul>
			<li>Alphanumeric</li>
			<li><code>-</code></li>
			<li><code>.</code></li>
		</ul>
	<td>
		<ul>
			<li>DNS subdomain format, with at least one <code>.</code></li>
			<li>Must end with <code>/</code></li>
		</ul></td>	
</tr>
<tr>
	<td>Key Name</td>
	<td>1-63</td>
	<td><ul>
			<li>Alphanumeric</li>
			<li><code>-</code></li>
			<li><code>_</code></li>
			<li><code>.</code></li>
		</ul></td>
	<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
	<td>Value</td>
	<td>0-5000</td>
	<td><i>n/a</i></td>
	<td><i>n/a</i></td>
</tr>
</table>
### <a id="prefix"></a> 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`.

## <a id="add"></a> Add Metadata to an Object

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

### <a id="label"></a> 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"`. 

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

### <a id="annotation"></a> 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. 

    <pre class="terminal">
    $ 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)" 
          }
        }
      }'
    </pre>

## <a id="update"></a> 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](#add) above. 

## <a id="remove"></a> 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](#add) above. 

## <a id="view"></a> 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:

    <pre class="terminal">
    $ 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)"
        }
      }
    }
    </pre>

## <a id="query"></a> 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](#requirements-reference) below. You can add multiple selector requirements using a comma-separated list. 
      <p class="note"><strong>Note</strong>: Ensure that this part of the URL is appropriately escaped.</p>

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

    <pre class="terminal">
    $ cf curl /v3/apps/?label_selector=environment=production
    </pre>

### <a id="requirements-reference"></a> Selector Requirement Reference

The following table describes how to form selector requirements: 

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

## <a id="example"></a> Example: Label Objects with a Git Commit

This section provides the following:

- A procedure for labeling an app, package, and droplet with a Git commit SHA. See [Manually Label Objects](#manual).
- A script that automates the procedure. See [Automate Labeling Objects](#example-script).

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](https://v3-apidocs.cloudfoundry.org/version/3.68.0/index.html).

### <a id="manual"></a> Manually Label Objects

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).
1. Run the following command and record the app GUID:

    ```
    cf app APP_NAME --guid
    ```
    Where `APP_NAME` is the name of the app.

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

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

    <pre class='terminal'>
    {
      "guid": "<span class='guid'>fd35633f-5c5c-4e4e-a5a9-0722c970a9d2</span>",
      ...
      "links": {
        "package": {
          "href": "https://api.run.pivotal.io/v3/packages/<span class='guid'>fd35633f-5c5c-4e4e-a5a9-0722c970a9d2</span>"
        }
      }    
    </pre>

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

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

### <a id="example-script"></a> Automate Labeling Objects

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

#### <a id="example-prerequisite"></a> Prerequisite

To run the following example script, you must install `jq`. To download `jq`, see [jq](https://stedolan.github.io/jq/).

#### <a id="script"></a> 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}"
```