Skip to content

Rename NATS server terminology to Choria Broker #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nmburgan merged 2 commits into from
Apr 27, 2026
+168 −103
Merged

Rename NATS server terminology to Choria Broker #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
113dd67
Fix nats-servers format in docs, examples, and specs
nmburgan Apr 22, 2026
139d85f
Rename nats-servers to choria-brokers with port defaulting
nmburgan Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion developer-docs/choria/choria-transport-testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ libdir = /opt/puppetlabs/mcollective/plugins
logger_type = console
loglevel = warn
securityprovider = choria
plugin.choria.middleware_hosts = nats://primary.example.com:4222
plugin.choria.middleware_hosts = primary.example.com:4222
plugin.security.provider = file
plugin.security.file.certificate = ~/.puppetlabs/etc/puppet/ssl/certs/<username>.mcollective.pem
plugin.security.file.key = ~/.puppetlabs/etc/puppet/ssl/private_keys/<username>.mcollective.pem
Expand Down
16 changes: 8 additions & 8 deletions documentation/choria-transport.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,9 @@ targets:
config:
choria:
collective: production
nats-servers:
- nats://broker1:4222
- nats://broker2:4222
brokers:
- broker1:4222
- broker2:4222
```

If the config file is in one of the auto-detected locations (`~/.choriarc`,
Expand Down Expand Up @@ -96,8 +96,8 @@ targets:
| `host` | | String | (from URI) | Target's Choria identity (FQDN). Overrides the hostname from the URI. |
| `interpreters` | | Hash | (none) | File extension to interpreter mapping (e.g., `{".rb": "/usr/bin/ruby"}`). |
| `mcollective-certname` | `--choria-mcollective-certname` | String | (auto) | Override the MCollective certname for Choria client identity. See [Non-root certname](#non-root-certname) below. |
| `nats-connection-timeout` | `--nats-connection-timeout` | Integer | `30` | Seconds to wait for the TCP connection to the NATS broker. |
| `nats-servers` | `--nats-servers` | String or Array | (from config file) | NATS broker addresses in `nats://host:port` format (comma-separated for multiple). Multiple servers provide failover if a broker is unavailable. Overrides the config file. |
| `broker-timeout` | `--choria-broker-timeout` | Integer | `30` | Seconds to wait for the TCP connection to a Choria broker. |
| `brokers` | `--choria-brokers` | String or Array | (auto-discovered) | Choria broker addresses in `host` or `host:port` format (comma-separated for multiple). Port defaults to 4222 if omitted. Do not use the `nats://` prefix. When not provided, the Choria client checks the config file, then SRV records, then falls back to `puppet:4222`. Multiple servers provide failover. |
| `puppet-environment` | `--choria-puppet-environment` | String | `production` | Puppet environment for bolt_tasks file URIs. |
| `rpc-timeout` | `--choria-rpc-timeout` | Integer | `30` | Seconds to wait for replies to individual RPC calls. |
| `ssl-ca` | `--choria-ssl-ca` | String | (from config file) | CA certificate path for TLS. |
Expand All @@ -114,14 +114,14 @@ wins. For ad-hoc targets specified via `--targets` that aren't defined in an
inventory file, CLI flags take full effect.

For options that have corresponding values in the Choria config file
(`nats-servers`, `ssl-ca`/`ssl-cert`/`ssl-key`, and `collective`), the full
(`brokers`, `ssl-ca`/`ssl-cert`/`ssl-key`, and `collective`), the full
precedence from lowest to highest is: Choria config file < CLI flags <
inventory. All other options use OpenBolt-level defaults and are not affected by
the Choria config file.

**Timeout hierarchy:** Three levels of timeout control different things:
- `nats-connection-timeout` (30s): How long to wait for the initial TCP
connection to the NATS broker
- `broker-timeout` (30s): How long to wait for the initial TCP
connection to a Choria broker
- `rpc-timeout` (30s): How long to wait for replies to each individual RPC
call (discovery, status checks, etc.)
- `command-timeout` (60s) / `task-timeout` (300s): How long to wait for the
Expand Down
16 changes: 8 additions & 8 deletions lib/bolt/bolt_option_parser.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ class BoltOptionParser < OptionParser
choria: %w[choria-config-file choria-mcollective-certname
choria-ssl-ca choria-ssl-cert choria-ssl-key
choria-collective choria-puppet-environment choria-rpc-timeout
choria-task-timeout choria-command-timeout nats-servers
nats-connection-timeout],
choria-task-timeout choria-command-timeout choria-brokers
choria-broker-timeout],
display: %w[format color verbose trace stream],
global: %w[help version log-level clear-cache] }.freeze

Expand Down Expand Up @@ -1149,13 +1149,13 @@ def initialize(options)
'Seconds to wait for commands and scripts to complete (default: 60).') do |timeout|
@options[:'command-timeout'] = timeout
end
define('--nats-servers SERVERS',
'NATS broker addresses in nats://host:port format (comma-separated for multiple).') do |servers|
@options[:'nats-servers'] = servers
define('--choria-brokers BROKERS',
'Choria broker addresses in host or host:port format (comma-separated). Port defaults to 4222 if omitted.') do |brokers|
@options[:brokers] = brokers.split(',')
end
define('--nats-connection-timeout SECONDS', Integer,
'Seconds to wait for the TCP connection to the NATS broker (default: 30).') do |timeout|
@options[:'nats-connection-timeout'] = timeout
define('--choria-broker-timeout SECONDS', Integer,
'Seconds to wait for the TCP connection to a Choria broker (default: 30).') do |timeout|
@options[:'broker-timeout'] = timeout
end

separator "\n#{self.class.colorize(:cyan, 'Module options')}"
Expand Down
6 changes: 3 additions & 3 deletions lib/bolt/config/transport/choria.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ class Choria < Base
host
interpreters
mcollective-certname
nats-connection-timeout
nats-servers
broker-timeout
brokers
puppet-environment
rpc-timeout
ssl-ca
Expand All @@ -30,7 +30,7 @@ class Choria < Base
DEFAULTS = {
'cleanup' => true,
'command-timeout' => 60,
'nats-connection-timeout' => 30,
'broker-timeout' => 30,
'puppet-environment' => 'production',
'rpc-timeout' => 30,
'task-timeout' => 300,
Expand Down
14 changes: 8 additions & 6 deletions lib/bolt/config/transport/options.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,9 @@ module Options
_plugin: true,
_example: "/etc/choria/client.conf"
},
"nats-connection-timeout" => {
"broker-timeout" => {
type: Integer,
description: "How long to wait in seconds for the initial TCP connection to the NATS broker. " \
description: "How long to wait in seconds for the initial TCP connection to a Choria broker. " \
"If the connection cannot be made within this time, the operation fails.",
minimum: 1,
_plugin: true,
Expand Down Expand Up @@ -284,15 +284,17 @@ module Options
_plugin: true,
_example: "primary.example.com"
},
"nats-servers" => {
"brokers" => {
type: [String, Array],
description: "One or more NATS server addresses for the Choria transport. Overrides the middleware " \
"hosts from the Choria client configuration file. Can be a single string or an array.",
description: "One or more Choria broker addresses in host or host:port format. " \
"Port defaults to 4222 if omitted. Do not use the nats:// prefix. " \
"Overrides the middleware hosts from the Choria client configuration file. " \
"Can be a single string or an array.",
items: {
type: String
},
_plugin: true,
_example: ["nats://broker1:4222", "nats://broker2:4222"]
_example: ["broker1:4222", "broker2:4222"]
},
"native-ssh" => {
type: [TrueClass, FalseClass],
Expand Down
14 changes: 7 additions & 7 deletions lib/bolt/transport/choria/client.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,10 +73,10 @@ def configure_client(target)
logger.debug { "MCOLLECTIVE_CERTNAME set to #{opts['mcollective-certname']}" }
end

if opts['nats-servers']
servers = [opts['nats-servers']].flatten
config.pluginconf['choria.middleware_hosts'] = servers.join(',')
logger.debug { "NATS servers overridden: #{servers.join(', ')}" }
if opts['brokers']
brokers = Array(opts['brokers']).map { |broker| broker.include?(':') ? broker : "#{broker}:4222" }
config.pluginconf['choria.middleware_hosts'] = brokers.join(',')
logger.debug { "Choria brokers overridden: #{brokers.join(', ')}" }
end

if opts['ssl-ca'] && opts['ssl-cert'] && opts['ssl-key']
Expand Down Expand Up @@ -117,11 +117,11 @@ def configure_client(target)
# @param timeout [Numeric] RPC call timeout in seconds
# @return [MCollective::RPC::Client] Configured client with direct addressing enabled
def create_rpc_client(agent_name, targets, timeout)
targets = [targets].flatten
targets = Array(targets)
options = MCollective::Util.default_options
options[:timeout] = timeout
options[:verbose] = false
options[:connection_timeout] = targets.first.options['nats-connection-timeout']
options[:connection_timeout] = targets.first.options['broker-timeout']

collective = collective_for(targets.first)
options[:collective] = collective if collective
Expand Down Expand Up @@ -169,7 +169,7 @@ def create_rpc_client(agent_name, targets, timeout)
# Includes all targets that responded (both :responded and :errors).
# Not populated when rpc_failed is true (no individual responses).
def rpc_request(agent, targets, context)
targets = [targets].flatten
targets = Array(targets)
rpc_results = @rpc_mutex.synchronize do
rpc_timeout = targets.first.options['rpc-timeout']
client = create_rpc_client(agent, targets, rpc_timeout)
Expand Down
44 changes: 22 additions & 22 deletions schemas/bolt-defaults.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -518,90 +518,90 @@
{
"type": "object",
"properties": {
"cleanup": {
"broker-timeout": {
"oneOf": [
{
"$ref": "#/transport_definitions/cleanup"
"$ref": "#/transport_definitions/broker-timeout"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"collective": {
"brokers": {
"oneOf": [
{
"$ref": "#/transport_definitions/collective"
"$ref": "#/transport_definitions/brokers"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"command-timeout": {
"cleanup": {
"oneOf": [
{
"$ref": "#/transport_definitions/command-timeout"
"$ref": "#/transport_definitions/cleanup"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"config-file": {
"collective": {
"oneOf": [
{
"$ref": "#/transport_definitions/config-file"
"$ref": "#/transport_definitions/collective"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"host": {
"command-timeout": {
"oneOf": [
{
"$ref": "#/transport_definitions/host"
"$ref": "#/transport_definitions/command-timeout"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"interpreters": {
"config-file": {
"oneOf": [
{
"$ref": "#/transport_definitions/interpreters"
"$ref": "#/transport_definitions/config-file"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"mcollective-certname": {
"host": {
"oneOf": [
{
"$ref": "#/transport_definitions/mcollective-certname"
"$ref": "#/transport_definitions/host"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"nats-connection-timeout": {
"interpreters": {
"oneOf": [
{
"$ref": "#/transport_definitions/nats-connection-timeout"
"$ref": "#/transport_definitions/interpreters"
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"nats-servers": {
"mcollective-certname": {
"oneOf": [
{
"$ref": "#/transport_definitions/nats-servers"
"$ref": "#/transport_definitions/mcollective-certname"
},
{
"$ref": "#/definitions/_plugin"
Expand Down Expand Up @@ -1862,8 +1862,8 @@
}
]
},
"nats-connection-timeout": {
"description": "How long to wait in seconds for the initial TCP connection to the NATS broker. If the connection cannot be made within this time, the operation fails.",
"broker-timeout": {
"description": "How long to wait in seconds for the initial TCP connection to a Choria broker. If the connection cannot be made within this time, the operation fails.",
"oneOf": [
{
"type": "integer",
Expand Down Expand Up @@ -2166,8 +2166,8 @@
}
]
},
"nats-servers": {
"description": "One or more NATS server addresses for the Choria transport. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
"brokers": {
"description": "One or more Choria broker addresses in host or host:port format. Port defaults to 4222 if omitted. Do not use the nats:// prefix. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
"oneOf": [
{
"type": [
Expand Down
72 changes: 36 additions & 36 deletions schemas/bolt-inventory.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,42 @@
{
"type": "object",
"properties": {
"broker-timeout": {
"description": "How long to wait in seconds for the initial TCP connection to a Choria broker. If the connection cannot be made within this time, the operation fails.",
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"brokers": {
"description": "One or more Choria broker addresses in host or host:port format. Port defaults to 4222 if omitted. Do not use the nats:// prefix. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
"oneOf": [
{
"type": [
"string",
"array"
],
"items": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/definitions/_plugin"
}
]
}
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"cleanup": {
"description": "Whether to clean up temporary files created on targets. When running commands on a target, Bolt might create temporary files. After completing the command, these files are automatically deleted. This value can be set to 'false' if you wish to leave these temporary files on the target.",
"oneOf": [
Expand Down Expand Up @@ -150,42 +186,6 @@
}
]
},
"nats-connection-timeout": {
"description": "How long to wait in seconds for the initial TCP connection to the NATS broker. If the connection cannot be made within this time, the operation fails.",
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"nats-servers": {
"description": "One or more NATS server addresses for the Choria transport. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
"oneOf": [
{
"type": [
"string",
"array"
],
"items": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/definitions/_plugin"
}
]
}
},
{
"$ref": "#/definitions/_plugin"
}
]
},
"puppet-environment": {
"description": "The Puppet environment to use when constructing task file URIs for the Choria bolt_tasks agent.",
"oneOf": [
Expand Down
Loading
Loading