Solace PubSub+ Service Instances

This topic describes how developers can manage instances of Solace PubSub+ services.

About the Solace Service Instance

A Solace Service Instance represents a Message VPN on a Solace PubSub+ Event Broker. A Message VPN allows for many separate apps to share a single Event Broker while still remaining independent and separated. For more information, see Message VPNs.

After deploying the Solace PubSub+ for VMware Tanzu tile, the Solace PubSub+ service appears in the Marketplace. Developers can use either the Cloud Foundry Command Line Interface (cf CLI) or Apps Manager to create an instance of the service which they can make available to apps that need to exchange messages.

By binding an app to the instance or creating a service key for the instance, developers give the app permission to access this Message VPN through a client username or LDAP. For more information about how developers can use the credentials provided by the binding or service keys, see Understanding Solace PubSub+ Credentials.

Creating a service instance also gives the developer permissions to manage the Message VPN through a Web UI on the Solace PubSub+ Event Broker or the SolAdmin administration tool. For more information, see Managing the Message VPN.

Service instances may be shared across Cloud Foundry orgs and spaces if you enable that feature when installing the tile. See the installation page to see how to enable it. For more information see Enabling Service Instance Sharing.

The following procedures show you:

  • Using the cf CLI:
    • How to create a Solace PubSub+ service called solace-pubsub-instance with no added service-specific parameters.
    • How to create a Solace PubSub+ service called solace-pubsub-instance-IoT with added service-specific parameters.
    • How to update the service instance solace-pubsub-instance with service-specific parameters.
    • How to delete a service instance.
  • Using Apps Manager
    • How to create a service instance.

While the provided procedures are relevant to Solace PubSub+, they do not provide a complete set of examples of how to manage service instances in VMware Tanzu. For more information, see Managing Service Instances with the cf CLI.

Service Specific Parameters

A service instance can be customized at creation time and updated as well using parameters when certain features are enabled. The parameters applied can be viewed in the service instance dashboard.

  1. When LDAP is enabled, these parameters can be used to control management access to a service instance.

    • ldapGroupAdminReadOnly: Admin ReadOnly permissions are granted to the provided value for that parameter.
    • ldapGroupAdminReadWrite: Admin ReadWrite permissions are granted to the provided value for that parameter.

  2. If TCP routes are enabled and the configuration per protocol is either “Enabled by default” or “Disabled by default”, then you can use these parameters with valid values: true, false to control TCP Routes per service instance. Only specified routes will be updated.

    • tcp_route_enabled
    • smf_tcp_route_enabled
    • smf_tls_tcp_route_enabled
    • smf_zip_tcp_route_enabled
    • web_messaging_tcp_route_enabled
    • web_messaging_tls_tcp_route_enabled
    • mqtt_tcp_route_enabled
    • mqtt_tls_tcp_route_enabled
    • mqtt_ws_tcp_route_enabled
    • mqtt_wss_tcp_route_enabled
    • rest_tcp_route_enabled
    • rest_tls_tcp_route_enabled
    • amqp_tcp_route_enabled
    • amqp_tls_tcp_route_enabled
    • health_check_tls_tcp_route_enabled

  3. The following parameters can be used to request a specific port for TCP routes on any of the above protocols if and only if they are enabled. These can subsequently be provided in an update-service request. If provided on an update service request, the original route will be deleted, and the new route will be bound to the requested port. This port should not be in use and should be within the range configured on the TCP router. When using a standalone plan, the primary variant of the request parameter should be used If the service is provisioned under a high-availability plan, the backup variant can be used as well.

    • smf_tcp_route_primary_port, smf_tcp_route_backup_port
    • smf_tls_tcp_route_primary_port, smf_tls_tcp_route_backup_port
    • smf_zip_tcp_route_primary_port, smf_zip_tcp_route_backup_port
    • web_messaging_tcp_route_primary_port, web_messaging_tcp_route_backup_port
    • web_messaging_tls_tcp_route_primary_port, web_messaging_tls_tcp_route_backup_port
    • mqtt_tcp_route_primary_port, mqtt_tcp_route_backup_port
    • mqtt_tls_tcp_route_primary_port, mqtt_tls_tcp_route_backup_port
    • mqtt_ws_tcp_route_primary_port, mqtt_ws_tcp_route_backup_port
    • mqtt_wss_tcp_route_primary_port, mqtt_wss_tcp_route_backup_port
    • rest_tcp_route_primary_port, rest_tcp_route_backup_port
    • rest_tls_tcp_route_primary_port, rest_tls_tcp_route_backup_port
    • amqp_tcp_route_primary_port, amqp_tcp_route_backup_port
    • amqp_tls_tcp_route_primary_port, amqp_tls_tcp_route_backup_port
    • health_check_tcp_route_primary_port, health_check_tcp_route_backup_port

  4. The top level configuration option vpnOptions can be provided to configure various properties on the VPN.

    1. Service REST Mode can be set to either messaging or gateway. The mode can be set with the vpnOptions.serviceRestMode json property with valid values gateway or messaging. This property defaults to messaging.

  5. A service orphaned resource policy can be set at service creation or update time. This service policy takes precedence over the operator set Default Orphaned Resource Policy. The orphaned resource policy is applied during unbind operations to ensure orphaned resources such as Queues and Topic Endpoints are handled according to this policy. The policy can be set using parameter key orphanedResourcePolicy with one of these values:

    • Abort: The unbind operation is aborted with an error if there are any resources owned by the binding linked credentials that would be orphaned once the credentials are removed.
    • Delete: Any orphaned resources owned by the current binding linked credentials are deleted from the service instance. All data held in the orphaned resources is lost.
    • MakeServiceOwned: The ownership of orphaned resource is set to be service-level. This resource can be accessed by any current and future client credentials sharing the service instance.

Service specific configuration parameters are a JSON object that is provided either in-line or in a file. For more information, see Arbitrary Parameters.

Create a Service Instance with the cf CLI

To create an instance of the Solace PubSub+ service with the cf CLI, do the following:

  1. Set your API endpoint to the Cloud Controller of your deployment.

    $ cf api api.YOUR-SYSTEM-DOMAIN
Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...OK
API endpoint:  <span>https:</span>//api.YOUR-SYSTEM-DOMAIN (API version: 2.59.0)
Not logged in. Use 'cf login' to log in.

  2. Log in to your deployment and select an org and a space.

    $ cf login
API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAIN
Email> user<span>@</span>example.com
Password>

  3. List the Marketplace services and locate the Solace PubSub+ service and its associated service plans.

    $ cf marketplace
Getting services from marketplace in org example / space development as user<span>@</span>example.com...OK

service          plans                                                                               description
solace-pubsub    enterprise-shared, enterprise-large, enterprise-medium-ha, enterprise-large-ha      Solace PubSub+ Event Broker for real-time, multi-protocol data distribution

  4. Create an instance of the Solace PubSub+ service. Select the appropriate service plan for your app. For how the service plans differ, see VMware Tanzu Marketplace Plans. The following example uses the enterprise-large-ha service plan and no service-specific parameters.

    $ cf create-service solace-pubsub enterprise-large-ha solace-pubsub-instance
Creating service instance solace-pubsub-instance in org example / space development as user@example.com...OK

    Note: Any parameter dependent features will use their defaults. For example, if you have TCP Routes enabled or LDAP enabled, all the selections made at tile installation time are applicable to the created service as per tile configuration.

  5. Make this new service instance accessible to an app by binding or creating a service key.

Create a Service Instance with the cf CLI Having Service-Specific Parameters

To create an instance of the Solace PubSub+ service with the cf CLI with service-specific parameters, do the following:

  1. Set your API endpoint to the Cloud Controller of your deployment.

    $ cf api api.YOUR-SYSTEM-DOMAIN
Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...OK
API endpoint:  <span>https:</span>//api.YOUR-SYSTEM-DOMAIN (API version: 2.59.0)
Not logged in. Use 'cf login' to log in.

  2. Log in to your deployment and select an org and a space.

    $ cf login
API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAIN
Email> user<span>@</span>example.com
Password>

  3. List the Marketplace services and locate the Solace PubSub+ service and its associated service plans.

    $ cf marketplace
Getting services from marketplace in org example / space development as user<span>@</span>example.com...OK

service          plans                                                                             description
solace-pubsub    enterprise-shared, enterprise-large, enterprise-medium-ha, enterprise-large-ha      Solace PubSub+ Event Broker for real-time, multi-protocol data distribution

  4. Create an instance of the Solace PubSub+ service and select the appropriate service plan for your app. For how the service plans differ, see VMware Tanzu Marketplace Plans.

  5. Add applicable service-specific parameters. The following example uses the enterprise-shared service plan with service-specific parameters for TCP routes that enable opening an MQTT TLS port to support IoT devices, setting the Orphaned Resource Policy to make any orphaned resources service instance owned and setting the VPN’s REST mode to gateway.

    $ cf create-service solace-pubsub enterprise-shared solace-pubsub-instance-IoT -c '{ "mqtt\_tls\_tcp\_route\_enabled" : "true" , "mqtt\_tls\_tcp\_route\_primary\_port": 1024 , "orphanedResourcePolicy": "MakeServiceOwned", "vpnOptions":{"serviceRestMode":"gateway"} }'
Creating service instance solace-pubsub-instance-IoT in org example / space development as user@example.com...OK

  6. Getting details about the created service.

    $ cf service solace-pubsub-instance-IoT<br>
Service instance: solace-pubsub-instance-IoT
Service: solace-pubsub
Bound apps:
Tags:
Plan: enterprise-shared
Description: Solace PubSub+ Event Broker for real-time, multi-protocol data distribution
Documentation url: http://docs.solace.com
Dashboard: https<span>:</span>//solace-service-dashboard YOUR-SYSTEM-DOMAIN/service-dashboard/f5d6bf5b-e84f-416b-8c08-4a0e782a51d2/
Last Operation Status: create succeeded
Message: Started: 2020-01-01T00:00:00Z Started: 2020-01-01T00:00:00Z

    Note: The Dashboard URL provides a Web UI to manage the service instance.

  7. Make this new service instance accessible to an app by binding or creating a service key.

Update a Service Instance with the cf CLI

Sometimes, you may want to update an existing service instance to enable or disable a special feature. For example, you may want to close some TCP routes port for a given protocol, due to security concerns. Or you may want adjust LDAP Admin access.

To update an instance of the Solace PubSub+ service with the cf CLI, do the following:

  1. Set your API endpoint to the Cloud Controller of your deployment.

    $ cf api api.YOUR-SYSTEM-DOMAIN
Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...OK
API endpoint:  <span>https:</span>//api.YOUR-SYSTEM-DOMAIN (API version: 2.59.0)
Not logged in. Use 'cf login' to log in.

  2. Log in to your deployment and select an org and a space.

    $ cf login
API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAINEmail> user<span>@</span>example.com
Password>

  3. Locate the previously created service.

    $ cf services
Getting services in org example / space dev as user<span>@</span>example.com...OK

name                        service            plan                bound apps   last operation
solace-pubsub-instance      solace-pubsub      enterprise-large-ha              create succeeded

  4. Update the service instance of the Solace PubSub+ service assuming both LDAP and TCP routes are enabled. This disables external access to the MQTT Plain Text messaging protocol, grants Admin ReadOnly and Admin ReadWrite to the Message VPN for this service instance to the provided LDAP groups, and sets the Orphaned Resource Policy to Delete.

    $ cf update-service solace-pubsub-instance -c '{ "orphanedResourcePolicy": "Delete", "mqtt\_tcp\_route\_enabled" : "false", "ldapGroupAdminReadOnly" : "cn=username1,ou=groups,dc=solace,dc=com", "ldapGroupAdminReadWrite" : "cn=username2,ou=groups,dc=solace,dc=com" }'
Updating service instance solace-pubsub-instance user...OK

    Note: Updating a Service Instance that has existing application bindings or service keys can be a service affecting operation. An existing app using bindings may need to unbind and rebind to obtain its updated Solace PubSub+ Credentials, while an existing app using service keys will need a new service key.

  5. Make this new service instance accessible to an app by binding or creating a service key.

Update a Service Instance to a new Service Plan

An on-demand service instance may be upgraded to a different service plan.

Assuming you have a service named ‘solace-pubsub-instance’ as in the previous section, you can update it to a new service plan by running:

$cf update-service solace-pubsub-instance -p <new-service-plan>

Several restrictions apply:

  1. The service instance must be an on-demand service
  2. The upgrade must be from standalone to HA
  3. The current and new service plans must have a maximum of one message VPN
  4. The current service plan must have AZs as a subset of the AZs of the new service plan
  5. The new service plan must have sufficient available quota
  6. The new service plan must have the same VM type
  7. Ugrading from standard to enterprise is not supported

Deleting a Service Instance with the cf CLI

A service instance may be deleted once it has no bindings and no service keys.

Note: Deleting a service instance is non-recoverable. All data that was in the service instance will be lost.

To delete an instance of the Solace PubSub+ service with the cf CLI, do the following:

  1. Set your API endpoint to the Cloud Controller of your deployment.

    $ cf api api.YOUR-SYSTEM-DOMAIN
Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...OK
API endpoint:  <span>https:</span>//api.YOUR-SYSTEM-DOMAIN (API version: 2.59.0)
Not logged in. Use 'cf login' to log in.

  2. Log in to your deployment and select an org and a space.

    $ cf login
API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAIN
Email> user<span>@</span>example.com
Password>

  3. Locate the previously created service.

    $ cf services
Getting services in org example / space dev as user<span>@</span>example.com...OK

name                            service            plan                bound apps   last operation
solace-pubsub-instance-IoT      solace-pubsub      enterprise-shared                create succeeded

  4. Delete the service instance solace-pubsub-instance-IoT of the Solace PubSub+ service.

    $ cf delete-service solace-pubsub-instance-IoT

Really delete the service solace-pubsub-instance-IoT?
Deleting service solace-pubsub-instance-IoT in org example / space dev as user<span>@</span>example.com...
OK

Delete in progress. Use 'cf services' or 'cf service solace-pubsub-instance-IoT' to check operation status.

  5. You can monitor the progress of the delete operation.

    $ cf services
Getting services in org example / space dev as user<span>@</span>example.com...OK

name                            service            plan                bound apps   last operation
solace-pubsub-instance-IoT      solace-pubsub      enterprise-shared                delete in progress

    Notice the delete in progress; this service is removed after the deletion is completed.

    $ cf services
Getting services in org example / space dev as user<span>@</span>example.com...OK

No services found

Create a Service Instance in Apps Manager

To create an instance of the Solace PubSub+ service in Apps Manager, do the following:

  1. Navigate to apps.YOUR-SYSTEM-DOMAIN in a browser and log in.

  2. Select the org and space in which you want to create the Solace PubSub+ service.

  3. Click on Service.

  4. Click on Add Service.

  5. Click Solace PubSub+.

  6. Select the appropriate service plan for your app. For information on how service plans differ, see VMware Tanzu Marketplace Plans.

    alt-text=""

  7. Enter an Instance Name, select a space under Add to Space and configure any optional parameters if desired. Then click Add.

    alt-text=""

  8. Make this new service instance accessible to an app by binding or creating a service key.

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