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+ message broker. A Message VPN allows for many separate apps to share a single message broker while still remaining independent and separated. For more information about Message VPNs, see Core Concepts.

After deploying the Solace PubSub+ for Pivotal Cloud Foundry (PCF) 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+ message broker or the SolAdmin administration tool. For more information, see Managing the Message VPN.

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 PCF. 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.

  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. When TCP routes are enabled, and unless the configuration per procotol is “Not Allowed”, you may use these parameters with valid values: true, false to control TCP Routes per service instance.

    • 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
  3. A service-scoped Orphaned Resource Policy may be set at service creation or update time. This service-scoped policy will take precendence over the operator set Default Orphaned Resource Policy. The Orphaned Resource Policy is applied during unbind operations to ensure any 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-scoped. 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:  https://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: https://api.YOUR-SYSTEM-DOMAIN
    Email> user@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@example.com...
    OK

service plans description solace-pubsub enterprise-shared, enterprise-large, enterprise-medium-ha, enterprise-large-ha Solace PubSub+ message broker for real-time, multi-protocol data distribution 1. Create an instance of the Solace PubSub+ service. Select the appropriate service plan for your app. For how the service plans differ, see PCF 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.

  1. 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:  https://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: https://api.YOUR-SYSTEM-DOMAIN
    Email> user@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@example.com...
    OK

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

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

  2. 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 and setting the Orphaned Resource Policy to make any orphaned resources service instance owned.

    $ cf create-service solace-pubsub enterprise-shared solace-pubsub-instance-IoT -c '{ "mqtt_tls_tcp_route_enabled" : "true" , "orphanedResourcePolicy": "MakeServiceOwned" }'
    Creating service instance solace-pubsub-instance-IoT in org example / space development as user@example.com...
    OK
    

  3. Getting details about the created service.

    $ cf service solace-pubsub-instance-IoT

Service instance: solace-pubsub-instance-IoT Service: solace-pubsub Bound apps: Tags: Plan: enterprise-shared Description: Solace PubSub+ message broker for real-time, multi-protocol data distribution Documentation url: http://docs.solace.com Dashboard: https://enterprise-shared-0.YOUR-SYSTEM-DOMAIN/#/msg-vpns/djAwMQ==?token=YWJj.jsalkdj01041024laqksdjalsdh8ayulaksfnaosfr0817u04ualknaglnzs0v8u0qusflasknrflknifQ%3D%3D.eHl6

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.

  1. 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:  https://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: https://api.YOUR-SYSTEM-DOMAIN
    Email> user@example.com
    Password>
    

  3. Locate the previously created service.

    $ cf services
    Getting services in org example / space dev as user@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.

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:  https://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: https://api.YOUR-SYSTEM-DOMAIN
    Email> user@example.com
    Password>
    

  3. Locate the previously created service.

    $ cf services
    Getting services in org example / space dev as user@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?> yes Deleting service solace-pubsub-instance-IoT in org example / space dev as user@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@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@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 PCF Marketplace Plans. Appsmanager select solace pubsub plan short form

  7. Enter an Instance Name and select a space under Add to Space. Then click Add. Appsmanager solace messaging create service do not bind short form new

  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