IBM Cloud Docs
Migrating your service binding

Migrating your service binding

Let's take a common cloud-native app that follows the 12-factor app principles, simplify and update the code, and create both a Cloud Foundry and a Code Engine version. These versions serve as an example for the discussion of migration steps and deployment aspects.

The sample app is a typical web app that is written in Node.js (JavaScript) and uses the Express web framework. An IBM Cloudant NoSQL database serves as the backing service to store data displayed by the app. As typical for cloud-native, 12-factor apps, the sample app is based on discrete, reusable components that act as microservices to make up the overall app. Both the deployed Node.js program and the database can be scaled, improved, or even replaced independently. The components work together because of how they are configured and by using well-defined APIs.

Simple cloud-native app with backend database service.
Figure 1. Simple cloud-native app with backend database service.

The IBM Cloudant database can be configured to work as an attached resource with the app versions that are deployed to Cloud Foundry and Code Engine. For simplicity, the solution is kept to these two components.

Creating the service bind

This sample application requires a Cloudant database to store content. You can configure access to Cloudant by manually injecting environment variables, but the typical process is through service binding. The relationship between the app and its backing services is explicitly stated, so credentials are created and automatically injected into the runtime environment. Cloud Foundry provides the credentials as part of the VCAP_SERVICES object. Code Engine mimics this object through its CE_SERVICES environment variable.

Both the Cloud Foundry and the Code Engine applications attach to the database service. The code deployed to Code Engine can be considered a different, newer version of the Cloud Foundry app. It continues to be bound to the same database service, but through other means.

To bind the Code Engine version of the app to a service,

  1. Access your Cloudant database instance. If you do not have one, create one.
  2. Create service credentials (IAM service key) for your Cloudant instance with a descriptive name. Specify the IAM role (Manager, Writer, or Reader) for your app. Pick a role with the least level of privilege required for your application.
  3. Bind the service to the app by using the existing credential. Code Engine can create credentials for you when you bind a service. However, by creating your own credential, you can track and even change the privilege independently of Code Engine.

For this sample app with Cloudant as the database service, run the following commands to create the service key Cloudant-CF2CE-Manager with the Manager role and then use it to bind the service.

ibmcloud resource service-key-create Cloudant-CF2CE-Manager Manager --instance-name Cloudant-CF2CE

ibmcloud ce app bind --name cf2ce-app --service-instance Cloudant-CF2CE --service-credential Cloudant-CF2CE-Manager

If your Cloud Foundry app connects to a service through a user-provided service, create an app that uses secrets or configmaps for Code Engine. By using secrets and configmaps, you can inject the service credentials into the runtime environment and manage them as a named object within the Code Engine project.

Migrating the code

Usually, code migration is straight-forward. For example, instead of reading from an environment variable that is called VCAP_SERVICES for Cloud Foundry, your code must read from CE_SERVICES for Code Engine. In addition, be aware of subtle differences in how services are named due to the method that services are made available through brokers for Cloud Foundry and through IAM-based resource management for Code Engine.

Depending on the programming language, your code might use a code library or module to access the Cloud Foundry runtime environment, locally injected configuration ("dotenv"), and more. Those sections must be adapted.

Compare the code in the server.js file in these two application examples.

Staging your application migration

If your application cannot be down while you move it from Cloud Foundry to Code Engine, consider performing the code migration with an intermediate step.

  • 1cloudfoundry_base: The Cloud Foundry code base as the initial source. This app runs only in Cloud Foundry.
  • 2cf_ce_intermediate_hybrid: Add code to also support a Code Engine deployment. This application runs in both Cloud Foundry and Code Engine.
  • 3codeengine_target: Finally, move to a Code Engine-only code base after the actual project migration is completed. This application runs only in Code Engine.

This approach is beneficial because you can continue to maintain or enhance the code base during the migration process, independently of the deployment environment.

Building your code and running your app

When you are finished setting up your service bind, migrating your code, and preparing to stage your migration, it is time to build your code. Follow the steps in the first migration tutorial to build your code from a local source. If you want to use the console to build your code, your code must be in Git-hub. For more information, see Deploying your app from source code.

Next steps

  1. Just starting your migration? Check out Getting started.
  2. Compare Cloud Foundry terminology with Code Engine.
  3. Try out Code Engine with a local build tutorial.
  4. Migrating your service binding (current page)
  5. Learn about scaling and traffic management.
  6. Find Code Engine equivalents to Cloud Foundry commands.
  7. Still have questions? Try the Migrating Cloud Foundry applications to Code Engine FAQ.

Other information