Configuring app deployments
Page last updated:
You can use Cloud Foundry Command Line Interface (cf CLI) commands or the Cloud Foundry API (CAPI) to push your apps to Cloud Foundry using a 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.
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:
- Rolling deployments bring up one or more web processes (as defined by
max-in-flight
) at a time. After those instances report healthy and routable, the deployment brings down an equivalent number instances of the old revision. The deployment repeats this process until all instances have been replaced, and finally replaces all old non-web processes with new processes before finishing. - Canary deployments bring up a single web process of the new revision, then pause indefinitely. This gives time for app operators or developers to evaluate the health of a new revision. After evaluating the effects, app operators can choose to either
cancel
orcontinue
the deployment. When the deployment is continued, the canary deployment proceeds in a way similar to a rolling deployment.
The following sections describe these deployment strategies and their limitations in detail.
Rolling Deployments
This section describes pushing an app with the rolling deployment strategy.
The
cf push APP-NAME --strategy rolling
command:- Stages the updated app package.
- Creates a droplet with the updated app package.
- 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 multipleweb
processes.
For more information about the deployment object, see the Deployments section of the CAPI V3 documentation.
- This starts up to
After the command creates the deployment, the
cc_deployment_updater
BOSH job runs in the background, updating deployments as follows:- 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.
- Removes the old web process. The new web process now fully replaces the old web process.
- Restarts all non-web processes of the app.
- Sets the deployment to
DEPLOYED
.
- Adds up to
Canary Deployments
This section describes pushing an app with the canary deployment strategy.
The
cf push APP-NAME --strategy canary
command:- Stages the updated app package.
- Creates a droplet with the updated app package.
- 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.
After the command creates the deployment, the
cc_deployment_updater
BOSH job runs in the background, updating deployments as follows:- 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 multipleweb
processes.
- Sets the deployment to
PAUSED
.
- Adds one instance of the new web process (the
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 in a way similar to a that of a rolling deployment.
- Changes the deployment reason to
After the command changes the status of the deployment, the
cc_deployment_updater
BOSH job runs in the background, updating deployments as follows:- 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.
- Removes the old web process. The new web process now fully replaces the old web process.
- Restarts all non-web processes of the app.
- Sets the deployment to
DEPLOYED
.
- 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.
Limitations
The following table describes the limitations when using these deployments.
Limitation | Description |
---|---|
Multiple app versions | During a deployment, Cloud Foundry serves both the old and new version of your app at the same route. This can lead to user issues if you push API changes that are not backwards-compatible. |
Database migrations | Deployments do not handle database migrations. Migrating an app database when the existing app is not compatible with the migration can result in downtime. |
Non-web processes | Deployments only run web processes through the update sequence described
earlier. 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 Processes in the CAPI V3 documentation. |
Quotas | Pushing updates to your app using a deployment strategy creates up to max_in_flight new instances (defaults to 1).
Additionally, canary deployments use an extra instance when pausing with the canary instance deployed.
If you lack sufficient quota, the deployment fails. Administrators might need to increase quotas to accommodate deployments. |
Simultaneous apps when interrupting a push | If you push an app before your previous push command for the same app has completed, your first push gets interrupted. Until the last deployment completes, there might be many versions of the app running at the same time. Eventually, the app runs the code from your most recent push. |
V3 APIs | During a rolling deploy for an app, requests to the V3 APIs for scaling or updating a process fail with an error message
like Cannot scale this process while a deployment is in flight . For more information, see Scale a process
or Update a process in the CAPI V3 documentation. |
New or stopped applications | When pushing an application for the first time, or if the app is stopped, no deployment strategy is used and all application instances are started immediately. |
Evaluating the canary instance |
Because the current processes share the same route, the best way to validate that traffic is reaching the canary instance is by looking at the logs.
If app revision logging is enabled, the logs for all instances will be tagged with process_id and revision_version values. e.g. APP/REV/4/PROC/WEB/1
Retrieve the logs by running the cf CLI command cf logs APP_NAME .
|
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 arerolling
andcanary
.
For CAPI V3
Log in to the cf CLI.
cf login
Create an empty app by running the following
curl
command withPOST /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.
Create a package with the following
curl
command withPOST /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.Upload the package bits by running the following
curl
command withPOST /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
.
Create the build by running the following
curl
command withPOST /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.Deploy your app by running the following
curl
command withPOST /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
andAPP-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 arerolling
andcanary
.
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 rolling deployment of the app.
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 arerolling
andcanary
.
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 arerolling
andcanary
.
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
andAPP-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 arerolling
andcanary
.
View the status of deployments
You can use CAPI to view the status of deployments.
To view the status of a deployment:
Log in to the cf CLI:
cf login
Find the GUID of your app by running:
cf app APP-NAME --guid
Where
APP-NAME
is the name of the app.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.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 isACTIVE
orFINALIZED
.status.reason
: Provides detail about the deployment status.status.details
: Provides the timestamp for the most recent successful health check. The value of thestatus.details
property can benil
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:
status.value | status.reason | Description |
---|---|---|
ACTIVE |
DEPLOYING |
The deployment is deploying. |
ACTIVE |
PAUSED |
The deployment is paused waiting for the user to continue with the deployment. Used only for canary Deployments. |
ACTIVE |
CANCELLING |
The deployment is cancelling. |
FINALIZED |
DEPLOYED |
The deployment is complete. |
FINALIZED |
CANCELLED |
The deployment was cancelled. |
FINALIZED |
SUPERSEDED |
The deployment was stopped and did not finish deploying because another deployment was created for the app. |