Backing services

• 1: Backing Services Overview
• 2: Use managed services
• 3: Configure user-provided services
• 4: User Provided Service Templates
• 5: Configure NFS volumes

1 - Backing Services Overview

Backing services are any processes that the App contacts over the network during its operation. In traditional operating systems, these services could have been accessed over the network, a UNIX socket, or could even be a sub-process. Examples include the following:

• Databases — for example: MySQL, PostgreSQL
• File storage — for example: NFS, FTP
• Logging services — for example: syslog endpoints
• Traditional HTTP APIs — for example: Google Maps, WikiData, Parcel Tracking APIs

Connecting to backing services over the network rather than installing them all into the same machine allows developers to focus on their App, independent security upgrades for different components, and flexibility to swap implementations.

Backing services in Kf

Kf supports two major types of backing services:

• Managed services: These services are created by a service broker and are tied to the Kf cluster.

• User-provided services: These services are created outside of Kf, but get can be bound to apps in the same way as managed services.

2 - Use managed services

Find a service

Use the kf marketplace command to find a service you want to use in your App. Running the command without arguments will show all the service classes available. A service class represents a specific type of service e.g. a MySQL database or a Postfix SMTP relay.

$ kf marketplace
5 services can be used in Space "test", use the --service flag to list the plans for a service

Broker      Name        Space      Status  Description
minibroker  mariadb                Active  Helm Chart for mariadb
minibroker  mongodb                Active  Helm Chart for mongodb
minibroker  mysql                  Active  Helm Chart for mysql
minibroker  postgresql             Active  Helm Chart for postgresql
minibroker  redis                  Active  Helm Chart for redis

Service classes can have multiple plans available. A service plan generally corresponds to a version or pricing tier of the software. You can view the plans for a specific service by supplying the service name with the marketplace command:

$ kf marketplace --service mysql
Name    Free  Status  Description
5-7-14  true  Active  Fast, reliable, scalable, and easy to use open-source relational database system.
5-7-27  true  Active  Fast, reliable, scalable, and easy to use open-source relational database system.
5-7-28  true  Active  Fast, reliable, scalable, and easy to use open-source relational database system.

Provision a service

Once you have identified a service class and plan to provision, you can create an instance of the service using kf create-service:

$ kf create-service mysql 5-7-28 my-db
Creating service instance "my-db" in Space "test"
Waiting for service instance to become ready...
Success

Services are provisioned into a single Space. You can see the services in the current Space by running kf services:

$ kf services
Listing services in Space: "test"
Name   ClassName  PlanName  Age   Ready  Reason
my-db  mysql      5-7-28    111s  True   <nil>

You can delete a service using kf delete-service:

$ kf delete-service my-db

Bind a service

Once a service has been created, you can bind it to an App, which will inject credentials into the App so the service can be used. You can create the binding using kf bind-service:

$ kf bind-service my-app my-db
Creating service instance binding "binding-my-app-my-db" in Space "test"
Waiting for service instance binding to become ready...
Success

You can list all bindings in a Space using the kf bindings command:

$ kf bindings
Listing bindings in Space: "test"
Name                  App     Service  Age  Ready
binding-my-app-my-db  my-app  my-db    82s  True

Once a service is bound, restart the App using kf restart and the credentials will be in the VCAP_SERVICES environment variable.

You can delete a service binding with the kf unbind-service command:

$ kf unbind-service my-app my-db

3 - Configure user-provided services

Users can leverage services that aren’t available in the marketplace by creating user-provided service instances. Once created, user-provided service instances behave like managed service instances created through kf create-service. Creating, listing, updating, deleting, binding, and unbinding user-provided services are all supported in Kf.

Create a user-provided service instance

The name given to a user-provided service must be unique across all service instances in a Space, including services created through a service broker.

Deliver service credentials to an app

A user-provided service instance can be used to deliver credentials to an App. For example, a database admin can have a set of credentials for an existing database managed outside of Kf, and these credentials include the URL, port, username, and password used to connect to the database.

The admin can create a user-provided service with the credentials and the developer can bind the service instance to the App. This allows the credentials to be shared without ever leaving the platform. Binding a service instance to an App has the same effect regardless of whether the service is a user-provided service or a marketplace service.

The App is configured with the credentials provided by the user, and the App runtime environment variable VCAP_SERVICES is populated with information about all of the bound services to that App.

A user-provided service can be created with credentials and/or a list of tags.

kf cups my-db -p '{"username":"admin", "password":"test123", "some-int-val": 1, "some-bool": true}' -t "comma, separated, tags"

This will create the user-provided service instance my-db with the provided credentials and tags. The credentials passed in to the -p flag must be valid JSON (either inline or loaded from a file path).

To deliver the credentials to one or more Apps, the user can run kf bind-service.

Suppose we have an App with one bound service, the user-provided service my-db defined above. The VCAP_SERVICES environment variable for that App will have the following contents:

{
  "user-provided": [
    {
      "name": "my-db",
      "instance_name": "my-db",
      "label": "user-provided",
      "tags": [
        "comma",
        "separated",
        "tags"
      ],
      "credentials": {
        "username": "admin",
        "password": "test123",
        "some-int-val": 1,
        "some-bool": true
      }
    }
  ]
}

Update a user-provided service instance

A user-provided service can be updated with the uups command. New credentials and/or tags passed in completely overwrite existing ones. For example, if the user created the user-provided service my-db above, called kf bind-service to bind the service to an App, then ran the command.

kf uups my-db -p '{"username":"admin", "password":"new-pw", "new-key": "new-val"}'

The updated credentials will only be reflected on the App after the user unbinds and rebinds the service to the App. No restart or restage of the App is required. The updated VCAP_SERVICES environment variable will have the following contents:

{
  "user-provided": [
    {
      "name": "my-db",
      "instance_name": "my-db",
      "label": "user-provided",
      "tags": [
        "comma",
        "separated",
        "tags"
      ],
      "credentials": {
        "username": "admin",
        "password": "new-pw",
        "new-key": "new-val"
      }
    }
  ]
}

The new credentials overwrite the old credentials, and the tags are unchanged because they were not specified in the update command.

4 - User Provided Service Templates

Before you begin

• Ensure your service is running and accessible on the same network running your Kf cluster.
• Ensure you have targeted the Space where you want to create the service.

Create the user-provided instance

The following examples use the most common parameters used by applications to autoconfigure services. Most libraries use tags to find the right bound service and a URI to connect.

MySQL

MySQL libraries usually expect the tag mysql and the following parameters:

uri

Example mysql://username:password@host:port/dbname. The MySQL documentation can help with creating a URI string. The port is usually 3306.

username

The connection username, required by some libraries even if included in uri.

password

The connection password, required by some libraries even if included in uri.

kf cups service-instance-name \
  -p '{"username":"my-username", "password":"my-password", "uri":"mysql://my-username:my-password@mysql-host:3306/my-db"}' \
  -t "mysql"

RabbitMQ

RabbitMQ libraries usually expect the tag rabbitmq and the following parameters:

uri

Example amqp://username:password@host:port/vhost?query. The RabbitMQ documentation can help with creating a URI string. The port is usually 5672.

Example:

kf cups service-instance-name \
  -p '{"uri":"amqp://username:password@host:5672"}' \
  -t "rabbitmq"

Redis

Redis libraries usually expect the tag redis and the following parameters:

uri

Example redis://:password@host:port/uery. The IANA Redis URI documentation can help with creating a URI string. The port is usually 6379.

Example for Redis with no AUTH configured:

kf cups service-instance-name \
  -p '{"uri":"redis://redis-host:6379"}' \
  -t "redis"

Example for Redis with AUTH configured:

kf cups service-instance-name \
  -p '{"uri":"redis://:password@redis-host:6379"}' \
  -t "redis"

Bind your App

Once the user-provided service has been created, you can bind your App to the user provided service by name, just like a managed service:

kf bind-service application-name service-instance-name

What’s next

• Learn about how the credentials are injected into your app.

5 - Configure NFS volumes

Kf supports mounting NFS volumes using the kf marketplace.

Prerequisites

• Your administrator must have completed the NFS platform setup guide.

Create an NFS service instance

Run kf marketplace to see available services. The built-in NFS service appears on the list if NFS is enabled on the platform.

Broker           Name  Namespace  Description
nfsvolumebroker  nfs              mount nfs shares

Mount an external filesystem

Create a service instance

To mount to an existing NFS service:

kf create-service nfs existing SERVICE-INSTANCE-NAME -c '{"share":"SERVER/SHARE", "capacity":"CAPACITY"}'

Replace variables with your values.

• SERVICE-INSTANCE-NAME is the name you want for this NFS volume service instance.
• SERVER/SHARE is the NFS address of your server and share.
• CAPACITY uses the Kubernetes quantity format.

Confirm that the NFS volume service appears in your list of services. You can expect output similar to this example:

$ kf services
...
Listing services in Space: demo-space
Name                Type      ClassName         PlanName  Age    Ready  Reason
filestore-nfs       volume    nfs               existing  6s     True   <nil>
...

Bind your service instance to an App

To bind an NFS service instance to an App, run:

kf bind-service YOUR-APP-NAME SERVICE-NAME -c '{"uid":"2000","gid":"2000","mount":"MOUNT-PATH","readonly":true}'

Replace variables with your values.

• YOUR-APP-NAME is the name of the App for which you want to use the volume service.

• SERVICE-NAME is the name of the volume service instance you created in the previous step.

• uid:UID and gid:GID specify the directory permissions of the mounting share.

• MOUNT-PATH is the path the volume should be mounted to within your App.

• (Optional) "readonly":true is an optional JSON string that creates a read-only mount. By default, Volume Services mounts a read-write file system.

  Note: Your App automatically restarts when the NFS binding changes.

You can list all bindings in a Space using the kf bindings command. You will see output similar to this example:

$ kf bindings
...
Listing bindings in Space: demo-space
Name                                     App           Service             Age  Ready
binding-spring-music-filestore-nfs       spring-music  filestore-nfs       71s  True
...

Access the volume service from your App

To access the volume service from your App, you must know which file path to use in your code. You can view the file path in the details of the service binding, which are visible in the environment variables for your App.

View environment variables for your App:

kf vcap-services YOUR-APP-NAME

Replace YOUR-APP-NAME with the name of your App.

The following is example output of the kf vcap-services command:

$ kf vcap-services YOUR-APP-NAME
{
  "nfs": [
    {
      "instance_name": "nfs-instance",
      "name": "nfs-instance",
      "label": "nfs",
      "tags": [],
      "plan": "existing",
      "credentials": {
        "capacity": "1Gi",
        "gid": 2000,
        "mount": "/test/mount",
        "share": "10.91.208.210/test",
        "uid": 2000
      },
      "volume_mounts": [
        {
          "container_dir": "/test/mount",
          "device_type": "shared",
          "mode": "rw"
        }
      ]
    }
  ]
}

Use the properties under volume_mounts for any information required by your App.