Installing and Configuring Solace Messaging for Pivotal Cloud Foundry

This topic describes how to install and configure Solace Messaging for Pivotal Cloud Foundry (PCF). Before installing Solace Messaging for PCF, you must complete the prerequisites.

Review Resource Requirements

Review the resource and IP requirements for installing the Solace Messaging for PCF tile.

Resource Instances CPU Ram (MB) Ephemeral (MB) Persistent (MB) Static IP Dynamic IP
Solace Service Broker 1 1 1024 1024 0 0 1
Large-VMR 11 4 12288 10240 409601 1 0
Shared-VMR 11 2 4096 10240 204801 1 0
Community-VMR 11 2 4096 10240 204801 1 0
Medium-HA-VMR 3 1, 2 2 4096 10240 204801 1 0
Large-HA-VMR 3 1, 2 4 12288 10240 409601 1 0

1 Note: You can modify the number of Instances and Persistent disk size when configuring the Solace Messaging for PCF tile for the VMR jobs. For more information, see the Configure Solace Messaging for PCF tile below.

2 Note: A single high-availability Solace Messaging service instance requires three (3) HA VMR job instances to be used. As such the number of HA VMR job instances specified for the HA VMR instances should be multiple of 3. If it is not, the remaining job instances go unused.

Prerequisites

The Solace Messaging for PCF Service Broker requires the following:

  • Java buildpack v3.7.1 or later.
  • The MySQL for PCF tile. When configuring the tile, set the maximum storage in the Service Plan section to 100 MB. For information on how to install and configure the tile, see MySQL for Pivotal Cloud Foundry.

Install Solace Messaging for PCF

To install Solace Messaging for PCF, perform the following steps:

  1. Download the product file from Pivotal Network.
  2. Upload the product file on the Ops Manager Installation Dashboard.
  3. Click Add next to the uploaded Solace Messaging tile in the Ops Manager Available Products view to add it to your staging area.
  4. Click the Solace Messaging tile.
  5. Follow the steps in the section below to configure the tile.

Configure Solace Messaging for PCF

To configure Solace Messaging for PCF, perform the following steps:

From the Settings tab of the Solace Messaging tile Select settings

  1. Configure the Required Settings:

  2. Configure the Optional Settings:

  3. Apply Changes.

Required Settings

Assign AZs and Networks

  1. From the Settings tab of the Solace Messaging tile, click Assign AZs and Networks. Select 1 assign azs and networks
  2. Under AZ and Network Assignments, choose the network and availability zones where Solace Messaging should run. If you are deploying Solace Messaging with high availability plans, consider using multiple availability zones for maximum fault tolerance.

    Form assign azs and networks

  3. Click Save.

Management Access

  1. Click Management Access.

    Select 1 management access

  2. Under Admin user password, pick a password for the Virtual Message Routers admin user.

    Form management access admin user password

  3. (Optional) if you want to use LDAP.

  4. Click Save.

TCP Routes (Save required)

You need to open this pane and click Save even if using the default setting. If you want to enable TCP routes, see (Optional) TCP Routes.

  1. Click TCP Routes.

    Select 1 tcp routes

  2. Default: TCP Routes Disabled.

    Form tcp routes

  3. Click Save.

Note: Failing to click Save might result in an unknown property "solace_router" exception when you attempt to Apply Changes.

Stemcell

You might need to import a stemcell import if the minimum stemcell required for Solace Messaging for PCF is not found.

  1. Click Stemcell.

    Select 1 stemcell

  2. Click Import Stemcell to import the required stemcell for your installation of PCF.

Resource Config

  1. Click Resource Config.

    Select 1 resource config

  2. Use the drop-down menus to configure the number of VMR job instances that are available in each of the five service plans mentioned above. These job instances are statically created when the tile is deployed. Service instances are then dynamically allocated at service instance creation time, post-deployment, using these job instances.

    Five Shared-VMR service instances can be hosted on a single Shared-VMR job instance. As such the maximum number of Shared-VMR service instances that can concurrently exist for the Shared-VMR service plan is equal to five times the number of Shared-VMR job instances. Conversely three HA VMR job instances are required for a single HA VMR service instance. As such the maximum number of HA VMR service instances that can concurrently exist for the Large-HA-VMR and Medium-HA-VMR service plans is equal to one-third the number of their corresponding job instances. In order for Large-HA-VMR and Medium-HA-VMR service plans to provide high availability fault tolerance, make use of multiple availability zones for your deployment, with a minimum of 2 and an ideal of 3 or more. If you have only one availability zone, the deployment is not fault tolerant and Solace does not recommend using high availability service plans under this scenario.

    Note: The number of job instances can be increased after the tile is deployed without impacting already bound apps however reducing the number of instances can result in app failure and message loss.

    Note: The size of the persistent disk can be changed both before and after deployment. Increasing the size of the persistent disks will impact the service of already bound apps however messages will not be lost. Reducing the size of the persistent disk post-deployment is not recommended and can result in message loss, inoperable VMRs, and/or undefined behaviors.

    Note: Solace recommends keeping the default values for VM Type, a reduction of the RAM or CPU capacity may lead to a deployment failure, or service degradation.

    Note: The deploy-all and delete-all are required errands for the installation and removal of the Solace Service Broker. Solace recommends leaving the default VM Type. The VM Type for these errands is not related to the required resources of the Solace Service Broker which runs in the Elastic Runtime.

    Form resource config

  3. Click Save.

Optional Settings

(Optional) Message Router Config

  1. Click Message Router Config.

    Select 1 message router config

  2. Under Starting Port, enter a port where the messaging services on the VMRs (e.g. MQTT, REST, or SMF) will start listening from, for example, 7000.
    The exact port numbers chosen for each service will be based on this starting port and specified in the VCAP_SERVICES environment variable passed to apps. For an example, see Example Environment Variable.

    Form message router config

  3. Click Save.

(Optional) TLS Config

  1. Click TLS Config.

    Select 1 tls config

    TLS is disabled by default.

    Form tls config

  2. Click TLS Enabled.

    Form tls config enabled By enabling and configuring TLS, you allow messaging between apps and the Solace VMRs to be encrypted. Apps requiring encryption would then need to use the TLS-specific URLs passed in the VCAP_SERVICES environment variable. For more information about the VCAP_SERVICES environment variable, see Example Environment Variable. If TLS is not configured, the TLS specific URLs continue to be passed in the VCAP_SERVICES environment variable but fail to connect to a VMR if used.

  3. Configure Message Router’s RSA certificate (Server Certificate) either by pasting in a certificate and private key in PEM format or asking one to be generated by clicking Generate RSA Certificate. Generated certificates are equivalent to self-signed certificates.

    Form tls config server certificate

    Note: The server certificate configured will be used by all Solace VMRs deployed and as such all VMRs deployed in a PCF instances will have the same identification.

    Form tls config disable sb cert validation

    Note: Communication between the Solace Messaging Service Broker and VMRs is also encrypted if a TLS certificate is configured. The Service Broker uses the Container Certificate Trust Store Framework to validate the server certificate returned by VMRs. So if the framework is not operational when the tile is deployed the Service Broker will be unable to validate server certificates sent by the VMRs and the tile will fail to deploy. In development environments it may be acceptable to not require server certificate validation in which case the Disable RSA Server Certificate validation on the Service Broker (For development only) checkbox can be selected. This checkbox should never be selected in production deployments, instead the framework should be made operational.

  4. (Optional) Configure Message Router’s Trusted Root Certificates. These certificates will be stored in the trust store on the VMRs. They are required if you choose to use LDAP with TLS. Form tls config trusted root certificates

  5. Click Save.

(Optional) Service Access

  1. Click Service Access.

    Select 1 service access

  2. Check the Enable global access to plans of service solace_messaging option. Form service access

    Note: To control access to Solace Messaging service plans on a case-by-case basis, do not enable this option.

  3. Click Save.

(Optional) Management Access

  1. Click Management Access.

    Select 1 management access

  2. If you configured LDAP, you may choose to have the LDAP Server provide the authentication and authorization for the management roles on a Solace service Instance. Form management access ldap

  3. (Optional) Configure Groups with VMR administration read-only privilege. Form management access ldap readonly

  4. (Optional) Configure Groups with VMR administration read-write privileges. Form management access ldap readwrite

  5. (Optional) Configure Groups with VMR administration administrator privileges. Form management access ldap admin

    Note: Cloud Operators need to have global access to the VMRs deployed by the tile. This will allow them to administer the VMRs with SolAdmin, CLI or SEMP-based tools. Cloud operators might have different roles. Each role requires one of the three types of access-level: administrator, read-write and read-only. When using “VMR Internal” the cloud operators access to a single administrator level role using the admin password. With “LDAP Server” users can be assigned to groups in LDAP mapping to their respective roles.

  6. Click Save.

(Optional) Application Access

  1. Click Application Access

    Select 1 application access

  2. Using the defaults, the VMR will use its internal database for user credentials per service instance. If you configured LDAP, you may request the VMR to use the LDAP Server for authentication and authorization of when a client attempts to access a Solace messaging service instance. Form application access

  3. Click Save.

(Optional) LDAP Settings.

  1. Click LDAP Settings

    Select 1 ldap settings

    LDAP is disabled by default. Form ldap settings

    Note: Using the default LDAP Disabled, the VMR will use its internal database for management and user credentials per service instance. To use an LDAP store you must select LDAP Enabled and provide all the required settings for your LDAP server.

  2. Click LDAP Enabled.

    Form ldap settings enabled

  3. Set LDAP Server URL.

    Form ldap settings server url

    Note: Consider network accessibility of the provided LDAP server, you may need to check the Internet Connected option in Resource Config

  4. Set LDAP TLS Preference.

    Form ldap settings starttls

  5. Set LDAP Credentials to use with the LDAP Server.

    Form ldap settings credentials

  6. Set User Search Base.

    Form ldap settings user search base

  7. Set User Search Filter.

    Form ldap settings user search filter

  8. Set User Group Membership Attribute Name.

    Form ldap settings user group membership attribute name

  9. Click Save.

In order to have an effective LDAP configuration, configure LDAP for Management Access and Application Access. If neither Management Access nor Application Access are configured for LDAP, the VMR will continue to use its internal database for management and user credentials.

(Optional) System Logging

  1. Click System Logging.

    Select 1 system logging

    System logging is disabled by default. Form system logging

  2. Click System Logging Enabled.

    Form system logging enabled

  3. Set the external syslog hostname.

    Form system logging server

    Note: Consider network accessibility of the provided syslog server, you may need to check the Internet Connected option in Resource Config.

  4. Set the external syslog port.

    Form system logging port

  5. Set the external syslog network protocol.

    Form system logging protocol

  6. Select what logs to send to the external syslog server.

    Form system logging vmr commands Form system logging vmr events Form system logging vmr system Form system logging sb

  7. Click Save.

(Optional) Enable TCP Routes

  1. Click TCP Routes.

    Select 1 tcp routes

    TCP routes are disabled by default.

    Form tcp routes

  2. Click TCP Routes Enabled.

    Form tcp routes enabled 1 Form tcp routes enabled 2

    Note: Fine grained control is available by protocol. If you choose “Not Allowed” a TCP Route will never be created for this protocol, even if requested at service creation time. If you choose “Disabled by default” at service creation time, a TCP Route will not be created for this protocol unless a user provided parameter overrides it with a “true” setting. If you choose “Enabled by default” a TCP Route will be created for this protocol at service creation time, unless a user provided parameter overrides it with “false” setting.

    TCP Routes A solace_router uaa agent is required to use the TCP Routes feature. If using a new version of the Elastic Runtime (v1.11, v1.10.11, v1.9.24, v1.8.46), the solace_router uaa client may be present already, and there is no need to provide cf credentials. Check your installation for the presence of the solace_router uaa client, this may be found under Pivotal Elastic Runtime->Credentials->UAA. When a solace_router is not found, you will need to create one. Instructions on how to create one are provided below.

    TCP Routes Lookup the UAA ‘Admin Client Credentials’ which will be needed to create the solace_router.

    TCP Routes Install uaac if you don’t already have it.

    $ gem install cf-uaac
    

    TCP Routes Login to CF, target the uaa api, login with uaac using the 'Admin Client Credentials’

    $ cf api api.YOUR-SYSTEM-DOMAIN
    $ cf login 
    $ uaac target uaa.sys.YOUR-SYSTEM-DOMAIN
    $ uaac token client get admin
    

    TCP Routes Create the solace_router uaa client with the necessary permissions, assign it a good secret password

    $ uaac client add solace_router --name solace_router --scope uaa.none --authorized_grant_types "refresh_token,client_credentials" \
    $ --authorities "routing.routes.read,routing.routes.write,routing.router_groups.read,cloud_controller.read,cloud_controller.write,cloud_controller.admin" \
    $ -s "A_GOOD_SECRET_PASSWORD"
    

    TCP Routes Ensure that you have a 'tcp’ domain.

    $ cf create-shared-domain tcp.YOUR-DOMAIN --router-group default-tcp
    

    TCP Routes Consider PCF quotas, networking, and firewalls when using TCP Routes. For example, removing the limits on reserved route ports.

    $ cf update-quota default --reserved-route-ports -1
    

    TCP Routes use solace_router and the A_GOOD_SECRET_PASSWORD as the cf credentials for TCP Routes.

  3. Click Save.

Apply Changes

In order to apply changes, all the settings for the Solace tile need to be marked with green checkmarks.

Select all done

  1. Click Installation Dashboard at the top left corner of the screen to leave the tile configuration and go back to dashboard.

    Link installation dashboard

  2. Click Apply Changes to deploy the tile.

    Apply changes

  3. After the tile has deployed, see Creating and Binding Solace Messaging Service Instances for information about creating instances of the Solace Messaging service and binding them to apps.

Create a pull request or raise an issue on the source for this page in GitHub