Using a9s Redis

This topic describes how to use a9s Redis.

Use a9s Redis with an Application

To use a9s Redis with an application, create a service instance and bind the service instance to your app. For more information about managing service instances, see Managing Service Instances with the cf CLI.

View the a9s Redis Service

After the tile is installed, you can see the a9s-redis32 and its service plans appear in your CF marketplace. Run cf marketplace to see the service listing:

´´´bash $ cf marketplace Getting services from marketplace in org test / space test as admin... OK service plans description a9s-redis32 redis-single-small, redis-single-big, redis-cluster-small, redis-cluster-big This is the a9s Redis 32 service. ´´´

Create a Service Instance

To provision a Redis database, run cf create-service. For example.

´´´bash $ cf create-service a9s-redis32 redis-single-small my-redis-service ´´´

Depending on your infrastructure and service broker utilization, it might take several minutes to create the service instance.

Run the cf services command to view the creation status. This command displays a list of all your service instances. To view the status of a specific service instance, run cf service NAME-OF-YOUR-SERVICE.

Bind an Application to a Service Instance

After your database is created, run cf bind-service to bind the service to your application:

´´´bash $ cf bind-service a9s-redis-app my-redis-service ´´´

Restage or Restart Your Application

To enable your application to access the service instance, run cf restage or cf restart to restage or restart your application.

Obtain Service Instance Access Credentials

After a service instance is bound to an application, the credentials of your Redis database are stored in the environment variables of the application. Run cf env APP-NAME to display the environment variables.

You can find the credentials in the VCAP_SERVICES key.

$ cf env a9s-redis-app
Getting env variables for app a9s-redis-app in org test / space test as admin...
OK

System-Provided:
{
 "VCAP_SERVICES": {
  "a9s-redis": [
   {
    "credentials": {
      "host": "EXAMPLE-master.service.dc1.consul",
      "hosts": [
        "EXAMPLE-redis-0.node.dc1.consul",
        "EXAMPLE-redis-1.node.dc1.consul",
        "EXAMPLE-redis-2.node.dc1.consul"
      ],
      "load_balanced_host": "EXAMPLE.service.dc1.consul",
      "password": "EXAMPLE-PWD",
      "port": 6379,
      "sentinel_master_name": "EXAMPLE-master",
      "sentinel_port": 26379
    },
    "label": "a9s-redis",
    "name": "my-redis-service",
    "plan": "redis-single-non-persistent-small",
   }
  ]
 }
}
...

You can use the host and password values to connect to your database with a Redis client, by using only the host variable, your application does not need to know anything about Redis Sentinel. However if you use the hosts variable or the load_balanced_host, your application needs to know about Redis Sentinel and being able to work with Redis Sentinel. This means, by using the host variable, the failover is handled by the logic within our service and if you use one of the other variables, the failover needs to be handled by your application.

Best Practices

There are some best practices for using service binding information in apps in a separate document.

Delete an a9s Redis Service Instance

WARNING: Before deleting a service instance, you must backup data stored in your database. This operation cannot be undone and all the data is lost when the service is deleted.

Before you can delete a service instance, you must unbind it from all apps.

List Available Services

Run cf services to list available services.

$ cf services

Getting services in org test / space test as admin...
OK

name                 service       plan                   bound apps        last operation
my-redis-service     a9s-redis     redis-single-small     a9s-redis-app     create succeeded

This example shows that my-redis-service is bound to the a9s-redis-app application.

Unbind a Service Instance

Run cf unbind-service to unbind the service from your app:

$ cf unbind-service a9s-redis-app my-redis-service

Delete a Service Instance

After unbinding the service, it is no longer bound to an app. Run cf delete-service to delete the service:

$ cf delete-service my-redis-service

It may take several minutes to delete the service. Deleting a service deprovisions the corresponding infrastructure resources. Run the cf services command to view the deletion status.

Upgrade the Service Instance to another Service Plan

Once created, you can upgrade your service instance to another, larger service plan. A larger service plan provides more CPU, RAM and storage. For more information, see the Update a Service Instance of the Managing Service Instances with the cf CLI topic.

$ cf update-service my-redis-service -p a-bigger-plan

Here are the plans you can upgrade to depending on the one you are currently using:

  • If you are currently using the redis-single-small plan, you can upgrade to redis-single-big plan.
  • If you are currently using the redis-cluster-small plan, you can upgrade to redis-cluster-big plan.

Change RDB Persistence Settings

a9s Redis supports RDB persistence with point in time snapshots. This setting can be changed by the user.

Default Behavior

SettingEffect
save 900 1Create a snapshot after 900 seconds if 1 write operations occurred.
save 300 10Create a snapshot after 300 seconds if 10 write operations occurred.
save 60 10000Create a snapshot after 300 seconds if 10 write operations occurred.

Configuring RDB

You can configure RDB according to the needs of your apps by providing customer settings. This setting must follow the original Redis configuration for RDB -c {"snapshot": "['save 900 1', 'save 300 10']"}.

´´´bash $ cf update-service my-redis-service -c {"snapshot": "['save 900 1', 'save 300 10']"} ´´´

In this example, it configures to snapshot the Redis database according to the following rules:

SettingEffect
save 900 1Create a snapshot after 900 seconds if 1 write operations occurred.
save 300 10Create a snapshot after 300 seconds if 10 write operations occurred.

Cache Only

You can disable snapshots and use Redis as cache only by creating the service with the following customer setting -c '{"snapshot": "[]"}'.

The command is:

  $ cf update-service my-redis-service -c {"snapshot": "[]"}

For more information, see the snapshot settings in the documentation of Redis Persistence.

Change Maxmemory Policy

With the maxmemory_policy, you can configure a9s Redis which key to remove when maxmemory is reached. There are several configurable behaviors. noeviction is the default.

SettingEffect
volatile-lruremove the key with an expire set using an LRU algorithm
allkeys-lruremove any key according to the LRU algorithm
volatile-randomremove a random key with an expire set
allkeys-randomremove a random key, any key
volatile-ttlremove the key with the nearest expire time (minor TTL)
noevictiondon't expire at all, just return an error on write operations

You can use -c {"maxmemory-policy": "volatile-ttl"} to update the maxmemory-policy.

  $ cf update-service my-redis-service -c {"maxmemory-policy": "volatile-ttl"}

For more information, see the maxmemory-policy settings in the self documented redis.conf.

HA Cluster with Redis Sentinel

a9s Redis uses Redis Sentinel to provide a high available replication set. Redis Sentinel is monitoring the several nodes, takes care about the automatic failover and is able to send notifcation when something in the cluster is changing.

a9s Redis provides two settings to adjust the cluster behaviour. min_slaves_max_lag and down_after_milliseconds

SettingEffect
min_slaves_max_lagTime in seconds how long the master waits before he stops accepting writes when slaves are no more reachable. Default is 10 seconds. min-slaves-to-write can not be changed, it is fxed set to 1. See redis.conf
down_after_millisecondsNumber of milliseconds the master should be unreachable in order to consider it in S_DOWN state. Default is 30000 ms. See sentinel.conf
  $ cf update-service my-redis-service -c {"min_slaves_max_lag": "10"}
  $ cf update-service my-redis-service -c {"down_after_milliseconds": "30000"}

Add a Graphite Endpoint

If you want to monitor your service with Graphite, you can set an endpoint to where to information will be sent with the cf update-service command. This command expects the -c flag and a JSON string containing the graphite and metrics_prefix keys. Depending on your graphite provider the metrics_prefix might require that each metrics must start with an API key in their name. You can also change the interval within the data is send to the endpoint. Do to this modify interval the default is 10s.

$ cf update-service my-rabbitmq-service -c '{ "graphite": ["yourspace.your-graphite-endpoint.com:12345"], "metrics_prefix": "your-api-key.my-cluster-rabbitmq", "interval": "5"}'

Add a Syslog Endpoint

The cf update-service command used with the -c flag can let you stream your syslog to a third-party service. In this case, the command expects a JSON string containing the syslog key. You can also change the interval for the syslog with the same key than for the graphite endpoint interval.

$ cf update-service my-rabbitmq-service -c '{ "syslog": ["logs4.your-syslog-endpoint.com:54321"], "interval": "5" }'

Cloud Foundry Application Security Groups

This topic describes how to check whether a security group was created.

Each a9s Data Service will automatically create and update Cloud Foundry security groups in order to protected service instances to be accessed by applications not running in the same Cloud Foundry applications space. To get a better understanding about Security Groups you can have a look on the Understanding Application Security Groups topic.

Get Service Instance GUID

Run cf service INSTANCE_NAME --guid to get the guid of the service instance.

$ cf service my-rabbitmq --guid
ca16f111-5073-40b7-973a-156c75dd3028

Check available Security Groups

To see all available security groups use cf security-groups.

$cf security-groups
Getting security groups as demo@anynines.com
OK

     Name                                         Organization     Space
#0   public_networks
#1   dns
#2   tcp_open
#3   guard_432fb752-876d-443b-a311-a075f4df2237   demonstrations   demo
#4   guard_ca16f111-5073-40b7-973a-156c75dd3028   demonstrations   demo

There we can see a security group with the named guard_ca16f111-5073-40b7-973a-156c75dd3028 was successfully created.

NOTE: in some circumstances the connection between the application and the service instance is not possible, in this case check if a security group was created.

Redis Custom Parameters

As an end user you have the opportunity to customize your service instance by using custom parameters. Custom parameters are passed on to a service instance by using the -c switch of the cf CLI commands cf create-service and cf update-service. For example

cf update-service myredis -c '{"maxclients": 1000}'

would set the maxclients limit to the value 1000 for the service instance mypg.

You don't have to utilize those settings. There are sane defaults in place that fit your service plan well.

Every parameter corresponds to a property in the configuration file for the respective Redis version.

lazyfree-lazy-eviction

The default value is 'no'. The allowed values are 'yes' and 'no'.

This custom param is not usable for instances running Redis 3.2.

lazyfree-lazy-expire

The default value is 'no'. The allowed values are 'yes' and 'no'.

This custom param is not usable for instances running Redis 3.2.

lua-time-limit

The default value is 5000. The value must be an integer.

maxclients

The default value is 10000. The value must be an integer > 0.

maxmemory-policy

The default value is 'volatile-lru' The allowed string values are 'volatile-lru', 'volatile-lfu', 'volatile-random', 'volatile-ttl', 'allkeys-lru', 'allkeys-lfu', 'allkeys-random' and 'noeviction'.

maxmemory-samples

The default value is 5. The value must be an integer >= 0.

notify-keyspace-events

This paramter allows to configure the Redis Keyspace Notifications.

The default value is '' which means by default keyspace events are disabled. The allowed value must include the following characters only: K, E, g, $, l, s, h, z, x, e, A and t.

Backup and Restore Service Instances

a9s Messaging provides an easy way to create backups and restore if needed. For a more detailed description, please see the a9s Service Dashboard documentation.

Make a Service Instance Locally Available

It is possible to access any of the a9s Data Services locally. That means you can connect with a local client to the service for any purpose such as debbuging. CF provides a smart way to create SSH forward tunnels via a pushed application. For more information about this feature see the Accessing Apps with SSH section of the CF documentation.

First of all you must have an application bound to the service. How to do this see Bind an Application to a Service Instance.

NOTE: cf ssh support must be enabled in the platform. Ask your administrator if you are not sure.

Get The Service Url and Credentials

When you follow this instructions Obtain Service Instance Access Credentials you will get the hostname of the service and the user credentials.

$ cf env a9s-redis-app
Getting env variables for app a9s-redis-app in org test / space test as admin...
OK

System-Provided:
{
  "VCAP_SERVICES": {
   "a9s-redis": [
    {
      "credentials": {
       "host": [
        "d67901c.service.dc1.a9svs"
       ],
       "password": "a9s-brk-usr",
       "username": "a9s-password"
     },
     "label": "a9s-redis",
     "name": "my-redis-service",
     "plan": "redis-cluster-small"
    }
   ]
  }
}
...

Notice the host d67901c.service.dc1.a9svs, the username a9s-brk-usr and the password a9s-password. You will need this in the next step.

Create a Tunnel to The Service

With the cf ssh as mentioned before you can create a ssh forward tunnel to the management dashboard. Use port 6379 to connect to the a9s Redis Instance.

$ cf ssh a9s-redis-app -L 6379:d67901c.service.dc1.a9svs:6379
vcap@956aaf4e-6da9-4f69-4b1d-8e631a403312:~$

When the ssh tunnel is open you can access the instance over the address localhost:6379.

NOTE: Don't forget to close the session with exit.

Setup Disk Usage Alerts

Each service comes with the a9s Parachute. This component monitors ephemeral and persistent disk usage. See the a9s Parachute documentation how to configure the component.