Configuring SSL/TLS Termination at HAProxy

Both Pivotal Application Service (PAS) and Isolation Segments for Pivotal Platform include an HAProxy instance.

HAProxy is appropriate to use in a deployment when features are needed that are offered by HAProxy but are not offered by the CF Routers or IaaS-provided load balancers such as with Azure load balancers. These include filtering of protected domains from trusted networks.

While HAProxy instances provide load balancing for the Gorouters, HAProxy is not itself highly available. For production environments, use a highly-available load balancer to scale HAProxy horizontally. The load balancer does not need to terminate TLS or even operate at layer 7 (HTTP), as it can provide layer 4 load balancing of TCP connections. Use of HAProxy does not remove the need for CF Routers. The Gorouter must always be deployed for HTTP apps, and the TCP router for non-HTTP apps.

You can generate a self-signed certificate for HAProxy if you do not want to obtain a signed certificate from a well-known certificate authority.

Terminate SSL/TLS at HAProxy

To configure SSL termination on HAProxy in Pivotal Platform:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Pivotal Application Service tile in the Installation Dashboard.

  3. Select Networking.

  4. Configure the following based on the IaaS of your Pivotal Platform deployment.

    If your Pivotal Platform deployment is on: Then configure the following: See also:
    OpenStack or vSphere Decide whether you want your HAProxy to be highly available.
    • If you need highly available HAProxy:
      1. Choose an IP address for each HAProxy instance on the subnet where you deployed Pivotal Platform.
      2. In the HAProxy IPs field of the Networking pane, enter the IP addresses you have selected for your HAProxy instances.
      3. Configure your load balancer (for example, F5 or NSX) to forward domain names to the HAProxy IP addresses.
    • If you do not require high availability (for example, you are setting up a development environment):
      1. Skip setting up the load balancer.
      2. Choose one IP address for the single HAProxy instance.
      3. Configure DNS to point at the IP address. For more information, see How to Set Up DNS for HAProxy.
    For more information, see the Configure Networking section of the Configuring PAS topic.
    AWS, GCP or Azure
    1. Leave the HAProxy IP address blank.
    2. In the Resource Config page of PAS tile, locate the HAProxy job.
    3. In the Load Balancer column for the HAProxy job, specify the appropriate IaaS load balancer resource.

    For more information, see the Configure Networking section of the Configuring PAS topic.

  5. In the Certificates and private keys for HAProxy and Router field, click the Add button to define at least one certificate keypair for HAProxy and Router. For each certificate keypair that you add, assign a name, enter the PEM-encoded certificate chain and PEM-encoded private key. You can either upload your own certificate or generate an RSA certificate in PAS. For options and instructions on creating a certificate for your wildcard domains, see the Creating a Wildcard Certificate for Pivotal Platform Deployments in the Providing a Certificate for Your TLS Termination Point topic.

  6. In the Minimum version of TLS supported by HAProxy and Router, select the minimum version of TLS to use in HAProxy communications. HAProxy use TLS v1.2 by default. If you need to accommodate clients that use an older version of TLS, select a lower minimum version. For a list of TLS ciphers supported by the HAProxy, see the TLS Cipher Suites section of the TLS Connections in PCF topic.

  7. Under HAProxy forwards requests to Router over TLS, leave Enable selected and provide the back end certificate authority.

  8. If you want to use a specific set of TLS ciphers for HAProxy, configure TLS cipher suites for HAProxy. Enter an ordered, colon-separated list of TLS cipher suites in the OpenSSL format. For example, if you have selected support for an earlier version of TLS, you can enter cipher suites supported by this version. For a list of TLS ciphers supported by the HAProxy, see the TLS Cipher Suites section of the TLS Connections in PCF topic.

  9. If you expect requests larger than the default maximum of 16.384 KB, enter a new value in bytes for HAProxy request maximum buffer size. You may need to do this, for example, to support apps that embed a large cookie or query string values in headers.

  10. If you want to force browsers to use HTTPS when making requests to HAProxy, select Enable in the HAProxy support for HSTS field and complete the following optional configuration steps:

    • Maximum age in seconds for the HSTS request. HAProxy will force HTTPS requests from browsers for the duration of this setting. The maximum age is one year, or 31536000 seconds.
    • Enable the Include subdomains checkbox to force browsers to use HTTPS requests for all component subdomains.
    • Enable the Enable preload checkbox to force instances of Google Chrome, Firefox, and Safari that access your HAProxy to refer to their built-in lists of known hosts that require HTTPS, of which HAProxy is one. This ensures that the first contact a browser has with your HAProxy is an HTTPS request, even if the browser has not yet received an HSTS header from HAProxy.
  11. (Optional) If you are not using SSL encryption or if you are using self-signed certificates, you can enable the Disable SSL certificate verification for this environment checkbox. This also disables SSL verification for route services.

    Note: Use this checkbox only for development and testing environments. Do not select it for production environments.

  12. (Optional) If you do not want HAProxy or the Gorouter to accept any non-encrypted HTTP traffic, select the Disable HTTP on HAProxy and Router checkbox.

  13. Under TLS termination point, select Infrastructure load balancer.

  14. (Optional) If your Pivotal Platform deployment uses HAProxy and you want it to receive traffic only from specific sources, use the following fields:

    • HAProxy protected domains: Enter a comma-separated list of domains from which Pivotal Platform can receive traffic.
    • HAProxy trusted CIDRs: Optionally, enter a space-separated list of CIDRs to limit which IP addresses from the protected domains can send traffic to Pivotal Platform.
  15. Click Save.

Set Up DNS for HAProxy

You only need to perform this procedure if you are using one instance of HAProxy such as in a development environment. If you would like HAProxy to be highly available, you must have a load balancer in front of it. In this case, you point DNS at the load balancer.

To use a single instance HAProxy load balancer in a vSphere or OpenStack deployment, create a wildcard A record in your DNS and configure some fields in the PAS product tile.

  1. Create an A record in your DNS that points to the HAProxy IP address. The A record associates the System domain and Apps domain that you configure in the Domains pane of the PAS tile with the HAProxy IP address.

    For example, with cf.example.com as the main subdomain for your Cloud Foundry (CF) deployment and an HAProxy IP address 203.0.113.1, you must create an A record in your DNS that serves example.com and points *.cf to 203.0.113.1.

    Name Type Data Domain
    *.cf A 203.0.113.1 example.com
  2. Use the Linux host command to test your DNS entry. The host command should return your HAProxy IP address.

    Example:

    $ host cf.example.com
    cf.example.com has address 203.0.113.1
    $ host anything.example.com
    anything.cf.example.com has address 203.0.113.1