Pivotal Cloud Foundry Deployment

Updated 6 days ago by Michael Cretzman

Harness provides support for the Pivotal Cloud Foundry (PCF) app development and deployment platform for public and private clouds. Your Harness applications support PCF in the following entities:

  • Services: Harness has a PCF service type. Harness automatically creates the manifest file, which you can customize.
  • Environments: You can deploy your apps to orgs and spaces in your foundation, specifying multiple route maps.
  • Workflows: Harness provides Basic, Canary, Blue/Green, Multi-Phase, and Rolling Deployment options. Default Rollback, Notification, and Failure Strategies are provided and can be easily changed.
  • Pipelines and Triggers: Create pipelines containing multiple workflows and triggers to run your workflows or pipelines automatically.
  • Continuous Verification: You can integrate your Verification Providers (AppDynamics, ELK, etc) and Harness will use its unsupervised machine learning feature to continually analyze provider analytics and logs to improve your deployments.

Intended Audience

  • Developers
  • DevOps

Before You Begin

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 one of the artifact servers set up in Add Artifact Servers that is compatible with PCF.

Jenkins

The PCF service can use Jenkins as an artifact source. The Jenkins dialog has the following fields.

Jenkins dialog

Fields

  • Name. Enter a name to identify this artifact source, or let Harness generate a name.
  • Source Server. Select the Jenkins artifact server you added to Harness. For more information, see Add Artifact Servers.
  • Job Name. When you select a Source Server, this list of Jenkins jobs is populated. Select the job you want to execute.
  • Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.
  • Artifact Path. When you select a Job Name, this list of artifacts is populated. Select the artifact for this service.

Bamboo

The PCF service can use Bamboo as an artifact source. The Bamboo dialog has the following fields.

Bamboo dialog

Fields

  • Name. Enter a name to identify this artifact source, or let Harness generate a name.
  • Source Server. Select the Bamboo artifact server you added to Harness. For more information, see Add Artifact Servers.
  • Job Name. When you select a Source Server, this list of Bamboo jobs is populated. Select the job you want to execute.
  • Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.
  • Artifact Path. When you select a Job Name, this list of artifacts is populated. Select the artifact for this service.

Google Cloud Storage

The PCF service can use Google Cloud Storage (GCP) as an artifact source. The GCP dialog has the following fields.

Google Cloud Storage dialog

Fields

  • Name. Enter a name to identify this artifact source, or let Harness generate a name.
  • Cloud Provider. Select the GCP cloud provider you added to Harness. For more information, see Add Cloud Providers.
  • Project Name. When you select a Cloud Provider, this list of GCP projects is populated. Select the project where the bucket containing the artifact is located.
  • Bucket. When you select a Project Name, this list of GCP buckets is populated. Select the bucket containing the artifact.
  • Artifact Path. When you select a Job Name, this list of artifacts is populated. Select the artifact for this service. Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.
  • Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.

Nexus Artifact Source

The PCF service can use a Nexus repository server as an artifact source. The Nexus dialog has the following fields.

Nexus dialog

Fields

  • Name. You can enter a name or have Harness generate one for you automatically.
  • Source Server. Select the name of the repository server you added in Add Artifact Servers.
  • Repository. Select the name of the repository where the artifact is located.
  • Group. Select the repository group where the artifact is located.
  • Artifact Path. Select the artifact path.
  • Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.

Artifactory Artifact Source

The PCF service can use a Artifactory repository server as an artifact source. The Artifactory dialog has the following fields.

Artifactory dialog

Fields

  • Name. You can enter a name or have Harness generate one for you automatically.
  • Source Server. Select the name of the repository server you added in Add Artifact Servers.
  • Repository Type. Select the type of repository (local, remote, or virtual).
  • Repository. Select the name of the repository where the artifact is located.
  • Artifact Path / File Filter. Select the artifact path or file filter (the content of the artifact is passed through a processor before being returned).
  • Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.

Amazon S3

The PCF service can use an Amazon S3 bucket as an artifact source. The Amazon S3 dialog has the following fields.

Amazon S3 dialog

Fields

  • Name. Enter a name to identify this artifact source, or let Harness generate a name.
  • Cloud Provider. Select the Amazon S3 cloud provider you added to Harness. For more information, see Add Cloud Providers.
  • Bucket. When you select a Cloud Provider, this list of S3 buckets is populated. Select the bucket containing the artifact.
  • Artifact Path. When you select a Bucket, this list of artifacts is populated. Select the artifact for this service.
  • Meta-data only. Select this option if you do not want Harness to download the artifact, but simply its meta-data.

Amazon Machine Image (AMI)

The PCF service can use an Amazon AMI as an artifact source. The Amazon AMI dialog has the following fields.

AMI dialog

Fields

  • Name. Enter a name to identify this artifact source, or let Harness generate a name.
  • Cloud Provider. Select the Amazon cloud provider you added to Harness. For more information, see Add Cloud Providers.
  • Region. Select the Amazon region where the AMI is located.
  • AWS Tags. Add any tags used to identify the AMI instance. Tags are a simple way to distinguish AMIs.
  • AMI Resource Filters. Add any of the AWS console Filter options to scope the list of displayed AMIs.

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

To use service-level variables, do the following:

  1. In Configuration, in Config Variables, click Add Variable. The Config Variable dialog appears.
  2. In Name, enter a name for your variable. This is the name you will use to reference your variable anywhere in your service.
  3. In Type, select Text or Encrypted Text.
  4. If you selected Text, enter a string in Value.
  5. If you select Encrypted Text, the Value field becomes a drop-down and you can select any of the Encrypted Text you have configured in Secrets Management. You can also click Add New Encrypted Text to create a new secret.
  6. Click SUBMIT. The variable is added to Config Variables.
  7. To reference the variable is any text field in your service configuration, type $ and Harness will provide a drop down of all variables. Begin typing the name of your variable to find it and select it.

Config Files

You can upload config files with variables to be used when deploying the service. The secrets variable file is an example.

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 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.
Before configuring the deployment environment for your application, ensure that you have PCF routes created. This allows you to associate one or more routes with your app as you create the deployment workflow in Harness. With multiple routes, you can map and unmap an app to temporary and final routes. This enables workflows such as Blue/Green.

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.
  3. 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,

Select Cloud Provider

These settings define the service, deployment type, and cloud provider for the service infrastructure.

Service

Select the service to be deployed. Only PCF services are displayed.

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

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 Total Number of Instances, enter 6. Later, in the App Resize step, we will deploy to 50% of these instances.
    3. In Map Route, ensure ${infra.pcf.route} is entered. This is the route you selected in the Route Maps field in your Service Infrastructure.
    4. Click SUBMIT.
    5. Click App Resize. The App Resize dialog appears.
    6. In Desired Instances, enter 50 and select Percent. The app will deploy on 3 of the 6 instances successfully before the workflow moves onto Phase 2.
    7. 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 100, select Percent, and 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:

name: App Setup
properties:
route: ${infra.pcf.tempRoute}
blueGreen: true
pcfAppName: ${app.name}__${service.name}__${env.name}
maxInstances: 4
resizeStrategy: RESIZE_NEW_FIRST
timeoutIntervalInMinutes: 10

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

harnessApiVersion: '1.0'
type: BLUE_GREEN
envName: Staging
failureStrategies:
- executionScope: WORKFLOW
failureTypes:
- APPLICATION_ERROR
repairActionCode: ROLLBACK_WORKFLOW
retryCount: 0
notificationRules:
- conditions:
- FAILED
executionScope: WORKFLOW
notificationGroupAsExpression: false
notificationGroups:
- General Store
phases:
- type: PCF
computeProviderName: pcf
daemonSet: false
infraMappingName: Harness -PCF_PCF--Pivotal Cloud Foundry- pcf- development
name: Phase 1
phaseSteps:
- type: PCF_SETUP
name: Setup
steps:
- type: PCF_SETUP
name: App Setup
properties:
route: ${infra.pcf.tempRoute}
blueGreen: true
pcfAppName: ${app.name}__${service.name}__${env.name}
maxInstances: 4
resizeStrategy: RESIZE_NEW_FIRST
timeoutIntervalInMinutes: 10
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: Checkout
statefulSet: false
preDeploymentSteps:
- type: ARTIFACT_CHECK
name: Artifact Check
rollbackPhases:
- type: PCF
computeProviderName: pcf
daemonSet: false
infraMappingName: Harness -PCF_PCF--Pivotal Cloud Foundry- pcf- development
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: Checkout
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?