Preparing for Upgrading MySQL for PCF

Warning: MySQL for PCF v2.5 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

Page last updated:

This topic explains how to prepare for upgrading the MySQL for Pivotal Cloud Foundry (PCF) service and existing service instances.

Overview

MySQL for PCF v2.5 requires app bindings and service keys to use BOSH DNS and does not support bindings that use IP addresses. However, apps that use MySQL for PCF v2.4 and earlier service instances can bind to their instances using an IP address.

Note: In this topic, the app bindings and service keys that use IP addresses instead of BOSH DNS are referred to as deprecated.

To avoid failure and app downtime when upgrading to MySQL for PCF to v2.5, all apps that bind to the service using an IP address must be re-bound and restarted before you upgrade. You must also re-create all service keys that use IP addresses.

To give developers time to update their apps and service keys, do the upgrade procedures on this page in advance of upgrading the MySQL for PCF tile.

Check for Bindings with IP Addresses

To check for apps or service keys that use IP addresses:

  1. Locate the BOSH deployment name for your MySQL service broker by running:

    bosh deployments
    
  2. Record the BOSH deployment name for the MySQL service broker. This looks like pivotal-mysql-GUID.

  3. Confirm which apps or service keys are using IP addresses or do not use TLS by running:

    bosh -d pivotal-mysql-GUID run-errand find-deprecated-bindings
    

    Where pivotal-mysql-GUID is the BOSH deployment name for your MySQL service broker.

    For example:

    $ bosh -d pivotal-mysql-e3ddd36247fe5b923caf run-errand find-deprecated-bindings
    Using environment '10.0.0.5' as client 'ops_manager'
    
    Using deployment 'pivotal-mysql-e3ddd36247fe5b923caf'
    
    Task 148
    
    Task 148 | 02:42:08 | Preparing deployment: Preparing deployment (00:00:01)
    Task 148 | 02:42:09 | Running errand: dedicated-mysql-broker/63f9ad1e-998e-451e-8c6e-f6211958f6fb (0) (00:00:03)
    Task 148 | 02:42:12 | Fetching logs for dedicated-mysql-broker/63f9ad1e-998e-451e-8c6e-f6211958f6fb (0): Finding and packing log files (00:00:01)
    
    Task 148 Started Tue Dec 18 02:42:08 UTC 2018
    Task 148 Finished Tue Dec 18 02:42:13 UTC 2018
    Task 148 Duration 00:00:05
    Task 148 done
    
    Instance   dedicated-mysql-broker/63f9ad1e-998e-451e-8c6e-f6211958f6fb
    Exit Code  0
    Stdout     +---------------------------+--------------------------------------+------------------------+--------------------------+--------------------+-------------------+-----------------------------+
               |          SERVICE          |             SERVICE GUI             |          ORG           |          SPACE           | APP OR SERVICE KEY |       TYPE        |           REASON            |
               +---------------------------+--------------------------------------+------------------------+--------------------------+--------------------+-------------------+-----------------------------+
               | tlsDB                     | a999db0b-176e-4ac8-8342-d72b338d1f0c | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | user-cli           | ServiceKeyBinding | no tls                      |
               | tlsDB                     | a999db0b-176e-4ac8-8342-d72b338d1f0c | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | user-cli           | ServiceKeyBinding | no dns: hostname="10.0.8.6" |
               | upgrade-outdated-instance | 34f26746-fb46-4f14-87bc-e1ddce26f340 | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | cs-accept          | AppBinding        | no dns: hostname="10.0.8.5" |
               | tlsDB                     | a999db0b-176e-4ac8-8342-d72b338d1f0c | MYSQL-ORG-upgrade-test | MYSQL-SPACE-upgrade-test | cs-accept-tls      | AppBinding        | no dns: hostname="10.0.8.6" |
               +---------------------------+--------------------------------------+------------------------+--------------------------+--------------------+-------------------+-----------------------------+
    
  4. Do the Remove IP-Based Bindings procedure below for any apps or service keys that list no dns in the REASON column of the output table.

    Note: You do not need to replace bindings listed as no tls.

Remove IP-Based Bindings

Warning: When you delete a service key, you lose the triggers, routines, and events created by the user. If you want to keep your triggers, routines, or events, contact Pivotal Support.

Some of the following steps require coordination with your app developers. You must remove any app bindings and service keys that use IP addresses.

To remove deprecated app bindings and service keys:

  1. If you have deprecated app bindings, developers must replace their IP-based app bindings with bindings that use BOSH DNS. They must do this for every app binding that is deprecated. See Re-Bind Apps to Use DNS below.
  2. If you have deprecated service keys, operators must replace their IP-based service keys with keys that use BOSH DNS. They must do this for every service key that is deprecated. See Re-create Service Keys below.
  3. Upgrade your service instances to be compatible with BOSH DNS. See Upgrade Service Instances below.

Re-Bind Apps to Use DNS

To replace your deprecated app bindings with new app bindings that use DNS hostnames, developers must do the following for each app binding listed in the log error above:

  1. Unbind your app from your service instance by running:

    cf unbind-service APP-NAME SERVICE-INSTANCE
    
  2. Re-bind your app to your service instance by running:

    cf bind-service APP-NAME SERVICE-INSTANCE
    
  3. Restart your app by running:

     cf restart APP-NAME
    

    After you restart your app, your app can connect to the database and resume service.

  4. Ensure that the deprecated app bindings has been replaced by running:

     bosh -d pivotal-mysql-GUID run-errand find-deprecated-bindings
    

    Confirm that no dns does not appear in the REASON column in the output table for the app binding.

Re-create Service Keys

To replace your deprecated service keys with new service keys that use DNS hostnames, operators must do the following for each service key listed in the log error above:

  1. Delete the service key by running:

    cf delete-service-key SERVICE-INSTANCE SERVICE-KEY
    
  2. Re-create the service key by running:

    cf create-service-key SERVICE-INSTANCE SERVICE-KEY
    
  3. Ensure that the service key has been replaced by running:

     bosh -d pivotal-mysql-GUID run-errand find-deprecated-bindings
    

    Confirm that no dns does not appear in the REASON column in the output table for the service key.

  4. Notify your developers that they must update connection strings that use the service key. For example, connection strings for apps that are not managed by your PCF deployment.

    Note: If you have any apps that cannot resolve BOSH DNS hostnames, you can use the DNS Lookup app to resolve the hostnames to IP addresses. See DNS Lookup App.

Upgrade Service Instances

To upgrade your service instances, operators must :

  1. Notify the developers who own the apps and service keys listed by the find-deprecated-bindings above that you are upgrading all service instances. This can impact connectivity to the database.
  2. Log in to the BOSH Director by doing the procedure in Log in to the BOSH Director VM.
  3. Locate the BOSH deployment name for your MySQL service broker by running:

    bosh deployments
    
  4. Record the BOSH deployment name for the MySQL service broker. This looks like pivotal-mysql-GUID.

  5. Upgrade all service instances by running:

    bosh -d pivotal-mysql-GUID run-errand upgrade-all-service-instances
    

    Where pivotal-mysql-GUID is the value you recorded in the previous step.

  6. Notify your developers that, at this time, apps that do hostname validation cannot establish a TLS connection to the database. These apps output an error similar the following example:

    failed to perform TLS handshake with host "10.0.8.5:3306": x509: certificate is valid for 127.0.0.1, not 10.0.8.5