metadata.html.md.erb

---
title: Using Metadata
owner: CAPI/CLI
---

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

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

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

### <a id="methods"></a> Methods of Adding Metadata

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

* **Cloud Foundry Command Line Interface (cf CLI) v7:** For procedures using this method of adding metadata, see [cf CLI Procedures](#cf-cli-procedures). For more information about cf CLI v7, see [Upgrading to cf CLI v7](../cf-cli/v7.html).

* **Cloud Foundry API (CAPI):** For procedures using this method of adding metadata, see [API Procedures](#api-procedures). For more information about adding metadata with CAPI, see [Metadata](http://v3-apidocs.cloudfoundry.org/version/3.78.0/index.html#metadata) in the CAPI documentation.

<%= vars.metadata_ref %>

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

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

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

#### <a id="annotations"></a> Annotations Sent to Service Brokers

For installations using CAPI v1.108.0 and later, <%= vars.app_runtime_abbr %> sends annotations with key prefixes to service brokers when service instances and service bindings are created.

When a service instance is created, <%= vars.app_runtime_abbr %> sends the following annotations to service brokers:

- `organization_annotations`
- `space_annotations`
- `instance_annotations`

When a service instance is bound to an app, <%= vars.app_runtime_abbr %> also sends `app_annotations` to service brokers.

For more information about the annotations listed above, see [Cloud Foundry Context Object](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md#cloud-foundry-context-object) in the Open Service Broker API Profile on GitHub.
For more general information about annotations, see [Annotations](https://v3-apidocs.cloudfoundry.org/#annotations) in the CAPI documentation.

### <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  ( \[a-z0-9A-Z\] )</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  ( \[a-z0-9A-Z\] )</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>
    </ul>
  </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">Annotation 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 ( \[a-z0-9A-Z\] )</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 ( \[a-z0-9A-Z\] )</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>Any unicode character</td>
	<td>N/A</td>
</tr>
</table>

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


## <a id="cf-cli-procedures"></a> cf CLI Procedures

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

<p class="note"><strong>Note:</strong> To see which resources are supported for this feature, run <code>cf labels -h</code>.
cf CLI v7 supports adding labels to apps, orgs, spaces, buildpacks, stacks, routes, domains, and various service resources.
</p>

### <a id="add-cli"></a> Add Metadata to a Resource

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

#### <a id="add-label-cli"></a> Add a Label

To add a label to a resource:

1. Run:

    ```
    cf 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 `example-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.

### <a id="update-cli"></a> 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. For more information, see [Add Metadata to a Resource](#add-cli) above.

### <a id="remove-cli"></a> Remove Metadata from a Resource

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

#### <a id="remove-label-cli"></a> Remove a Label

To remove a label from a resource:

1. Run:

    ```
    cf 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 `example-app`.
    * `KEY` is the key for the label.

### <a id="view-cli"></a> View Metadata for a Resource

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

#### <a id="view-label-cli"></a> View Labels

To view labels for a resource:

1. Run:

    ```
    cf 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 `example-app`.

#### <a id="select-resources-cli"></a> Select Resources by Labels

To select resources by labels:

1. Run:

    ```
    cf apps --labels 'environment in (production,staging),tier in (backend)'
    ```


## <a id="api-procedures"></a> API Procedures

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

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

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

#### <a id="add-label"></a> Add a Label

To add a label to a resource using CAPI:

1. Run:

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

#### <a id="annotation"></a> Add an Annotation

To add an annotation:

1. Run:

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

### <a id="update"></a> 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. For more information, see [Add Metadata to a Resource](#add) above.

### <a id="remove"></a> 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. For more information, see [Add Metadata to a Resource](#add) above.

### <a id="view"></a> View Metadata for a Resource

To view metadata using the list endpoint of a resource:

1. Run:

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

### <a id="query"></a> List Resources by Querying Labels

To list resources by querying label metadata:

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

    ```
    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](#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>

#### <a id="requirements-reference"></a> 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 |
| inexistence | `!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 exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |


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

This section provides the following:

* A procedure for labeling an app, package, and droplet with a Git commit SHA. For more information, see [Manually Label Resources](#manual) below.

* A script that automates the procedure. For more information, see [Automate Labeling Resources](#example-script) below.

Labeling your app and related resources with a Git commit SHA allows you to track which version of your code is running on <%= vars.app_runtime_abbr %>.

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 Resources

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.

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

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

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.
    <br>
    <br>
    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<span>:</span>//api.run.pivotal.io/v3/packages/<span class='guid'>fd35633f-5c5c-4e4e-a5a9-0722c970a9d2</span>"
        }
      }
    </pre>

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

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

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

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

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