Pivotal Cloud Foundry Deployment

Updated 1 week ago by Michael Cretzman

Harness provides support for the Pivotal Cloud Foundry (PCF) app development and deployment platform for public and private clouds.

Harness also supports the Cloud Foundry Open Source Cloud Application Platform.

This topic covers the following:

Before You Begin

Harness Delegate

The Harness Delegate is a service you run in your local network or VPC to connect your artifact servers, PCF infrastructure, and any other providers with the Harness Manager.

For information on setting up a Harness Delegate, see Delegate Installation and Management.

PCF Cloud Provider

A Harness PCF Cloud Provider connects Harness to your PCF account and allows the Harness Delegate to make API calls.

For steps on setting up the PCF Cloud Provider, see Add Cloud Providers.

Artifact Server

Harness integrates with many different types of repositories and artifact providers. We call these Artifact Servers, and they help you pull your artifacts into your Harness Applications.

Once you set up an Artifact Server, Harness can pull artifacts and add them to the Harness Service you will deploy to PCF.

For steps on setting up an Artifact Server, Add Artifact Servers.

Add a PCF Service

The following procedure creates a Harness application with a PCF service, an environment with a PCF service infrastructure, and a workflow that deploys the service.

Before you configure a PCF service infrastructure in Harness, it is recommended that you create your route maps using the cf CLI cf map-route command to associate an app and route. If you do not, Harness will create route maps for you using random names. For more information, see Routes and Domains from Pivotal.

To add a PCF service, do the following:

  1. Ensure you have set up a PCF cloud provider connection in Harness, as described in Add Cloud Providers. This connection will log into the foundation.
  2. Ensure you have set up an artifact server connection in Harness, as described in Add Artifact Servers.
  3. Create a Harness application. The PCF service is managed within a Harness application, along with its environment, workflows, pipelines, etc. For more information, see Application Checklist.
    1. Click Setup, and then click Add Application. The Application dialog appears.
    2. Enter a name for your application, such as PCF_App, and click SUBMIT. The application is created.
    3. Click your application’s name. The application entities appear.
      Next, add the PCF services to your application, including its artifact sources, container types, configuration variables, and files.
  4. Add the PCF service and artifact.
    1. In your application, click Services. On the Services page, click Add Service. The Service dialog appears.
    2. In Name, enter a name for your service. Typically, the name is the same as the micro-service or app you are going to deploy.
    3. In Artifact Type, select Pivotal Cloud Foundry. Once you select an artifact type, Harness will only present configuration options related to that type.
    4. Click SUBMIT. The new service is added.
  5. Next, add an artifact source for the service. Click Add Artifact Source, and select the artifact source.
    For a list of the PCF-supported artifact sources, see Artifact Sources below.

Artifact Sources

The artifact source for your Harness Service is taken from one of the Artifact Servers set up in Add Artifact Servers and is compatible with PCF.

For more information, see Service Types and Artifact Sources.

Deployment Specification

When you create the PCF service, the Deployment Specification section is created and a default PCF manifest file is added.

Manifest File

Manifests provide consistency and reproducibility, and help automate in deploying apps. For more information about the manifests file, see Deploying with Application Manifest from Pivotal.

The comments in the manifest file identify the required fields and their placeholders.

Do not replace the placeholders with information about your application. The values for the placeholders are picked up by Harness at runtime, according to the deployment workflow, and any infrastructure mapping. Anything you enter here will not be used.

Here is an example manifest made from the placeholders at runtime:

applications:
- name: my-app
memory: 750M
INSTANCES : 1
path: /path/to/application/bits
ROUTES:
- route: example.com

Configuration Variables and Files

Configuration variables and files enable you to specify information in the service that can be referenced in other parts of the Harness application. For example, you can specify a variable in the service once, and then use it in multiple workflows without having to manage multiple values.

  • Config Variables - You can create Service-level variables to use throughout your service configuration settings. Any Service variables are added as environment variables when the app is created in the Pivotal environment (cf push).
  • Config Files - You can upload config files with variables to be used when deploying the Service. The secrets variable file is an example.

For details on configuration variables and files, see Configuration Variables and Files.

Secrets Variable File

A secrets.yml defines a format for mapping a variable to a location where a secret is stored.

You can add a secrets.yml variable file to your service and when the service is deployed, the secrets.yml file will be added to the cf push command.

PCF Environments

You can specify the PCF deployment environment for you application in a Harness Environment. In the Environment, you specify the following:

  • The Service you created.
  • The PCF deployment type.
  • The PCF Cloud Provider that you added, as described in Add Cloud Providers.

To set up your PCF deployment Environment, do the following:

  1. In your Harness Application, click Environments.
  2. Click Add Environment. The Environment dialog appears.
    1. In Name, enter a name for the PCF Environment, such as Staging.
    2. In Environment Type, select Production or Non-Production.
    3. Click SUBMIT. The Environment is created.

PCF Service Infrastructures

The Service Infrastructure is where you specify the PCF deployment infrastructure, using a Cloud Provider, a PCF deployment type, and the specific infrastructure details for the deployment, like route maps.

  1. Add a Service Infrastructure. In the Environment, click Add Service Infrastructure. The Service Infrastructure dialog appears.

In Service Infrastructure, you will specify the PCF org, space, and route maps for the app deployment.

The Service Infrastructure dialog has the following fields.

Fields

Description

Name

You can enter a name for your Service Infrastructure or let Harness generate one automatically,

Service

Select the Harness Service to be deployed. Only Services of the PCF type are displayed.

Cloud Provider

Select the PCF Cloud Provider that you set up in PCF Cloud Provider.

Deployment Type

Select PCF.

Cloud Provider

Select the cloud provider to use to connect to the foundation. This will be one of the cloud providers you set up in Add Cloud Providers.

Configuration

These are the foundation-specific settings that determine where in your foundation the application is deployed.

Organization

Select the PCF org for the development account.

Space

Select the space where the application you are deploying is scoped.

Route Maps

Select or create the final route map for the app. In a Blue/Green Workflow, this route is the Green route.

You will use the route when defining the deployment Workflow. In a Workflow, the expression for this route is ${infra.pcf.route}. Here is an example of the route being used in the Map Route step of a workflow:

Temporary Route Maps

Select or create a temporary route for the app. A temporary route can be used to verify an app deployment and, once verified, the workflow can map the app to the primary route, defined in Route Maps.

You will use the route when defining the deployment Workflow. The expression for this route is ${infra.pcf.tempRoute}.

If you do not have route maps inside PCF, Harness will generate route maps with random names.

You can create route maps (add a URL route to an app) in the Service Infrastructure dialog. This setting will perform the same operation as the Cloud Foundry create-route CLI command.

To create Route Maps and Temporary Route Maps, do the following:

  1. For either Route Maps or Temporary Route Maps, click Add Route Map. The Route Type assistant appears.
  2. Select HHTP Route or TCP Route. HTTP Route is the most common. Hostname and path are not supported for TCP routes. For information on the differences, see HTTP vs. TCP Routes from Cloud Foundry.
  3. In Domain Name, enter a public name such as myapp.io.
  4. In Host Name, enter a hostname, such as checkout-1. In Cloud Foundry, a host name is the label that indicates a subdomain of the domain associated with the route.
  5. In Path, enter the path for the route. Developers can use paths to route requests for the same hostname and domain to different apps. See Create an HTTP Route with a Path from Cloud Foundry.
  6. Click SUBMIT. Repeat for additional route maps.
With multiple routes, you can map and unmap an app to temporary and final routes. This enables workflows such as Blue/Green.

When you are finished configuring your service infrastructure, it will look something like this:

Service Configuration Overrides

You can configure your environment to override settings of the services that use the environment. For example, a service might use a specific YAML file with specific metadata, but your environment might need to change the name and namespace of the metadata because it is deploying the service to a QA environment.

For more information, see Override a Service Configuration.

PCF Workflows

Workflows are the deployment steps that use the Harness services and environments, including deployment types such as Canary and Blue/Green. Workflows can involve a few steps or multiple phases each composed of several steps.

Canary Deployments

To explain PCF workflow options, 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:

  1. Phase 1:
    1. App Setup: 6 instances set up. The map route is the primary route.
    2. App Resize: 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: 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. The Workflow dialog has the following fields.

Workflow dialog

Fields

  • Name. Enter a name that describes what the workflow does. For example, for a simple Canary deployment, Canary PCF.
  • Workflow Type. Select your deployment type. For the steps below, we will use Canary Deployment.
  • Environment. Select the environment containing the service infrastructure where you will deploy your application. Environments can contain multiple service infrastructures.
  • Service. Select the service containing the artifact you want to deploy.
  • Service Infrastructure. Select the service infrastructure where you will deploy your application.

When the Workflow dialog is finished, click SUBMIT. The Canary workflow appears.

The Phase 1 steps must be successful before the workflow will proceed to Phase 2.

To configure the Canary phases, do the following:

  1. Click Phase 1. The Phase 1 steps appear.
    In a Canary deployment, you deploy your app to a small percentage of available instances in Phase 1.
    1. Click App Setup. The App Setup dialog appears.
    2. In Desired Instance Count, you can select Same as already running instances or Fixed. Since this is the first time we can deployed, there will be no already running instances. Click Fixed.
    3. In Fixed Instances Count, enter 6. Later, in the App Resize step, we will deploy to 50% of these instances.
    4. In Map Route, ensure ${infra.pcf.route} is entered. This is the route you selected in the Route Maps field in your Service Infrastructure.

      When you are done, the dialog will look like this:
    5. Click SUBMIT.
    6. Click App Resize. The App Resize dialog appears.
    7. In Desired Instances, enter 3 and choose Count. The app will deploy on 3 of the 6 instances successfully before the workflow moves onto Phase 2.
    8. Click SUBMIT.
  2. From the breadcrumb menu, select Phase 2.
    The Phase 2 steps appear.
    These step will be executed when the Phase 1 steps are successful.
    1. Click App Resize. The App Resize dialog appears. Now that the app successfully deployed to 50% of the instances in Phase 1, you can deploy it to 100% of the instances.
    2. In Desired Instances, enter 6 and choose Count, 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.

Blue/Green Deployments

The following Workflow shows the default steps generated by Harness when you select a Blue/Green Deployment for Workflow Type.

As you can see, the App Setup and App Resize commands are used in the same way as they were used in Canary Workflows Phases. The difference in a Blue/Green deployment is that the App Resize step is always 100% and the Update Route section contains the Swap Routes command.

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).

The Swap Routes command switches the networking routing in your Service Infrastructure, directing production traffic (Green) to the new app and stage traffic (Blue) to the old app.

App and Map Route Expressions and Commands

You can use expressions in your workflow to reference new and old apps, and expressions and commands to manage route maps.

App Expressions

There are two expressions you can use to reference your old and new apps.

  • New app expression: ${pcfAppName}
  • Old app expression: ${pcfOldAppName}

To use these expressions, start typing ${pcf into a workflow dialog field and the expressions will appear.

Route Map Expressions

You can change the PCF routes used by new and old apps in a deployment by using expressions in the workflow commands to reference the route maps you set in the Service Infrastructure of the environment.

For example, in the following App Setup command, the ${infra.pcf.tempRoute} expression is used in Map Route to set up instances for a new app using the Temporary Route Map you set up in Service Infrastructure.

Temporary Route Map in Service Infrastructure

Temporary Route Map in Workflow

There are two expressions available for route maps:

Service Infrastructure Field

Workflow Command Expression

Route Maps

${infra.pcf.route}

Temporary Route Maps

${infra.pcf.tempRoute}

In you enter multiple route maps in Service Infrastructure, the workflow expressions use all of the route maps. You cannot select individual route maps in the workflow.

Route Map Commands

In addition to the App Resize commands generated by Harness, there are several other route map command:

  • Map Route - Map an app to a route. In a Blue/Green deployment, this could be a stage app mapped to the Blue deployment environment or a production app mapped to a Green deployment environment, or vice versa.
  • Unmap Route - Unmap an app from a route.
  • Swap Routes - In a Blue/Green deployment, this command is applied after the staging of the new app is verified and swaps routes between the Blue and Green environments.

To add the map route commands to your workflow, click Add Command, and select the command under Flow controls.

Map Route and Unmap Route

It helps to look at the Map Route or Unmap Route command dialogs side-by-side.

Map Route

Unmap Route

In Map Route, you are mapping the ${pcfAppName} to the ${infra.pcf.route} (Green deployment environment), and in Unmap Route, you are unmapping ${pcfAppName} from the ${infra.pcf.route} (Blue deployment environment).

To use the expressions, start typing ${infra in the Map Route field of a dialog and the options appear.

Swap Routes

In a Blue/Green deployment, this command is applied after the staging of the new app is verified. When you select a Blue/Green Workflow Type, the Swap Routes command is automatically applied to the Update Route step of the Workflow.

The Swap Routes command swaps the networking routes for the Blue and Green environments, directing production traffic (Green) to the newly deployed app and stage traffic (Blue) to the previously deployed app.

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 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 UI, 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:
route: ${infra.pcf.tempRoute}
olderActiveVersionCountToKeep: 3
blueGreen: true
useCurrentRunningCount: false
pcfAppName: ${app.name}__${service.name}__${env.name}
maxInstances: '4'
resizeStrategy: RESIZE_NEW_FIRST
timeoutIntervalInMinutes: 5
stepsInParallel: false
...

Here's the full YAML for the PCF Blue/Green Workflow:

harnessApiVersion: '1.0'
type: BLUE_GREEN
envName: QA
failureStrategies:
- executionScope: WORKFLOW
failureTypes:
- APPLICATION_ERROR
repairActionCode: ROLLBACK_WORKFLOW
retryCount: 0
notificationRules:
- conditions:
- FAILED
executionScope: WORKFLOW
notificationGroupAsExpression: false
userGroupAsExpression: false
userGroupIds:
- GXFtTUS2Q9Gmo1r4MhqS4g
phases:
- type: PCF
computeProviderName: pcf
daemonSet: false
infraMappingName: Harness -PCF--Pivotal Cloud Foundry- pcf- Harness_Pcf_Demo
name: Phase 1
phaseSteps:
- type: PCF_SETUP
name: Setup
steps:
- type: PCF_SETUP
name: App Setup
properties:
route: ${infra.pcf.tempRoute}
olderActiveVersionCountToKeep: 3
blueGreen: true
useCurrentRunningCount: false
pcfAppName: ${app.name}__${service.name}__${env.name}
maxInstances: '4'
resizeStrategy: RESIZE_NEW_FIRST
timeoutIntervalInMinutes: 5
stepsInParallel: false
- type: PCF_RESIZE
name: Deploy
steps:
- type: PCF_RESIZE
name: App Resize
properties:
downsizeInstanceUnitType: PERCENTAGE
instanceUnitType: PERCENTAGE
instanceCount: 100
downsizeInstanceCount: 100
stepsInParallel: false
- type: VERIFY_SERVICE
name: Verify Staging
stepsInParallel: false
- type: PCF_SWICH_ROUTES
name: Update Route
steps:
- type: PCF_BG_MAP_ROUTE
name: Swap Routes
properties:
downsizeOldApps: false
stepsInParallel: false
- type: WRAP_UP
name: Wrap Up
stepsInParallel: false
provisionNodes: false
serviceName: Pivotal-cloud-foundry
statefulSet: false
preDeploymentSteps:
- type: ARTIFACT_CHECK
name: Artifact Check
rollbackPhases:
- type: PCF
computeProviderName: pcf
daemonSet: false
infraMappingName: Harness -PCF--Pivotal Cloud Foundry- pcf- Harness_Pcf_Demo
name: Rollback Phase 1
phaseNameForRollback: Phase 1
phaseSteps:
- type: PCF_SWICH_ROUTES
name: Update Route
phaseStepNameForRollback: Update Route
statusForRollback: SUCCESS
steps:
- type: PCF_BG_MAP_ROUTE
name: Swap Routes
properties:
service2: ${STAGE_SERVICE_NAME}
service1: ${PRIMARY_SERVICE_NAME}
stepsInParallel: false
- type: PCF_RESIZE
name: Deploy
phaseStepNameForRollback: Deploy
statusForRollback: SUCCESS
steps:
- type: PCF_ROLLBACK
name: App Rollback
stepsInParallel: false
- type: VERIFY_SERVICE
name: Verify Service
phaseStepNameForRollback: App Resize
statusForRollback: SUCCESS
stepsInParallel: false
- type: WRAP_UP
name: Wrap Up
stepsInParallel: false
provisionNodes: false
serviceName: Pivotal-cloud-foundry
statefulSet: false
templatized: false

Deploy PCF Workflows

Now that you have set up your PCF workflow you can deploy it and view the deployment in real-time.

To deploy your PCF workflow, do the following:

  1. Go to the main page for your workflow.
  2. Click Deploy.
    The Start New Deployment dialog appears.
  3. In Checkout, select the artifact to deploy. The menu displays all the recent versions of the artifact in the Artifact Source you set up in the service used by this workflow.
  4. Click SUBMIT. The workflow is run and the app is deployed.
    Click through the workflow steps to see the details. In the example above, App Resize in Phase 2 is clicked, and the resize information is displayed:
    INFO   2018-09-07 10:21:11    ---------- Starting PCF Resize Command
    INFO 2018-09-07 10:21:11
    INFO 2018-09-07 10:21:16 # Upsizing new application,
    INFO 2018-09-07 10:21:16 APPLICATION-NAME: PCF_Demo_App__Checkout__Staging__2
    INFO 2018-09-07 10:21:16 CURRENT-INSTANCE-COUNT: 3
    INFO 2018-09-07 10:21:16 DESIRED-INSTANCE-COUNT: 6
    INFO 2018-09-07 10:21:26 # Application upsized successfully
    INFO 2018-09-07 10:21:26
    INFO 2018-09-07 10:21:26 # Application state details after upsize:
    INFO 2018-09-07 10:21:26 NAME: PCF_Demo_App__Checkout__Staging__2
    INFO 2018-09-07 10:21:26 INSTANCE-COUNT: 6
    INFO 2018-09-07 10:21:26 ROUTES: [link2.cfapps.io]

Next Steps

  1. Workflow Strategies: Once you have set up a successful workflow, you can refine the workflow using Rollback, Notification, and Failure strategies. For more information, see Rollback Steps, Notification Strategy, and Failure Strategy in Add a Workflow.
  2. Verification: Add Verify Steps to your using workflow using Verification Providers. Harness unsupervised machine learning analyzes verification provider analytics and logs to improve your deployments. For more information, see Verify Steps and Continuous Verification.
  3. Templates: Once the workflow is ready for production, you can turn the workflow into a template for other DevOps to use. For more information, see Template a Workflow.
  4. Pipelines and Triggers: Create pipelines containing multiple workflows and triggers to run your workflows or pipelines automatically. For more information, see Add a Pipeline and Add a Trigger.


How did we do?