Installing and Configuring Concourse for PCF

IMPORTANT: The Concourse for PCF tile is currently in Beta and is meant for evaluation and test purposes only. Do not use this product in a PCF production environment.

This topic explains how to install the Concourse tile for Pivotal Cloud Foundry (PCF). Before installation, make sure you have installed compatible versions of Pivotal Cloud Foundry Operations Manager (Ops Manager) and Elastic Runtime.

Step 1: Configure Your Ops Manager Director

The Concourse tile requires the following configurations in the Ops Manager Director tile for your deployment.

  1. In the Ops Manager tile Director Config pane, select the Enable Post Deploy Scripts checkbox. opsman director config enabled post deploy scripts

  2. In the Create Networks pane, select or add a network to designate as a service network and select the Service Network checkbox.

    This configures a network in your PCF environment as a Service Network. This network flexibly provisions virtual machines (VMs) on demand. network-concourse configured a service network

  3. Create a new subnet for your service network by following the instructions for your IaaS in the table below:

    IaaS Steps
    AWS
    1. Navigate to the VPC Dashboard your AWS console.
    2. Click Subnets, then Create Subnet.
    3. Complete the following fields:
      • Name tag: Enter a name, such as concourse-subnet.
      • Set VPC to pcf-vpc.
      • Set CIDR block to a valid available range.
    4. Click Yes, Create to create the subnet.
    5. In the Create Networks pane of the Ops Manager Director tile, enter the Subnet ID into the VPC Subnet ID field.
    Azure The following steps assume a default installation of PCF on Azure as outlined in Launching an Ops Manager Director Instance on Azure.
    1. Create a subnet using the Azure CLI: $ azure network vnet subnet create $RESOURCE_GROUP pcf-net concourse-subnet --address-prefix 10.0.48.0/24
    2. In the Create Networks pane in Ops Manager, enter the following for the Service Network you added in Step 2 above:
      • Azure Network Name: pcf-net/concourse-subnet
      • CIDR: 10.0.48.0/24
      • Reserved IP Ranges: 10.0.48.0-10.0.48.4
      • DNS: 168.63.129.16
      • Gateway: 10.0.48.1
    GCP
    1. In the GCP console, select Networking > Networks.
    2. Click Create Network.
    3. Complete the following fields:
      • Name: Enter a network name, such as concourse-subnet.
      • Region: Set this value to match your region, such as us-west-1.
      • IP address range: Specify a CIDR block, such as 10.1.0.0/24.
    4. Click Create.
    5. In the Ops Manager Director Settings tab, select the Create Networks pane. Enter the name of the subnet in the Google Network Name field. Ensure you enter your subnet name in the following format: NETWORK-NAME/SUBNET-NAME/REGION-NAME
    OpenStack
    1. In the OpenStack console, select the tenant that hosts your PCF Deployment.
    2. Select Network > Networks and click Create Network.
      1. Enter a Network Name.
      2. Set the Admin State to UP.
      3. Select the Create Subnet checkbox.
      4. Click Next.
    3. Complete the fields for the subnet:
      1. Enter a Subnet Name.
      2. Enter a CIDR block in the Network Address field. Example: 192.168.123.0/24.
      3. For IP Version, choose IPv4.
      4. Enter a Gateway IP. Example: 192.168.123.1.
      5. Click Next.
      6. Enter an IP Allocation Pool. Example: 192.168.124.2,192.168.124.254.
      7. Enter the DNS Name Servers for your organization. Example: 10.87.8.10 10.87.8.11.
    4. Click Create to create the network and subnet.
    5. Select Network > Routers.
    6. Select the router of your PCF deployment.
    7. Click Interfaces > Add Interface.
      1. Select the subnet you created.
      2. For the IP address, use the IP Gateway from the subnet you created.
      3. Click Submit.
    8. In the Ops Manager Director tile, select the Create Networks pane.
      1. Create a new Service Network and complete the fields:
        1. Enter the Network ID of the OpenStack network you just created.
        2. Enter the same CIDR block you used when creating the OpenStack subnet.
        3. For Reserved IP Ranges, enter the same values that you specified for the IP allocation pool when creating the OpenStack subnet.
        4. Enter the DNS you used when creating the OpenStack subnet.
      2. For Gateway, enter the value for the IP Gateway that you specified when adding an interface to the OpenStack network.
    vSphere
    1. Create a new virtual network with a valid CIDR block.
    2. Enter the name of the subnet into the Ops Manager Director Settings tab > Create Networks pane > vSphere Network Name field.

Step 2: Import the Concourse Tile

  1. Download the Concourse tile from Pivotal Network.

  2. Upload the Concourse tile to Ops Manager. Concourse tile in Ops Man Installation Dashboard

  3. Click the Concourse tile to begin setup.

Step 3: Assign AZs and Networks

The following steps describe how to configure the two networks that Concourse requires to function properly. Ops Manager manages the first network, which hosts the master-shared Concourse components. The BOSH Director manages the second network, a service network that hosts the worker VM pool. BOSH provisions service instances on demand from this pool to specific orgs and spaces.

  1. Click Assign AZs and Networks.

  2. Under Network, designate a network to host the shared components of the Concourse service. See the Concourse Architecture documentation for details. The shared components include the following:

    • Air Traffic Controller (ATC)
    • TSA, which registers worker VMs
    • Concourse database
    • On-Demand Service Broker (ODB)
  3. Under Service Network, designate a network to host worker pool VMs. Applying AZ and Network config changes

Step 4: Configure ERT Certificate

In this step, you configure Concourse to use the same certification as the Elastic Runtime load balancer.

Note: If your Elastic Runtime instance uses HAProxy, skip this step.

Record your certificate from the Elastic Runtime tile > Networking pane > Router SSL Termination Certificate and Private Key and insert it into the Concourse tile > ERT Config pane > Cloud Foundry Access Point CA Certificate field.

Self-signed cert in ERT Certificate config

Step 5: Secure Access to the ATC

Concourse interfaces with users through the Fly CLI and a web interface. To secure connections between the Concourse UI and the ATC, you must provide an SSL certificate and key. The certificate can be signed a trusted authority, signed by an authority within your organization, or self-signed.

  1. Click ATC TLS. ATC TLS configuration

  2. Paste your TLS certificate and private key into the TLS Certificate and Private Key fields. If you do not have a certificate from an external authority, you can generate one using either of the options below.

    Note: Certificates signed by the Operations Manager Certificate Authority are not technically self-signed, but they are referred to as ‘self-signed certificates’ in the Ops Manager GUI and throughout this documentation.

    (Option 1) Generate a certificate signed by the Operations Manager Certificate Authority

    a. Click Generate RSA certificate.
    b. At the prompt, enter a wildcard subdomain, such as *.system.EXAMPLE.com, for the System Domain configured in your Elastic Runtime tile > Domains pane.

    Note: If you are using a certificate signed by Ops Manager, you must supply the root CA certificate to any developer before they can use the Fly CLI. Retrieve the root CA certificate from Ops Manager by selecting your username at the top right, choosing Settings, and clicking Download Root CA Cert within the Advanced pane.

    (Option 2) Generate a self-signed certificate from the command line

    a. Use the following command to generate a private key:

    $ openssl genrsa -out my-private-key.pem 2048
    b. Generate a Certificate Signing Request (CSR):
    $ openssl req -sha256 -new -key my-private-key.pem -out csr.pem
        You are about to be asked to enter information that will be incorporated
        into your certificate request.
        What you are about to enter is what is called a Distinguished Name or a DN.
        There are quite a few fields but you can leave some blank
        For some fields there will be a default value,
        If you enter '.', the field will be left blank.
        ...
        Country Name (2 letter code) [AU]:US
        State or Province Name (full name) [Some-State]:California
        Locality Name (eg, city) []:San Francisco
        Organization Name (eg, company) [Internet Widgits Pty Ltd]:Pivotal Inc.
        Organizational Unit Name (eg, section) []:Engineering
        Common Name (e.g. server FQDN or YOUR name) []:*.run.xyzzy-20.pez.pivotal.io
        Email Address []:support@pivotal.io
        ...
        Please enter the following 'extra' attributes
        to be sent with your certificate request
        A challenge password []:
        An optional company name []:Pivotal Inc.
        
    At the Common Name prompt, enter a wildcard subdomain for the System Domain configured in your Elastic Runtime tile > Domains pane. For example *.system.EXAMPLE.com.
    c. Generate your TLS certificate my-certificate.pem from your CSR and private key:
    $ openssl x509 -req -days 365 -in csr.pem -signkey my-private-key.pem -out my-certificate.pem

  3. Select the TLS authority for the certificate you pasted in. If you are using a certificate trusted by a widely trusted authority, specify an Intermediate trust chain.

Step 6: Configure Service Plans

Configure the service plans offered by your service broker:

  1. Click On-Demand Plans.

    On-Demand Plans configuration

  2. Enter a Plan Name and a meaningful Plan Description. Separate spaces in the plan name with hyphens.

  3. Enter the Minimum Concourse Worker Instances and the Maximum Concourse Worker Instances that a developer can specify for their service instance.

  4. Select a Concourse Worker VM type to use for your workers. Pivotal recommends a minimum of 32 GB of disk space.

  5. Select the Worker VM Availability Zones (AZs) that you want to balance the workers across.

Step 7: Configure Errands

  1. Review the Errands pane and ensure that each errand is set to On.

  2. If you are installing on vSphere for the first time, you must set Run Concourse Smoke Tests errands to Off. Otherwise, the smoke tests will fail because vSphere does not allocate an IP to HAProxy until after the installation. After your initial installation, you can set this errand to On.

Errands configuration

Step 8: Configure Resources

  1. Click Resource Config and review the instance number and types required for all Concourse jobs, including the number of worker VMs you want to run, and make sure your IaaS account can provision these resources.

    Resource Config

  2. Complete the procedure below that corresponds to your IaaS.

    For this IaaS…Follow this procedure…
    AWSConfigure for AWS.
    AzureConfigure for Azure.
    GCPConfigure for GCP.
    OpenStackConfigure for OpenStack.
    vSphereConfigure for vSphere.

Configure for AWS

For AWS, Concourse requires its own load balancer, separate from the load balancer or HAProxy that Elastic Runtime uses. In this step, you create the load balancer for Concourse.

The HAProxy is enabled by default, but you can disable it and point your ELB directly to the ATC.

  1. Under EC2 Dashboard > Load Balancers, create a new Classic Load Balancer named concourse for the same VPC and subnet that contain your Ops Manager.

  2. Choose one of the following options:

    Note: Pivotal recommends choosing Option 1 to use the HAProxy, which is enabled by default.

    • (Option 1) Use the Concourse HAProxy and an ELB:
      • In the EC2 Dashboard > Load Balancers > Listeners tab, configure the port forwarding as shown below.
        • HTTP 80HTTP 80
        • HTTPS 443HTTPS 443
        • SSL 2222SSL 2222
      • For the port rules above, ensure that you set the protocol to TCP, with no certificate associated with the rules. Concourse for PCF requires unencrypted traffic forwarded to ATC.
      • Copy the new ELB name from the EC2 Dashboard > Load Balancers in AWS and paste it in the HAProxy row under ELB Names.
    • (Option 2) Use only an ELB for Concourse:
      • Set the number of HAProxy instances to 0 to disable HAProxy.
      • Add the name of your ELB in the Concourse row, under ELB Names. With this configuration, the ELB routes traffic directly from your ELB to Concourse.
      • In the EC2 Dashboard > Load Balancers > Listeners tab, configure the port forwarding as follows:
        • TCP 80TCP 8080
        • TCP 443TCP 4443
        • TCP 2222TCP 2222
  3. Continue to Step 9: Configure Stemcell.

Configure for Azure

  1. Ensure that HAProxy is set to the Automatic value under Instances.
  2. Create a network load balancer by running the following command from the Azure CLI:

    $ azure network lb create $RESOURCE_GROUP concourse-lb $LOCATION
    

  3. Create a public IP address for the load balancer:

    $ azure network public-ip create $RESOURCE_GROUP concourse-lb-ip $LOCATION --allocation-method Static
    

  4. Record the IP address for use in Step 11: Set Up DNS.

  5. Assign the public IP address to the load balancer frontend-ip:

    $ azure network lb frontend-ip create $RESOURCE_GROUP concourse-lb concourse-fe-ip --public-ip-name concourse-lb-ip
    

  6. Create an address pool for the load balancer:

    $ azure network lb address-pool create $RESOURCE_GROUP concourse-lb concourse-vms
    

  7. Run the following commands to create rules for the load balancer:

    • $ azure network lb rule create $RESOURCE_GROUP concourse-lb http --protocol tcp --frontend-port 80 --backend-port 80
    • $ azure network lb rule create $RESOURCE_GROUP concourse-lb https --protocol tcp --frontend-port 443 --backend-port 443
    • $ azure network lb rule create $RESOURCE_GROUP concourse-lb diego-ssh --protocol tcp --frontend-port 2222 --backend-port 2222
  8. Return to the Resource Config pane in Ops Manager and enter the name of the load balancer, concourse-lb, in the HAProxy row of the Load Balancers column.

  9. Continue to Step 9: Configure Stemcell.

Configure for vSphere

For vSphere, Concourse requires its own HAProxy, separate from the load balancer or HAProxy that Elastic Runtime uses. You cannot change the number of Concourse HAProxy instances in the Resource Config pane, but you can set the number of instances for the Concourse and Worker jobs.

Configure for GCP

  1. Ensure that HAProxy is set to the Automatic value under Instances.
  2. Create a new load balancer in the GCP console:

    1. Select Networking > Load balancing.
    2. Click Create Load Balancer.
    3. Under TCP Load Balancing, click Start configuration.
    4. Keep the default settings, From internet to my VMs and No (TCP), and click Continue.
    5. Enter a name for the load balancer, such as atc-lb.
    6. Select Backend configuration and specify a Name and Region.
    7. Select Frontend Configuration.
      1. In the IP dropdown, select Create IP Address.
      2. Enter the following ports for the IP address you created: 80, 443, and 2222.
    8. Click Create.
    9. In the Concourse tile > Resource Config pane, enter the name of your load balancer in the Load Balancers column of the HAProxy row. Prepend the name of the load balancer with tcp:, such as tcp:atc-lb.
  3. Continue to Step 9: Configure Stemcell.

Configure for OpenStack

  1. Ensure that HAProxy is set to the Automatic value under Instances.

  2. Continue to Step 9: Configure Stemcell.

Step 9: Configure Stemcell

  1. If prompted in the Stemcell pane, download the indicated stemcell version. If your PCF deployment runs on Azure, download the stemcell from bosh.io. For all other IaaS providers, download the stemcell from Pivotal Network. Stemcell

Step 10: (Optional) Configure Networking

Complete this step if you need to specify a proxy for outgoing HTTP requests from containers.

  1. Select the Networking pane.
  2. Complete the following fields:
    • HTTP Proxy URL: Enter the URL of your HTTP proxy
    • HTTPS Proxy URL Enter the URL of your HTTPS proxy

Step 11: (Optional) Configure Github OAuth

Complete this step if you want your users and teams to be able to use Github orgs and teams for OAuth authorization.

  1. In your browser, navigate to the Register a new OAuth application page in Github.
  2. Complete the following fields:
    • Application name: Enter the name of your app, such as Concourse.
    • Homepage URL: Optionally, enter a URL for your app.
    • Application description: Enter a short description of your app.
    • Application callback URL: Enter the URL of ATC in your Concourse deployment, such as https://p-concourse.YOUR-SYSTEM-DOMAIN.
  3. Click Register application.
  4. Record the Client and Secret values when they appear.
  5. In the Concourse for PCF tile in Ops Manager, select the Github OAuth pane.
  6. Paste the Client and Secret values into the corresponding fields.

Step 12: Deploy Concourse for PCF

Return to the Installation Dashboard and click Apply Changes.

Step 13: Set up DNS

Complete the procedure below that corresponds to your IaaS.

For this IaaS…Follow this procedure…
AWSSet up for AWS.
AzureSet up for Azure.
GCPSet up for GCP.
OpenStackSet up for OpenStack.
vSphereSet up for vSphere.

Set up for AWS

Create a new DNS CNAME record for p-concourse.YOUR-SYSTEM-DOMAIN that points to the DNS Name of the ELB from Step 8: Configure Resources. Use the Route53 dashboard or contact your network administrator.

Set up for Azure

Create a DNS A record for p-concourse.YOUR-SYSTEM-DOMAIN that points to the static IP of the load balancer you created in Step 8: Configure Resources. You may need to contact your network administrator to create this new DNS entry.

Set up for vSphere

Create a new DNS record for p-concourse.YOUR-SYSTEM-DOMAIN that points to the IP address of HAProxy:

  1. Navigate to the Status tab in the Concourse tile and record the IP address for the HAProxy job.
  2. Create a DNS A record that points to this IP address. You may need to contact your network administrator to create this new DNS entry.

Set up for GCP

Create a DNS A record for p-concourse.YOUR-SYSTEM-DOMAIN that points to the static IP of the load balancer you created in Step 8: Configure Resources. You may need to contact your network administrator to create this new DNS entry.

Set up for OpenStack

  1. In the OpenStack console, select the project for your PCF deployment.
  2. Select Compute > Instances.
  3. In the row that corresponds to your HAProxy instance, choose Associate Floating IP from the dropdown in the Actions column.

    Note: If you do not know the IP address of your HAProxy, you can find it under the Status tab of the Concourse tile.

  4. Choose an IP Address from the dropdown and record its value.
  5. Click Associate.
  6. Create a DNS A record for p-concourse.YOUR-SYSTEM-DOMAIN that points to the floating IP that you just created. You may need to contact your network administrator to create this new DNS entry.

Step 14: Set up Access Rights for the Service Network

Complete the procedure below that corresponds to your IaaS.

For this IaaS…Follow this procedure…
AWSSet up for AWS.
AzureSet up for Azure.
GCPSet up for GCP.
OpenStackSet up for OpenStack.
vSphereSet up for vSphere.

Set up for AWS

  1. Navigate to the VPC Dashboard of your AWS console.
  2. Click Subnets.
  3. Locate the Subnet ID you created in Step 1: Configure your Ops Manager Director.
  4. Click Route Table, then the Route Table link, followed by the entry in the Route Table.
  5. Click Routes > Edit > Add another route.
  6. Enter the following values:
    1. Destination: 0.0.0.0/0
    2. Target: Select i-xxxxxxxx NAT Instance

Set up for Azure

No configuration in needed because the default pcf-nsg security group already allows all traffic.

Set up for vSphere

Ensure that the service network you created in Step 1: Configure your Ops Manager Director allows outbound access to the Internet.

Set up for GCP

  1. In the GCP console, select Networking > Firewall rules.
  2. Click Create Firewall Rule and complete the following fields:
  3. Click Create.

Set up for OpenStack

In the Network Topology view in the OpenStack console, ensure that the service network you created in Step 1: Configure your Ops Manager Director allows outbound access to the Internet.


Congratulations! Now the Concourse service broker is running in your PCF environment, and developers can use the Cloud Foundry Command Line Interface (cf CLI) to create their own service instances of Concourse within their PCF spaces.

Create a pull request or raise an issue on the source for this page in GitHub