System Services

The term service has different meanings in various Helion Stackato contexts:

  • A system service is a service types (for example, MySQL, RabbitMQ, Filesystem) available for use on Helion Stackato.
  • A provisioned service is a service allocated to an authenticated user.
  • A service instance (a provisioned service) is an instance of a system service created for an end-user application.
  • A user-provided service instance is a collection of credentials and connection information for external services, specified by users.

To display a list of all system services available on the current Helion Stackato system, as well as a list of provisioned services, run the stackato services command.

A Helion Stackato administrator can configure external data services to work in the same way as core Helion Stackato system services, exposing existing software and infrastructure to Helion Stackato.

Service Brokers

Service brokers are RESTful web services that allow Helion Stackato (or any Cloud Foundry-based PaaS) to connect to services that hosted applications can consume.

Stackato's built-in system services have their own service brokers that handle the provisioning of service instances. You can add your own service brokers to provide custom services (databases, message queues, and so on) to users.

The Cloud Foundry v2 Service Broker API provides a simplified mechanism for connecting data services to the system. A service broker is responsible for:

  • Implementing a REST server that interfaces with the cloud controller
  • Authenticating requests using HTTP basic access authentication
  • Providing an interface to the data service for all provision, unprovision, bind, or unbind events
  • Maintaining a catalog of available services and associated service plans
  • Maintaining a consistent record of the provisioned service instances and bindings
  • Ensuring services are persistent between broker restarts

Using the Universal Service Broker

You can use the Universal Service Broker to connect external services to a Helion Stackato cluster. You can administer the Universal Broker using usbc, a CLI tool available within Helion Stackato instances.

To Install the Universal Service Broker

  1. ssh into the core node.

  2. Add the usb role:

    $ kato role add usb

To Add an External Service (MSSQL)

In the following examples, the MSSQL database is added. You can add any number of additional services using a similar process.

  1. Create and configure your external database instance (for example, a standalone MSSQL server, or a SQL Server Express RDS instance on AWS EC2).

  2. Create a driver instance, specifying the driver name and service name, for example:

    $ usbc create-driver-instance mssql mssql-dev

    Tip

    Note the service name. Developers will need to add it to the services: block of their applications' manifest.yml files and to specify your, for example:

    services:
  ${name}-db: mssql-dev

  3. When prompted, enter the database connection details, for example:

    $ usbc create-driver-instance mssql mssql-dev
    Insert string value for /server [required]> dev-db.abcdefghi1ab.us-west-2.rds.amazonaws.com
    Insert integer value for /port [required]> 1433
    Insert string value for /userid [required]> admin
    Insert string value for /password [required]> myPassword123
    Insert string value for /db_identifier_prefix> stackato-

    Note

    db_identifier_prefix is unique to the MSSQL database. It allows for the database to be uniquely identified on the server.

  4. To display a list of available external services, run the usbc services command:

    $ usbc services
Service Name      Service Id                             Driver Instance   Driver     Description   Tags
mssql-dev         12abf3c4-5678-90de-1b23-fgh456789b01   mssql-dev         mssql                    mssql-dev

  5. To display a list of available service plans, run the stackato services command, for example:

    $ stackato services
============== Service Plans ================

+-----------+---------+-----------------+--------------+------+--------+----------+---------+--------+------+
| Vendor    | Plan    | Description     | Details      | Free | Public | Provider | Version | Broker | Orgs |
+-----------+---------+-----------------+--------------+------+--------+----------+---------+--------+------+
| mssql-dev | default | Default service | default plan | yes  | yes    |          |         | usb    |      |
+-----------+---------+-----------------+--------------+------+--------+----------+---------+--------+------+

=========== Provisioned Services ============

    Note

    The Provisioned Services section remains empty until the service is provisioned by an application.

To Create a Custom Service Broker

You can use the open-source service broker library cf-services-connector to create custom service brokers for Helion Stackato.

  1. ssh into a DEA and install the library:

    $ npm install cf-services-connector

    Note

    You can also include the library in the package.json file of your service broker implementation. For more information, see the documentation of the cf-services-connector library.

  2. Clone or download the echo-service sample application.

  3. Navigate to the /cf-services-connector-nodejs/example/echo-service/config directory and enter the values for authUser, authPassword, and database:encryptionKey into the echo-service.json file,

    Tip

    For detailed description of the configuration of the services: block, see the Cloud Foundry documentation:

  4. Push the echo-service application to Helion Stackato (or any web server that supports Node.js).

  5. Start the application using the node server.js command.

  6. As an administrator, add the service broker to Helion Stackato using the the stackato add-service-broker command, for example:

    $ stackato add-service-broker
Enter name: echo-broker
Enter url: http://echo-service-broker.example.com
Enter username: admin
Enter password: myPassword123
Creating new service broker [echo-broker] ... OK

    The service broker is added to Helion Stackato.

  7. To display a list of the available services, run the stackato services command:

    ============== Service Plans ================

+-----------------+-----------+-----------------------+----------------------------+------+--------+----------+---------+-------------+------+
| Vendor          | Plan      | Description           | Details                    | Free | Public | Provider | Version | Broker      | Orgs |
+-----------------+-----------+-----------------------+----------------------------+------+--------+----------+---------+-------------+------+
| Echo Service    | default   | Echo Service - echoes | This is the first plan     | yes  | yes    |          |         | echo-broker |      |
| Echo Service    | secondary | Echo Service - echoes | This is the secondary plan | no   | no     |          |         | echo-broker |      |
+-----------------+-----------+-----------------------+----------------------------+------+--------+----------+---------+-------------+------+

  8. By default, service plans are created as private. To make the plan available to your organization, run the update-service-plan command, for example:

    $ stackato update-service-plan --vendor "Echo Service" --public default