Cloud Foundry API app revisions

Page last updated:

A revision represents code and configuration used by an app at a specific time. It is a Cloud Foundry API (CAPI) object that can contain references to a droplet, a custom start command, and environment variables. The most recent revision for a running app represents code and configuration running in Cloud Foundry. App revisions do not include any tasks run on the app.

For additional information about app revisions, see Revisions in the Cloud Foundry API (CAPI) documentation.

CAPI v3 is the recommended API version for revisions. While revisions work with CAPI v2, there are several inconsistencies. For example, revision descriptions for apps with multiple processes can be inaccurate because CAPI v2 does not support apps with multiple processes. Additionally, pushing an app for the first time with revisions in CAPI v2 creates two revisions.

Overview

Every Cloud Foundry app has a name. When you first deploy an app, Cloud Foundry gives it the revision version number 1. When you re-deploy the app under the same name, for example as an update, Cloud Foundry increments its version number and saves the old version.

This saved application history is used by the revisions and revision CAPI endpoints and cf CLI commands to let you:

  • View revisions for an app: To help you understand how your app has changed over time.

  • Roll back to a previous revision: To deploy a version of the app that you had running previously without needing to track that previous state yourself or have multiple apps running. When roll back an app, the specified revision deploys as the new current version of your app.

Note The cf revision command takes a --version flag to specify a version number, but the command’s output lists the same number as its revision.

When current app revision changes

The app’s revision version number increments when:

  • A new droplet is deployed for an app.
  • An app is deployed with --strategy rolling or --strategy canary as described in Configuring app deployments.
  • An app is deployed with a new environment variables.
  • An app is deployed with a new or changed custom start command.
  • An app rolls back to a prior revision.
    • In this case, the newly-running version is identical to the specified old version.

By default, CAPI retains a maximum of 100 revisions per app.

Revision descriptions

Each revision includes a description of what changed in your app at the time the revision was created. The description includes one or more of these descriptions:

  • Process type removed
  • New process type added
  • Rolled back to revision X
  • Custom start command removed
  • Custom start command updated
  • Custom start command added
  • New environment variables deployed
  • New droplet deployed

Droplet storage considerations

By default, Cloud Foundry retains the five most recent staged droplets in its droplets bucket. This means that you can roll back to revisions as long as they are using one of those five droplets. Not all revisions include a change in droplet.

Operators can configure Cloud Foundry to retain more droplets if necessary using the systemblobstoreccdropletmaxstageddropletsstored property in the Cloud Foundry manifest.

View revisions

This section describes how to use CAPI endpoints for viewing revisions.

List revision history for an app

To list both current and stopped revisions for an app:

  • Using the revisions command:
  cf revisions APP-NAME

Where APP-NAME is the name of your app.

  • Using the curl command:

  1. Retrieve the GUID of the app by running:

    cf app APP-NAME --guid

    Where APP-NAME is the name of your app.

  2. Run:

    cf curl /v3/apps/GUID/revisions

    Where GUID is the GUID you retrieved in an earlier step.

Get an app’s current revision(s)

The current revision of an app is its currently-deployed, running revision, linked to started processes. There may be multiple currently running revisions during an active canary or rolling deployment. To list an app’s current revision(s):

  • Using the revision command:
  cf revision APP-NAME

Where APP-NAME is the name of your app.

  • Using the curl command

  1. Retrieve the GUID of the app by running:

    cf app APP-NAME --guid

    Where APP-NAME is the name of your app.

  2. Run:

    cf curl /v3/apps/GUID/revisions/deployed

    Where GUID is the GUID you retrieved in an earlier step.

When the current app is still deploying or is in a stopped state, the command output states, It is not possible to show which revision is currently deployed.

Retrieve a revision

To retrieve a revision:

  • Using the revision command:
  cf revision APP-NAME --version VERSION

Where APP-NAME is the name of your APP and VERSION is the revision version.

  • Using the curl command:
  1. Run:
  cf curl /v3/revisions/GUID

Where GUID is the GUID of the revision.

Roll back to a previous revision

To roll back to a previous revision:

  • Using the rollback command:
  cf rollback APP-NAME --version VERSION

Where APP-NAME is the name of your APP and VERSION is the revision version you want to rollback to.

  • Using curl command:

  1. Retrieve the GUID of the app:

    cf app APP-NAME --guid

    Where APP-NAME is the name of your app.

  2. Retrieve the GUID of the revision. See Retrieve a revision.

  3. Create a deployment using CAPI by running:

    cf curl v3/deployments \
-X POST \
-d '{
  "revision": {
    "guid": "REVISION-GUID"
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "APP-GUID"
      }
    }
  }
}'

    Where:

    • REVISION-GUID is the GUID of the revision.
    • APP-GUID is the GUID of the app.

Add metadata to a revision

To add metadata to a revision, see Add metadata to an object.

Deactivate revisions for an app

CAPI activates app revisions by default. To deactivate revisions for an app, you must manually turn them off.

To deactivate revisions for an app:

  1. Retrieve the GUID of the app by running:
  cf app APP-NAME --guid

Where APP-NAME is the name of your app.

  1. Run:
  cf curl /v3/apps/GUID/features/revisions -X PATCH -d '{ "enabled": false }'

Where GUID is the GUID you retrieved in an earlier step.

View the source for this page in GitHub