How-tos

Migrate your app between Bluemix Regions

Share this post:

On the heels of the announcement of a new Bluemix region in Sydney, I thought it would be appropriate to sit down and write a post on migrating your app from one Bluemix region to another. There are a multitude of reasons why I might want to move an app, for example, if I wanted better performance for my users in Australia and Asia by reducing latency.

For this blog post, I am going to migrate a Node.js app that uses a Cloudant database. These steps apply to any app independent of the language, so feel free to reuse these basics for any apps you want to move.

Below are the high-level steps required to migrate your app between regions:

  • Setting up the Cloud Foundry command line
  • Identify what services your app is using
  • Login to the new region
  • Create services in new Bluemix region
  • Deploy your app to the new Bluemix region

Below are two optional steps:

  • Replicate your data to the new Bluemix region
  • Redirect your old URL to your new URL (This won’t be covered in this post).

For those who prefer to follow video instruction, please see below:

Watch the video (https://www.youtube.com/watch?v=X3Ge0beEfdI)

Required steps for migrating an app between regions

Again, this post does not cover setting up SSL and setting up a custom domain and performing load balancing and high-availability between Bluemix regions. An upcoming post will go over those topics.

Setting up the Cloud Foundry command line

To get started you will need the CloudFoundry CLI (command line interface) to perform these changes. If you do not have it setup, download the Cloud Foundry CLI tool and run the installer.

Once you have downloaded and installed the CLI, you will need to connect it to the Bluemix region that hosts your app. Below are URLs for the Bluemix API by region:

  • US South – https://api.ng.bluemix.net
  • London – https://api.eu-gb.bluemix.net
  • Sydney – https://api.au-syd.bluemix.net

You will need to login with the CLI to the region that your Bluemix app is currently running in. For example, if my Bluemix app was in US South, I would use the following:

cf login -a https://api.ng.bluemix.net

Identify what services your app is using

Next we will need to determine what services are bound to the app. To do this, you can do this from the Bluemix UI or you can do it from the command line; let’s do it from the command line. For this example, I am referencing an app called talent-manager:

cf services | grep talent-manager

Of course you would want to replace talent-manager with the name of your application. The command above returns the following:
personality-insights-talent-manager    personality_insights    standard    talent-manager    create succeeded 

talent-manager-db cloudantNoSQLDB Shared talent-manager create succeeded


In my case, I am using two services—Watson Personality Insights and Cloudant. I will need to setup these services in the new Bluemix region.

Login to the new region

Next, we will need to login to the new region. To get the URL for it, refer to the list of region URLs mentioned earlier. In this case, I want to move my app to au-syd, our new region in Sydney, Australia. To connect to au-syd, I would use the following command:

cf login -a https://api.au-syd.bluemix.net

Once there, I need to re-create my services. For Watson Personality Insights, I would use the following to re-create the service:
cf create-service personality_insights tiered personality-insights-talent-manager

For Cloudant, I would use the following to re-create the service:
cf create-service cloudantNoSQLDB Shared talent-manager-db

Deploy your app to the new Bluemix region

Next, you need to deploy your code to the new region. This simply can be done with cf push. My application (if you are interested in the source code it’s available in project talent-manager on GitHub) has a manifest.yml file, so the services will be automatically bound to my new app. If your app doesn’t have a manifest, you can bind your services to your app manually. Let’s go through both cases.

Case #1: Application with a manifest.yml file:

cf push

Now sit back and wait and you will be done!

Case #2: Application without a manifest.yml file:

cf push <em>myappname</em> --no-start
cf bind <em>myappname</em> talent-manager-db
cf bind <em>myappname</em> personality-insights-talent-manager
cf start <em>myappname</em>

The above seems like a lot, but it really isn’t. Let’s go into what it’s doing. The first command cf push myappname --no-start uploads our app code to the new Bluemix region and doesn’t start the app because we need to connect two services to it.

The new two commands (cf bind myappname talent-manager-db and cf bind myappname personality-insights-talent-manager) connect the two services and my app.

The last command cf start myappname starts the application.

That’s basically it. There are a couple more optional steps below that you might consider. With the steps above, you have migrated your app to a new Bluemix region; give yourself a pat on the back!

Optional app migration steps

Since you now have moved your app, what is your app good for without your data? You need to move your data as well. As shown below, if you are using Cloudant, it is pretty easy.

Replicate your data to the new Bluemix region

  1. Login to the Bluemix Dashboard, click DASHBOARD at the top, and then click on your application tile
  2. Click on the Cloudant service and take note of the names of your databases
  3. Click on the “Launch” button in the upper right hand corner
  4. Click on replication on the left
  5. Under “Source Database”, type in the name of your database
  6. Under Target Database, click “New Database”
  7. Click “Create a new remote database”
  8. Formulate the URL for your new database (instructions below)
    To do this we need to use the Cloud Foundry command line to formulate this

    • Run the following, replacing appname with the name of your new application
      cf environment <i>myappname</i>
    • It it going to return a bunch of data (JSON) on the screen, but we are interested in only 1 line. Under a line that contains cloudantNoSQLDB we should see a line that has url in it, example below.credentialsYou want to copy the value to the right of "url:", it will start with https and end in .com.

      Make sure you do not copy the " and the ,

    • Paste the copied value into the browser table that is open to Cloudant Replication for the target database
    • At the end of the url that you pasted enter /mydbname, replacing mydbname with the name of your existing database that you noted earlier
      The final URL should looking something like this (with your db name and usernames and passwords being different, don’t worry the credentials below don’t work):
      https://1acbc2c3-7f46-449a-8cbf-d9f790c37795-bluemix:bc1bddf2c86e45e3a23656a8832f3d6531d237de5ee34eaab5a004572bf260f7@1acbc2c3-7f46-449a-8cbf-d9f790c37795-bluemix.cloudant.com/talent-manager
  9. Click “Replicate”
  10. Go back to the tab with the Bluemix Dashboard and click “Overview” in the top left
  11. At the bottom left side of the box for the Cloudant Service click “Show Credentials”
  12. Copy the value next to "password:", don’t copy the " or the ,
    The value you copied should look like something below:
    bc1bddf2c86e45e3a23656a8832f3d6531d237de5ee34eaab5a004572bf260f7
  13. Go back to the Cloudant Replication tab, paste in the password and click “Continue”

The time required to copy from the old database to the new one will depend on how much data you have in your database.

Redirect your old URL to your new URL

As a reminder, you may need redirection from your old app to your new app. For example, from http://myappname.mybluemix.net to http://myapp.au-syd.mybluemix.net. The redirection won’t be covered in this post, but basically you just need to do a 301 redirection. A 301 is a permanent redirection.

A proper production application would be using a load balancer and custom domain; in this situation you would not have to setup redirection, as you would just need to update your DNS CNAME or A records for your application. Again, instructions on this will be provided in a future blog post.

Feedback

I would love to hear your feedback and any suggestions you have, please reach out to me on Twitter @jsloyer.

IBM Cloud Kubernetes Service - Core Dev Lead

More stories
May 1, 2019

Two Tutorials: Plan, Create, and Update Deployment Environments with Terraform

Multiple environments are pretty common in a project when building a solution. They support the different phases of the development cycle and the slight differences between the environments, like capacity, networking, credentials, and log verbosity. These two tutorials will show you how to manage the environments with Terraform.

Continue reading

April 29, 2019

Transforming Customer Experiences with AI Services (Part 1)

This is an experience from a recent customer engagement on transcribing customer conversations using IBM Watson AI services.

Continue reading

April 26, 2019

Analyze Logs and Monitor the Health of a Kubernetes Application with LogDNA and Sysdig

This post is an excerpt from a tutorial that shows how the IBM Log Analysis with LogDNA service can be used to configure and access logs of a Kubernetes application that is deployed on IBM Cloud.

Continue reading