LATEST VERSION: 2.3 - RELEASE NOTES

Using TLS

This topic describes how developers can use TLS to secure the communication between their apps and the MySQL for Pivotal Cloud Foundry (PCF) v2 service.

To use TLS with your apps, the PCF operator must have completed the procedures in Preparing for TLS and enabled TLS in the tile configuration when performing the steps in Configure Security.

The procedures below describe how to enable TLS for your service instances, and how to activate TLS for your Java and Spring apps to use TLS. If your app is not written in Java or Spring, see Modifying Apps for TLS.

If you want to use the mysql client to establish a TLS connection to a MySQL for PCF service instance that has TLS enabled, see Establish a TLS Connection to a Service Instance.

Enable TLS

You cannot automatically configure encryption for a service instance when creating the instance. Instead, you must enable encryption for the instance after creating it.

Perform the following steps to enable TLS for an existing service instance:

  1. Create a service key, specifying the name of your service instance and a name for the service key.

    Run the following command:

    cf create-service-key SERVICE-INSTANCE SERVICE-KEY
    


    Where:

    • SERVICE-INSTANCE is the name of the existing service instance that you want to secure communication to and from.
    • SERVICE-KEY is a name for the service key you are creating.

      For example:
      $ cf create-service-key my-service-instance my-service-key
  2. Retrieve the service key credentials, specifying the same values as above. For example:

    $ cf service-key my-service-instance my-service-key
    {
    "hostname": "10.1.16.3",
    "jdbcUrl":    "jdbc:mysql://10.1.16.3:3306/service_instance_db?user=6bf07ae455a14064a9073cec8696366c\u0026password=a22aaa2a2a2aaaaa\u0026",
    "name": "service_instance_db",
    "password": "a22aaa2a2a2aaaaa",
    "port": 3306,
    "uri": "mysql://6bf07ae455a14064a9073cec8696366c:a22aaa2a2a2aaaaa@10.244.16.3:3306/service_instance_db?reconnect=true",
    "username": "6bf07ae455a14064a9073cec8696366c"
    }
    
    If you are using a leader-follower topology, the command displays hostnames and multiple IP addresses rather than hostname and a single IP address. For example:
    {
    "hostname": ["10.1.16.3", "10.1.16.4"],
    [...]
    

  3. In the output, record the value for hostname or hostnames.

  4. Update the existing service instance to enable TLS by providing configuration parameters.

    Run the following command:

    cf update-service SERVICE-INSTANCE -c '{"enable_tls": ["HOSTNAME"]}'
    


    Where:

    • SERVICE-INSTANCE is the name of the existing service instance that you want to secure communication to and from.
    • HOSTNAME is the value for hostname or hostnames retrieved above. If you are using a leader-follower topology, enter the comma-separated list of IP addresses that appears under hostnames.

    For example:

    $ cf update-service my-service-instance -c '{"enable_tls": ["10.1.16.3"]}'
    
    If you receive the following error message, the operator has not enabled TLS. See the procedures in Preparing for TLS and Configure Security.
    TLS has not been enabled in the service offering. Speak with your Operator to make this available.

  5. Updating the service instance takes a moment. To check the status of the operation, run cf services and locate your service instance. For example:

    $ cf services
    Getting services in org example / space development as admin...
    OK
    
    name service plan bound apps last operation my-service-instance p.mysql db-small update in progress
    When the operation has completed, update succeeded appears under last operation.

  6. Delete the service key. For example:

    $ cf delete-service-key my-service-instance my-service-key
    

Activate TLS for Java and Spring Apps

For your apps to use TLS, you must update them to request encrypted communications when connecting to the MySQL data service.

The procedure for updating your app depends on the app’s language and framework.

Java and Spring apps automatically detect TLS, while apps written in other languages and frameworks must be manually modified to use TLS:

  • If your app is written in Java or Spring, perform the procedure below.
  • If your app is not written in Java or Spring, see Modifying Apps for TLS.

WARNING: Any apps using an existing service instance must be rebound after enabling TLS for the instance.

To activate TLS for Java and Spring apps, you must stop and rebind the app to the service instance after enabling TLS on the instance. Perform the following steps:

  1. Stop the app. For example:
    $ cf stop my-app
  2. Unbind the app from the service instance. For example:
    $ cf unbind-service my-app my-service-instance
  3. Re-bind the app to the service instance. For example:
    $ cf bind-service my-app my-service-instance
  4. Restage the app. For example:
    $ cf restage my-app

Your app should now communicate securely with the MySQL service instance.

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