Connecting Your Application to a Platform Service Instance

To establish communication between the service instance that you have created and your application, you bind your application to the service instance.

Before you begin

Deploy your application to Cloud Foundry.

About this task

When you bind your application to your service instance, Cloud Foundry provisions the service's connection details in the VCAP_SERVICES environment variable. Cloud Foundry runtime uses the VCAP_SERVICES environment variable to communicate with a deployed application about its environment.

You can retrieve the following instance details from VCAP_SERVICES environment variable:

  • An instance_uri for your service instance.
  • A instance_GUID is the zoneID for your service instance.
  • HTTP header information to access your service instance. It includes:
    • http-header-name as Predix-Zone-Id
    • http-header-value
  • An oauth-scope for your instance. The end-user token requires the scope to access the specific service instance.

If you bind to a UAA service instance, you get the following information in addition to instance_uri and instance_GUID:

  • A uaa_instance_issuerId for your instance. The issuerID is required when you create an instance of another service that uses your UAA instance for authentication.

Procedure

  1. Use the Cloud Foundry CLI to log into Cloud Foundry. 
    cf login -a <API_Endpoint>
    Note: If you are a GE employee, you must use the cf login --sso command to log into Cloud Foundry. After you enter your SSO, you will receive a one-time passcode URL. Copy this URL and paste it in a browser to retrieve your one-time passcode. Use this code with the cf command to complete the CF login process.

    The value of <API_Endpoint> is available in the Predix welcome email that you receive when you register for a Predix.io user account. Depending on your Predix.io registration, the <API_Endpoint> value is one of the following:

    • Predix US-West

      https://api.system.aws-usw02-pr.ice.predix.io

    • Predix Europe

      https://api.system.aws-eu-central-1-pr.ice.predix.io

    For example,

    cf login -a https://api.system.aws-usw02-pr.ice.predix.io
    The command produces the following output: 
    Email> <your_predix_login> 
Password> <your_predix_password> 
Authenticating...OK 
Targeted org <your_predix_org> 
Targeted space dev     
API endpoint: https://api.system.aws-usw02-pr.ice.predix.io (API version: <version>)   
User: <your_predix_login> 
Org:  <your_predix_org>  
Space: dev
  2. Bind your application to the service instance by entering the following command:
    cf bind-service <your_app_name> <service_instance_name>
    Your application is bound to the <service_instance_name> instance, and the following message is returned:
    Binding service <service_instance_name> to app <your_app_name> in org predix-platform / space predix as [email protected]...
OK
TIP: Use 'cf restage' to ensure your env variable changes take effect
  3. Verify the binding by entering the following command:
    cf env <your_app_name>

Example

If you bind an application, myApp, to a UAA instance, the following messages are returned:

Getting env variables for app myApp in org predix-platform / space security as [email protected]...
OK
...
  ],
  "predix-uaa": [
        {
        "credentials":
        {
         "issuerId":
          "https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token",
         "uri": 
           "https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io",
          "zone": {
                    "http-header-name": "X-Identity-Zone-Id",
                    "http-header-value": "ff27c315-d027-4d1d-a30c-64f49b369ed9"
                   }
        },
        "label":
        "predix-uaa",
        "name":
        "my_uaa_instance",
        "plan":
        "free",
        "tags":
        []
        }
        ],

In this example, the following values are displayed:

  • uaa_instance_issuerId = https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token
  • uaa_instance_uri = https://ff27c315-d027-4d1d-a30c-64f49b369ed9.predix-uaa.run.aws-usw02-pr.ice.predix.io
  • uaa_instance_GUID = ff27c315-d027-4d1d-a30c-64f49b369ed9

If you bind an application, myApp, to the ACS service instance, the following messages are returned:

Getting env variables for app myApp in org predix-platform / space security as [email protected]...
OK
...
  ],
"predix-acs": [
   {
    "credentials": {
     "uri": "https://predix-acs.run.aws-usw02-pr.ice.predix.io",
     "zone": {
      "http-header-name": "Predix-Zone-Id",
      "http-header-value": "9615a95a-9275-4a82-926d-89f06cbe04e1",
      "oauth-scope": "predix-acs.zones.9615a95a-9275-4a82-926d-89f06cbe04e1.user"
     }
    },
    "label": "predix-acs",
    "name": "acs-sample-instance",
    "plan": "Tiered",
    "provider": null,
    "syslog_drain_url": null,
    "tags": []
   }
  ],

In this example, the following values are displayed:

  • acs_instance_uri = https://predix-acs.run.aws-usw02-pr.ice.predix.io
  • acs_instance_GUID = 9615a95a-9275-4a82-926d-89f06cbe04e1
  • http-header-name = Predix-Zone-Id
  • http-header-value = 9615a95a-9275-4a82-926d-89f06cbe04e1
  • oauth-scope = predix-acs.zones.9615a95a-9275-4a82-926d-89f06cbe04e1.user