Configuring app deployments

Page last updated:

This page describes how to use the Cloud Foundry Command Line Interface (cf CLI) or API (CAPI) to push apps to Cloud Foundry using rolling deployment or canary deployment strategies, which update apps safely and avoid downtime.

For information about the older method for avoiding app downtime while pushing app updates, see Using blue-green deployment to reduce downtime and risk.

For more information about CAPI, see the Cloud Foundry API (CAPI) documentation.

Prerequisites

The procedures in this topic require one of the following:

• cf CLI v7 or later

• CAPI V3: If you use CAPI V3 API, you must install the cf CLI.

Or for canary deployments:

• cf CLI v8.8.0 or later

• CAPI V3.173.0 or later

How Deployment Strategies Work

Cloud Foundry provides two different strategies for deployments:

• A Rolling deployment brings up one or more web processes for the new app version, with the number set by max-in-flight, which defaults to 1. After those instances report as healthy and routable, it brings down the same number of instances of the old version. The deployment repeats this process to replace all web process instances and then updates all old non-web processes.
• A Canary deployment brings up one or more web processes for the new app version, defaulting to one. It then pauses to let app operators or developers evaluate the health of a new version instances. App operators can then choose to either cancel or continue the deployment. When the deployment is continued, the canary deployment proceeds in the same way as a rolling deployment.
  • To gradually increase instance counts and check app health in multiple steps, the latest cf CLI v8 supports an --instance-steps option that sets a series of increasing instance counts.

Each rolling or canary deployment increments the revision count for the new app deployment, as listed by the cf revisions command described in [] described in xxyx

The following sections describe the rolling and canary deployment strategies and their limitations.

Rolling Deployments

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

1. The cf push APP-NAME --strategy rolling command:

   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 up to max_in_flight processes that shares the route with the old process.
      • If you run cf app on your app at this point, you see multiple web processes.
        For more information about the deployment object, see the Deployments section of the CAPI V3 documentation.

2. After the command creates the deployment, the cc_deployment_updater BOSH job runs in the background, updating deployments as follows:

   1. Adds up to max_in_flight instances of the new web process and removes instances from the old web process. This step repeats until the new web process reaches the required number of instances.

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

   2. Removes the old web process. The new web process now fully replaces the old web process.
   3. Restarts all non-web processes of the app.
   4. Sets the deployment to DEPLOYED.

Canary Deployments

This section describes pushing an app with the default canary deployment strategy, without specifying specific step weights as described in Canary Deployments with Step Weights.

1. The cf push APP-NAME --strategy canary command:

   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.
      For more information about the deployment object, see the Deployments section of the CAPI V3 documentation.

2. After the command creates the deployment, the cc_deployment_updater BOSH job runs in the background, updating deployments as follows:

   1. Adds one instance of the new web process (the canary instance).
      • This process shares routes with the old process.
      • If you run cf app on your app at this point, you see multiple web processes.
   2. Sets the deployment to PAUSED.

3. After validating that the canary instance is running as expected, execute the command cf continue-deployment APP-NAME:

   • Changes the deployment reason to DEPLOYING and resumes following the same process as a rolling deployment.

4. After the command changes the status of the deployment, the cc_deployment_updater BOSH job runs in the background, updating deployments as follows:

   1. Adds MaxInFlight number of instances (by default it is 1) of the new web process and removes MaxInFlight number of instance from the old web process. This step repeats until the new web process reaches the required number of instances.

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

   2. Removes the old web process. The new web process now fully replaces the old web process.
   3. Restarts all non-web processes of the app.
   4. Sets the deployment to DEPLOYED.

Canary Deployments with Step Weights

By default, as described in Canary Deployments, when you push an app with the canary deployment strategy, the process pauses after it deploys one canary instance, and you manually continue as described in Continue a canary deployment to update the remaining instances to the full-scale deployment.

To run a canary deployment more gradually, you can pass a series of step weights to the --instance-steps option of cf push.

• The series specifies increasing numbers of canary instances to deploy, to let you manually continue after each step.
• Separate step weights with commas and without spaces, for example 5,10,20.
• Continuing after the last canary step proceeds to the full-scale deployment.
• As with the default canary deployment process, a rolling deployment strategy updates instances to the new instance count at each step.

For example, to update gradually in four steps, running 5, 10, and 20 canary instances before replacing all running instances of an app:

  cf push APP-NAME --strategy canary --instance-steps 5,10,20

Limitations

The following table describes the limitations when using these deployments.

Commands

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

Deploy an app

To deploy an app without incurring downtime:

For cf CLI v7+

Run:

cf push APP-NAME --strategy rolling

Where APP-NAME is the name that you want to give your app.

Review the limitations of this feature before running the command. For more information, see Limitations.

cf CLI v7 exits when one instance of each process is healthy. It also includes a --no-wait flag for users who don’t want to wait for the operation to complete. When cf push is used with the --no-wait flag, the process exits as soon as one instance is healthy.

If the deployment stops and doesn’t restart, cancel it and run it again as described in an earlier step. To cancel, see Cancel a deployment.

For cf CLI v8.8.0+ and CAPI V3.173.0 or later

Run:

cf push APP-NAME --strategy STRATEGY --max-in-flight MAX_IN_FLIGHT

Where:

• APP-NAME is the name that you want to give your app.
• MAX_IN_FLIGHT specifies the maximum number of new instances to start up simultaneously until the deployment is complete. This parameter is optional and defaults to 1.
• STRATEGY is the strategy you want to use for the deployment. Valid strategies are rolling and canary.

For CAPI V3

1. Log in to the cf CLI.

   cf login
   

2. Create an empty app by running the following curl command with POST /v3/apps.
   Record the app GUID from the output.

   cf curl /v3/apps \
     -X POST \
     -H "Content-type: application/json" \
     -d '{
       "name": "APP-NAME",
       "relationships": {
         "space": {
           "data": {
             "guid": "SPACE-GUID"
           }
         }
       }
     }'
   

   Where:

   • APP-NAME is the name that you want to give your app.
   • SPACE-GUID is the space identifier that you want to associate with your app.

3. Create a package with the following curl command with POST /v3/packages. Record the package GUID from the output.

   cf curl /v3/packages \
     -X POST \
     -H "Content-type: application/json" \
     -d '{
       "type": "bits",
       "relationships": {
         "app": {
           "data": {
             "guid": "APP-GUID"
           }
         }
       }
     }'
   

   Where APP-GUID is the app GUID that you recorded in an earlier step. This app GUID is a unique identifier for your app.

4. Upload the package bits by running the following curl command with POST /v3/packages/PACKAGE-GUID/upload.

   cf curl /v3/packages/PACKAGE-GUID/upload \
   -X POST \
   -F bits=@"PACKAGED-APP" \
   

   Where:

   • PACKAGE-GUID is the package GUID that you recorded in an earlier step.
   • PACKAGED-APP is your app packaged in a file such as .zip.

5. Create the build by running the following curl command with POST /v3/builds. Record the droplet GUID from the output.

   cf curl /v3/builds \
     -X POST \
     -H "Content-type: application/json" \
     -d '{
       "package": {
         "guid": PACKAGE-GUID"
       }
     }'
   

   Where PACKAGE-GUID is the package GUID that you recorded in an earlier step.

6. Deploy your app by running the following curl command with POST /v3/deployments. To verify the status of the deployment or take action on the deployment, record the deployment GUID from the output.

   cf curl /v3/deployments \
   -X POST \
   -H "Content-type: application/json" \
   -d '{
     "droplet": {
       "guid": "DROPLET-GUID"
     },
     "strategy": STRATEGY,
     "options": {
       "max_in_flight": MAX_IN_FLIGHT
     },
     "relationships": {
       "app": {
         "data": {
           "guid": "APP-GUID"
         }
       }
     }
   }'
   

   Where:

   • DROPLET-GUID and APP-GUID are the GUIDs that you recorded in earlier steps.
   • MAX_IN_FLIGHT is an integer that specifies the maximum number of new instances to start up simultaneously until the deployment is complete. Optional and defaults to 1.
   • STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

For more information about this command, see How Deployment Strategies Work.

Cancel a deployment

To stop the deployment of an app that you pushed:

• For cf CLI v7+, run:

  cf cancel-deployment APP-NAME
  

  Where APP-NAME is the name of the app.

• For CAPI V3, run:

  cf curl /v3/deployments/DEPLOYMENT-GUID/actions/cancel" -X POST
  

  Where DEPLOYMENT-GUID is the GUID of the deployment that you recorded after following the CAPI procedure in Deploy an app.

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

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

The cancel command is designed to revert the app to its original state as quickly as possible and does not guarantee zero downtime.
It is important to note that changes to environment variables and service bindings are not reverted.

Continue a canary deployment

To finish a canary deployment after the deployment has paused and the canary instance has been validated:

• For cf CLI v8+, run:

  cf continue-deployment APP-NAME
  

  Where APP-NAME is the name of the app.

• For CAPI V3, run:

  cf curl /v3/deployments/DEPLOYMENT-GUID/actions/continue" -X POST
  

  Where DEPLOYMENT-GUID is the GUID of the deployment that you recorded after following the CAPI procedure in Deploy an app.

This continues the deployment of the app, following the same process as a rolling deployment.

Restart an app

Restart your app to apply configuration updates that require a restart, such as environment variables or service bindings.

To restart your app without downtime, run the appropriate command as shown here.

• For cf CLI v7+, run:

  cf restart APP-NAME --strategy STRATEGY
  

  Where:

  • APP-NAME is the name of the app.
  • STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

• For cf CLI v8.8.0+ and CAPI V3.173.0 or later, run:

  cf restart APP-NAME --strategy STRATEGY --max-in-flight MAX_IN_FLIGHT
  

  Where:

  • APP-NAME is the name of the app.
  • MAX_IN_FLIGHT specifies the maximum number of new instances to restart simultaneous until the deployment is complete. Optional and defaults to 1.
  • STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

• For CAPI V3, run:

  cf curl /v3/deployments \
  -X POST \
  -H "Content-type: application/json" \
  -d '{
    "droplet": {
      "guid": DROPLET-GUID
    },
    "strategy": STRATEGY,
    "options": {
      "max_in_flight": MAX_IN_FLIGHT
    },
    "relationships": {
      "app": {
        "data": {
          "guid": APP-GUID
        }
      }
    }
  }'
  

  Where:

  • DROPLET-GUID and APP-GUID are the GUIDs that you recorded in earlier steps.
  • MAX_IN_FLIGH is an integer that specifies the maximum number of new instances to start up simultaneous until the deployment is complete. Optional and defaults to 1.
  • STRATEGY is the strategy you would like to use for the deployment. Valid strategies are rolling and canary.

View the status of deployments

You can use CAPI to view the status of deployments.

To view the status of a deployment:

1. Log in to the cf CLI:

   cf login
   

2. Find the GUID of your app by running:

   cf app APP-NAME --guid
   

   Where APP-NAME is the name of the app.

3. Find the deployment for that app by running:

   cf curl GET /v3/deployments?app_guids=APP-GUID&status_values=ACTIVE
   

   Where APP-GUID is the GUID of the app. Deployments are listed in chronological order, with the latest deployment displayed as the last in the list.

4. Run:

   cf curl GET /v3/deployments/DEPLOYMENT-GUID
   

   Where DEPLOYMENT-GUID is the GUID of the deployment.

The cf curl GET /v3/deployments/DEPLOYMENT-GUID command returns the following status properties:

• status.value: Indicates if the deployment is ACTIVE or FINALIZED.

• status.reason: Provides detail about the deployment status.

• status.details: Provides the timestamp for the most recent successful health check. The value of the status.details property can be nil with no successful health check for the deployment. For example, there might be no successful health check if the deployment was cancelled.

The following table describes the possible values for the status.value and status.reason properties: