User-Provided Services¶

User-provided service instances allow you connect applications running on Helion Stackato to specified external data services without hard-coding the credentials into the application. Like the built-in data services, user-provided service instances provide the connection information to the application via the VCAP_SERVICES or STACKATO_SERVICES environment variables.

User-provided services act similarly to a credential database for your Helion Stackato application space. When Helion Stackato receives your connection information, it stores it in a JSON object which you can bind to any application within the space.

Working with User-Provided Services¶

Creating a User-Provided Service Instance¶

User-provided service instances are typically used for connecting applications hosted on Helion Stackato to existing external database hosts or clusters. For example, to connect an application to a PostgreSQL database hosted outside of Helion Stackato, run the stackato create-service command:

$ stackato create-service user-provided prod-db-int
Which credentials to use for connections [hostname, port, password]: host, port, database, user, pass
host: dbhost1.example.com
port: 5432
database: prod-django-321
user: ro-web
pass: vsTLP2gs
Creating new service ... OK

Here, the parameter names provided in the first step will later become the keys in the JSON object exposed to the application.

Binding a User-Provided Service Instance¶

After you create a service instance, you can bind it to an application, like any other service, by running the stackato bind-service command:

$ stackato bind-service prod-db-int django-cms
Binding prod-db-int to scaling-demo ...
Stopping Application [django-cms] ... OK
Starting Application [django-cms] ...
OK
http://django-cms.stackato.example.com/ deployed

To bind existing service instances directly from the manifest.yml file, use just the service name(s) in the services: block using YAML list syntax:

services:
- prod-db-int
- prod-tokens

Using a User-Provided Service Instance¶

To display the existing credentials, run the stackato service command:

$ stackato service prod-db-int

prod-db-int
+--------------+------------------------------+
| What         | Value                        |
+--------------+------------------------------+
| Type         | user-provided                |
| Space        | example::example-dev         |
|              |                              |
| Credentials  |                              |
| - database   | prod-django-321              |
| - host       | dbhost1.example.com          |
| - pass       | vsTLP2gs                     |
| - port       | 5432                         |
| - user       | ro-web                       |
|              |                              |
| Applications | django-cms                   |
+--------------+------------------------------+

The STACKATO_SERVICES and VCAP_SERVICES environment variables expose the connection information within the application container. The parameter names you entered while setting up the service instance become keys in the prod-db-int JSON object:

django-cms$ echo $STACKATO_SERVICES |json
{
  "prod-db-int": {
    "database": "prod-django-321",
    "host": "dbhost1.example.com",
    "pass": "vsTLP2gs",
    "port": "5432",
    "user": "ro-web"
  }
}

To pass this information to your application, extract the credentials at runtime by parsing the variable in your application code. For examples, see Language Specific Deployment.

Note

Buildpacks that automatically configure applications for system-provided services can also automatically configure applications for user-provided service instances. For example, the Java Buildpack configures applications to connect to databases if the service has a name or tag that includes postgres, mariadb, or mysql. For supported configuration options, see the documentation or source code of your buildpack.

Other Environment Variables¶

User-provided service instances do not set the DATABASE_URL environment variable or any database-specific URL environment variables.

If your application uses variables in URL format, you must add variables to the application using the stackato set-env command. For example:

$ stackato set-env appname MYSQL_URL mysql://dbuser:pass@10.0.0.55:3306/dbname

You can create these variables regardless of the creation of any user-provided service instances.