Installing Redis for Pivotal Platform

Page last updated:

This topic describes the process of installing Redis for Pivotal Platform. It covers tasks from downloading the file from Pivotal Network through verifying the installation after configuration.

Role-Based Access in Ops Manager

Ops Manager admins can use Role-Based Access Control (RBAC) to manage which operators can make deployment changes, view credentials, and manage user roles in Ops Manager. Therefore, your role permissions might not allow you to follow every procedure in this operator guide.

For more information about roles in Ops Manager, see Understand Roles in Ops Manager.

Download and Install the Tile

To add Redis for Pivotal Platform to Ops Manager, follow the procedure for adding Ops Manager tiles:

  1. Download the Redis for Pivotal Platform file from Pivotal Network. Select the latest release from the Releases dropdown.
  2. In the Ops Manager Installation Dashboard, click Import a Product to upload the Redis for Pivotal Platform file.
  3. Click the + sign next to the uploaded product description to add the tile to your staging area.
  4. To configure Redis for Pivotal Platform, click the newly added tile. See configuration instructions in the sections below.
  5. After completing the required configuration, in the Ops Manager Dashboard, do the following to complete the installation:

    1. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

    2. Click Apply Changes.

For guidance on ports and ranges used in the Redis service, see Select Networks below.

Assign AZs and Networks

To assign AZs and networks, click the Assign AZs and Networks settings tab.

AZ Assignment Diagram

Assign AZs

You can assign multiple availability zones (AZs) to Redis jobs, however this does not ensure high availability. You must select AZs that are in the service network you configured in your BOSH Director. For more information, see Availability Zones.

To assign AZs:

  1. Select Assign AZs and Networks.

  2. Under Place singleton jobs in, select an AZ for the on-demand or shared service broker VM, and any shared instances.

  3. Under Balance other jobs in, select the AZs that you want the broker to balance on-demand service instances across.

  4. Click Save.

Select Networks

You can use Redis for Pivotal Platform with or without using the on-demand service. To use the Redis for Pivotal Platform on-demand service, you must select a network in which the service instances are created. For more information, see Networking for On-Demand Services.

To select networks:

  1. In the Assign AZs and Networks tab, select a Network.

    • Pivotal recommends that each type of Pivotal Platform service run in its own network. For example, run Redis for Pivotal Platform on a separate network from RabbitMQ for Pivotal Platform.
    • Typically the service broker network and service instance network(s) are the same.
  2. If using the on-demand service, select a Service Network. Otherwise, select an empty service network. For more information, see Creating an Empty Services Network when using on-demand Service Tiles for Non-On-Demand Usage Only in the Pivotal Support knowledge base.

Note: In Ops Manager v2.0 and earlier, a specific network was designated as the Service Network to reserve IPs for the on-demand service. As of Ops Manager v2.1, IPs are no longer managed in this way. All networks are now available to use as a Service Network.

The following ports and ranges are used in Redis for Pivotal Platform:

Port Protocol Direction and Network Purpose
8202 TCP Inbound to the Cloud Foundry network
Outbound from the service broker and service instance networks
Allows Redis metron_agent to forward metrics to the Cloud Foundry Loggregator
12350 TCP Outbound from Cloud Foundry to the cf-redis-broker service broker network Allows the cloud controllers to access the cf-redis-broker
8080 TCP Outbound from Cloud Foundry to the on-demand service broker network Allows the cloud controllers to access the on-demand service broker when using an on-demand service
6379 TCP Outbound from Cloud Foundry to any on-demand service instance networks Allows the Diego Cell and Diego Brain networks to access all on-demand service instances
16379 TCP Outbound from Cloud Foundry to any on-demand service instance networks This port allow the Diego Cell and Diego Brain networks to access all on-demand service instances.
This access is only required if TLS is set to optional.
32768–61000 TCP Outbound from Cloud Foundry to the cf-redis-broker service broker network These ports allow Diego Cell and Diego Brain networks to access the service broker VM. This access is only required for the shared service plan.
80 http Outbound from any service instance networks Gives access to the backup blobstore when using service backups
443 https Outbound from any service instance networks Gives access to the backup blobstore when using service backups
8443 and 25555 TCP Outbound from any on-demand service broker network to the BOSH Director network Allows the on-demand service broker to communicate with the BOSH Director

Configure On-Demand Service Settings

To configure settings that apply across the whole on-demand service offering:

  1. In the Redis for Pivotal Platform tile, select On-Demand Service Settings. settings Click here to view a larger version of this image.

  2. Enter the Maximum service instances across all on-demand plans. The maximum number of instances you set for all your on-demand plans combined cannot exceed this number.
    For more information, see Setting Limits for On-Demand Service Instances.

  3. Select the Allow outbound internet access from service instances checkbox. You must select this checkbox to allow external log forwarding, send backup artifacts to external destinations, and communicate with an external BOSH blobstore.

    Note: Outbound network traffic rules also depend on your IaaS settings. Consult your network or IaaS admin to ensure that your IaaS allows outbound traffic to the external networks you need.

  4. (Optional) Select the checkbox to enable Service Instance Sharing. Turning on sharing enables this feature for all on-demand instances.

    Note: To enable this feature a user with admin privileges must run cf enable-feature-flag service_instance_sharing. For information about this feature, see Sharing a Redis Instance with Another Space.

  5. (Optional) Use the Maximum Parallel Upgrades field to configure the maximum number of Redis service instances that can be upgraded at the same time.

    When you click Apply Changes, the on-demand broker upgrades all service instances. By default, each instance is upgraded serially. Allowing parallel upgrades reduces the time taken to apply changes.

    Note: Multiple Redis service instances are concurrently unavailable during the upgrade.

  6. (Optional) Use the Number of Canaries to run before proceeding with upgrade field and the Specify Org and Space that Canaries will be selected from? options to specify settings for upgrade canaries. Canaries are service instances that are upgraded first. The upgrade fails if any canaries fail to upgrade.

    You can limit canaries by number and by org and space. To use all service instances in an org and space as canaries, set the number of canaries to zero. This upgrades all service instances in the selected org and space first.

    canary-options

    Note: If you specify that canaries should be limited to an org and space that has no service instances, the upgrade fails.

    Note: Canary upgrades comply with the Maximum Parallel Upgrades settings. If you specify three canaries and a Maximum Parallel Upgrades of two, then two canaries upgrade, followed by the third.

    For information about this feature, see canaries in Upgrade All Service Instances in the On-Demand Services SDK documentation.

  7. (Optional) Select the checkbox to enable BOSH HotSwaps. This reduces downtime during upgrades. For how this feature works, see Changing VM Update Strategy in the BOSH documentation.

  8. (Optional) Select the Not Configured option under Enable TLS if you do not want to allow TLS connections to on-demand service instances. TLS support is optional in new installations by default. If TLS is configured in Redis for Pivotal Platform v2.2, follow the procedures in Preparing for TLS before enabling TLS.

    Note: Selecting TLS optional does not enforce the use of TLS. After deploying the tile, notify developers that they must unbind, bind, and restage existing service instances to ensure Spring and Steeltoe apps use TLS. Further configuration might be needed for other frameworks and languages to ensure use of the TLS port.

    Warning: After TLS has been enabled for the on-demand Redis service, disabling TLS causes downtime and service outage for all apps that connect to Redis through TLS.
    If you disable TLS, you must unbind all apps bound to on-demand instances from the TLS port, rebind to the non-TLS port and then re-stage to resume service access.

Configure On-Demand Plan Settings

You can configure multiple on-demand plans with memory and disk sizes suited to different use cases. The configuration of resources varies depending on your IaaS.

To add and configure each on-demand service plan:

  1. In the Redis for Pivotal Platform tile, select On-Demand Plans. on demand config

  2. Click Add to add an on-demand plan. on demand plan config Click here to view a larger version of this image.

  3. Configure the settings in the table below for your on-demand plans and then click Save.

    Warning: Do not downsize the VMs or disk size. Doing so can cause data loss in pre-existing instances.

    Field Default Description
    Plan Name on-demand-cache The name that you choose for the plan. This is displayed in the Marketplace. Pivotal recommends that you give your plans descriptive names based on their configuration.
    Plan Description This plan provides an on-demand Redis instance, tailored for caching use cases with persistence to disk enabled. The description that you write for your plan. This is displayed in the Marketplace. Include details that are relevant to app developers.
    Plan ID Empty An ID that you configure when recovering deleted plans. Leave this field blank unless it is already configured or you are recovering a deleted plan.
    Plan Quota 20 The maximum number of instances of this plan that app developers can create. For more information, see Setting Limits for On-Demand Service Instances.
    CF Service Access Enabled for all orgs and spaces This setting does not modify the permissions that have been previously set, and allows for manual access to be configured from the CLI.
    AZ to deploy Redis instances of this plan None selected The AZs in which to deploy the Redis instances from the plan. These must be AZs of the service network, which are configured in the BOSH Director tile. If you select multiple AZs, instances are distributed randomly between them.
    Server VM type Varies depending on IaaS Pivotal recommends that the persistent disk is at least 2.5x the VM memory for on-demand service instances.
    Server Disk type Varies depending on IaaS Pivotal recommends that the persistent disk is at least 2.5x the VM memory for on-demand service instances.
    Redis Client Timeout 3600 The server timeout for an idle client specified in seconds. Adjust this setting as needed.
    Redis TCP Keepalive 60 The interval in seconds at which TCP ACKs are sent to clients. Adjust this setting as needed.
    Max Clients 1000 The maximum number of clients that can be connected at any one time. Adjust this setting as needed.
    Lua Scripting Disabled Pivotal recommends keeping Lua scripting disabled unless developers are running apps that require Lua scripting, such as .Net Steeltoe apps.
    Verify that your apps are using a language that does not require Lua scripting.

(Optional) Enable Secure Service Instance Credentials for On-Demand Redis

To secure your on-demand binding credentials in runtime CredHub instead of the Cloud Controller database (CCDB):

  1. Configure the Pivotal Application Service (PAS) tile to support securing service instance credentials in runtime CredHub. See Step 1: Configure the PASTile.

  2. After deploying the tile, notify developers that they must unbind and rebind existing service instances to secure their credentials with CredHub.

Updating On-Demand Service Plans

Operators can update certain settings after the plans have been created. If the operator updates the VM size, disk size, or the Redis configuration settings (enabling Lua Scripting, max-clients, timeout and TCP keepalive), these settings are implemented in all instances that are already created.

Operators should not downsize the VMs or disk size because this can cause data loss in pre-existing instances. Additionally, operators cannot make a plan that was previously active, inactive, until all instances of that plan have been deleted.

Remove an On-Demand Service Plan

Warning: Do not remove an on-demand service plan with service instances deployed. Doing so causes Apply Changes to fail. For how to recover a deleted plan, see Recover a deleted Redis for Pivotal Platform On-Demand Plan in the Pivotal Support knowledge base.

To remove an on-demand service plan from your tile:

  1. Ensure that there are no deployed service instances of the plan by running:

    cf services
    

    For example:

    $ 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     on-demand-cache                 create succeeded
    

  2. In the Redis for Pivotal Platform tile, select On-Demand Plan Settings.

  3. Delete the plan by clicking the trash can icon next to the plan name.

  4. Click Save.

  5. Navigate to the Errands page on the Redis for Pivotal Platform tile, and set the Register On-Demand Broker errand to on. This updates the plans available in the Marketplace.

Remove All On-Demand Service Plans

Warning: Do not remove an on-demand service plan with service instances deployed. Doing so causes Apply Changes to fail. For how to recover a deleted plan, see Recover a deleted Redis for Pivotal Platform On-Demand Plan in the Pivotal Support knowledge base.

To remove the on-demand service from your tile:

  1. In the Redis for Pivotal Platform tile, select Resource Config

  2. Set the Redis On-Demand Broker job instances to 0.

  3. Navigate to the Errands page on the Redis for Pivotal Platform tile, and set the following errands to off:

    • Register On-Demand Broker
    • On-Demand Broker Smoke Tests
    • Upgrade All On-Demand Service Instances
    • Delete All Service Instances and Deregister On-Demand Broker
  4. Create an empty service network. For instructions, see Creating an Empty Services Network when using on-demand Service Tiles for Non-On-Demand Usage Only in the Pivotal Support knowledge base.

  5. Go to each On-Demand Plans page on the Redis for Pivotal Platform tile, and delete each plan by clicking the trash can icon next to the plan name.

Configure Shared-VM Plan Settings

To configure shared-VM service plans:

  1. In the Redis for Pivotal Platform tile, select Shared-VM Plan. shared vm config

  2. Configure these fields:

    • Redis Instance Memory Limit—Maximum memory used by a shared-VM instance.
    • Redis Service Instance Limit—Maximum number of shared-VM instances.
    • Lua Scripting—Enable or disable Lua Scripting as needed. Pivotal recommends that Lua Scripting is disabled unless developers need it to be enabled.

    Memory and instance limits depend on the total system memory of your Redis broker VM and require some additional calculation. For more information, see Memory Limits for Shared-VM Plans below.

  3. Click Save.

  4. If you do not want to use the on-demand service, you must make all of the on-demand service plans inactive. Click the tab for each on-demand plan, and select Plan Inactive. See the example in Step 4 of Remove On-Demand Service Plans above.

  5. To change the allocation of resources for the Redis broker, click the Resource Config tab.

    The Redis broker server runs all of the Redis instances for your shared-VM plan. From the Resource Config page, you can change the CPU, RAM, Ephemeral Disk, and Persistent Disk made available, as needed.

Configure Memory Limits for Shared-VM Plans

Additional calculation is required to configure memory limits for shared-VM plans. With these plans, several service instances share the VM, and the Redis broker also runs on this same VM. Therefore, the memory used by all the shared-vm instances combined should be at most 45% of the memory of the Redis broker VM.

To configure the limits in these fields:

  1. Estimate the combined maximum memory that all your Redis shared-VM instances can use.

  2. If your estimate is higher than 45% of the Redis broker VM’s total system memory, do any of the following:

  • Decrease the Redis Instance Memory Limit in the Shared-VM Plan tab.
  • Decrease the number of instances in Redis Service Instance Limit in the Shared-VM Plan tab.
  • Increase the RAM for the Redis Broker in the Resource Config tab as shown below.

Here are some examples for setting these limits:

Redis Broker VM Total Memory Redis Instance Memory Limit Redis Service Instance Limit
16 GB 512 MB 14
16 GB 256 MB 28
64 GB 512 MB 56

Note: You can configure a larger Redis Service Instance Limit, if you are confident that the majority of the deployed instances do not use a large amount of their allocated memory, for example in development or test environments.

However, this practice is not supported and can cause your server to run out of memory, preventing users from writing any more data to any Redis shared-VM instance. Do not use shared-VM instances in production environments.

Configure Resources for Shared-VM Plans

To configure resources for the shared-VM plans, click the Resource Config settings tab on the Redis for Pivotal Platform tile. The shared-VM plan is on the Redis Broker resource.

The following are the default resource and IP requirements for Redis for Pivotal Platform when using the shared-VM plans:

Product Resource Instances CPU Ram Ephemeral Persistent Static IP Dynamic IP
Redis Redis Broker 1 2 3072 4096 9216 1 0
Redis Broker Registrar 1 1 1024 2048 0 0 1
Redis Broker De-Registrar 1 1 1024 2048 0 0 1
Redis Compilation 2 2 1024 4096 0 0 1

Pivotal recommends that the persistent disk is at least 3.5x the VM memory for the shared-VM.

Disable Shared VM Plans

You can disable shared-VM plans by doing the following while configuring the Redis tile:

  1. Ensure at least one on-demand plan is active.

  2. Configure the following tabs:

    • Shared-VM Plan:
      a. Set Redis Service Instance Limit to 0.
      b. Click Save.

    • Errands:
      a. Set Broker Registrar to Off.
      b. Set Smoke Tests to Off.
      c. Set Broker Deregistrar to Off.
      d. Leave all four on-demand errands On.
      e. Click Save.

    • Resource Config:
      a. Decrease Redis Broker Persistent disk type to the smallest size available.
      b. Decrease Redis Broker VM type to the smallest size available.
      c. Click Save.

Configure Syslog Forwarding

Pivotal recommends that operators configure syslog forwarding to a remote destination. Forwarding your system logs to a remote destination lets you:

  • View logs from every VM in the Redis for Pivotal Platform deployment in one place.
  • Effectively troubleshooting when logs are lost on the source VM.
  • Set up alerts for important error logs to monitor the deployment.

All logs follow RFC5424 format.

To configure syslog forwarding:

  1. Select Syslog.

    The Syslog configuration page in the Redis for PCF tile in Ops Manager.

  2. (Optional) Select Yes to send Redis for Pivotal Platform system logs to a remote server.

  3. Enter the IP address or DNS name for the remote server in Address.

  4. Enter the port number that the remote server listens on in Port.

  5. Select TCP or UDP from the Transport Protocol dropdown. This selection determines which transport protocol is used to send the logs to the remote server.

  6. (Optional) Select the Enable TLS checkbox to send encrypted logs to remote server with TLS. After you select the checkbox:

    1. Enter either the name or SHA1 fingerprint of the remote peer in Permitted Peer.
    2. Enter the SSL certificate for the remote server in SSL Certificate.

      Note: Pivotal strongly recommends that you enable TLS encryption when you are forwarding logs. Logs can contain sensitive information, such as cloud provider credentials.

  7. (Optional) Enter an integer in Queue Size. This value specifies the number of log messages held in the buffer. The default value is 100,000.

  8. (Optional) Select the checkbox to Forward Debug Logs to an external source. This option is deselected by default. If you select it, you may generate a large amount of log data.

  9. (Optional) Enter configuration details for rsyslog in the Custom rsyslog Configuration field. This field requires the rainerscript syntax.

  10. Click Save.

Update Stemcell

If required, do the following to update the stemcell for Redis for Pivotal Platform:

  1. Download the stemcell from Pivotal Network.
  2. From the Ops Manager Installation Dashboard, click Stemcell Library.
  3. Click Import Stemcell, and then select the stemcell you downloaded from Pivotal Network.


    Stemcell Library

  4. Click Save.

Apply Changes from Your Configuration

To apply your configuration changes:

  1. Return to the Ops Manager Installation Dashboard.

  2. In the Ops Manager Dashboard, do the following to complete the installation:

    1. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

    2. Click Apply Changes.

Create App Security Groups

To allow this service to have network access, you must create App Security Groups (ASGs). Ensure your security group allows access to the Redis Service Broker VM configured in your deployment. You can obtain the IP addresses for these VMs in Ops Manager under the Resource Config section for the Redis for Pivotal Platform tile.

Note: Without ASGs, this service is unusable.

App Container Network Connections

App containers that use instances of the Redis for Pivotal Platform service require the following outbound network connections:

Destination Ports Protocol Reason
ASSIGNED_NETWORK 32768-61000 TCP To enable apps to access shared-VM service instances
ASSIGNED_NETWORK 6379 TCP To enable apps to access on-demand service instances
ASSIGNED_NETWORK 16379 TCP To enable apps to have TLS encrypted access to on-demand service instances

Create an ASG called redis-app-containers with the above configuration and bind it to the appropriate space or, to give all started apps access, bind to the default-running ASG set and restart your apps. Example:

[
  {
    "protocol": "tcp",
    "destination": "ASSIGNED_NETWORK",
    "ports": "6379,16379"
  }
]

Validating the Installation

Smoke tests run as part of Redis for Pivotal Platform installation to verify that the installation succeeded. For more information, see Redis for Pivotal Platform Smoke Tests.

Uninstall Redis for Pivotal Platform

To uninstall Redis for Pivotal Platform:

  1. In the Ops Manager Installation dashboard, click the trash can icon in the lower-right corner of the Redis for Pivotal Platform tile.
  2. Confirm the product was deleted.
  3. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  4. Click Apply Changes.