4 - PCF Workflows and Deployments

Updated 1 day ago by Michael Cretzman

Workflows are the deployment steps that use the Harness PCF Services and Environments to deploy your PCF app to your target PCF space.

Workflow use different deployment methods, such as Basic, Canary, or Blue/Green. Workflows can involve a few steps or multiple phases each composed of several steps.

In this topic in the tutorial, you will build Canary and Blue/Green Workflows to deploy the applications described by your Harness Services to the infrastructure described by the PCF Environment.

Basic Deployment

A PCF Workflow performing a Basic deployment simply takes your Harness PCF Service and deploys it to your PCF Infrastructure Definition. Once the PCF app is set up in the Workflow using the App Setup command, you can resize the number of instances specified in the Service manifest.yml or App Setup command using the App Resize command.

Here is an example of a successful PCF Basic deployment:

Set up a PCF Basic Deployment

To set up a PCF Basic deployment, do the following:

  1. In your Harness Application, create your PCF Service, as described in 2 - Services for PCF.
  2. Create your PCF Infrastructure Definition, as described in 3 - PCF Environments.
  3. In your Harness Application, click Workflows.
  4. Click Add Workflow. The Workflow dialog appears.
  5. Name your Workflow, and then, in Workflow Type, select Basic Deployment.
  6. In Environment, select the Environment containing your target Infrastructure Definition.
  7. In Service, select the PCF Service you want to deploy.
  8. In Infrastructure Definition, select your target Infrastructure Definition.

When you are done, the dialog will look something like this:

Click Submit. The PCF Basic Workflow is created.

Next, we'll walk through the default steps in the Workflow.

App Setup

The App Setup command uses the manifest.yml in your Harness PCF Service to set up your app.

The Match running instances setting can be used after your first deployment to override the instances setting in the manifest.yml.

To add routes in addition to the routes defined in the Service manifest, select routes in Additional Routes.

For information on using the Use App Autoscaler Plugin settings, see App Autoscaler CLI Plugin.

App Resize

When you first create your PCF Workflow, the App Resize command is displayed as incomplete. Harness simply needs you to confirm or change the default number of desired instances, 100 Percent.

You can select to use a percentage of the number specified in your manifest.yml, or if you used the App Setup Match desired count with current running instances setting, the current number of running instances. You can also use a count to explicitly set the number of desired instances.

Click Advanced to see Desired Instances - Old Version. Here you can set the number of instances for the previous version of the app. By default, the app will downsize to the same number as the number of new app instances.

App Rollback

In Rollback Steps, you can see the App Rollback command.

There is nothing to set in this command. It is simply the command to rollback to the old version of the app in case of a deployment failure.

Deploy a PCF Basic Workflow

To deploy your PCF Basic Workflow, click Deploy.

Select the artifact for your new app and click Submit. The Workflow is deployed.

The App Setup command output shows your app was created successfully:

---------- Starting PCF App Setup Command

# Fetching all existing applications
# No Existing applications found

# Creating new Application
# Manifest File Content:
---
applications:
- name: ExampleForDoc__PCF__basic__Staging__0
memory: ((PCF_APP_MEMORY))
instances: 0
path: /home/ubuntu/harness-delegate/./repository/pcfartifacts/BY3yUoB7Q3ibJicbwmgn8Q/1573586245429SampleWebApp.war
random-route: true

# CF_HOME value: /home/ubuntu/harness-delegate/./repository/pcfartifacts/BY3yUoB7Q3ibJicbwmgn8Q
# Performing "login"
API endpoint: api.run.pivotal.io
Authenticating...
OK

Targeted org Harness
Targeted space AD00001863

API endpoint: https://api.run.pivotal.io (API version: 2.142.0)
User: john.doe@harness.io
Org: Harness
Space: AD00001863
# Login Successful
# Performing "cf push"
Pushing from manifest to org Harness / space AD00001863 as john.doe@harness.io...
Using manifest file /home/ubuntu/harness-delegate/./repository/pcfartifacts/BY3yUoB7Q3ibJicbwmgn8Q/ExampleForDoc__PCF__basic__Staging__0_1.yml
Getting app info...
Creating app with these attributes...
+ name: ExampleForDoc__PCF__basic__Staging__0
path: /home/ubuntu/harness-delegate/repository/pcfartifacts/BY3yUoB7Q3ibJicbwmgn8Q/1573586245429SampleWebApp.war
+ instances: 0
+ memory: 350M
routes:
+ examplefordocpcfbasicstaging0-zany-waterbuck.cfapps.io

Creating app ExampleForDoc__PCF__basic__Staging__0...
Mapping routes...
Comparing local files to remote cache...
Packaging files to upload...
Uploading files...
0 B / 4.70 KiB 0.00% 4.70 KiB / 4.70 KiB 100.00% 4.70 KiB / 4.70 KiB 100.00% 4.70 KiB / 4.70 KiB 100.00% 4.70 KiB / 4.70 KiB 100.00% 4.70 KiB / 4.70 KiB 100.00% 4.70 KiB / 4.70 KiB 100.00% 1s
Waiting for API to complete processing files...
...
There are no running instances of this process.

# Application created successfully
# App Details:
NAME: ExampleForDoc__PCF__basic__Staging__0
INSTANCE-COUNT: 0
ROUTES: [examplefordocpcfbasicstaging0-zany-waterbuck.cfapps.io]

---------- PCF Setup process completed successfully
# Deleting any temporary files created

Next, the App Resize command shows the app instances upsized to the new instance count, in our example, 1.

---------- Starting PCF Resize Command
# Downsizing previous application version/s
# No Application is available for downsize
# Upsizing new application:
APPLICATION-NAME: ExampleForDoc__PCF__basic__Staging__0
CURRENT-INSTANCE-COUNT: 0
DESIRED-INSTANCE-COUNT: 1
# Application upsized successfully

# Application state details after upsize:
NAME: ExampleForDoc__PCF__basic__Staging__0
INSTANCE-COUNT: 1
ROUTES: [examplefordocpcfbasicstaging0-zany-waterbuck.cfapps.io]

Instance Details:
Index: 0
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0
--------- PCF Resize completed successfully

You PCF Basic Workflow is complete.

PCF Versioning and Rollback

As you can see the app name is ExampleForDoc__PCF__basic__Staging__0, and it has a suffix __0. The suffix identifies the version of the app. The next time this app is deployed the suffix will increase to __1.

You cannot disable the versioning suffix because it is used to identify the version of the app and perform rollbacks to previous versions, if needed.

Canary Deployments

PCF Canary deployments contain two or more phases that deploy app instances gradually, ensuring the stability of a small percentage of instances before rolling out to your desired instance count.

Here is an example of a successful PCF Canary deployment containing two phases:

Set up a PCF Canary Deployment

To explain PCF Canary Workflow steps and settings, we will create a Canary Workflow that deploys a new app to 50% of instances and, if it is successful, deploys it to 100% of instances.

The Canary Workflow will contains two phases:

  1. Phase 1:
    1. App Setup command: 6 instances set up. The number of instances defined in the manifest.yml via the vars.yml variable value for instances:
    2. App Resize command: 50% desired instances. This ensures that the app deploys on a small number of instances before moving on to Phase 2.
  2. Phase 2:
    1. App Resize command: 100% of instances.

To implement this Canary workflow, do the following:

  1. In your Harness application, click Workflows. The Workflows page appears.
  2. Click Add Workflow. The Workflow dialog appears.
  3. In Name, enter a name that describes what the Workflow does. For example, for a simple Canary deployment, Canary PCF.
  4. In Workflow Type, select Canary Deployment.
  5. In Environment, select the Environment containing the Infrastructure Definition for the target space where you will deploy your PCF app.
  6. When the Workflow dialog is finished, click SUBMIT. The PCF Canary Workflow appears.

First, we will set up Phase 1, where we will deploy 50% of the 6 instances defined in our Service's Manifests section.

To configure the Canary phases, do the following:

  1. In the Workflow, in Deployment Phases, click Add Phase. The Workflow Phase dialog appears.
  2. In Service, ensure you select the Harness Service that contains the manifest for the PCF app you want to deploy.
  3. In Infrastructure Definition, select the Infrastructure Definition that defines the target space where you want to deploy your app.
  4. Click Submit. Phase 1 appears.

Now we configure this phase to deploy 50% of the PCF app instances we have set in the Service manifest.yml.

  1. Click App Setup. The App Setup dialog appears.

You don't need to change any settings in App Setup, but let's review the default settings:

Setting

Description

Match running instances

The first time you deploy this Workflow, this setting isn't used because we have no running instances.

In future deployments, you might wish to select this setting. For Canary Workflows, it isn't relevant because you will be setting the desired instance count for the phase.

Resize Strategy

Specify the order in which you want Harness to downsize and add old and new instances.

The first time you deploy this Workflow, this setting isn't used because we have no running instances.

Active Versions To Keep

Enter the number of previous app versions to downsize and keep. You can upsize these versions later if needed. The most recent app version will not be downsized.

Additional Routes

Select any routes that you want to map to your app, in addition to the routes specified in the manifest in your Harness Service.

Use App Autoscaler Plugin

Enable this setting if you have the App Autoscaler service running in your target Pivotal space and bound to the app you are deploying.

For more information on using the plugin with Harness, see App Autoscaler CLI Plugin.

Timeout

Set how long you want the Harness Delegate to wait for the PCF cloud to respond to API requests before timing out.

  1. Click Submit or close the dialog.

Next, we will resize the number of instances to 50% of the instance count set in your Service manifest.yml.

  1. Click App Resize. The App Resize dialog appears.
  2. In Desired Instances, enter 50 and choose Percent. The app will deploy on 3 instances successfully before the Workflow moves onto Phase 2.
  3. Click SUBMIT.

Next, we'll add Phase 2 where we will deploy to 100% of the instances specified in the Service manifest.yml.

  1. From the breadcrumb menu, click back to the main Canary Workflow page.
  2. In Deployment Phases, under Phase 1, click Add Phase. The Workflow Phase dialog appears.
  3. Select the same Service and Infrastructure Definition that you selected in Phase 1, and then click Submit.

The Phase 2 steps appear.

These step will be executed when the Phase 1 steps are successful.

  1. Click App Resize. The App Resize settings appear.
    In Phase 1, the app successfully deployed to 50% of the instances set in the Service manifest.yml. In Phase 2, you can deploy it to 100% of the instances.
  2. In Desired Instances, enter 100 and choose Percent, and then click Submit. This will deploy the new app to 100% of the instances you set up in Phase 1. The Phase 2 steps are now complete.

If your manifest does not specify the number of instances, Harness defaults to 2 instances.

In Advanced Settings, you can specify Desired Instances - Old Version. This allows you to manage how many instances of the old app version to keep running.

if you do not enter a value, Harness uses the number of new instances as its guide. For example, if you deployed 4 new instances and then select 50 Percent in Desired Instances - Old Version, Harness downsizes the old app version to 50% of 4 instances.

If you are using the App Autoscaler plugin, then autoscaling is applied after the final phase of deployment. After all phases are completed and the number of old version instances has reached the desired number, then the final number of instances will be as configured as defined by the Autoscaler.

Deploy a PCF Canary Workflow

Now that the Canary Workflow is configured, from the breadcrumb menu, click back to the main Canary Workflow page. You can see both Phases are complete.

You can now deploy the Canary Workflow.

  1. Click Deploy.
  2. In Start New Deployment, select an artifact to deploy.

  1. Click Submit to deploy your app.

Here you can see the App Setup step in Phase 1:

When this step is deployed, the output will look something like this:

---------- Starting PCF App Setup Command

# Fetching all existing applications
# No Existing applications found

# Creating new Application
# Manifest File Content:
---
applications:
- name: ExampleForDoc__PCF__Latest__Staging__0
memory: ((PCF_APP_MEMORY))
instances: 0
path: /home/ubuntu/harness-delegate/./repository/pcfartifacts/VsOd7PkCTgWyl0SEEZ5E0w/1572389711331todolist.war
random-route: true
...

name: ExampleForDoc__PCF__Latest__Staging__0
requested state: started
routes: examplefordocpcflateststaging0-anxious-wolverine.cfapps.io
last uploaded: Tue 29 Oct 22:55:40 UTC 2019
stack: cflinuxfs3
buildpacks: client-certificate-mapper=1.11.0_RELEASE container-security-provider=1.16.0_RELEASE java-buildpack=v4.24-offline-https://github.com/cloudfoundry/java-buildpack.git#a2dd394 java-opts java-security jvmkill-agent=1.16.0_RELEASE open-jdk-like-jre=...

type: web
instances: 0/0
memory usage: 350M
...
There are no running instances of this process.
# Application created successfully
# App Details:
NAME: ExampleForDoc__PCF__Latest__Staging__0
INSTANCE-COUNT: 0
ROUTES: [examplefordocpcflateststaging0-anxious-wolverine.cfapps.io]


---------- PCF Setup process completed successfully
# Deleting any temporary files created

Note that since this is the first time this Workflow is deployed, there are no running instances.

Next is the App Resize step in Phase 1:

When this step is deployed, the output will look something like this:

---------- Starting PCF Resize Command

# Downsizing previous application version/s
# No Application is available for downsize
# Upsizing new application:
APPLICATION-NAME: ExampleForDoc__PCF__Latest__Staging__0
CURRENT-INSTANCE-COUNT: 0
DESIRED-INSTANCE-COUNT: 3
# Application upsized successfully

# Application state details after upsize:
NAME: ExampleForDoc__PCF__Latest__Staging__0
INSTANCE-COUNT: 3
ROUTES: [examplefordocpcflateststaging0-anxious-wolverine.cfapps.io]

Instance Details:
Index: 0
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 1
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 2
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

--------- PCF Resize completed successfully

Note the DESIRED-INSTANCE-COUNT: 3 and INSTANCE-COUNT: 3 information. This is the result of setting 50% in Desired Instances.

In Phase 2 we see the final step, App Resize:

When this App Resize step is deployed, the output will look something like the following:

---------- Starting PCF Resize Command

# Downsizing previous application version/s
# No Application is available for downsize
# Upsizing new application:
APPLICATION-NAME: ExampleForDoc__PCF__Latest__Staging__1
CURRENT-INSTANCE-COUNT: 3
DESIRED-INSTANCE-COUNT: 6
# Application upsized successfully

# Application state details after upsize:
NAME: ExampleForDoc__PCF__Latest__Staging__1
INSTANCE-COUNT: 6
ROUTES: [examplefordocpcflateststaging1-fearless-eland.cfapps.io]

Instance Details:
Index: 0
State: STARTING
Disk Usage: 138027008
CPU: 0.0
Memory Usage: 7250563

Index: 1
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 2
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 3
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 4
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 5
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

--------- PCF Resize completed successfully

You can see that the app was deployed to 100% of the instances set in the manifest.yml (6).

App Resizing in Canary Deployments

To understand how app resizing works in a Canary deployment, let's look at an example of a 3 phase deployment:

  1. Phase 1 is set to 25% for new instances (Desired Instances (cumulative) in App Resize step) and 25% old instances (Desired Instances - Old Version in App Resize step).
  2. Phase 2 is set to 50% for new instances and 50% old instances.
  3. Phase 3 is set to 100% for new instances and 0% old instances.

Now, let's imagine the PCF manifest specified in the Harness Service requests 4 instances and there is no autoscaler plugin configured.

Here's what will happen each time you deploy:

First deployment:

  1. Phase 1 deploys 1 new instance.
  2. Phase 2 deploys 2 new instances.
  3. Phase 3 deploys all 4 desired instances.

There are no running instances before deployment, and so there is nothing to downsize.

Second deployment:

  1. There are 4 running instances now. These were deployed by the first deployment. All downsize percentages refer to this number.
  2. Phase 1 deploys 1 new instance and downsizes 1 instance. Downsize is 25%. It results in 25% of 4 which is 1 instance.
    Current state: 1 new versioned instance and 3 old versioned instances running.
  3. Phase 2 deploys 2 new versioned instances and downsizes 2 instances. Downsize is 50% of the number of old versioned instances (4). So 2 instances are downsized.
    Current state: 2 new versioned instances and 1 old versioned instance running.
  4. Phase 2 deploys 4 new versioned instances and downsizes 1 old instance.
    Final state: 4 new instances and 0 old instances.

What about Autoscaler?

If you were using an App Autoscaler plugin, it would be applied at the end of the deployment. For example, if Autoscaler is set to min 8 and max 10, Harness will set the desired number of instances to the minimum value. So the total number of new instances is 8.

Blue/Green Deployments

Harness PCF Blue/Green deployments use the route(s) in the PCF manifest.yml and a temporary route you specify in the Harness Workflow.

The Workflow deploys the app using the temporary route first using the App Setup command. Next, in the App Resize command, Harness maintains the number of instances at 100% of the instances specified in the manifest.yml.

For Blue/Green deployments, the App Resize step is always 100% because it does not change the number of instances as it did in the Canary deployment. In Blue/Green, you are simply deploying the new app to the number of instances set in the App Setup step and keeping the old app at the same number of instances (100% count).

Once that deployment is successful, the Workflow Swap Routes command switches the networking routing, directing production traffic (Green) to the new app and stage traffic (Blue) to the old app.

PCF Service Routes

In the manifest.yml in your Harness PCF Service, you can specify the route(s) to use for the Blue/Green deployment. For example:

  ...
routes:
- route: example.com

Each route for the app is created if it does not already exist.

As you will see when you set up the Blue/Green Workflow, you specify a temporary route in the App Setup command's Temporary Routes setting:

Set up a PCF Blue/Green Workflow

To explain PCF Blue/Green Workflow commands and settings, we will create a Blue/Green Workflow that uses a temporary route and, if it is successful, deploys 100% of instances using the primary route.

To implement this Blue/Green Workflow, do the following:

  1. In your Harness Application, click Workflows.
  2. In Workflows, click Add Workflow. The Workflow dialog appears.
  3. In Name, enter a name for the Workflow.
  4. In Workflow Type, select Blue/Green Deployment.
  5. In Environment, select the Environment you created for PCF.
  6. In Service, select a Harness PCF Service you have created. The Service manifest.yml must contain a route. The route can be an existing route or not. If the doesn't exist, Harness will create it for you. This is the route that will be used at the final stage of the Blue/Green deployment. The temporary route for the prior stage will be selected in the App Setup step of Workflow.
  7. In Infrastructure Definition, select the Infrastructure Definition that describes the target PCF space.

    When you are done, the dialog will look something like this:
  8. Click Submit.

The new Blue/Green Workflow is displayed, along with the preconfigured steps:

Let's look at each step to understand how the Blue/Green Workflow deploys you app.

App Setup

Click App Setup to see the default, preconfigured command:

None of the settings in this dialog are mandatory, but for Blue/Green Workflows, the Match running instances, Additional Routes, and Temporary Routes settings are important.

If you select Match running instances, Harness will ignore the number of instances set in the Service's manifest.yml instances property and use the number of currently running instances as the desired instance count during deployment.

The first time you deploy this Workflow, there is no reason to select Match running instances as there are no current running instances.

Additional Routes is automatically populated with the routes Harness can find using the Infrastructure Definition you selected for this Workflow

Additional Routes has two uses in Blue/Green deployments:

  • Select the routes that you want mapped to the app in addition to the routes already mapped in the app in the manifest in your Harness Service.
  • You can also omit routes in the manifest in your Harness Service, and simply select them in Additional Routes. The routes selected in Additional Routes will be used as the final (green) routes for the app.

Temporary Routes is automatically populated with the routes Harness can find using the Infrastructure Definition you selected for this Workflow.

In Temporary Routes, you can select one or more temporary routes for Harness to use when it creates the PCF app. Later, in the Swap State step, Harness will replace these routes with the routes in the manifest.yml routes property in your Service.

If you do not select a route in Temporary Routes, Harness will create one automatically.

For information on using the Use App Autoscaler Plugin settings, see App Autoscaler CLI Plugin.

App Resize

Click App Resize to see the default settings.

For Blue/Green deployments, the App Resize step is always 100% because it does not change the number of instances as it did in the Canary deployment. In Blue/Green, you are simply deploying the new app to the number of instances set in the App Setup step and keeping the old app at the same number of instances.

Verify Staging

There are no commands in Verify Staging because you have not set up verification steps in this tutorial, and you would not add them in the initial deployment because there are no other deployments for the steps to use in comparison.

Later, when you are developing Blue/Green Workflows, add verification steps to verify the deployment of your app using the temporary route(s). This way, Harness will only proceed to the Swap Routes step if verification does not detects failures. For more information about verifying deployments, see Continuous Verification.

Swap Routes

The final step in the PCF Blue/Green Workflow is the Swap Routes command.

This command will swap the route(s) used by the deployed app from the temporary route(s) to the route(s) specified in the manifest.yml in your Service.

When Swap Routes is used in a Workflow's Rollback Steps, the app that was active before deployment is restored to its original state with the same instances and routes it had before deployment. The new app is left with the temporary route set in App Setup with 0 instances so you can troubleshoot it.

Deploy a PCF Blue/Green Workflow

Now that the Blue/Green Workflow is configured, from the breadcrumb menu, click back to the main Workflow page.

You can now deploy the Blue/Green Workflow.

  1. Click Deploy.
  2. In Start New Deployment, select an artifact to deploy, and click Submit.

The PCF Blue/Green Workflow deploys.

Here you can see the App Step command deployed:

When this step is deployed, the output will look something like this:

---------- Starting PCF App Setup Command

# Fetching all existing applications
# Existing applications:
ExampleForDoc__PCF__Blue__Green__Staging__2

# Processing Apps with Non-Zero Instances
# No Change For Most Recent Application: ExampleForDoc__PCF__Blue__Green__Staging__2

# No applications were eligible for deletion

# Creating new Application
# Manifest File Content:
---
applications:
- name: ExampleForDoc__PCF__Blue__Green__Staging__3
memory: ((PCF_APP_MEMORY))
instances: 0
path: /home/ubuntu/harness-delegate/./repository/pcfartifacts/11uZOBMRQoSbDqr_WfRuaQ/1572474750133SampleWebApp.war
random-route: true


# CF_HOME value: /home/ubuntu/harness-delegate/./repository/pcfartifacts/11uZOBMRQoSbDqr_WfRuaQ
# Performing "login"
API endpoint: api.run.pivotal.io
Authenticating...
OK

Targeted org Harness
Targeted space AD00001863
...
Getting app info...
Creating app with these attributes...
+ name: ExampleForDoc__PCF__Blue__Green__Staging__3
path: /home/ubuntu/harness-delegate/repository/pcfartifacts/11uZOBMRQoSbDqr_WfRuaQ/1572474750133SampleWebApp.war
+ instances: 0
+ memory: 350M
routes:
+ examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io
...
# Application created successfully
# App Details:
NAME: ExampleForDoc__PCF__Blue__Green__Staging__3
INSTANCE-COUNT: 0
ROUTES: [examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io]

---------- PCF Setup process completed successfully
# Deleting any temporary files created

The route specified in the Service manifest.yml is docs.cfapps.io:

Note that in the App Setup step, a temporary route has been used: examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io.

Here you can see the App Resize command deployed:

When this step is deployed, the output will look something like this:

---------- Starting PCF Resize Command

# Upsizing new application:
APPLICATION-NAME: ExampleForDoc__PCF__Blue__Green__Staging__3
CURRENT-INSTANCE-COUNT: 0
DESIRED-INSTANCE-COUNT: 6
# Application upsized successfully

# Application state details after upsize:
NAME: ExampleForDoc__PCF__Blue__Green__Staging__3
INSTANCE-COUNT: 6
ROUTES: [examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io]

Instance Details:
Index: 0
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 1
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 2
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 3
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 4
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

Index: 5
State: STARTING
Disk Usage: 0
CPU: 0.0
Memory Usage: 0

# BG Deployment. Old Application will not be downsized.
--------- PCF Resize completed successfully

Note that 100% of the instances specified in the Service manifest.yml have been deployed (6).

Here you can see the Swap Routes command deployed:

When this step is deployed, the output will look something like this:

--------- Starting PCF Route Update

# Adding Routes
APPLICATION: ExampleForDoc__PCF__Blue__Green__Staging__3
ROUTE:
[
docs.cfapps.io
]

# Unmapping Routes
APPLICATION: ExampleForDoc__PCF__Blue__Green__Staging__3
ROUTES:
[
examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io
]
# Unmapping Routes was successfully completed

# Adding Routes
APPLICATION: ExampleForDoc__PCF__Blue__Green__Staging__2
ROUTE:
[
examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io
]

# Unmapping Routes
APPLICATION: ExampleForDoc__PCF__Blue__Green__Staging__2
ROUTES:
[
docs.cfapps.io
]
# Unmapping Routes was successfully completed

--------- PCF Route Update completed successfully

Note how the new app receives the docs.cfapps.io route from the Service manifest.yml and the old route receives the temporary route examplefordocpcfbluegreenstaging3-insightful-cat.cfapps.io.

The Blue/Green deployment is complete.

CF Command

You can use the CF Command to run any CF CLI command or script at any point in your Harness PCF Workflows.

You can also use the CF Command to create the service for the App Autoscaler plugin, as described in Using CLI Plugins in Harness PCF Deployments

The CF Command script does not require cf login. Harness performs logins using the credentials in the PCF Cloud Provider set up in the Infrastructure Definition for the Workflow executing the CF Command.

The CF Command has the settings described below.

Script

You can enter any CF CLI commands and scripts, but be sure to add the CF Command to a point in your Workflow where the targets of the script are available. If you add CF Command before the App Setup step, the new app is not available.

Script Variables

There are two built-in Harness PCF variables you can use to reference the manifest and vars files used by the script:

  • If you are using inline Manifest files, the variable ${service.manifest} refers to the folder containing your manifest files.
  • If you are using remote Manifest files via a Git repo, ${service.manifest} refers to the folder containing your manifest files and ${service.manifest.repoRoot} refers to the root folder of the repo.

You can use the variables together to point to different locations. For example, here the manifest.yml file is one folder and the vars.yml is located using a path from the repo root folder:

cf create-service-push --service-manifest ${service.manifest}/manifest.yml --no-push --vars-file ${service.manifest.repoRoot}/QA/vars.yml
cf plugins | grep autoscaling-apps

These variables appear when you type ${service in Script:

Environment Service Overrides, such as PCF Manifests Override, do not apply to or override the ${service.manifest} variable. The ${service.manifest} variable only looks in the Harness Service.

You can also use variables in your script to templatize paths to manifest files. For example, if your Workflow Environment were templatized (see Template a Workflow), you can use the Environment variable ${env.name} in your path, like this:

${service.manifest.repoRoot}/${env.name}/vars.yml

When the Workflow is deployed, the user will have to provide a name for the Environment to use. The same name will be substituted for ${env.name} in the path in your script.

This substitution can be useful if you have folder names in your remote Git repo that match Harness Environment names, such as QA and PROD. The same Workflow and CF Command can be used for both Environments and use manifest files in separate repo folders.

Delegate Tags

In order for the commands in your script to execute, the Harness Delegate(s) running the script must have the CF CLI and any related CF plugins installed.

Unless all of your Harness Delegates have the CF CLI and CF plugins installed, you can refer to the specific Delegates using Delegate Tags. Add the Delegate Tag(s) for the Delegates with the CF CLI and CF plugins installed.

If you do not add any Delegates Tags to the CF Command, when the CF Command runs, Harness will only use Delegates that have the CF CLI installed.

However, if you are running plugins in CF Command, Harness cannot know which Delegates have the plugins installed.

This is why the Delegate Tags setting ensures that CF Command only executes on Delegates that can run the plugins mentioned in the CF Command script.

Timeout

Set the timeout period for your CF Command. If the command execution hangs beyond the timeout, Harness will fail the step.

CF Command Templates

You can also create CF Command templates in your Application or Account templates. Other users can then use these templates to quickly add the CF Commands to their Workflows.

Here are the steps for creating and adding a CF Command template:

  1. Decide on whether you want to use Application or Account templates.

    Application templates can be used by any Workflow in the Application, and Account templates can be used by any Workflow in any Application. For an overview of template, see Use Templates.
    For this example, we will create an Application template.
  2. In your Application, in Application Resources, click Template Library.
  3. Click Add Template, and then click PCF Command. The PCF Command settings appear:
  4. Configure the template the same way you would configure the CF Command in a Workflow, described in CF Command above.
  5. In Variables, enter the variable names and default values you want to use in the template. When a user adds or links this template to a Workflow, the user will provide the values for the variables.
    You can also type the variables in the Script field and Harness will prompt you to create them:
    Here's an example showing variables used in the command script:
  6. When you are done, click Submit.
  7. Navigate to a Workflow for a PCF Service.
  8. In the Setup section on the Workflow steps, click Add Command.
  9. Select Application Templates to select from the command from the Application Template Library.
  10. Locate your command and click Link or Copy. A copied template does not provide version control like a linked template. In this example, we'll click Link.
    The CF Command template settings appear.
  11. Recommended: Add a Delegate Tag in Run only on delegates having the following Tags, as described in Delete Tags.
  12. Provide values for the variables, if any.
  13. Click Submit.

The CF Command template is added to your Workflow.

If you open the template, you can edit the Run only on delegates having the following Tags and Variables settings.

Configure PCF Workflow as Code

Harness provides a YAML code editor that enables you to perform all configuration using YAML in addition to the Harness Manager UI. In the Workflow page, simply click the </> button next to Deploy.

Harness syncs with Git, so you can create a Harness Workflow using YAML or the Harness Manager, sync it, and then simply make changes in Git. For more information, see Configuration as Code.

Blue/Green Workflow using Code

As an example of Harness code editor functionality, let's compare how a PCF Blue/Green Workflow looks in the UI and in the code editor.

PCF Blue/Green Workflow in the UI

PCF Blue/Green Workflow in the Code Editor

As you can see, the Setup step in the UI has an App Setup step:

In the YAML the App Setup is very simple to view:

...
- type: PCF_SETUP
name: App Setup
properties:
blueGreen: true
isWorkflowV2: true
olderActiveVersionCountToKeep: 3
resizeStrategy: RESIZE_NEW_FIRST
tempRouteMap: null
templateUuid: null
templateVariables: null
templateVersion: null
timeoutIntervalInMinutes: 5
useCurrentRunningCount: false
...

PCF Built-in Variables

Harness includes the following variables to help you output PCF deployment information in your Workflows, such as in the CF Command or the Shell Script command.

In Blue/Green deployments, the outputs for the ${pcf.finalRoutes} and ${pcf.tempRoutes} variables do not change, but the outputs for ${pcf.newAppRoutes} and ${pcf.oldAppRoutes} change as the routes are swapped in the Swap Routes or Rollback step. Simply put, ${pcf.newAppRoutes} and ${pcf.oldAppRoutes} reflect the routes at a point in time (before or after the Swap Routes or Rollback step).

Variable

Description

${service.manifest}

Refers to the folder containing your manifest files. See Script Variables.

${service.manifest.repoRoot}

Refers to the remote Git repo root folder containing your manifest files. See Script Variables.

${pcf.newAppRoutes}

An array of all the routes defined in your manifest.yml in your Harness Service.

You can reference any route in the array using its index, such as ${pcf.newAppRoutes[0]}.

You can use the route to create a URL in a script, such as http://${pcf.newAppRoutes[0]}.

In a Blue/Green deployment, ${pcf.newAppRoutes} are the same as ${pcf.tempRoutes} until the Swap Routes step is run, after which ${pcf.newAppRoutes} is the same as ${pcf.finalRoutes}.

${pcf.newAppName}

New app name.

${pcf.newAppGuid}

New app GUID.

${pcf.oldAppName}

Old app name. This is the app that is replaced by your newly deployed app.

${pcf.oldAppGuid}

Old app GUID.

${pcf.oldAppRoutes}

An array of the routes that were used for the old app.

You can reference any route in the array using its index, such as ${pcf.oldAppRoutes[0]}.

You can use the route to create a URL in a script, such as http://${pcf.oldAppRoutes[0]}.

${pcf.finalRoutes}

An array of the active routes once deployment is successful.

${pcf.tempRoutes}

An array of the temporary routes used for Blue/Green deployments.

${infra.pcf.cloudProvider.name}

The Cloud Provider name used in the Infrastructure Definition set up in the Workflow.

${infra.pcf.organization}

The Organization name used in the Infrastructure Definition set up in the Workflow.

${infra.pcf.space}

The Space name used in the Infrastructure Definition set up in the Workflow.

Here is a script that outputs all the variables:

echo ${pcf.newAppRoutes[0]}

echo New App Name: ${pcf.newAppName}
echo New App Guild: ${pcf.newAppGuid}
echo New App Routes: ${pcf.newAppRoutes}

echo "\n\n"
echo Old App Name: ${pcf.oldAppName}
echo Old App Guild: ${pcf.oldAppGuid}
echo Old App Routes: ${pcf.oldAppRoutes}

echo activeRoute: ${pcf.finalRoutes}
echo inActiveRoute: ${pcf.tempRoutes}

echo ${infra.pcf.cloudProvider.name}
echo ${infra.pcf.organization}
echo ${infra.pcf.space}

Harness PCF Environment Variables

For Blue/Green Workflow deployments only, Harness uses the PCF user-provided environment variable HARNESS_STATUS_INDENTIFIER to identify new and old (active) apps.

When a new app is deployed, the variable is HARNESS_STATUS_INDENTIFIER : STAGE.

When Harness swaps route, the variable is updated to HARNESS_STATUS_INDENTIFIER : ACTIVE for the new app, and the old app variable becomes HARNESS_STATUS_INDENTIFIER : STAGE.

If rollback occurs, Harness restores routes and environment variables for old and new apps.

You can view this HARNESS_STATUS_INDENTIFIER variable in the PCF app in the PCF console.

Next Steps


How did we do?