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 a9s-redis
and its service plans appear in your CF marketplace. Run cf marketplace
to see the service listing:
$ cf marketplace
Getting services from marketplace in org test / space test as admin...
OK
service plans description
a9s-redis redis-single, redis-cluster, redis-single-ssl redis-cluster-ssl This is the a9s Redis service.
SSL/TLS plans are available with a9s Redis 6 and above.
Create a Service Instance
To provision a Redis database, run cf create-service
. For example.
cf create-service a9s-redis redis-single 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:
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...
System-Provided:
{
"VCAP_SERVICES": {
"a9s-redis": [
{
(...)
"credentials": {
"host": "EXAMPLE-master.service.dc1.a9ssvc",
"hosts": [
"EXAMPLE-redis-0.node.dc1.a9ssvc",
"EXAMPLE-redis-1.node.dc1.a9ssvc",
"EXAMPLE-redis-2.node.dc1.a9ssvc"
],
"load_balanced_host": "EXAMPLE.service.dc1.a9ssvc",
"redis": {
"password": "EXAMPLE-REDIS-PASSWORD",
"port": 6379,
"username": "EXAMPLE-REDIS-USERNAME"
},
"sentinel": {
"master_name": "EXAMPLE-master",
"password": "EXAMPLE-SENTINEL-PASSWORD",
"port": 26379,
"username": "EXAMPLE-SENTINEL-PASSWORD"
}
}
(...)
}
]
}
}
...
Check credentials for a9s Redis 7 RC and below
$ cf env a9s-redis-app
Getting env variables for app a9s-redis-app in org test / space test as admin...
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
}
(...)
}
]
}
}
...
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.
The sentinel
information and its subfields are only present for Service Instances with cluster plans.
Access Credentials
Versions bellow a9s Redis 7 GA do not have support for multiple unique access credentials. These versions share the same credentials for different service bindings/keys with administrator permissions.
The user access control is based on Redis Access Control List (ACL). Each credential has some pre-configured permissions and does not have admin privileges.
Best Practices
There are some best practices for using service binding information in apps in a separate document.
Delete an a9s Redis Service Instance
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 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
Upgrades from single to cluster plans via the CF CLI update-service
command are not possible for a9s Redis 6 and
above.
However, it is possible to migrate to a new (empty) instance matching the desired plan via the migration feature. This way the you are able to import your data from a single instance into a cluster instance. For more information please refer to our migration guide.
Change RDB Persistence Settings
a9s Redis supports RDB persistence with point in time snapshots. This setting can be changed by the user.
Default Behavior
By default, persistency is disabled for a9s Redis Service Instances. However, if a backup snapshot is created and
the instance is restarted by an update, the backup snapshot is restored, even if persistence is disabled.
This affects both single instances and clusters. Data created between the backup and the update is not persistent and
will be lost after the restart. Therefore, we recommend the following setup for cache-only instances with
disabled persistency: Use the exclude_from_auto_backup
option to avoid the creation of backups.
More information is available here.
Configuring RDB
You can configure RDB according to the needs of your apps by providing custom parameters as settings. This setting must follow the original Redis configuration for RDB -c "{\"snapshot\": \"['save 900 1','save 300 10']\"}
.
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:
Setting | Effect |
---|---|
save 900 1 | Create a snapshot after 900 seconds if 1 write operations occurred. |
save 300 10 | Create 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 custom parameter: -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.
Setting | Effect |
---|---|
volatile-lru | Remove the key with an expire set using an LRU algorithm This is the default value. |
allkeys-lru | Remove any key according to the LRU algorithm |
volatile-random | Remove a random key with an expire set |
allkeys-random | Remove a random key |
volatile-ttl | Remove the key with the nearest expire time (minor TTL) |
noeviction | Don'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 several nodes, takes care of the automatic failover and is able to send notifications when something in the cluster is changing.
a9s Redis provides some settings to adjust the cluster behavior.
min-slaves-max-lag
, down-after-milliseconds
, and failover-timeout
.
Setting | Effect |
---|---|
min-slaves-max-lag | Redis < 6: Time in seconds how long the master waits before he stops accepting write operations, when slaves are no more reachable. Default is 10 seconds . min-slaves-to-write can not be changed, it is fixed set to 1 .See redis.conf |
min_replicas_max_lag | Redis >= 6: Time in seconds how long the master waits before he stops accepting write operations, when replicas are no more reachable. Default is 10 seconds . min-replicas-to-write can not be changed, it is fixed set to 1 .See redis.conf |
down-after-milliseconds | Number of milliseconds the master is unreachable in order to mark it a S_DOWN state. Default is 10000 ms .See sentinel.conf |
failover-timeout | The failover timeout value in milliseconds. Default is 30000 ms .See sentinel.conf |
# a9s Redis < 6
cf update-service my-redis-service -c {"min-slaves-max-lag": "10"}
# a9s Redis >= 6
cf update-service my-redis-service -c {"min_replicas_max_lag": "10"}
cf update-service my-redis-service -c '{"down-after-milliseconds": "10000"}'
cf update-service my-redis-service -c '{"failover-timeout": "30000"}'
Add a Graphite Endpoint
Important: Streaming of logs and metrics might not be availabale for your plan! If unsure, please check your plan description.
If you want to monitor your service with Graphite, you can set the custom
parameter graphite
. It expects the host and port where the Graphite metrics
should be sent to.
For example, in order to send Graphite metrics to an endpoint
yourspace.your-graphite-endpoint.com:12345
, you can use the following
command:
cf update-service my-instance -c '{ "graphite": "yourspace.your-graphite-endpoint.com:12345" }'
The endpoint would then receive metrics in the format:
<service_guid>.<service_type>.<host>.<metric> <metric value> <metric timestamp>
Metrics Frequency
By default, metrics will be emitted every 10
seconds.
You can change the interval via the custom parameter metrics_frequency
.
For example, in order to send Graphite metrics to an endpoint every minute, you
would set the custom parameter metrics_frequency
to 60
using the following command:
cf update-service my-instance -c '{ "metrics_frequency": 60 }'
Metrics Prefix
Depending on your graphite provider, you might need to prefix the metrics with
a certain value, like an API key for example. In this case you can leverage the
custom parameter metrics_prefix
.
cf update-service my-instance -c '{ "metrics_prefix": "my-api-key-for-a-certain-provider" }'
The resulting metric path would have the format:
<metrics_prefix>.<service_guid>.<service_type>.<host>.<metric>
Metrics
These are all metrics provided by a9s Redis.
Metric Id | Type | Description |
---|---|---|
blocked_clients | Integer | Number of clients pending on a blocking call (BLPOP, BRPOP, BRPOPLPUSH, BLMOVE, BZPOPMIN, BZPOPMAX). documentation |
connected_clients | Integer | Number of client connections (excluding connections from replicas). documentation |
evicted_keys | Integer | Number of evicted keys due to maxmemory limit. documentation |
expired_keys | Integer | Total number of key expiration events. documentation |
instantaneous_ops_per_sec | Integer | Number of commands processed per second. documentation |
keyspace_hits | Integer | Number of successful lookup of keys in the main dictionary. documentation |
keyspace_misses | Integer | Number of failed lookup of keys in the main dictionary. documentation |
mem_fragmentation_ratio | Float | Ratio between usedmemory_rss and used_memory. Note that this doesn't only includes fragmentation, but also other process overheads (see the allocator* metrics), and also overheads like code, shared libraries, stack, etc. documentation |
rejected_connections | Integer | Number of connections rejected because of maxclients limit. documentation |
total_commands_processed | Integer | Total number of commands processed by the server. documentation |
total_connections_received | Integer | Total number of connections accepted by the server. documentation |
used_memory | Integer | Total number of bytes allocated by Redis using its allocator (either standard libc, jemalloc, or an alternative allocator such as tcmalloc) documentation |
used_memory_lua | Integer | Number of bytes used by the Lua engine. documentation |
used_memory_peak | Integer | Peak memory consumed by Redis (in bytes). documentation |
used_memory_rss | Integer | Number of bytes that Redis allocated as seen by the operating system (a.k.a resident set size). documentation |
*.redis.*.*.*.blocked_clients
*.redis.*.*.*.connected_clients
*.redis.*.*.*.evicted_keys
*.redis.*.*.*.expired_keys
*.redis.*.*.*.instantaneous_ops_per_sec
*.redis.*.*.*.keyspace_hits
*.redis.*.*.*.keyspace_misses
*.redis.*.*.*.mem_fragmentation_ratio 4
*.redis.*.*.*.rejected_connections
*.redis.*.*.*.total_commands_processed
*.redis.*.*.*.total_connections_received
*.redis.*.*.*.used_memory
*.redis.*.*.*.used_memory_lua
*.redis.*.*.*.used_memory_peak
*.redis.*.*.*.used_memory_rss
Cloud Foundry Org and Space Guid
The platform operators can enable support on a global level to prefix the Graphite metrics with the CloudFoundry organization and space. This means that all metrics of all Service Instances (not only yours!) contain that information.
In this case the Graphite metric paths have the following format:
<organization_guid>.<space_guid>.<service_guid>.<service_type>.<host>.<metric>
When you enable in addition the metrics_prefix
for your instance, you will
end up with the metric path format:
<metrics_prefix>.<organization_guid>.<space_guid>.<service_guid>.<service_type>.<host>.<metric>
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-redis-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-redis-service --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.
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 myredis
.
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
.
lazyfree-lazy-expire
The default value is no
.
The allowed values are yes
and no
.
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
noeviction
For an explanation, see here.
maxmemory-samples
The default value is 5
.
The value must be an integer
>= 0
.
notify-keyspace-events
This parameter 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
t
failover-timeout
It is a Redis sentinel property that specifies the failover timeout in milliseconds. The default is 30 seconds.
The default value is 30000
.
The value must be an integer
>= 0
.
down-after-milliseconds
It is a Redis sentinel property that specifies the milliseconds a node is unreacheable in order to consider it subjectively down. The default is 10 seconds.
The default value is 10000
.
The value must be an integer
>= 0
.
tls-protocols
Only available with SSL/TLS plans that are available with a9s Redis 6 and above.
You can explicitly specify TLS versions to support. Allowed values are "TLSv1.2" and "TLSv1.3" or any combination.
- Improper changes to this value can easily break existing instances.
- When using TLSv1.3 only, Redis specific metrics will not be provided.
The default value is null
.
In this case Redis uses TLSv1.2 and TLSv1.3.
tls-ciphers
Only available with SSL/TLS plans that are available with a9s Redis 6 and above. This configuration only applies when using TLSv1.2.
Configure allowed ciphers. See the ciphers(1ssl) manpage for more information about the syntax of this string.
There is no validation enabled for the user provided values and therefore existing instances can break when applying this parameter.
The default value is null
which comments out the Redis config tls-ciphers
in the Redis and Sentinel configuration files.
tls-ciphersuites
Only available with SSL/TLS plans that are available with a9s Redis 6 and above. This configuration only applies when using TLSv1.3.
Configure allowed ciphersuites. See the ciphers(1ssl) manpage for more information about the syntax of this string, and specifically for TLSv1.3 ciphersuites.
There is no validation enabled for the user provided values and therefore existing instances can break when applying this parameter.
The default value is null
which comments out the Redis config
tls-ciphersuites
in the Redis and Sentinel configuration files.
hostname-resolution
- This feature is exclusive to a9s Redis versions 7 and above.
- This feature specifically applies to a9s Redis Cluster instances.
- When enabling or disabling the feature in an existing a9s Service Instance, there might be an increased downtime during the first cluster update due to a temporary divergence in Sentinel's settings when switching between IP address and hostname.
- When enabled, unexpected delays in address resolution may have a negative impact on Sentinel. For more information, refer to the Redis documentation.
The feature provides the option to enable and disable DNS/hostname support in Redis and Sentinel. When enabled, it will utilize the hostname for internal cluster communication and announce Redis and Sentinel node information using the hostname instead of the typical IP address.
Using this feature is useful when Redis clients use TLS to connect to Service Instances and require a hostname rather than an IP address in order to perform certificate ASN matching.
Using it
To enable or disable hostname-resolution
, it is important to follow a series of steps to ensure safety and prevent
significant downtime or data loss. Depending on its current state, the process may require adjusting a custom parameter
in two steps. See the cases below:
- To enable it in an existing Service Instance, follow these steps:
disabled → resolve-only → enabled
. - To disable it in an existing Service Instance, follow these steps:
enabled → resolve-only → disabled
. - When you create a new Service Instance, you can set any value directly. We suggest using either
enabled
ordisabled
.
Please note that transitioning directly from disabled
to enabled
, and vice versa, is not possible in an existing
Service Instance.
States/Values | Description |
---|---|
disabled | Hostname resolution and announcement are fully disabled. |
resolve-only | Hostname resolution is enabled but announcement is disabled. |
enabled | Hostname resolution and announcement are fully enabled. |
The default value is disabled
.
Backup and Restore Service Instances
a9s Redis 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 debugging. 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.
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-redis7": [
{
(...)
"credentials": {
"cacrt": "-----BEGIN CERTIFICATE-----\nMIIDGzCCAgOgAwIBAgIUJaCrwZnds7aY8+Jr+mvE....CMYZPYrlJ7jsTRt4NMrIp+jr+8tUd8J\n9eb7012/YK0d025ik2Qt\n-----END CERTIFICATE-----\n",
"host": "EXAMPLE-master.service.dc1.a9ssvc",
"redis": {
"password": "EXAMPLE-REDIS-PASSWORD",
"port": 6379,
"username": "EXAMPLE-REDIS-USERNAME"
},
"sentinel": {
"master_name": "EXAMPLE-master",
"password": "EXAMPLE-SENTINEL-PASSWORD",
"port": 26379,
"username": "EXAMPLE-SENTINEL-PASSWORD"
}
}
(...)
}
]
}
}
...
Notice the host EXAMPLE.service.dc1.a9svs
, the username EXAMPLE-REDIS-USERNAME
and the password
EXAMPLE-REDIS-PASSWORD
. You will need this in the next step.
a9s Redis 7 RC and below have a different structure for the credentials
field.
Please see Obtain Service Instance Access Credentials
for more information.
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:EXAMPLE.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
.
If the instance you have created is based on an SSL-plan, then you would need to provide a CA
certificate when connecting to it using the tunnel approach. To do so you can rely on the certificate
shown when executing cf env
, as shown above.
You should save the certificate from the credentials.cacrt
value of the VCAP_SERVICES
object into
some local file.
Then, while the tunnel is open you can use the redis-cli
to interact with your Redis instance from your
local machine:
redis-cli -h 127.0.0.1 -p 6379 --user <user> --pass <password> --tls --cacert "$LOCAL_CA_CERT_FILE"
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.