network

package
v0.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2024 License: Apache-2.0 Imports: 31 Imported by: 1

README

Choria Network Broker

This is a NATS compatible Network Broker for use by the Choria Orchestration System.

Please review the official documentation at choria.io for installation and usage.

Motivation

Running a middleware broker for Choria is quite the undertaking, while NATS is really easy to operate it does have a plethora of settings and using the wrong ones can adversely affect your network.

The Choria Network Broker is a managed NATS broker that integrates into the choria broker command. It ships as part of the normal Choria package and exist within the single binary.

It sets up the NATS server in ways thats suitable for use by Choria with sane defaults enabled.

Features:

  • Works by default without any broker specific configuration in your Choria broker
  • Secure by default - only accepts TLS connections with certificates signed by the known CA
  • Support NATS Accounts technology for large scale multi tenancy
  • Supports Clustering using a simple comma separated list of peers - TLS by default
  • Support Gateways enabling communication between NATS clusters - an alternative to Choria Federation
  • Support Leafnodes enabling joining older or unauthenticated clients to a secure multi tenant network
  • Exports statistics using the popular Prometheus format via the normal Choria statistics port

Configuration

The broker is configured using the Choria daemon configuration, below a reference of the settings it supports.

Choria core settings that affect the broker:
Setting Description
plugin.choria.broker_network Enables the network broker when running choria broker run
loglevel The logging level to use
plugin.choria.stats_port The port Choria listens on for metrics, when >0 the broker enables statistics
plugin.choria.stats_address The network address to listen on for metrics requests

It also uses the build.maxBrokerClients build time configuration in Choria to configure it's maximum connection limit, this defaults to 50 000.

Basic Broker Settings
Setting Description Default
plugin.choria.network.listen_address The network address to listen on ::
plugin.choria.network.client_port The port to listen on for network clients 4222
plugin.choria.network.write_deadline The time to allow for writes to network clients to complete before considering them slow 5s
plugin.choria.network.client_hosts List of hosts - ip addresses or cidrs - that are allowed to use clients all
plugin.choria.network.client_tls_force_required Force TLS on for client connections regardless of build settings false
plugin.choria.network.tls_timeout Sets the timeout for establishing TLS connections 2
Cluster Settings

Network Clusters are suitable for creating a cluster of up to 5 nodes on a local LAN. These form a full Mesh and provides scalability and HA.

They are based on NATS technology and you can read more about them at NATS.io

Setting Description Default
plugin.choria.network.peer_port The port to listen on for broker cluster peers 5222
plugin.choria.network.peer_user Username to connect to cluster peers with unset
plugin.choria.network.peer_password Password to use when connecting to cluster peers unset
plugin.choria.network.peers Comma separated List of cluster peers to connect to unset
Gateway Settings

Gateways allow you to combine multiple Clusters into a single large cluster. This allow you to span your collective across multiple data centers without the need for the much harder to configure federation brokers.

By default if the broker is compiled with TLS the Gateway will use the same TLS settings for the connection - you can customize it on a per remote basis.

They are based on NATS technology and you can read more about them at NATS.io

Setting Description Default
plugin.choria.network.gateway_port The port to listen to for Gateway connections, disabled when 0 0
plugin.choria.network.gateway_name Unique name for the cluster listening on the port CHORIA
plugin.choria.network.gateway_remotes A comma sep list of remote names to activate ""
plugin.choria.network.gateway_remote.C1.urls A comma sep list of host:port combinations to connect to for the remote C1 cluster
plugin.choria.network.gateway_remote.C1.tls.cert Path to a custom certificate for this remote only
plugin.choria.network.gateway_remote.C1.tls.key Path to a custom private key for this remote only
plugin.choria.network.gateway_remote.C1.tls.ca Path to a custom ca for this remote only
plugin.choria.network.gateway_remote.C1.tls.disable Disables the TLS configuration that would have inherited from the Choria Security system false
plugin.choria.network.gateway_remote.C1.tls.verify Disables full TLS verify for this remote only true
Leafnode Settings

Leafnodes exist to take unauthenticated or unsecured connections and forge them into a specific Account (see below). They allow older Choria agents and clients to take part of a multi tenant or account secured network.

By default if the broker is compiled with TLS the leafnode will use the same TLS settings for the connection - you can customize it on a per remote basis.

They are based on NATS technology and you can read more about them at NATS.io

Setting Description Default
plugin.choria.network.leafnode_port The port to listen to for Gateway connections, disabled when 0 0
plugin.choria.network.leafnode_remotes A comma sep list of remote names to activate ""
plugin.choria.network.leafnode_remote.C1.url A host:port combination to connect to for the remote C1 leafnode
plugin.choria.network.leafnode_remote.C1.account The local account name to use when connecting to the remote
plugin.choria.network.leafnode_remote.C1.credential The local credential file to use when connecting to the remote
plugin.choria.network.leafnode_remote.C1.tls.cert Path to a custom certificate for this remote only
plugin.choria.network.leafnode_remote.C1.tls.key Path to a custom private key for this remote only
plugin.choria.network.leafnode_remote.C1.tls.ca Path to a custom ca for this remote only
plugin.choria.network.leafnode_remote.C1.tls.disable Disables the TLS configuration that would have inherited from the Choria Security system false
plugin.choria.network.leafnode_remote.C1.tls.verify Disables full TLS verify for this remote only true
Accounts

Accounts are based on NATS technology, you can read more about them at NATS.io

Setting Description Default
plugin.choria.network.operator_account The operator account that is managing this cluster
plugin.choria.network.system_account The system account to use, when set enables server events

Statistics

When Statistics are enabled in Choria by setting plugin.choria.stats_port to nonzero the Choria Broker expose the following Prometheus statistics:

Statistic Description
choria_network_connections Current connections on the network broker
choria_network_total_connections Total connections received since start
choria_network_routes Current active routes to other brokers
choria_network_remotes Current active connections to other brokers
choria_network_leafnode_remotes Current active connections to leaf nodes
choria_network_in_msgs Messages received by the network broker
choria_network_out_msgs Messages sent by the network broker
choria_network_in_bytes Total size of messages received by the network broker
choria_network_out_bytes Total size of messages sent by the network broker
choria_network_slow_consumers Total number of clients who were considered slow consumers
choria_network_subscriptions Number of active subscriptions to subjects on this broker
choria_network_leafnode_rtt_ms RTT for the Leafnode connection
choria_network_leafnode_in_msgs Messages received over the leafnode connection
choria_network_leafnode_out_msgs Messages sent over the leafnode connection
choria_network_leafnode_in_bytes Bytes received over the leafnode connection
choria_network_leafnode_out_msgs Total size of messages sent over the leafnode connection
choria_network_leafnode_subscriptions Number of active subscriptions to subjects on this leafnode

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BuildInfoProvider 

type BuildInfoProvider interface {
	MaxBrokerClients() int
}

BuildInfoProvider provider build time flag information, example go-choria/build

type ChoriaAuth added in v0.23.0 

type ChoriaAuth struct {
	// contains filtered or unexported fields
}

ChoriaAuth implements the Nats server.Authentication interface and allows IP limits to be configured, connections that do not match the configured IP or CIDRs are not allowed to publish to the network targets used by clients to request actions on nodes.

Additionally, when the server is running in a mode where anonymous TLS connections is accepted then servers are entirely denied and clients are allowed but restricted based on the JWT issued by the AAA Service. This is activated using the plugin.choria.network.client_anon_tls setting, however this should be avoided atm.

Clients can present a JWT token signed by the AAA service if that token has a purpose field matching choria_client_id and if the AAA signer is configured in the broker using plugin.choria.security.request_signing_certificate those with valid tokens and that are fully verified can connect but will be restricted to client only functions. These clients will not be able to access any Choria Streams features, KV buckets etc

Additionally when provisioning support is enabled any non mTLS connection will be placed in the provisioning account and unable to connect to the fleet or provisioned nodes. This is only enabled if plugin.choria.network.provisioning.signer_cert is set

func (*ChoriaAuth) Check added in v0.23.0 

func (a *ChoriaAuth) Check(c server.ClientAuthentication) bool

Check checks and registers the incoming connection

type Logger 

type Logger struct {
	// contains filtered or unexported fields
}

Logger is nats server.Logger compatible logging wrapper for logrus

func NewLogger added in v0.15.0 

func NewLogger(l *log.Entry) Logger

NewLogger creates a new NATS compliant logger instance that uses logrus for actual logging

func (Logger) Debugf 

func (l Logger) Debugf(format string, v ...any)

Debugf logs at debug level

func (Logger) Errorf 

func (l Logger) Errorf(format string, v ...any)

Errorf logs at error lovel

func (Logger) Fatalf 

func (l Logger) Fatalf(format string, v ...any)

Fatalf logs at fatal level

func (Logger) Noticef 

func (l Logger) Noticef(format string, v ...any)

Noticef logs at info level

func (Logger) Tracef 

func (l Logger) Tracef(format string, v ...any)

Tracef logs at debug level

func (Logger) Warnf 

func (l Logger) Warnf(format string, v ...any)

Warnf logs at warn lovel

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server represents the Choria network broker server

func NewServer 

func NewServer(c inter.Framework, bi BuildInfoProvider, debug bool) (s *Server, err error)

NewServer creates a new instance of the Server struct with a fully configured NATS embedded

func (*Server) HTTPHandler 

func (s *Server) HTTPHandler() http.Handler

HTTPHandler Exposes the natsd HTTP Handler

func (*Server) InProcessConn added in v0.26.1 

func (s *Server) InProcessConn() (net.Conn, error)

InProcessConn implements nats.InProcessConnProvider

func (*Server) IsTLS 

func (s *Server) IsTLS() bool

IsTLS determines if tls should be enabled

func (*Server) IsVerifiedTLS 

func (s *Server) IsVerifiedTLS() bool

IsVerifiedTLS determines if tls should be enabled

func (*Server) Start 

func (s *Server) Start(ctx context.Context, wg *sync.WaitGroup)

Start the embedded NATS instance, this is a blocking call until it exits

func (*Server) Started 

func (s *Server) Started() bool

Started determines if the server have been started

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.