Declarative SEMP
This section provides information about Solace PubSub+ Declarative SEMP.
PubSub+ Declarative SEMP enables you to configure a PubSub+ event broker
Overview
PubSub+ Declarative SEMP enables a declarative API for the configuration of the PubSub+ event broker for services. Declarative API configuration relies on a target configuration without knowledge of the current configuration. The declarative configuration system then determines how to convert from the current state to the target state.
More specifically, Declarative SEMP provides for a declarative API based on the concept of a module, which is a data structure containing configuration information, and a plug-in that takes the module and a CRUD instruction and maps them to the SEMPv2 API in a declarative fashion. Typical instructions to be taken by the Declarative SEMP interface include:
-
Generate—Provides the current configuration of objects described in the input module as a Hashicorp Configuration Language (HCL) Infrastructure as Code (IaC) file
-
Plan—Identifies the series of changes to be applied to convert the current configuration to the target configuration IaC directory provided
-
Apply—Apply takes a plan or target configuration IaC directory and executes it to convert the current configuration to the target configuration
-
Destroy—Generates a plan to remove configuration elements in the target configuration IaC directory
While a declarative SEMP API could be used in a variety of applications, this feature is initially limited to service configuration, which is defined as the configuration elements contained within a Message VPN (as configured by PubSub+ Broker Manager).
Use Cases
Good examples of uses for declarative configuration include golden configurations, configuration management systems, and service additions from teams other than the messaging infrastructure team.
PubSub+ Declarative SEMP supports the following use cases:
- Application Team Self Serve Infrastructure as Code with Environment Separation
- Configuration Management
Application Team Self Serve Infrastructure as Code with Environment Separation
In this case, suppose you have deployed an event mesh and your application teams have begun to adopt the use of the event mesh en masse. Your messaging infrastructure team cannot keep up with incoming requests to configure consumers and producers on the event mesh infrastructure. You need Solace to provide the ability for your application teams to write IaC to add or remove consumers and/or producers and other non-environmental components within certain constraints to the broker environment your team has already created. You also need to be able to copy services from one environment to the next (for example, in a CICD pipeline). Finally, you need to be able to provide templates (for example, different queue types) for your application teams to leverage in their IaC.
Configuration Management
In this case let's also suppose you have deployed an event mesh and your application teams have begun to adopt the use of the event mesh en masse. However, this time you need to be able to pull down the current configuration of the services (non-infrastructure components) on your event mesh and hold them in a set of configuration files at version control for your event mesh. These version control files can be utilized to revert your event mesh services to their prior configuration in the same environments in the event of configuration corruption or a failed attempt to reconfigure your event mesh services. The version control configurations can also be manually modified to apply these services to the other environments.
Dependencies
PubSub+ Declarative SEMP has the following dependencies:
-
Requires Terraform. Terraform is a command-line program that applies a declarative configuration to create or update as necessary a set of resources via pluggable providers (SEMP objects correspond to resources in Terraform). Providers are automatically downloaded as needed from the public Terraform registry or from private registries as specified in the configuration. The PubSub+ event broker provider
-
In order to properly configure event broker objects for a particular release, you must use the appropriate event broker provider and SEMPv2 versions. For more information, see Version Compatibility .
Limitations
PubSub+ Declarative SEMP has the following limitations:
-
Terraform apply will not be atomic. If interrupted by a user, failure, reboot, or switchover the configuration changes may be partly applied and there will be no attempt to rollback the changes.
-
Terraform must be the authoritative source of configuration. If there is any overlap between Terraform controlled configuration and either pre-existing configuration or modifications from other management interfaces, the behaviour will be undefined.
-
Apply operations may impact performance (especially large changes).
-
Application of configuration may not be hitless. In other words, brief service interruptions may occur during an apply. These can include a queue missing a published message, or clients being briefly disconnected.
-
Declarative SEMP does not support OpenTofu.
-
Declarative SEMP is supported in production environments only on configuration elements specific to a Message VPN. In other words, the elements that you can configure under a Message VPN via PubSub+ Broker Manager. Use of any resource not contained within a Message VPN is not supported.
Within a Message VPN, the following objects are coupled to other objects and subject to additional limitations:
-
ACL profiles—You cannot destroy an ACL profile without removing the coupling from all objects that reference the profile.
-
User profiles—You cannot destroy a user profile without removing the coupling from all objects that reference the profile.
-
Authorization groups—You cannot destroy an authorization group without removing the coupling from all objects that reference the group.
-
LDAP groups—You cannot destroy an LDAP group without removing the coupling from all objects that reference the group.
-
RDP consumer OAuth JWT claims—You cannot manage RDP consumer OAuth JWT claims with Declarative SEMP.
-
Getting Started with PubSub+ Declarative SEMP
For a description of how to use the Solace event broker providers to execute operations against PubSub+ event broker configuration as described in HCL, see the documentation included with each provider:
-
For the
-
For the appliance provider, see https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest/docs.
For a description of how to use the event broker provider to execute operations against PubSub+ event broker configuration as described in HCL, see the documentation included with the provider.
The PubSub+ event broker provider also offers the ability to generate a configuration file from a preconfigured event broker. For more information, see the software event broker
Terraform uses the snake case naming scheme, while SEMP uses camel case. It is also universal practice that resources and datasource be prefixed with the preferred local name of the provider. SEMP names will be converted appropriately for those two requirements but otherwise used as is. For example, this means that solacebroker_msg_vpn is the Message VPN resource name and max_subscription_count is the attribute for the maximum subscription count, since MsgVpn is the SEMP API object name and maxSubscriptionCount is the name of the SEMP attribute.
PubSub+ Terraform Modules
Terraform modules encapsulate the configuration of a set of related Terraform resources into a single module block. The input variables of the module become the configurable attributes of the module block. The output variables of the module become attributes that can be referenced elsewhere from the module object.
Solace includes the following Terraform modules in each provider:
The intent of these modules is to provide a default configuration that middleware teams can modify and pass on to the application development team for further adjustments.
The relationship between each module is described in the following diagram:
Service Module
The Service module encapsulates Message VPN-level service configuration, including protocols, authentication and authorization settings, and resource limits. It defines and makes ACL and client profiles available for use.
For more information, including examples that show common use cases, see the Service Terraform module documentation.
Client Module
The Client module represents a client user entity, either a client username or authorization group.
For more information, including examples that show common use cases, see the Client Terraform module documentation.
JNDI Module
The JNDI module provides a wrapper for a JMS connection factory event broker object. More specifically, this module enables an application team member to create a connection factory object in the JNDI store of an event broker with minimal insight into all of the necessary Solace configuration components by only providing the resource-specific information.
For more information, including examples that show common use cases, see the JNDI Terraform module documentation.
Queue Endpoint Module
The Queue Endpoint module represents a durable event broker endpoint to publish to, or consume from. In addition, it can also represent an endpoint template.
For more information, including examples that show common use cases, see the Queue Endpoint Terraform module documentation.
REST Delivery Module
The Rest Delivery module represents REST delivery point (RDP), REST consumer, and queue binding configuration. More specifically, this module enables an application team member to create an RDP that connects to a consumer (for example, a public cloud) with minimal insight into all of the necessary Solace configuration components by only providing the resource-specific information.
For more information, including examples that show use cases, see the Rest Delivery Terraform module documentation.
Version Compatibility
This section lists the releases of the PubSub+ event broker with the corresponding required PubSub+ provider and SEMPv2 versions.
| PubSub+ Event Broker Version | PubSub+ Event Broker Provider Version | SEMPv2 Version |
|---|---|---|
| 10.9.1 | 1.1.0 | 2.42 |
| 10.8.1 | 1.0 | 2.41 |
| 10.6.1 | 0.9.3 (BETA) | 2.39 |
| 10.4.1 | 0.9.0 (BETA) | 2.36 |
If you use an older Solace event broker provider with a newer event broker, you will not have the option to configure the new resources that might come with the new event broker load. Similarly, for an older event broker with a newer Solace provider, you might have the ability to create resources that the event broker doesn’t support. In that case your Terraform configuration will fail since SEMP doesn’t have the ability to configure your request.