Service Instance Access

This page describes usage specific to a9s KeyValue. It builds upon the information provided in Getting Started - Accessing a Service Instance.

a9s KeyValue Client Library Compatibility

Compatibility between existing Redis®^* client libraries with a9s KeyValue are not guaranteed. Please verify the existence of a Valkey client library for the chosen programming language, or use the Redis® client library with caution.

Accessing an a9s KeyValue Service Instance

In order to access an a9s KeyValue Service Instance, the Service Instance's credentials stored in the environment variables of the application bound to it. This is further explanined in Lifecycle of a Service Instance - Obtain Credentials for Accessing a Service Instance.

The resulting environment variables for an a9s KeyValue application can be seen below:

cf env a9s-keyvalue-app

Output

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

System-Provided:
{
  "VCAP_SERVICES": {
    "a9s-keyvalue": [
      {
        (...)
        "credentials": {

          "host": "EXAMPLE-master.service.dc1.a9ssvc",
          "valkey": {
            "password": "EXAMPLE-VALKEY-PASSWORD",
            "port": 6379,
            "username": "EXAMPLE-VALKEY-USERNAME"
          },
          "sentinel": {
            "master_name": "EXAMPLE-master",
            "password": "EXAMPLE-SENTINEL-PASSWORD",
            "port": 26379,
            "username": "EXAMPLE-SENTINEL-PASSWORD"
          }
        }
        (...)
      }
    ]
  }
}
...

The host and password values can be used to connect to the database with a Valkey client, by using only the host variable, the application does not need to know anything about Valkey Sentinel. However if the hosts or the load_balanced_host variable is used, the application needs to know about Valkey Sentinel and being able to work with Valkey Sentinel. This means, by using the host variable, the failover is handled by the logic within the Service Instance, but if one of the other variables is used, the failover needs to be handled by the application.

note

The sentinel information and its subfields are only present for Service Instances with cluster plans.

Accessing an HA Cluster

a9s KeyValue uses Valkey Sentinel to provide a high available replication set. Valkey 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 KeyValue provides some settings to adjust the cluster behavior: min-slaves-max-lag, down-after-milliseconds, and failover-timeout. For more information, see the Custom Parameters page.

Access Credentials

The user access control is based on Valkey Access Control List (ACL). Each credential has some pre-configured permissions and does not have admin privileges.

Create a Tunnel to The Service

With the cf ssh command a ssh forward tunnel to the management dashboard can be created. Use port 6379 to connect to the a9s KeyValue Instance.

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

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

If the created Service Instance is based on an SSL-plan, then it would be necessary to provide a CA certificate when connecting to it using the tunnel approach. To do so, the certificate shown when executing cf env can be relied upon, as shown above.

The certificate from the credentials.cacrt value of the VCAP_SERVICES object should be saved into some local file.

Then, while the tunnel is open it can used the valkey-cli to interact with the a9s KeyValue Service Instance from the local machine:

valkey-cli -h 127.0.0.1 -p 6379 --user <user> --pass <password> --tls --cacert "$LOCAL_CA_CERT_FILE"

note

Don't forget to close the session with exit.

---

*Redis is a registered trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd. Any use by anynines GmbH is for referential purposes only and does not indicate any sponsorship, endorsement or affiliation between Redis and anynines GmbH.