Using Metadata to Label PAS App Resources with a git SHA

The CAPI Product Team

Introduction

The PAS 2.5 release added the ability to add metadata to a given resource. The metadata feature allows users to add both labels and annotations to their PAS resources. One interesting use case is to tag your app and related resources with a git commit SHA. This allows you to track which version of your code is running on PAS.

When you push an app to PAS, the files you push are stored in a resource called a package. Packages are an input into the staging process, along with buildpacks, the output of which is a droplet.

Tracking the version of your code through these various resources can be difficult, so it may help to label them.

 

Prerequisites

 

Adding Labels with the API

The first step is to get the git commit SHA:

git rev-parse --short HEAD

Then, we need to find the GUIDs of the resource we want to label. Here, we'll label the app, package, and droplet.

To get the app's GUID:

cf app appName --guid

The CLI does not yet support labels, so we'll have to access the API directly. Luckily, the CLI does include a curl command that takes care of authentication and targeting the appropriate API endpoint.

To get the GUID of the current droplet associated with the app:

cf curl "/v3/apps/${APP_GUID}/droplets/current" | jq -r .guid

Droplet are built from packages, so to get the package GUID associated with your droplet:

cf curl "/v3/droplets/${DROPLET_GUID}" | jq -r .links.package.href | xargs basename

To add a label to a resource, you must submit a PATCH request. All of the bodies will be the same for each resource, so we can construct it:

jq -nc --arg commit "${COMMIT_SHA}" '{"metadata": { "labels": { "commit": $commit } } }'

Then, PATCH against, say, the app:

cf curl /v3/apps/${APP_GUID} -X PATCH -d "${REQUEST_BODY}"

Once you have labeled the resources, you can then query the API using the label_selector query parameter. Here is an example of finding apps with the commit SHA:

cf curl "/v3/apps?label_selector=commit=${COMMIT_SHA}"

This should return all apps that have been tagged with our commit SHA. You can swap out apps for packages and droplets to see those tagged resources.

Here is a script that, when run from the repository of your app, will tag the app, droplet, and package with the commit SHA:

#!/usr/bin/env bash

# Run this from your app's git repo

set -ex

APP_GUID="$(cf app appName --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}"

# Get a short version of your git SHA
COMMIT_SHA="$(git rev-parse --short HEAD)"
REQUEST_BODY="$(jq -nc --arg commit "${COMMIT_SHA}" '{"metadata": { "labels": { "commit": $commit } } }')"

# Label the app, package, and droplet with the code's current commit SHA.
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}"

 

Viewing and editing labels in Pivotal Apps Manager

You can also view and edit app labels in Pivotal Apps Manager. In order to do this, you will want to navigate to your application page in Apps Manager. Your app's metadata is stored under the Settings tab.

If you already successfully ran the script from above, you will notice the commit label exists for the app. Apps Manager allows you to add, edit and remove metadata directly from the UI. Simply make your edits via the metadata text boxes or the JSON editor and hit the `Update Metadata` button. Your metadata will be saved to your app and will be accessible via Apps Manager or API.

Now you are ready to begin labeling your app, package and droplet resources with your git commit SHA to help you better understand what code is running on PAS.  This is just one use case for using metadata, but there are many more. We look forward to seeing how our users adopts this new feature

 

About the Author

The CAPI Product Team

The CAPI Product Team is a core component team for PAS and Cloud Foundry. The team’s core mission is to simplify the experience of running cloud applications at scale.

Previous
How to Become a Continuously Delivered Enterprise
How to Become a Continuously Delivered Enterprise

A continuously delivered enterprise can deliver new features to customers rapidly and securely. Here, we de...

Next
How Two Operators are Continuously Patching Pivotal Cloud Foundry
How Two Operators are Continuously Patching Pivotal Cloud Foundry

Learn how two Pivotal customers, Cerner and Wells Fargo, are staying secure.

SpringOne Platform 2019

Learn More