In the realm of cloud-native applications, developers see the world as a combination of scalable runtime and externalized services. Application runtime gets scaled horizontally, managing the number of instances of each app against its expected workload. Data integration is addressed through the orchestration of external services, binding them to app instances in a one-to-many model. The orchestration fabric that supports this design worldview is commonly known as Platform-as-a-Service, or PaaS.

AppFog, Heroku, and other PaaS providers offer a service broker facility that allows providers of an external service to register their services to the runtime environment, giving developers easy access from the PaaS environment command line. Services that work at Heroku or other Cloud Foundry-based platforms are extremely easy to migrate to the CenturyLink AppFog environment using the CenturyLink Add-On framework. This article describes the process using the example of a Database-as-a-Service service provider, GraphStory.

Using a Manifest for Service Description

Any service implementation must provide provisioning endpoints to allow a user to bind to the service, as described in the CloudFoundry API documentation. These endpoints allow a user application to bind to the service using an http PUT, and to release from the service, using an http DELETE.

The next step is describing your service in a manifest file that identifies your service, describes its endpoints, and describes the billing plans available for the service. The AppFog manifest format is almost identical to other formats. Graphstory’s format for Heroku is as follows:

{
    "id": "graphstory",
    "api": {
        "config_vars": [
            "GRAPHSTORY_URL"
        ],
        "regions": [
            "us"
        ],
        "password": “XXXXXXXX",
        "sso_salt": “XXXXXXXX",
        "production": {
            "base_url": "https://console.graphstory.com/heroku/resources",
            "sso_url": "https://console.graphstory.com/heroku-sso/login"
        },
        "test": {
            "base_url": "https://console.graphstory.dev/heroku/resources",
            "sso_url": "https://console.graphstory.dev/heroku-sso/login"
        }
    }
}

The corresponding manifest file for AppFog is:

{
    "id": "graphstory",
    "name": "Graph Story",
    "plans": [
        {
        "id": "developer",
        "name": "developer",
        "description": "Free developer instance of Enterprise Neo4j"
        }
        ],
    "api": {
        "config_vars": [
        "GRAPHSTORY_URL"
        ],
        "sso_salt": “XXXXXXXXX",
        "production": {
            "base_url": "https://console.graphstory.com/app-fog/resources",
            "sso_url": "https://console.graphstory.com/app-fog-sso/login"
        },
        "test": {
            "base_url": "https://console.graphstory.dev/app-fog/resources",
            "sso_url": "https://console.graphstory.dev/app-fog-sso/login"
        },
        "password": “XXXXXXXX"
    }
}

There are three simple differences between the two:

  • the ‘name’ value
  • the ‘plans’ section
  • the URLs comprising the base URLs and SSO URLs.

That’s all there is to it. The underlying code for the URLs is the same and can be reused.

Creating the Provisioning Service

The provisioning service that needs to be created receives the provisioning request. This service receives a GET request, and is responsible for returning parameters necessary for the user to bind to the service. The details of the service request can be found on our KB article on the Provisioning Request. The protocol of the request is identical to the Heroku request, with the exception that we do not currently support a callback URL.

Further details on this file structure can be found in our KB article that covers the migration from Heroku to Appfog.

Using Kiri to Test Integration

Having created this file, you need to load it to AppFog. To do this, you need a CenturyLink Cloud account and the kiri loading tool.

  1. Sign up for a CenturyLink Cloud account.
  2. Obtain the kiri package.

The CenturyLink Cloud Environment

Having created the CLC account and downloaded the correct binary, you are almost done.

  1. The next step is logging in to the CLC environment as follows:

    $ kiri login myusername --authendpoint https://addon.ctl.io

  2. This logs you in for further activity. You then load the manifest file:

    $ kiri manifest upload graphstory.json

  3. Once your service manifest is uploaded successfully, you can test provision and deprovision of a service instance using the Service Manifest defined api/test/base_url URL value:

    $ kiri test provision graphstory 1234567890

  4. This provisions an instance of the graphstory service with a fake instance ID 1234567890. You can also use the ID to deprovision the instance.

  5. If successful, deprovision the service instance as follows:

    $ kiri test deprovision graphstory 1234567890

That is all there is to joining the CenturyLink AppFog marketplace. Thanks for reading. For more information, please consult our Knowledge Base or contact CenturyLink Support directly.