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 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|
|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 a multiple of 3. If it is not, the remaining job instances go unused.
3 Note: The Community-VMR plan is only available in the Evaluation Edition of Solace Messaging for PCF Tile.
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.
To install Solace Messaging for PCF, do the following:
- Download the product file from Pivotal Network.
- Upload the product file on the Ops Manager Installation Dashboard.
- Click Add next to the uploaded Solace Messaging tile in the Ops Manager Available Products view to add it to your staging area.
- Click the Solace Messaging tile.
- Follow the steps in the section below to configure the tile.
To configure Solace Messaging for PCF, do the following:
From the Settings tab of the Solace Messaging tile:
Configure the Required Settings:
Configure the Optional Settings:
- From the Settings tab of the Solace Messaging tile, click Assign AZs and Networks.
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.
Click Management Access.
Under Admin user password, pick a password for the Virtual Message Routers
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.
Click TCP Routes.
Default: TCP Routes Disabled.
Note: Failing to click Save might result in an
unknown property "solace_router" exception when you attempt to Apply Changes.
You might need to import a stemcell import if the minimum stemcell required for Solace Messaging for PCF is not found.
Click Import Stemcell to import the required stemcell for your installation of PCF.
Click Resource Config.
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-VMRservice plan is equal to five times the number of
Shared-VMRjob 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
Medium-HA-VMRservice plans is equal to one-third the number of their corresponding job instances. In order for
Medium-HA-VMRservice 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 Elastic Runtime.
Note: The solace_tests errand will test that a deployment has completed as expected and that it is ready for service. Solace recommends always running this errand after a deployment. Solace recommends leaving the default VM Type.
Click Message Router Config.
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,
The exact port numbers chosen for each service will be based on this starting port and specified in the
VCAP_SERVICESenvironment variable passed to apps. For an example, see Example Environment Variable.
Note: The Starting Port may only be set at tile installation time. Its value may not be changed later.
Click TLS Config.
TLS is disabled by default.
Click TLS 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_SERVICESenvironment variable. For more information about the
VCAP_SERVICESenvironment variable, see Example Environment Variable. If TLS is not configured, the TLS specific URLs continue to be passed in the
VCAP_SERVICESenvironment variable but fail to connect to a VMR if used.
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.
Note: The server certificate configured will be used by all Solace VMRs deployed. As such, all VMRs deployed in a PCF instances will have the same identification.
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.
(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.
Click Service Access.
Check the Enable global access to plans of service solace_messaging option.
Note: To control access to Solace Messaging service plans on a case-by-case basis, do not enable this option.
Click Management Access.
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.
(Optional) Configure Groups with VMR administration read-only privilege.
(Optional) Configure Groups with VMR administration read-write privileges.
(Optional) Configure Groups with VMR administration administrator privileges.
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.
Click Application Access
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.
Click LDAP Settings
LDAP is disabled by default.
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.
Click LDAP Enabled.
Set LDAP Server URL.
Note: Consider network accessibility of the provided LDAP server, you may need to check the Internet Connected option in Resource Config.
Set LDAP TLS Preference.
Set LDAP Credentials to use with the LDAP Server.
Set User Search Base.
Set User Search Filter.
Set User Group Membership Attribute Name.
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.
Click System Logging.
System logging is disabled by default.
Click System Logging Enabled.
Set the external syslog hostname.
Note: Consider network accessibility of the provided syslog server. You may need to check the Internet Connected option in Resource Config.
Set the external syslog port.
Set the external syslog network protocol.
Select what logs to send to the external syslog server.
Click TCP Routes.
TCP routes are disabled by default.
Click TCP Routes Enabled.
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 Look up 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, and log in 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 and assign it a 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.
In order to apply changes, all the settings for the Solace tile need to be marked with green checkmarks.
Click Installation Dashboard at the top left corner of the screen to leave the tile configuration and go back to dashboard.
Click Apply Changes to deploy the tile.
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.
Solace Messaging for PCF supports upgrades starting with release 1.3.0. Future releases can upgrade a deployment if the deployment is 1.3.0 or higher. In-Service-Upgrades are supported from release 1.3.0 for high-availability service plans.
Upgrades are service-affecting for non-HA service plans
The messaging service for an application will experience an outage that lasts no longer than the time it takes to upgrade the VMR and start it up again.
Upgrades are non-service-affecting for high-availability plans
Medium-HA-VMR, so there will always be a service available during upgrades. Upgrades will affect each VM providing the HA service one at a time.
An application using an HA service will experience at least one switch-over during an upgrade, and at most two switch-overs.
Please see our Getting Started Samples with full source code available in GitHub for some examples of how HA connections are used, as well as Configuring-Client-Connections for additional information on client connection setup to allow for switch-overs during upgrades.
The upgrade process is designed to keep services available.
Failures in upgrades are due to either pre-conditions or post-conditions, and are intended to keep services available in case of any failure.
The following pre-conditions must be met before an upgrade can proceed, or the upgrade will abort.
- The version of the tile being upgraded must be version 1.3.0 or higher.
- The redundancy state of HA services must be healthy.
If any failure occurs during an upgrade, services will remain available.
Please see the Troubleshooting Guide for further details.