nservicebusservicecontrol
Version information
This version is compatible with:
- Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
- Puppet >= 4.7.0 < 9.0.0
Tasks:
- get_instances
Plans:
- compact_database
- import_failed_messages
Start using this module
Add this module to your Puppetfile:
mod 'tragiccode-nservicebusservicecontrol', '4.1.0'
Learn more about managing modules with a PuppetfileDocumentation
nservicebusservicecontrol
Table of Contents
- Description
- Setup requirements
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Contributing
Description
The nservicebusservicecontrol module installs and manages Service Control along with Service Control Instances.
ServiceControl is the backend web api used for monitoring and replaying of messages for nservicebus endpoints.
Setup Requirements
The nservicebusservicecontrol module requires the following:
- Puppet Agent 4.7.1 or later.
- Access to the internet.
- Microsoft .NET 4.6.1 Runtime.
- Windows Server 2012/2012R2/2016/2019.
- Powershell v7.2 or greater (pwsh/powershell-core)
Beginning with nservicebusservicecontrol
To get started with the nservicebusservicecontrol module simply include the following in your manifest:
include nservicebusservicecontrol
This example downloads, installs, and configures the latest version of servicecontrol. After running this you should be able to begin to create service control instances and perform other tasks using the nservicebusservicecontrol::instance
, nservicebusservicecontrol::audit_instance
, and nservicebusservicecontrol::monitoring_instance
defined types.
NOTE: By default this module pulls the package from chocolatey (https://chocolatey.org/packages/servicecontrol)
Usage
All parameters for the nservicebusservicecontrol module are contained within the main nservicebusservicecontrol
class, so for any function of the module, set the options you want. See the common usages below for examples.
Install a specific version of service control from chocolatey
class { 'nservicebusservicecontrol':
package_ensure => '4.3.3',
}
NOTE: We recommend always specifying a specific version so that it's easily viewable and explicit in code. The default value is present which just grabs whatever version happens to be the latest at the time your first puppet run happened with this code
Automatically install newer versions as they are released on chocolatey
class { 'nservicebusservicecontrol':
package_ensure => 'latest',
}
NOTE: Put simply, never use this in production ( or really anywhere to be honest ). New versions could contain major breaking changes that this module is incompatible possibly putting servicecontrol in a unknown/undefined state.
Install your license
Installing your commercial license is a piece of cake as shown below.
$license_xml = @(LICENSE)
<?xml version="1.0" encoding="utf-8"?>
<license type="Commercial" ..>
...
</license>
LICENSE
class { 'nservicebusservicecontrol':
package_ensure => 'present',
license_xml => $license_xml,
}
NOTE: Installing or Updating the license will cause the main servicecontrol instance ( error ) to automatically restart. This is to immediately reflect the license change in servicepulse. Since servicecontrol is like any other message based application you can expect no disruptions for your production systems.
Service Control Deployment Topologies
When installing and configuring service control in your environment you have multiple deployment topologies available depending on your needs.
NOTE: Read more about deployment topologies here https://docs.particular.net/servicecontrol/servicecontrol-instances/remotes
Default Deployment
This deployment is the most typical and contains 1 primary/main service control instance and 1 service control audit instance.
$primary_service_control_instance = 'Particular.ServiceControl.Development'
nservicebusservicecontrol::instance { $primary_service_control_instance:
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
remote_instances => ['http://localhost:44444/api'],
}
nservicebusservicecontrol::audit_instance { "${primary_service_control_instance}.Audit":
ensure => 'present',
port => 44444, # This is the default but added here for clarity
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
service_control_queue_address => $primary_service_control_instance,
}
NOTE: The primary/main servicecontrol instance must be created first. This is because in order to create a servicecontrol audit instance you must pass in the queue name of the primary service control instance in which to send notifications to (https://docs.particular.net/servicecontrol/audit-instances/installation-powershell#servicecontrol-audit-instance-cmdlets-and-aliases-adding-an-instance )
Sharding Audit Messages With Competing Consumers
This deployment is commonly used when you have a high number of messages and need to use the competing consumers pattern on the your audit queue.
$primary_service_control_instance = 'Particular.ServiceControl.Development'
nservicebusservicecontrol::instance { $primary_service_control_instance:
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
remote_instances => ['http://localhost:44444/api', 'http://localhost:44445/api'],
}
nservicebusservicecontrol::audit_instance { "${primary_service_control_instance}.Audit":
ensure => 'present',
port => 44444, # This is the default but added here for clarity
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
service_control_queue_address => $primary_service_control_instance,
}
nservicebusservicecontrol::audit_instance { "${primary_service_control_instance}.Audit2":
ensure => 'present',
port => 44445,
database_maintenance_port => 44446,
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
service_control_queue_address => $primary_service_control_instance,
}
Sharding Audit Messages With Split Audit Queue
This deployment is commonly used when you have endpoints whos audit messages should have different retention periods.
$primary_service_control_instance = 'Particular.ServiceControl.Development'
nservicebusservicecontrol::instance { $primary_service_control_instance:
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
remote_instances => ['http://localhost:44444/api', 'http://localhost:44445/api'],
}
nservicebusservicecontrol::audit_instance { "${primary_service_control_instance}.Audit":
ensure => 'present',
port => 44444, # This is the default but added here for clarity
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
service_control_queue_address => $primary_service_control_instance,
}
nservicebusservicecontrol::audit_instance { "${primary_service_control_instance}.CustomerRelations.Audit":
ensure => 'present',
port => 44445,
database_maintenance_port => 44446,
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
audit_queue => 'audit.customerrelations',
service_control_queue_address => $primary_service_control_instance,
}
Service Control Instances
This represents the primary/main service control instance that ingests messages from your centralized error queue.
NOTE: In most cases users will install both a primary/main service control instance to ingest from their error queue with one or more audit instances ( remote instances ) to ingest from their audit queue. The examples below this point highlight specifically the main/primary service control instance and therefore the audit instance resource you typically declare next to it is left out for brevity
Create a Service Control Instance using the MSMQ Transport
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'MSMQ',
}
NOTE: Ensure the MSMQ Windows Feature is is already installed. ServiceControl by default will take care of creating the tables for using as queues
Create a Service Control Instance using the RabbitMQ Conventional Routing Topology (quorum queues) Transport
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
}
Create a Service Control Instance using the RabbitMQ Conventional Routing Topology (classic queues) Transport
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (classic queues)',
connection_string => 'host=localhost;username=guest;password=guest',
}
Create a Service Control Instance using the SQLServer Transport ( SQL Authentication )
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=Particular.ServiceControl.Development; User Id=svc-servicecontrol; Password=super-secret-password;',
}
NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.
Create a Service Control Instance using the SQLServer Transport ( Windows Authentication )
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=Particular.ServiceControl.Development; Trusted_Connection=True;',
service_account => 'DOMAIN\svc-servicecontrol',
service_account_password => 'super-secret-password',
}
NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.
Create a Service Control Instance using the Azure Storage Queue Transport
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'Azure Storage Queue',
# connection_string => 'UseDevelopmentStorage=true',
connection_string => 'DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];',
...
}
Create a Service Control Instance using the Azure Service Bus Transport
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'Azure Service Bus',
connection_string => 'Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]',
...
}
Create a Service Control Instance using the Amazon SQS Transport
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'AmazonSQS',
...
}
Service Control Instance with forward error queues
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
forward_error_messages => true,
error_log_queue => 'error.log',
}
NOTE: If external integration is not required, it is highly recommend to turn forwarding queues off. Otherwise, messages will accumulate unprocessed in the forwarding queue until eventually all available disk space is consume
Enable ability to edit message body & headers in Service Pulse
nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
allow_message_editing => true,
}
Service Control Audit Instances
This represents the 1 or more service control audit instance that ingests messages from your centralized audit queue. This is also needed if you plan on utilizing the Particular Service Insight tool for debugging.
Create a Service Control Audit Instance using the MSMQ Transport
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'MSMQ',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
}
NOTE: Ensure the MSMQ Windows Feature is is already installed. ServiceControl by default will take care of creating the tables for using as queues
Create a Service Control Audit Instance using the RabbitMQ Conventional Routing Topology Transport
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
}
Create a Service Control Audit Instance using the SQLServer Transport ( SQL Authentication )
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=Particular.ServiceControl.Development; User Id=svc-servicecontrol; Password=super-secret-password;',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
}
NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.
Create a Service Control Audit Instance using the SQLServer Transport ( Windows Authentication )
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=Particular.ServiceControl.Development; Trusted_Connection=True;',
service_account => 'DOMAIN\svc-servicecontrol',
service_account_password => 'super-secret-password',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
}
NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.
Create a Service Control Audit Instance using the Azure Storage Queue Transport
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'Azure Storage Queue',
# connection_string => 'UseDevelopmentStorage=true',
connection_string => 'DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
...
}
Create a Service Control Audit Instance using the Azure Service Bus Transport
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'Azure Service Bus',
connection_string => 'Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
...
}
Create a Service Control Audit Instance using the Amazon SQS Transport
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'AmazonSQS',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
...
}
Service Control Audit Instance with forward audit queues
nservicebusservicecontrol::audit_instance { 'Particular.ServiceControl.Development.Audit':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
forward_audit_messages => true,
audit_log_queue => 'audit.log',
service_control_queue_address => 'Particular.ServiceControl.Development', # The queue name of the primary/main service control instance
}
NOTE: If external integration is not required, it is highly recommend to turn forwarding queues off. Otherwise, messages will accumulate unprocessed in the forwarding queue until eventually all available disk space is consume
Service Control Monitoring Instances
Create a Service Control Monitoring Instance using the MSMQ Transport
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'MSMQ',
}
NOTE: Ensure the MSMQ Windows Feature is is already installed. ServiceControl by default will take care of creating the tables for using as queues
Create a Service Control Monitoring Instance using the RabbitMQ Conventional Routing Topology Transport
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology (quorum queues)',
connection_string => 'host=localhost;username=guest;password=guest',
}
Create a Service Control Monitoring Instance using the SQLServer Transport ( SQL Authentication )
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=Particular.Monitoring.Development; User Id=svc-servicecontrol; Password=super-secret-password;',
}
NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.
Create a Service Control Monitoring Instance using the SQLServer Transport ( Windows Authentication )
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=Particular.Monitoring.Development; Trusted_Connection=True;',
service_account => 'DOMAIN\svc-servicecontrol',
service_account_password => 'super-secret-password',
}
NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.
Create a Service Control Monitoring Instance using the Azure Storage Queue Transport
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'Azure Storage Queue',
# connection_string => 'UseDevelopmentStorage=true',
connection_string => 'DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];',
..
}
Create a Service Control Instance using the Azure Service Bus Transport
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'Azure Service Bus',
connection_string => 'Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]',
...
}
Create a Service Control Instance using the Amazon SQS Transport
nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
ensure => 'present',
transport => 'AmazonSQS',
...
}
Create a Retry Redirect
When a failed message needs to be retried, but the destination endpoint no longer exists, and the message needs to be routed to a different endpoint. This is where retry redirects comes in and those can be managed using the nservicebusservicecontrol::retry_redirect
resource as shown below.
nservicebusservicecontrol::retry_redirect { 'Ordering.Endpoint':
ensure => present,
destination_queue => 'SomeDestinationEndpoint',
service_control_url => 'http://localhost:33333',
}
Reimport failed errror/audit messages
When you have messages that fail to be imported you can easily re-import them in an automated and painless way using the nservicebusservicecontrol::import_failed_messages
bolt plan.
NOTE: This plan requires the puppet agent installed on the remote.
$ bolt plan show nservicebusservicecontrol::import_failed_messages
nservicebusservicecontrol::import_failed_messages
Imports failed error or audit messages.
Usage
Invoke-BoltPlan -Name nservicebusservicecontrol::import_failed_messages
instance_name=<value> instance_type=<value> targets=<value>
Parameters
instance_name String[1]
The name of the servicecontrol instance.
instance_type Enum['error', 'audit']
The servicecontrol instance type (Audit or Error).
targets TargetSpec
Targets to import failed messages on.
Workflow followed by plan
Below is the documented workflow of the above nservicebusservicecontrol::import_failed_messages
plan so that you, as an administrator, have a better understanding on what to expect and what is happening.
- Disable the puppet agent
- Wait for any currently active puppet agent runs to finish
- Stop the specificed service control instance
- Import the failed error or audit messages
- Start the specified service control instance
- Enable the puppet agent
Compact RavenDB Database
To compact the RavenDB Database for a given servicecontrol instance you can simply use the nservicebusservicecontrol::compact_database
bolt plan.
NOTE: This plan requires the puppet agent installed on the remote.
$ bolt plan show nservicebusservicecontrol::compact_database
nservicebusservicecontrol::compact_database Compacts the servicecontrol instance's RavenDB Database. Usage Invoke-BoltPlan -Name nservicebusservicecontrol::compact_database
instance_name=<value> targets=<value>
Parameters
instance_name String[1]
The name of the servicecontrol instance.
targets TargetSpec
Targets to compact databases.
Workflow followed by plan
Below is the documented workflow of the above nservicebusservicecontrol::compact_database
plan so that you, as an administrator, have a better understanding on what to expect and what is happening.
- Disable the puppet agent
- Wait for any currently active puppet agent runs to finish
- Stop the specificed service control instance
- Check to ensure database is in a consistent state and ready for defragmentation
- Defragment the database
- Start the specified service control instance
- Enable the puppet agent
Reference
See REFERENCE.md
Limitations
Unable to detect failing to create servicecontrol instance
There is a bug in the New-ServiceControlInstance powershell cmdlet that ships with servicecontrol that causes any failure to not be propogated to the caller correctly. This makes it impossible to determine if the instance creation was successful or failed. Therefore, failed puppet runs could be misleading and the resulting errors might be caused from this situation.
https://github.com/Particular/ServiceControl/issues/1565
Forwarding queues are created only at servicecontrol instance creation time only
If you enable the error or audit forwarding queue features after a service control instance is created these queues will not get created. It's therefore your responsibility to manually create these and set them up if you decide to change your mind after a servicecontrol instance has been created. This is a limitation of servicecontrol itself.
Unsupported transports
I have selectively chosen not to support what appears to be old or deprecated transports. If you need one feel free to open an issue and if your feeling lucky submitting a pull-request.
- Azure Service Bus - Forwarding topology (Legacy)
- Azure Service Bus - Forwarding topology (Old)
- Azure Service Bus - Endpoint-oriented topology (Legacy)
- Azure Service Bus - Endpoint-oriented topology (Old)
- RabbitMQ - Direct routing topology (Old)
Contributing
- Fork it ( https://github.com/tragiccode/tragiccode-nservicebusservicecontrol/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Reference
Table of Contents
Classes
Public Classes
nservicebusservicecontrol
: Installs and configures Particular's Service Control Monitoring Tool.
Private Classes
nservicebusservicecontrol::config
: This class handles the configuration of servicecontrol.nservicebusservicecontrol::install
: This class handles the management of the servicecontrol installer and package.
Defined types
nservicebusservicecontrol::audit_instance
: Manages Service Control Instances.nservicebusservicecontrol::instance
: Manages Service Control Instances.nservicebusservicecontrol::monitoring_instance
: Manages Service Control Monitoring Instances.nservicebusservicecontrol::retry_redirect
: Manages Retry Redirects.
Data types
Nservicebusservicecontrol::Log_level
: Supported log levels for servicecontrolNservicebusservicecontrol::Transport
: Supported NServicebus transports
Tasks
get_instances
: Gets all servicecontrol instances.
Plans
nservicebusservicecontrol::compact_database
: Compacts the servicecontrol instance's RavenDB Database.nservicebusservicecontrol::import_failed_messages
: Imports failed error or audit messages.
Classes
nservicebusservicecontrol
Installs and configures Particular's Service Control Monitoring Tool.
Parameters
The following parameters are available in the nservicebusservicecontrol
class:
package_ensure
Data type: String
Whether to install the ServiceControl package.
Default value: 'present'
package_source
Data type: Optional[String]
The package source for the package.
Default value: undef
license_xml
Data type: Optional[String]
A valid NServiceBus XML License.
Default value: undef
Defined types
nservicebusservicecontrol::audit_instance
Manages Service Control Instances.
Parameters
The following parameters are available in the nservicebusservicecontrol::audit_instance
defined type:
ensure
service_control_queue_address
instance_name
install_path
log_path
db_path
db_index_storage_path
instance_log_level
host_name
port
database_maintenance_port
maximum_concurrency_level
expose_ravendb
audit_queue
audit_log_queue
ravendb_log_level
transport
display_name
connection_string
description
forward_audit_messages
service_account
service_account_password
service_restart_on_config_change
audit_retention_period
time_to_restart_audit_ingestion_after_failure
enable_full_text_search_on_bodies
expiration_process_timer_in_seconds
expiration_process_batch_size
data_space_remaining_threshold
max_body_size_to_store
http_default_connection_limit
minimum_storage_left_required_for_ingestion
service_manage
skip_queue_creation
remove_db_on_delete
remove_logs_on_delete
automatic_instance_upgrades
instance_create_and_upgrade_acknowledgements
ensure
Data type: Enum['present', 'absent']
Specifies whether the instance should exist.
service_control_queue_address
Data type: String
The ServiceControl queue name to use for plugin messages (e.g. Heartbeats, Custom Checks, Saga Audit, etc ).
instance_name
Data type: String
Specify the name of the ServiceControl Instance (title).
Default value: $title
install_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl Instance.
Default value: "C:\\Program Files (x86)\\Particular Software\\${instance_name}"
log_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl Logs.
Default value: "C:\\ProgramData\\Particular\\ServiceControl\\${instance_name}\\Logs"
db_path
Data type: Stdlib::Absolutepath
Specify the directory that will contain the nservicebusservicecontrol database for this ServiceControl Instance.
Default value: "C:\\ProgramData\\Particular\\ServiceControl\\${instance_name}\\DB"
db_index_storage_path
Data type: Stdlib::Absolutepath
Specify the path for the indexes on disk.
Default value: "${db_path}\\Indexes"
instance_log_level
Data type: Nservicebusservicecontrol::Log_level
Specify the level of logging that should be used in ServiceControl logs.
Default value: 'Warn'
host_name
Data type: Stdlib::Fqdn
Specify the hostname to use in the URLACL.
Default value: 'localhost'
port
Data type: Stdlib::Port
Specify the port number to listen on. If this is the only ServiceControl instance then 44444 is recommended.
Default value: 44444
database_maintenance_port
Data type: Stdlib::Port
Specify the database maintenance port number to listen on. If this is the only ServiceControl instance then 44445 is recommended.
Default value: 44445
maximum_concurrency_level
Data type: Integer
This setting controls how many messages can be processed concurrently (in parallel) by ServiceControl.
Default value: 32
expose_ravendb
Data type: Boolean
Specify if the embedded ravendb database should be accessible outside of maintenance mode.
Default value: false
audit_queue
Data type: String
The name of the audit queue.
Default value: 'audit'
audit_log_queue
Data type: String
The name of the audit forwarding queue.
Default value: 'audit.log'
ravendb_log_level
Data type: Nservicebusservicecontrol::Log_level
Specify the level of logging that should be used in ravendb logs.
Default value: 'Warn'
transport
Data type: Nservicebusservicecontrol::Transport
Specify the NServiceBus Transport to use.
Default value: 'MSMQ'
display_name
Data type: String
Specify the Windows Service Display name. If unspecified the instance name will be used.
Default value: $instance_name
connection_string
Data type: Optional[String]
Specify the connection string to use to connect to the queuing system.
Default value: undef
description
Data type: String
Specify the description to use on the Windows Service for this instance.
Default value: 'A ServiceControl Audit Instance'
forward_audit_messages
Data type: Boolean
whether or not to forward audit messages.
Default value: false
service_account
Data type: String
The Account to run the Windows service.
Default value: 'LocalSystem'
service_account_password
Data type: Optional[String]
The password for the ServiceAccount.
Default value: undef
service_restart_on_config_change
Data type: Boolean
Specify if the servicecontrol instance's windows service should be restarted to pick up changes to its configuration file.
Default value: true
audit_retention_period
Data type: String
Specify thd grace period that faulted messages are kept before they are deleted.
Default value: '30.00:00:00'
time_to_restart_audit_ingestion_after_failure
Data type: String
Specify the maximum time delay to wait before restarting the audit ingestion pipeline after detecting a connection problem. This setting was introduced in ServiceControl version 4.4.1.
Default value: '00.00:01:00'
enable_full_text_search_on_bodies
Data type: Boolean
Allows full text searches to happen on the body of messages. This setting was introduced in ServiceControl version 4.17.0.
Default value: true
expiration_process_timer_in_seconds
Data type: Integer
Specifies the number of seconds to wait between checking for expired messages.
Default value: 600
expiration_process_batch_size
Data type: Integer
Specifies the batch size to use when checking for expired messages.
Default value: 65512
data_space_remaining_threshold
Data type: Integer
The percentage threshold for the Message database storage space check. If the remaining hard drive space drops below this threshold (as a percentage of the total space on the drive), then the check will fail, alerting the user.
Default value: 20
max_body_size_to_store
Data type: Integer
Specifies the upper limit on body size to be configured.
Default value: 102400
http_default_connection_limit
Data type: Integer
Specifies the maximum number of concurrent connections allowed by ServiceControl.
Default value: 100
minimum_storage_left_required_for_ingestion
Data type: Integer
The percentage threshold for the Critical message database storage space check.
Default value: 5
service_manage
Data type: Boolean
Specifies whether or not to manage the desired state of the windows service for this instance.
Default value: true
skip_queue_creation
Data type: Boolean
Normally an instance will attempt to create the queues that it uses. If this flag is set, queue creation will be skipped.
Default value: false
remove_db_on_delete
Data type: Boolean
Remove service control instance ravendb database when instance is deleted.
Default value: false
remove_logs_on_delete
Data type: Boolean
Remove service control instance logs when instance is deleted.
Default value: false
automatic_instance_upgrades
Data type: Boolean
Automatically upgrade the service control monitoring instance when a new version of servicecontrol is installed.
Default value: true
instance_create_and_upgrade_acknowledgements
Data type: Optional[String]
Acknowledge mandatory requirements have been met during instance creation and upgrades.
Default value: undef
nservicebusservicecontrol::instance
Manages Service Control Instances.
Parameters
The following parameters are available in the nservicebusservicecontrol::instance
defined type:
ensure
instance_name
install_path
log_path
db_path
db_index_storage_path
db_logs_path
instance_log_level
host_name
port
database_maintenance_port
maximum_concurrency_level
retry_history_depth
remote_instances
expose_ravendb
ravendb_log_level
error_queue
error_log_queue
transport
display_name
connection_string
description
forward_error_messages
service_account
service_account_password
service_restart_on_config_change
error_retention_period
time_to_restart_error_ingestion_after_failure
disable_external_integrations_publishing
enable_full_text_search_on_bodies
event_retention_period
expiration_process_timer_in_seconds
expiration_process_batch_size
data_space_remaining_threshold
http_default_connection_limit
heartbeat_grace_period
allow_message_editing
notifications_filter
minimum_storage_left_required_for_ingestion
service_manage
skip_queue_creation
remove_db_on_delete
remove_logs_on_delete
automatic_instance_upgrades
instance_create_and_upgrade_acknowledgements
ensure
Data type: Enum['present', 'absent']
Specifies whether the instance should exist.
instance_name
Data type: String
Specify the name of the ServiceControl Instance (title).
Default value: $title
install_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl Instance.
Default value: "C:\\Program Files (x86)\\Particular Software\\${instance_name}"
log_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl Logs.
Default value: "C:\\ProgramData\\Particular\\ServiceControl\\${instance_name}\\Logs"
db_path
Data type: Stdlib::Absolutepath
Specify the directory that will contain the nservicebusservicecontrol database for this ServiceControl Instance.
Default value: "C:\\ProgramData\\Particular\\ServiceControl\\${instance_name}\\DB"
db_index_storage_path
Data type: Stdlib::Absolutepath
Specify the path for the indexes on disk.
Default value: "${db_path}\\Indexes"
db_logs_path
Data type: Stdlib::Absolutepath
Specify the path for the Esent logs on disk.
Default value: "${db_path}\\logs"
instance_log_level
Data type: Nservicebusservicecontrol::Log_level
Specify the level of logging that should be used in ServiceControl logs.
Default value: 'Warn'
host_name
Data type: Stdlib::Fqdn
Specify the hostname to use in the URLACL.
Default value: 'localhost'
port
Data type: Stdlib::Port
Specify the port number to listen on. If this is the only ServiceControl instance then 33333 is recommended.
Default value: 33333
database_maintenance_port
Data type: Stdlib::Port
Specify the database maintenance port number to listen on. If this is the only ServiceControl instance then 33334 is recommended.
Default value: 33334
maximum_concurrency_level
Data type: Integer
This setting controls how many messages can be processed concurrently (in parallel) by ServiceControl.
Default value: 10
retry_history_depth
Data type: Integer
The depth of retry history.
Default value: 10
remote_instances
Data type: Array[String]
Specify an optional array of remote instances.
Default value: []
expose_ravendb
Data type: Boolean
Specify if the embedded ravendb database should be accessible outside of maintenance mode.
Default value: false
ravendb_log_level
Data type: Nservicebusservicecontrol::Log_level
Specify the level of logging that should be used in ravendb logs.
Default value: 'Warn'
error_queue
Data type: String
Specify ErrorQueue name to consume messages from.
Default value: 'error'
error_log_queue
Data type: String
Specify Queue name to forward error messages to.
Default value: 'error.log'
transport
Data type: Nservicebusservicecontrol::Transport
Specify the NServiceBus Transport to use.
Default value: 'MSMQ'
display_name
Data type: String
Specify the Windows Service Display name. If unspecified the instance name will be used.
Default value: $instance_name
connection_string
Data type: Optional[String]
Specify the connection string to use to connect to the queuing system.
Default value: undef
description
Data type: String
Specify the description to use on the Windows Service for this instance.
Default value: 'A ServiceControl Instance'
forward_error_messages
Data type: Boolean
Specify if audit messages are forwarded to the queue specified by ErrorLogQueue.
Default value: false
service_account
Data type: String
The Account to run the Windows service.
Default value: 'LocalSystem'
service_account_password
Data type: Optional[String]
The password for the ServiceAccount.
Default value: undef
service_restart_on_config_change
Data type: Boolean
Specify if the service control instance's windows service should be restarted to pick up changes to its configuration file.
Default value: true
error_retention_period
Data type: String
Specify thd grace period that faulted messages are kept before they are deleted.
Default value: '15.00:00:00'
time_to_restart_error_ingestion_after_failure
Data type: String
Specify the maximum time delay to wait before restarting the error ingestion pipeline after detecting a connection problem. This setting was introduced in ServiceControl version 4.4.1.
Default value: '00.00:01:00'
disable_external_integrations_publishing
Data type: Boolean
Disable external integrations publishing.
Default value: false
enable_full_text_search_on_bodies
Data type: Boolean
Allows full text searches to happen on the body of messages. This setting was introduced in ServiceControl version 4.17.0.
Default value: true
event_retention_period
Data type: String
Specifies the period to keep event logs before they are deleted.
Default value: '14.00:00:00'
expiration_process_timer_in_seconds
Data type: Integer
Specifies the number of seconds to wait between checking for expired messages.
Default value: 600
expiration_process_batch_size
Data type: Integer
Specifies the batch size to use when checking for expired messages.
Default value: 65512
data_space_remaining_threshold
Data type: Integer
The percentage threshold for the Message database storage space check. If the remaining hard drive space drops below this threshold (as a percentage of the total space on the drive), then the check will fail, alerting the user.
Default value: 20
http_default_connection_limit
Data type: Integer
Specifies the maximum number of concurrent connections allowed by ServiceControl.
Default value: 100
heartbeat_grace_period
Data type: String
Specifies the period that defines whether an endpoint is considered alive or not since the last received heartbeat.
Default value: '00:00:40'
allow_message_editing
Data type: Boolean
Enables the ability for servicepulse to allow users to edit failed messages before being retried.
Default value: false
notifications_filter
Data type: String
Configures notification filters.
Default value: ''
minimum_storage_left_required_for_ingestion
Data type: Integer
The percentage threshold for the Critical message database storage space check.
Default value: 5
service_manage
Data type: Boolean
Specifies whether or not to manage the desired state of the windows service for this instance.
Default value: true
skip_queue_creation
Data type: Boolean
Normally an instance will attempt to create the queues that it uses. If this flag is set, queue creation will be skipped.
Default value: false
remove_db_on_delete
Data type: Boolean
Remove service control instance ravendb database when instance is deleted.
Default value: false
remove_logs_on_delete
Data type: Boolean
Remove service control instance logs when instance is deleted.
Default value: false
automatic_instance_upgrades
Data type: Boolean
Automatically upgrade the service control monitoring instance when a new version of servicecontrol is installed.
Default value: true
instance_create_and_upgrade_acknowledgements
Data type: Optional[String]
Acknowledge mandatory requirements have been met during instance creation and upgrades.
Default value: undef
nservicebusservicecontrol::monitoring_instance
Manages Service Control Monitoring Instances.
Parameters
The following parameters are available in the nservicebusservicecontrol::monitoring_instance
defined type:
ensure
instance_name
install_path
log_path
instance_log_level
host_name
port
maximum_concurrency_level
endpoint_uptime_grace_period
error_queue
transport
display_name
connection_string
description
service_account
service_account_password
service_restart_on_config_change
service_manage
skip_queue_creation
remove_logs_on_delete
automatic_instance_upgrades
instance_create_and_upgrade_acknowledgements
ensure
Data type: Enum['present', 'absent']
Specifies whether the monitoring instance should exist.
instance_name
Data type: String
Specify the name of the ServiceControl Monitoring Instance (title).
Default value: $title
install_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl Monitoring Instance.
Default value: "C:\\Program Files (x86)\\Particular Software\\${instance_name}"
log_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl Monitoring Logs.
Default value: "C:\\ProgramData\\Particular\\ServiceControl\\${instance_name}\\Logs"
instance_log_level
Data type: Nservicebusservicecontrol::Log_level
Specify the level of logging that should be used in ServiceControl Monitoring logs.
Default value: 'Warn'
host_name
Data type: Stdlib::Fqdn
Specify the hostname to use in the URLACL.
Default value: 'localhost'
port
Data type: Stdlib::Port
Specify the port number to listen on. If this is the only ServiceControl Monitoring instance then 33633 is recommended.
Default value: 33633
maximum_concurrency_level
Data type: Integer
This setting controls how many messages can be processed concurrently (in parallel) by ServiceControl.
Default value: 32
endpoint_uptime_grace_period
Data type: String
The grace period for endpoint uptime.
Default value: '00:00:40'
error_queue
Data type: String
Specify the ErrorQueue name.
Default value: 'error'
transport
Data type: Nservicebusservicecontrol::Transport
Specify the NServiceBus Transport to use.
Default value: 'MSMQ'
display_name
Data type: String
Specify the Windows Service Display name. If unspecified the monitoring instance name will be used.
Default value: $instance_name
connection_string
Data type: Optional[String]
Specify the connection string to use to connect to the queuing system.
Default value: undef
description
Data type: String
Specify the description to use on the Windows Service for this instance.
Default value: 'A Monitoring Instance'
service_account
Data type: String
The Account to run the Windows service.
Default value: 'LocalSystem'
service_account_password
Data type: Optional[String]
The password for the ServiceAccount.
Default value: undef
service_restart_on_config_change
Data type: Boolean
Specify if the servicecontrol monitoring instance's windows service should be restarted to pick up changes to its configuration file.
Default value: true
service_manage
Data type: Boolean
Specifies whether or not to manage the desired state of the windows service for this instance.
Default value: true
skip_queue_creation
Data type: Boolean
Normally an instance will attempt to create the queues that it uses. If this flag is set, queue creation will be skipped.
Default value: false
remove_logs_on_delete
Data type: Boolean
Specifies if the service control logs should be deleted with the instance.
Default value: false
automatic_instance_upgrades
Data type: Boolean
Automatically upgrade the service control monitoring instance when a new version of servicecontrol is installed.
Default value: true
instance_create_and_upgrade_acknowledgements
Data type: Optional[String]
Acknowledge mandatory requirements have been met during instance creation and upgrades.
Default value: undef
nservicebusservicecontrol::retry_redirect
Manages Retry Redirects.
Parameters
The following parameters are available in the nservicebusservicecontrol::retry_redirect
defined type:
ensure
Data type: Enum['present', 'absent']
Specifies whether the retry redirect should exist.
source_queue
Data type: String
Specify the queue for which this redirect will be applied.
Default value: $title
service_control_url
Data type: String
Url for servicecontrol in format of 'http://localhost:33333'.
destination_queue
Data type: String
Specify the queue that will be the new destination when retrying.
Data types
Nservicebusservicecontrol::Log_level
Supported log levels for servicecontrol
Alias of Enum['Trace', 'Debug', 'Info', 'Warn', 'Error', 'Fatal', 'Off']
Nservicebusservicecontrol::Transport
Supported NServicebus transports
Alias of Enum['RabbitMQ - Conventional routing topology', 'RabbitMQ - Conventional routing topology (classic queues)', 'RabbitMQ - Conventional routing topology (quorum queues)', 'SQL Server', 'MSMQ', 'Azure Storage Queue', 'Azure Service Bus', 'AmazonSQS']
Tasks
get_instances
Gets all servicecontrol instances.
Supports noop? false
Plans
nservicebusservicecontrol::compact_database
Compacts the servicecontrol instance's RavenDB Database.
Parameters
The following parameters are available in the nservicebusservicecontrol::compact_database
plan:
targets
Data type: TargetSpec
Targets to compact databases.
instance_name
Data type: String[1]
The name of the servicecontrol instance.
nservicebusservicecontrol::import_failed_messages
Imports failed error or audit messages.
Parameters
The following parameters are available in the nservicebusservicecontrol::import_failed_messages
plan:
targets
Data type: TargetSpec
Targets to import failed messages on.
instance_name
Data type: String[1]
The name of the servicecontrol instance.
instance_type
Data type: Enum['error', 'audit']
The servicecontrol instance type (Audit or Error).
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
get_instances
Gets all servicecontrol instances.
What are plans?
Modules can contain plans that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
v4.1.0 - 2024-10-29
Added
- (GH-155) Update GH actions to match puppetlabs #156 (TraGicCode)
v4.0.0 - 2023-12-13
Changed
- (GH-146) Particular.ServiceControl.Management powershell 7.2 >= requirement #147 (TraGicCode)
v3.5.0 - 2023-09-21
Added
- (GH-139) Add minimum_storage_left_required_for_ingestion to error instance #144 (TraGicCode)
v3.4.0 - 2023-09-21
Added
- (GH-140) Update audit instance settings #142 (TraGicCode)
v3.3.0 - 2023-09-20
Added
- (GH-136) Use powershell gallery module #137 (TraGicCode)
v3.2.0 - 2023-09-19
Added
- (GH-121) Remove DisableRavenDbPerformanceCounters Appsettings #132 (TraGicCode)
v3.1.0 - 2023-09-07
Added
- (GH-122) Add puppet 8 support #123 (TraGicCode)
v3.0.0 - 2022-11-22
Changed
- (GH-116) update audit instances to use newer ravendb #117 (TraGicCode)
v2.2.1 - 2022-10-10
Fixed
- (GH-112) Update acceptance tests to use always 'instance_create_and_upgrade_acknowledgements' #113 (TraGicCode)
v2.2.0 - 2022-10-04
Added
- (GH-99) Add retry redirect resource #110 (TraGicCode)
v2.1.0 - 2022-08-07
Added
- (GH-107) Add windows server 2022 support #108 (TraGicCode)
v2.0.0 - 2022-08-05
Changed
- (GH-103) add new rabbitmq transport types #104 (TraGicCode)
v1.9.0 - 2022-08-04
Added
- (GH-100) Add open source Apache license #101 (TraGicCode)
v1.8.2 - 2022-05-13
Fixed
- (GH-95) Fix config file not being idempotent after instance upgrades #96 (TraGicCode)
v1.8.1 - 2022-02-23
Fixed
- (GH-84) Fix instance auto upgrade failing #85 (TraGicCode)
v1.8.0 - 2022-02-08
v1.7.0 - 2022-02-08
Added
- (GH-68) Add Notifications Filter, DisableExternalIntegrationsPublishing, and RetryHistoryDepth configuration settings #77 (TraGicCode)
- (GH-65) Implement new audit, error, and monitoring app.config settings #66 (TraGicCode)
v1.6.0 - 2021-11-10
Added
- (GH-64) Add full text search on body setting #63 (TraGicCode)
v1.5.0 - 2021-07-02
Added
- Add compact_database plan #60 (TraGicCode)
v1.4.2 - 2021-07-01
Fixed
- (GH-57) Fix module import causing bolt task to output non-json #58 (TraGicCode)
v1.4.1 - 2020-06-24
Fixed
- (GH-51) Create license folder to license installation doesn't blow up! #52 (TraGicCode)
v1.4.0 - 2020-06-08
Added
- (GH-44) Automatically restart main servicecontrol instance upon license install/update #46 (TraGicCode)
Fixed
- (GH-47) Properly compare version numbers when doing automatic instance upgrade #48 (TraGicCode)
v1.3.0 - 2020-05-20
Added
- Improve validation and handling of user input in failed audit/error import bolt plan #41 (TraGicCode)
- (GH-39) Add license to filesystem along with registry #40 (TraGicCode)
- (GH-36) Removed maxbodysize from error servicecontrol instance #37 (TraGicCode)
- (GH-14) Bolt plan to import failed audit and error #35 (TraGicCode)
- (GH-25) Added DataSpaceRemainingThreshold setting #34 (TraGicCode)
v1.2.0 - 2020-04-11
Added
- (GH-31) Add message ingestion failure restart #32 (TraGicCode)
v1.1.0 - 2019-10-09
Added
- (GH-28) Allow enabling editing messages for retry #29 (TraGicCode)
v1.0.0 - 2019-10-07
Changed
- Implement v4 breaking changes #26 (TraGicCode)
Fixed
- (GH-23) Set forward_audit_messages parameter to false as default #24 (TraGicCode)
0.3.1 - 2019-02-06
Fixed
- (GH-12) Remove instance config settings limitation from docs #13 (TraGicCode)
- (GH-10) Remove package upgrade limitation from docs #11 (TraGicCode)
0.3.0 - 2019-02-04
Added
- (GH-6) Ability to manage service control monitoring instances #8 (TraGicCode)
0.2.1 - 2019-01-25
Fixed
- Fixing up dependency conflict with chocolatey. #5 (TraGicCode)
0.2.0 - 2019-01-24
Added
- Use chocolatey for the servicecontrol package. #3 (TraGicCode)
0.1.0 - 2019-01-24
Dependencies
- gabe/agent_disenable (>= 1.0.0 < 2.0.0)
- encore/powershellmodule (>= 2.0.0 < 3.0.0)
- puppetlabs/chocolatey (>= 3.0.0 < 9.0.0)
- puppetlabs/powershell (>= 1.0.1 < 7.0.0)
- puppetlabs/pwshlib (>= 1.0.0 < 2.0.0)
- puppetlabs/registry (>= 1.0.0 < 6.0.0)
- puppetlabs/stdlib (>= 4.0.0 < 10.0.0)