nservicebusservicecontrol
Version information
This version is compatible with:
- Puppet Enterprise 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 < 7.0.0
Start using this module
Add this module to your Puppetfile:
mod 'tragiccode-nservicebusservicecontrol', '0.2.1'
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.
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
defined type.
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 => '3.6.2',
}
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: Use this with caution. New versions could contain a bug and since servicecontrol sometimes performs migrations on upgrades it's impossible to downgrade without going through the hassle of uninstalling and reinstalling the package
Install your license
$license_xml = @(LICENSE)
<?xml version="1.0" encoding="utf-8"?>
<license type="Commercial" DeploymentType="Elastic Cloud" Quantity="4" Edition="Enterprise" Applications="All" RenewalType="Subscription" expiration="2020-01-23" Notes="BlueSnap" id="7d26ad59-8805-4da6-8dad-f3540213ca">
...
</license>
LICENSE
class { 'nservicebusservicecontrol':
package_ensure => 'present',
license_xml => $license_xml,
}
Create a Service Control Instance using the RabbitMQ Conventional Routing Topology Transport
nservicebusservicecontrol::instance { 'Development':
ensure => 'present',
transport => 'RabbitMQ - Conventional routing topology',
connection_string => 'host=localhost;username=guest;password=guest',
}
Create a Service Control Instance using the SQLServer Transport ( SQL Authentication )
nservicebusservicecontrol::instance { 'Development':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=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 { 'Development':
ensure => 'present',
transport => 'SQL Server',
connection_string => 'Data Source=.; Database=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 MSMQ Transport
nservicebusservicecontrol::instance { '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 Azure Storage Queue Transport
nservicebusservicecontrol::instance { '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 { '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 { 'Development':
ensure => 'present',
transport => 'AmazonSQS',
..
}
Service Control Instance with forward error & audit queues
nservicebusservicecontrol::instance { 'Development':
ensure => 'present',
transport => 'RabbitMQ',
connection_string => 'host=localhost;username=guest;password=guest',
forward_audit_messages => true,
audit_log_queue => 'audit.log',
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 consumed.
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
Upgrading of the package after initial install
Currently there is no implementation to handle upgrading the package after intiail install via this module. In the future it might be helpful to implement the ability to specify an internal chocolatey server the user can use as well as handle upgrades, if possible, when downloading the install file from the public internet.
Module is missing some Service Control Instance Configuration settings
Neither the Unattended file method or New-ServiceControlInstance powershell cmdlet ( which this modules uses ) cover all the many configuration settings that are available to a ServiceControl Instance. The only mechanism that can be used to utilize all of the available customizations is by specifying them in the "ServiceControl.exe.config" file that resides in the service control instances install directory. If you would like to be able to configure one of these please open up a Github issue.
All documented available settings ( https://docs.particular.net/servicecontrol/creating-config-file )
Forwarding queues are created only at servicecontrol instance creation time only
If you try and a forwarding queue ( error or audit ) 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::instance
: Manages Service Control Instances.
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: ''
Defined types
nservicebusservicecontrol::instance
Manages Service Control Instances.
Parameters
The following parameters are available in the nservicebusservicecontrol::instance
defined type.
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}"
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"
log_path
Data type: Stdlib::Absolutepath
Specify the directory to use for this ServiceControl 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 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
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'
audit_queue
Data type: String
Specify AuditQueue name to consume messages from.
Default value: 'audit'
error_log_queue
Data type: Optional[String]
Specify Queue name to forward error messages to.
Default value: 'error.log'
audit_log_queue
Data type: Optional[String]
Specify Queue name to forward eudit messages to.
Default value: 'audit.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_audit_messages
Data type: Boolean
Specify if audit messages are forwarded to the queue specified by AuditLogQueue.
Default value: true
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 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 the period to keep an audit message before it is deleted.
Default value: '30.00:00:00'
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'
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
hours_to_keep_messages_before_expiring
Data type: Integer
Specifies the number of hours to keep a message before it is deleted.
Default value: 720
maximum_message_throughput_per_second
Data type: Integer
Specifies the maximum throughput of messages ServiceControl will handle per second and is necessary to avoid overloading the underlying messages database.
Default value: 350
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
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'
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
Default value: false
remove_logs_on_delete
Data type: Boolean
Default value: false
automatic_instance_upgrades
Data type: Boolean
Default value: true
Change log
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.
0.2.1 (2019-01-25)
Fixed
- Fixing up dependency conflict with chocolatey. #5 (TraGicCode)
0.2.0 (2019-01-25)
Added
- Use chocolatey for the servicecontrol package. #3 (TraGicCode)
0.1.0 (2019-01-24)
* This Changelog was automatically generated by github_changelog_generator
Dependencies
- puppetlabs/chocolatey (>= 3.0.0 < 4.0.0)
- puppetlabs/powershell (>= 1.0.1 < 3.0.0)
- puppetlabs/registry (>= 1.0.0 < 3.0.0)
- puppetlabs/stdlib (>= 4.0.0 < 6.0.0)