Rolling App Deployments

Note: This topic includes references to cf CLI v7 beta commands. Consider the following when using these commands:
  • cf CLI v7 beta and CAPI v3 are both in active development and subject to change.
  • cf CLI v7 beta is developed and tested against the latest CAPI release candidate.
  • cf CLI v7 beta does not yet use CAPI v3 for all commands. Some commands still use CAPI v2 during beta.
For more information, see Upgrading to cf CLI v7 (Beta).

This topic describes how developers use beta Cloud Foundry Command Line Interface (cf CLI) commands to push their apps using a rolling deployment.

For information about the traditional method for addressing app downtime while pushing app updates, see Using Blue-Green Deployment to Reduce Downtime and Risk.

Prerequisites

The procedures in this topic require the following:

  • cf CLI v7:
    • You must have the cf CLI v7. While in beta, cf CLI v7 is only tested against the latest CAPI release candidate.
  • cf CLI v6:
    • You must have cf CLI v6.40 or later.
    • The rolling deployment feature must be enabled for your installation.

Commands

This section describes the commands for working with rolling app deployments.

Deploy an App

To deploy an app without incurring downtime:

  • cf CLI v7:

    cf7 push APP-NAME --strategy rolling
    

    Note: cf CLI v7 exits when one instance of each process is healthy. It also includes a --no-wait flag on push for users who do not want to wait for the operation to complete. No wait exits as soon as one instance is healthy.

  • cf CLI v6:

    cf v3-zdt-push APP-NAME
    

    Warning: Ensure that you understand the limitations of this feature before running the command. For more information, see Limitations.

For more information about this command, see How It Works.

Cancel a Deployment

To stop the deployment of an app that you pushed:

  • cf7 CLI v7:

    cf7 cancel-deployment APP-NAME
    
  • cf CLI v6:

    cf v3-cancel-zdt-push APP-NAME
    

This reverts the app to its state from before the deployment started by doing the following:

  • Scaling up the original web process
  • Removing any deployment artifacts
  • Resetting the current_droplet on the app

Note: The cancel command is designed to revert the app to its original state as quickly as possible and does not guarantee zero downtime.

Restart an App

Restart your app without downtime using the command below. This is useful when applying configuration updates that require a restart, such as environment variables or service bindings.

  • cf CLI v7: cf7 restart APP-NAME --strategy rolling

  • cf CLI v6:

    cf v3-zdt-restart APP-NAME
    

How It Works

This section describes the rolling deployments and their limitations.

Rolling Deployment Process

This section describes the process of pushing an app with a rolling deployment strategy.

  1. The cf7 push APP-NAME --strategy rolling command does the following:

    1. Stages the updated app package
    2. Creates a droplet with the updated app package
    3. Creates a deployment with the new droplet and any new configuration.
      • This starts a new process with one instance that shares the route with the old process.
      • At this point, if you run cf app on your app, you see multiple web processes.
      • For more information about the deployment object, see the Deployments section of the CAPI v3 docs.
  2. Once the command creates the deployment, the cc_deployment_updater BOSH job runs in the background, updating deployments as follows:

    1. Adds another instance of the new web process and removes an instance from the old web process.

      Note: This only happens if all instances of the new web process are currently running.

    2. Repeats the above step until the new web process reaches the desired number of instances.
    3. Removes the old web process. The new web process now fully replaces the old web process.
    4. Restarts all non-web processes of the app.
    5. Sets the deployment to DEPLOYED.

Limitations

The following table describes the limitations to consider when using the rolling deployments.

Limitation Description
App Manifests The v3-zdt-push command does not support providing an app manifest with the -f flag. If you have a `manifest.yml` file in your app directory, it is ignored. The cf CLI v7 beta does not have this limitation. However, the cf CLI v7 beta does not support multi-app manifests.
SSH to app instances Pushing updates to your app with a v3-zdt command causes the new web process and app GUID to mismatch. cf ssh does not handle this scenario. You must use the cf v3-ssh command instead.

Note: This limitation only applies to cf CLI v6.

Multiple app versions During a deployment, Cloud Foundry serves both the old and new version of your app at the same route. This could lead to user issues if you push backwards-incompatible API changes.
Database migrations Deployments do not handle database migrations. If you are migrating an app database and the old app is not compatible with the migration, you may still have downtime.
Non-web processes Rolling deployments only run web processes through the rolling update sequence described above. The commands restart worker and other non-web processes in bulk after updating all web processes.

The CAPI v3 API introduces the concept of processes as runnable units of an app. Each app has a web process by default. You can specify additional processes with a procfile, and in some cases buildpacks create additional processes. For more information about processes, see the Processes section of the CAPI v3 documentation.
Quotas Pushing updates to your app using a rolling deployment strategy creates an extra instance of your app. If there is not enough quota available, the deployment does not work. Administrators may need to increase quotas to account for rolling deployments.
Simultaneous apps when interrupting a push If you push app before your previous push command for the same app has completed, your first push gets interrupted. Until the last deployment completes, there may be many versions of the app running at once. Eventually, the app runs the code from your most recent push.
Create a pull request or raise an issue on the source for this page in GitHub