LATEST VERSION: 1.9 - CHANGELOG
Redis for PCF v1.9

Using Redis for PCF

Page last updated:

Redis for Pivotal Cloud Foundry (PCF) can be used both via Pivotal Apps Manager and the Cloud Foundry Command Line Interface (cf CLI). Both methods are outlined below.

You can find an example app has to help you get started with Redis for PCF. Download the example app by clicking this link.

For recommendations regarding Redis for PCF service plans and memory allocation, see the service offerings for the on-demand plan and the dedicated and shared plans. .

Prerequisites

To use Redis for PCF with your PCF apps, you need:

  • A PCF installation with Redis for PCF installed and listed in the Marketplace. The three Redis services are listed differently in the marketplace, ensure the service you want to use is enabled.
  • A Space Developer or Admin account on the PCF installation
  • To use the cf CLI, you must log into the org and space containing your app and have a local machine with the following installed:

Use Redis for PCF in a PCF app

Every app and service in PCF is scoped to a space. To use a service, an app must exist in the same space as an instance of the service.

To use Redis for PCF in a PCF app:

  1. Use the cf CLI or Apps Manager to log in to the org and space that contains the app.

  2. Make sure an instance of the Redis for PCF service exists in the same space as the app.

    • If the space does not already have a Redis for PCF instance, create one.
    • If the space already has a Redis for PCF instance, you can bind your app to the existing instance or create a new instance to bind to your app.
  3. Bind the app to the Redis for PCF service instance, to enable the app to use Redis.

Confirm Redis for PCF Service Availability

For an app to use a service, the following two things must be true:

  • The service must be available in the Marketplace for its space.
  • An instance of the service must exist in its space.

You can confirm both of these using the cf CLI as follows:

  1. To find out if a Redis for PCF service is available in the Marketplace:

    1. Enter cf marketplace.
    2. If the output lists p.redis in the service column, on-demand Redis for PCF is available. If the output lists p-redis in the service column, dedicated-VM and shared-VM Redis for PCF is available. If it is not available, ask your operator to install it.
    $ cf marketplace
    Getting services from marketplace in org my-org / space my-space as user@example.com...
    OK
    service             plans                     description
    p-redis             shared-vm, dedicated-vm   Redis service to provide pre-provisioned instances configured as a datastore, running on a shared or dedicated VM.
    p.redis             cache-small, cached-med   Redis service to provide on-demand dedicated instances configured as a cache.
    [...]
    
  2. To confirm that a Redis for PCF instance is running in the space:

    1. Enter cf services.
    2. Any p.redis listings in the service column are service instances of on-demand Redis for PCF in the space. Any p-redis in the service column are service instances of dedicated-VM and shared-VM Redis for PCF.
    $ cf services
    Getting services in org my-org / space my-space as user@example.com...
    OK
    name          service     plan        bound apps    last operation
    my-instance   p.redis     cache-small               create succeeded
    

    You can bind your app to an existing instance or create a new instance to bind to your app.

Create a Redis for PCF Service Instance

Create a Service Instance with the cf CLI

Dedicated-VM and Shared-VM Service

Dedicated-VM and Shared-VM service instances have been pre-provisioned by the operator. This means, if an instance is available, the app developer can provision it immeditately. These plans are both listed under the p-redis service in the Marketplace.

To create an instance of the Redis for PCF Dedicated-VM of Shared-VM service, run this command:

cf create-service p-redis SERVICE_TYPE SERVICE_NAME

where:

  • SERVICE_TYPE is dedicated-vm or shared-vm.
  • SERVICE_NAME is a name for your service instance.
$ cf create-service p-redis dedicated-vm dedicated-instance
Creating service dedicated-instance in org my-org / space my-space as user@example.com... OK

On-Demand Service

Unlike pre-provisioned services, on-demand instances are created asynchronously, not immediately. On-demand plans are listed under the p.redis service in the Marketplace.

To create an instance of the Redis for PCF On-Demand service, run this command:

cf create-service p.redis CACHE_PLAN SERVICE_NAME

where:

  • CACHE_PLAN is cache-small, cache-medium, or cache-large.
  • SERVICE_NAME is a name for your service.
$ cf create-service p.redis cache-small od-instance
Creating service my-ondemand-instance in org my-org / space my-space as user@example.com... OK

As the On-Demand instance can take longer to create, the watch command is helpful as a way to track when your service instance is ready to bind and use.

$ watch cf services
Getting services in org my-org / space my-space as user@example.com... OK name service plan bound apps last operation od-instance p.redis cache-small create succeeded

If you get an error, see Troubleshooting Instances. For information on the on-demand cache plans, see On-Demand Service Plans.

Create a Service Instance with Apps Manager

From within Pivotal Apps Manager, select Marketplace from the left navigation menu under Spaces.

marketplace

Dedicated-VM and Shared-VM Service

  1. Select Redis from the displayed tiles in the Marketplace.

    marketplace_p-redis

  2. Click on the appropriate Select this plan button to select the required Redis Service Plan.

    info_p-redis

  3. In the Instance Name field, enter a name that will identify this specific Redis service instance.

  4. From the Add to Space drop-down list, select the space where you or other users will deploy the apps that will bind to the service.

  5. Click the Add button.

On-Demand Service

  1. Select On-Demand Redis from the displayed tiles in the Marketplace.

    marketplace_predis

  2. Click on the appropriate Select this plan button to select the required Redis Service Plan.

    info_predis

  3. In the Instance Name field, enter a name that will identify this specific Redis service instance.

  4. From the Add to Space drop-down list, select the space where you or other users will deploy the apps that will bind to the service.

  5. Click the Add button.

Bind a Service Instance to Your App

For an app to use a service, you must bind it to a service instance. Do this after you push or re-push the app using cf push.

Bind a Service Instance with the cf CLI

To bind an app to a Redis for PCF instance use $ cf bind-service.

  1. Run cf services to view running service instances.

    $ cf services
    
    Getting services in org system / space apps-manager as admin...
    OK
    
    name                service         plan        bound apps    last operation
    my-instance   p-redis         shared-vm                 create succeeded
    
  2. Enter cf bind-service APP SERVICE_INSTANCE where:

    • APP is the app you want to use the Redis service instance.
    • SERVICE_INSTANCE is the name you supplied when you ran cf create-service.
    $ cf bind-service my-app my-instance
    Binding service my-instance to my-app in org my-org / space test as user@example.com... OK TIP: Use 'cf push' to ensure your env variable changes take effect

Bind a Service Instance with Apps Manager

  1. Select the app that you want to bind to the service. A page displays showing the already bound services and instances for this app.
  2. Click Bind. A list of available services displays.
  3. Click the Bind button for the Redis service you want to bind to this app.
  4. Start or restage your app from the command line, for example:

    $ cf restage my-app
    

Customize an On-Demand Service Instance

The On-Demand Service allows operators and app developers to customize certain configuration variables.

Operators can customize the memory size, org and space access, Redis Client Timeout (default 3600 seconds), Redis TCP Keepalive (default 60 seconds), Redis Max Clients (default 1000), and can enable Lua Scripting.

App developers can customize the following parameters. See the Redis documentation for more detail.

Property Default Options Description
maxmemory-policy allkeys-lru allkeys-lru, noeviction, volatile-lru, allkeys-random, volatile-ttl Sets the behavior Redis follows when `maxmemory` is reached
notify-keyspace-events “” Set a combination of the following characters (e.g., Elg): K, E, g, $, l, s, h, z, x, e, A Sets the keyspace notifications for events that affect the Redis data set
slowlog-log-slower-than 10000 0-20000 Sets the threshhold execution time (seconds). Commands that exceed this execution time are added to the slowlog.
slowlog-max-len 128 1-2024 Sets the length (count) of the slowlog queue.

Customize an On-Demand Instance with the cf CLI

You can customize an instance in two ways:

  • While creating the instance, run:
    cf create-service SERVICE PLAN NAME -c '{"PROPRETY":"SETTING"}'
  • After creating the instance, run:
    cf update-service NAME -c '{"PROPRETY":"SETTING"}'

For both scenarios, the -c flag requires a valid JSON object containing service-specific configuration parameters, provided either in-line or in a file.

$ cf update-service my-instance -c '{"maxmemory-policy":"noeviction"}'

You can pass through mutliple arbitrary parameters:

$ cf update-service my-instance -c '{"maxmemory-policy":"noeviction", "notify-keyspace-events":"El"}'

If the update is not successful, an error is displayed with a description of what went wrong. Here is an example where a hyphen is added to the noeviction setting.

$ cf update-service my-instance -c '{"maxmemory-policy":"no-eviction", "notify-keyspace-events":"El"}'
Updating service instance my-instance as admin...
FAILED
Server error, status code: 502, error code: 10001, message: Service broker error: invalid value "no-eviction" specified for maxmemory-policy

Customize an On-Demand Instance with the Apps Manager

You can customize an instance in two ways:

  • While creating the instance, after you select the plan, click advanced settings.

    am-create
  • After creating the instance, navigate to the instance Settings page.

    am_arbitrary_params

In either of the above cases, do the following:

  1. In the parameters fields enter each property you want to change and its new setting.
    Click the + sign to add more parameter fields.
  2. Depending on the page you are on, click either Add or Update.

If the update is not successful, an error is diplayed with a description of what went wrong. Here is an example where we forgot the hyphen in the volatile-lru setting.

am-error

Access the Redis Service

All Redis for PCF instances are password-protected and require authentication. This is enforced with the requirepass directive in the configuration file.

To retrieve the password, do the following:

  1. Create a service-key for your Redis instance using the command cf create-service-key INSTANCE-NAME SERVICE-KEY-NAME.

  2. Retrieve the password using the command cf service-key INSTANCE-NAME SERVICE-KEY-NAME.

Here is an example of this procedure:

$ cf create-service-key my-instance my-key
Creating service key my-key for service instance my-instance as admin...
OK
$ cf service-key my-instance my-key
Getting key my-key for service instance my-instance as admin...
{
 "host": "10.0.8.4",
 "password": "",
 "port": 6379
}

Redis for PCF data is accessible from apps bound to that instance. Some Redis for PCF users bind the opensource cf-redis-commander app to view instance data. This app is not maintained by the Redis for PCF team, and Pivotal cannot guarantee its performance or security.

Use the Redis Service in Your App

To access the Redis service from your app:

  1. Run cf env APP_NAME with the name of the app bound to the Redis for PCF instance.

  2. In the output, note the connection strings listed in the VCAP_SERVICES > credentials object for the app. Example VCAP_SERVICES

        {
          "p-redis": [{
            "credentials": {
                "host": "10.0.0.11",
                "password": "<redacted>",
                "port": 6379
            },
            "label": "p-redis",
            "name": "redis",
            "plan": "dedicated-vm",
            "provider": null,
            "syslog_drain_url": null,
            "tags": [
            "pivotal",
            "redis"
            ],
            "volume_mounts": []
          }]
        }
    

    Note: You can also search for your service by its name, given when creating the service instance, or dynamically via the tags or label properties.

  3. In your app code, call the Redis service using the connection strings.

For information on how to code your app to use Redis messaging, see About Using Pivotal Redis > Client Documentation in the Redis documentation.

Delete a Redis Instance

When you delete a Redis service instance, all apps that are bound to that service are automatically unbound and any data in the service instance is cleared.

Delete a Redis Instance with the cf CLI

  1. Run cf delete-service SERVICE-INSTANCE-NAME and enter y when prompted to confirm.


    For example:

    $ cf delete-service my-redis-instance
    
    Really delete the service my-redis-instance?> y
    Deleting service my-redis-instance in org system / space apps-manager as admin...
    OK
    
  2. If you had apps that were bound to this service, you might need to restage or re-push your app for the app changes to take effect. For example:

    $ cf restage my-app
    

Delete a Redis Instance with Pivotal Apps Manager

  1. In the service instance Settings page, click Delete Service Instance.

    am_settings

  2. If you had apps that were bound to this service, you might need to restage or re-push your app for the app changes to take effect. For example:

    $ cf restage my-app
    
Create a pull request or raise an issue on the source for this page in GitHub