1 Note: The management VM is required to support Solace PubSub+ for PCF. Two instances are required for a production setup and must be combined with One arbitrator VM.

2 Note:One arbitrator VM is required for a production setup and must be combined with Two management VM instances. Otherwise set this to zero.

3 Note: You can modify the number of operator allocated instances and persistent disk size when configuring the tile for the Solace PubSub+ message broker jobs. For more information, see the Configure Solace PubSub+ for PCF tile below.

4 Note: A high availability Solace PubSub+ service instance requires three (3) HA Solace PubSub+ message broker job instances to be used. As such, the operator allocated number of HA Solace PubSub+ message broker job instances specified for the HA Solace PubSub+ message broker instances should be a multiple of 3. If it is not, the remaining job instances go unused.

Prerequisites

Solace PubSub+ for PCF requires the following:

PCF version 2.1.x. or later.

Java buildpack v4.x.x or later.

MySQL database, which can be made available in one of these methods:

Internal deployment as part of the Solace PubSub+ for PCF on a management VM

Required Settings

Assign AZs and Networks

From the Settings tab of the Solace PubSub+ tile, click Assign AZs and Networks.

Under AZ and Network Assignments, choose the availability zones and network where the Solace PubSub+ deployment should run. This will include all Operator Allocated Message Brokers. If you are deploying Solace PubSub+ with high availability plans, consider using multiple availability zones for maximum fault tolerance. Also choose the Service Network, this is where On Demand Allocated Message Brokers will be deployed, the Availability Zones for On Demand Allocated Message Brokers are controlled in each plan.

Click Save.

MySQL Configuration

Click MySQL Database.

(Optional) Database columns holding credentials can be encrypted by
entering an encryption key in DB Encryption Key.
There are no restrictions on the length of the characters for the key.

Warning: You cannot recover a loss
encryption key. You must safeguard against the loss of encryption keys.

Depending on your use case, do one of the following:

If you redeploy and do not want to change the encryption, leave the
DB Encryption Key with its current value.

If you want to change the encryption key, enter the new key in DB
Encryption Key and enter the old key in Previous DB Encryption Key.
The previously encrypted data is decrypted using the old key and re-encrypted using the new key.

If you want to decrypt the database, enter the last used key in Previous
DB Encryption Key and clear DB Encryption Key.

Select one of the supported MySQL configuration for the service broker’s database.

Internal MySQL: The default option is for an ‘Internal MySQL’ deployed to a single management VM. For a production setup please make sure to allocate two management VMs and one arbitrator VM. The arbitrator VM should be located in a different availability zone than the management VMs. Without a load balancer, the service broker relies on MySQL driver for failover functions using up to two management VMs when available.

Internal MySQL (Highly Available): Make sure to allocate two management VMs and one arbitrator VM. The arbitrator VM should be located in a different availability zone than the management VMs. When using a load balancer setup, ensure to point to the two management VMs with health check port 1936. The load balancer setup must be sticky. For more information, see CF MySQL Release - Proxy: Configuring Load Balancer. Without a load balancer, the service broker relies on MySQL driver for failover functions using up to two management VMs when available.

MySQL for PCF: When MySQL for PCF tile is available, select a highly available service plan with a minimum of 100 MB database size.

External MySQL: When MySQL is available as an external service, it may be provided as a user-provided-service to Solace PubSub+ for PCF. Ensure you have a highly available deployment with a minimum of 100 MB database size.

Note: Except for the encryption keys, you cannot modify your MySQL configurations after the deployment has completed. Be sure to select the most appropriate option for your deployment.

Click Save.

Management Access

Click Management Access.

Under Admin user password, pick a password for the message brokers admin user.

Note: The password can only contain alphanumeric characters and any of .!@#$%^-_+={}[]/?

Resource Config

Click Resource Config.

Use the drop-down menus to configure the number of Solace PubSub+ message broker job instances that are available in each of the 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 Enterprise Shared service instances can be hosted on a single Enterprise Shared job instance. As such, the maximum number of Enterprise Shared service instances that can concurrently exist for the Enterprise Shared service plan is equal to five times the number of Enterprise Shared job instances. Conversely, three HA Solace PubSub+ message broker job instances are required for a single HA Solace PubSub+ message broker service instance. As such, the maximum number of HA Solace PubSub+ message broker service instances that can concurrently exist for the Enterprise Large-HA and Enterprise Medium-HA service plans is equal to one-third the number of their corresponding job instances. In order for Enterprise Large-HA and Enterprise Medium-HA 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 Automatic number of job instances is kept to the same values found in previous tile releases. This is just to ensure no instances are lost during upgrades.

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 Solace PubSub+ message broker, and/or undefined behaviors.

Note: Unless there are no existing service instances or you are configuring a new plan, Solace recommends keeping the default values for VM Type and ensuring it matches the configurable service plan. A reduction of the RAM or CPU capacity may lead to a deployment failure or service degradation.

Click Save.

Optional Settings

(Optional) General Settings

Click General Settings.

In Service Name, enter the name you want as the service name in the Marketplace.

Note: If you change the name to something
other than solace-pubsub, any apps that use the
Solace PubSub+ Spring Cloud Connectors
have to be changed. Clone the project and change any instances of the string
solace-pubsub to the service name you selected.

Under Starting Port, enter a port where the messaging services on the Solace PubSub+ message brokers (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.

Note: The Starting Port may only be set at tile installation time. Its value may not be changed later.

Under Default Orphaned Resource Policy, choose a default policy for your deployment. This default policy is used when a service does not have its own policy. See Service Orphaned Resource Policy for more details about the options.

Under User Controlled Upgrades for On Demand Instances, configure whether or not
users can control when their services are upgraded.

To enable user-controlled upgrades, select true from the dropdown.

When eligible, on-demand services users can indicate through their service dashboard if they want to upgrade. A task runs periodically to check for pending upgrade requests and perform them as required.

To set how often the task runs, do one of the following:

Select a preconfigured interval in On Demand Upgrade Task Timer.

Select Custom Time and enter an interval in Cron format.

When an upgrade is available, the service dashboard looks like this:

If the user clicks Mark for Upgrade, then the service is upgraded at the next scheduled time.

Under Web Hook, you can choose to Enable or Disable.

Web Hook enables an endpoint to receive POST requests for service create,
delete, and update events.

The operation field describes the service event. The possible values are create,update, or delete.
The message has service identifying information with network information for all
messaging services.

The following sample message is for a service create event.
Many lines in the services section of this sample have been
removed for brevity:

An operator has a chance to confirm the buildpack and the amount of memory used for the Service Broker installation in CF.

Adjust Monitor VM Type and Disk Type

The Monitor VM Type and Disk Type settings apply to all on-demand plans with High Availability enabled.
A Monitor node requires 1 CPU and 1 GB of RAM.

Click Save.

(Optional) TLS Config

Click TLS Config.

TLS is disabled by default.

Click TLS Enabled.

By enabling and configuring TLS, you allow messaging between apps and the Solace PubSub+ message broker 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 PubSub+ Message Broker if used.

Note: The server certificate configured
is used by all Solace PubSub+ message brokers deployed.
As such, all Solace PubSub+ message brokers deployed in a PCF instances
have the same identification.

Note: Communication between the Solace PubSub+
Service Broker and Solace PubSub+ message broker 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 Solace PubSub+ message brokers. If the framework is not operational
when the tile is deployed, the Service Broker is unable to validate
server certificates sent by the Solace PubSub+ message brokers and the tile
fails 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 Broker’s Trusted Root Certificates.
These certificates are stored in the trust store on the Solace PubSub+ message brokers.
They are required if you choose to use LDAP with TLS. If you want, use
Client Certificate Authentication.

Click Save.

(Optional) Service Access

Click Service Access.

Check the Enable global access to plans of service solace_pubsub option.

Note: To control access to Solace PubSub+ service plans on a case-by-case basis, do not enable this option. Once this is enabled, it cannot be disabled from this form. It must be revoked by the operator manually.

Note: This allows for application security
groups to be created for each service binding and deleted on unbind.
The created application security groups grants an app’s space
access to the Solace PubSub+ Service Instance IP and service ports only.

Click Save.

(Optional) Management Access

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.

Note: Cloud Operators need to have global
access to the Solace PubSub+ message brokers deployed by the tile.
This allows them to administer the Solace PubSub+ message brokers 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 "Message Broker 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 Save.

(Optional) Application Access

Click Application Access.

Using the defaults, the Solace PubSub+ message broker
uses its internal database for user credentials per service instance.
If you configured LDAP, you may request the Solace PubSub+ message broker to
use the LDAP Server for authentication and authorization of when a client attempts
to access a Solace PubSub+ service instance.

Click Save.

(Optional) LDAP Settings

Click LDAP Settings.

LDAP is disabled by default.

Note: Using the default
LDAP Disabled, the Solace PubSub+ message broker uses 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 the network accessibility of the provided LDAP server. You may need to check the Internet Connected option in Resource Config.

(Optional) System Logging

Note: Consider the network accessibility of the provided syslog server. You may need to check the Internet Connected option in [Resource Config](#required_resource_config).

Set the external syslog port.

Set the external syslog network protocol.

Select what logs to send to the external syslog server.

Click Save.

(Optional) Enable TCP Routes

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 is never created for this protocol,
even if requested at service creation time.
If you choose Disabled by default, at service creation time,
a TCP route is not created for this protocol unless a user-provided parameter overrides it
with a true setting.
If you choose Enabled by default,
a TCP route is created for this protocol at service creation time,
unless a user-provided parameter overrides it with false setting.

(Optional) Configure Errands

Errands are scripts that are run when a tile is installed, updated or removed. The errands page lists them and lets you choose whether to run them.

Unless otherwise stated in this documentation you should not modify these settings, otherwise the tile may not get installed properly. The only time you would change them would be if you were trying to remove a tile and one of the errands was preventing you to do this because the errand itself was failing.

Apply Changes

In order to apply changes, all the settings for the Solace tile must 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.

Upgrades

Solace PubSub+ for PCF supports upgrades starting with PCF v2.0. Future releases can upgrade a deployment if the deployment is v2.0 or higher. In-Service-Upgrades are supported from PCF v2.0 for high-availability service plans.

If a v1.x.x tile is currently installed, a direct upgrade path to v2.0.0 is not supported. The v1.x.x tile should be uninstalled before a v2.0.0 tile is installed.

Non-High Availability Upgrades

The messaging service for an application will experience an outage that lasts no
longer than the time it takes to upgrade the Solace PubSub+ message broker and start it up again.

High Availability Upgrades

Upgrades are non-service-affecting for high-availability plans Enterprise Large-HA, Enterprise Medium-HA and Standard Medium-HA, 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 experiences at least one switch-over during an upgrade, and at most two switch-overs.

Networking

Applications deployed in PCF that consume PubSub+ services must be able to
connect to the VMs hosting the PubSub+ instances. They can connect
using the IP address that is provided to the application through the VCAP_SERVICES
environment variables. Alternatively, the operator can enable TCP Routing
to allow internal and external applications to communicate with the PubSub+ instance through a DNS name.

By default PubSub+ services are consumed starting at port 7000. You can configure this value.
To see which ports have been allocated for a service, use the Web Hook feature.

The service broker must communicate with any VMs that
host PubSub+ instances, whether they are on the same network or a different one.
When using On-Demand Services,
the service broker must communicate with VMs running
in the Services network.

The service broker must communicate with the management and arbitrator VMs.

The service broker must communicate with cf.

The service broker and the VMs hosting the PubSub+ message broker must
communicate with the CredHub service if the
Secure Service Instance feature is enabled.

Solace PubSub+ instances must communicate with cf and the cf nats service
when TCP Routing is enabled. The instances
use the route registrar which internally uses nats.

The service broker is provided with a PubSub+ service for its internal use.
Determine which ports are required by looking at the service broker’s VCAP_SERVICES
environment variable for the service named 'internal-service-broker’.

PubSub+ for PCF uses bosh dns to communicate with PCF services such as Credhub.

Here is a table showing the ports that are required for internal communication between our components. All use TCP (none uses UDP.)

Source

Destination

Port

Secure Port

Protocol

Purpose

Service Broker

Message Broker (Internal)

443

HTTPS

Used configure the internal message broker through the gorouter.

Service Broker

Message Broker (Service instance)

2222

SSH

Used to ssh into the message brokers used as service instances.

Service Broker

Internal MySql instance

3306

JDBC

Used to connect with the internal MySql instance, unless an external database is used.

Service Broker

Message Broker (Service instance)

8080

943

HTTP/S

Used to configure the message brokers used as service instances.

Service Broker

Broker Agent

18080

HTTP

Used to communicate with the broker agents running on the service instance VMs.

Service Broker

Message Broker (Internal)

38080

3943

HTTP/S

Used configure the internal message broker through the gorouter.

Service Broker

Message Broker (Internal)

39090

HTTP

Used to connect to the health endpoint on the internal message broker.

Cloud Foundry

On-Demand Service Broker

7979

HTTP

Used by cf to send commands to the on-demand service broker (Management vm).

Message Broker (Service instance)

9090

HTTP

PubSub+ health check

TCP Routes Requirements

A solace_router UAA agent is required to use the TCP Routes feature. If
using a new version of the Pivotal Application Service (v2.1+), the
solace_router UAA client may be present already, and there is no need to
provide Cloud Foundry credentials. Check your installation for the presence of
the solace_router UAA client, which can be found under Pivotal
Application Service > Credentials > UAA. If a solace_router is not
found, you must to create one. To create a solace_router, do the following:

Look up the UAA Admin Client Credentials, which is needed to create the solace_router.

Install uaac if you do not already have it.

$ gem install cf-uaac

Log in to CF, target the UAA API, and log in with uaac using the Admin Client Credentials.