Solace Messaging Service Instances

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

About the Solace Service Instance

A Solace Service Instance represents a Message VPN on a Solace Virtual Message Router (VMR). A Message VPN allows for many separate apps to share a single message router while still remaining independent and separated. For more information about Message VPNs, see Core Concepts.

After deploying the Solace Messaging for Pivotal Cloud Foundry (PCF) tile, the Solace Messaging 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 Messaging Credentials.

Creating a service instance also gives the developer permissions to manage the Message VPN through 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 Messaging service called solace-messaging-instance with no added service-specific parameters.
    • How to create a Solace Messaging service called solace-messaging-instance-IoT with added service-specific parameters.
    • How to update the service instance solace-messaging-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 Messaging, 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

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 Messaging service with the cf CLI, perform the following steps:

  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 Messaging 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-messaging shared, large, community, medium-ha, large-ha Solace Messaging for real-time, multi-protocol data distribution

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

    $ cf create-service solace-messaging large-ha solace-messaging-instance
    Creating service instance solace-messaging-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 Messaging service with the cf CLI with service-specific parameters, perform the following steps:

  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 Messaging 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-messaging shared, large, community, medium-ha, large-ha Solace Messaging for real-time, multi-protocol data distribution

  4. Create an instance of the Solace Messaging service. Select the appropriate service plan for your app. For how the service plans differ, see PCF Marketplace Plans. Add applicable service-specific parameters. The following example uses the shared service plan with service-specific parameters for TCP Routes that enable opening an MQTT TLS port to support IoT devices.

    $ cf create-service solace-messaging shared solace-messaging-instance-IoT -c '{ "mqtt_tls_tcp_route_enabled" : "true" }'
    Creating service instance solace-messaging-instance-IoT in org example / space development as user@example.com...
    OK
    
  5. Getting details about the created service.

    $ cf service solace-messaging-instance-IoT
    
    Service instance: solace-messaging-instance-IoT
    Service: solace-messaging
    Bound apps:
    Tags:
    Plan: shared
    Description: Solace Messaging for real-time, multi-protocol data distribution
    Documentation url: http://docs.solace.com
    Dashboard:
    
    Last Operation
    Status: create succeeded
    Message:
    Started: 2020-01-01T00:00:00Z
    Started: 2020-01-01T00:00:00Z
    
  6. 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, let’s say MQTT Plain Text port due to security concerns. Or you may want adjust LDAP Admin access.

To update an instance of the Solace Messaging service with the cf CLI, perform the following steps:

  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-messaging-instance solace-messaging large-ha create succeeded

  4. Update the service instance of the Solace Messaging service assuming both LDAP and TCP Routes are enabled. This disables external access to the MQTT Plain Text messaging protocol, and grants Admin ReadOnly and Admin ReadWrite to the Message VPN for this service instance to the provided LDAP groups.

        $ cf update-service solace-messaging-instance -c '{ "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-messaging-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 Messaging Credentials, an existing app using service keys will need to get 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 Messaging service with the cf CLI, perform the following steps:

  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-messaging-instance-IoT solace-messaging shared create succeeded

  4. Delete the service instance solace-messaging-instance-IoT of the Solace Messaging service.

    $ cf delete-service solace-messaging-instance-IoT
    
    Really delete the service solace-messaging-instance-IoT?> yes
    Deleting service solace-messaging-instance-IoT in org example / space dev as user@example.com...
    OK
    
    Delete in progress. Use 'cf services' or 'cf service solace-messaging-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-messaging-instance-IoT   solace-messaging   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 Messaging service in Apps Manager, perform the following steps:

  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 Messaging service.
  3. Click on Service.
  4. Click on Add Service.
  5. Click Solace Messaging.
  6. Select the appropriate service plan for your app. For now the service plans differ, see PCF Marketplace Plans. Appsmanager solace messaging marketplace selection
  7. Enter an Instance Name and select a space under Add to Space. Then click Add. Appsmanager solace messaging create service do not bind
  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