Includes Configuration
Overview
The Includes
section allows to reference other participant configuration files.
This can be used to share common parts of a participant configuration or to include dynamically generated configurations into a static configuration base.
Includes:
Files:
- LoggingIncludes.silkit.yaml
- generated/MiddlewareInclude.silkit.yaml
To deal with different locations of the included files depending on the execution scenario, a list of search paths pointing to the locations of the included files can be specified in the SearchPathHints
:
Includes:
SearchPathHints:
- ConfigSnippets/Logging # relative paths are valid (same as ./ConfigSnippets/Logging/)
- /urs/etc/sil-kit-configs/ # absolute paths are valid
- C:\Temp\ConfigSnippets # for Windows, backslash as path separator is valid
- C:\Temp\Path with spaces\ # for Windows, paths with spaces are valid
Files:
- LoggingIncludes.silkit.yaml
- generated/MiddlewareInclude.silkit.yaml
When using ParticipantConfigurationFromFile()
, the current working directory and the path of the including participant configuration file are considered as additional search paths.
When using ParticipantConfigurationFromString()
, the default search path is the current working directory.
Merge rules
The included configurations are merged according to the following rules:
All properties of the
Middleware
section can only be defined once, otherwise aSilKit::ConfigurationError
occurs:# root.silkit.yaml Includes: Files: - included.silkit.yaml Middleware: RegistryUri: silkit://localhost:8500
# included.silkit.yaml Middleware: RegistryUri: silkit://0.0.0.0:8501 # Already specified in root.silkit.yaml, ConfigurationError!
Multiple inclusions of the same file are automatically prevented. This also applies for nested includes of the same file:
# root.silkit.yaml Includes: Files: - included_1.silkit.yaml - included_2.silkit.yaml
# included_1.silkit.yaml Includes: Files: - included_2.silkit.yaml # Ignored (already appeared in root.silkit.yaml)
List items of top-level properties (e.g.
CanControllers
,DataPublishers
) are combined:# root.silkit.yaml Includes: Files: - included.silkit.yaml DataPublishers: - Name: DataPublisher1 # Will be used Topic: SomeTopic
# included.silkit.yaml DataPublishers: - Name: DataPublisher2 # Will also be used Topic: SomeTopic
Named items with the same name cannot be merged in a meaningful way and result in a
SilKit::ConfigurationError
:# root.silkit.yaml Includes: Files: - included.silkit.yaml CanControllers: - Name: CAN1 # Name "CAN1" set here Network: CAN1
# included.silkit.yaml CanControllers: - Name: CAN1 # SilKit::ConfigurationError: Conflicting name "CAN1" Network: CAN2
Named items where all properties match (i.e., duplicates of named items) are permitted.
The list items of
Sinks
in theLogging
section are merged as follows:Only a single sink of type
Type: Stdout
can be defined, otherwise aSilKit::ConfigurationError
occurs. The same applies to the sink typeType: Remote
.Sinks of
Type: File
are combined. However theirLogName
must be unique, otherwise aSilKit::ConfigurationError
occurs.
List items of the
SearchPathHints
in the sectionsIncludes
orExtensions
are merged and all entries are retained. Possible duplicates here are uncritical.All properties of the
HealthCheck
section can only be defined once, otherwise aSilKit::ConfigurationError
occurs.
Dynamic port generation
An important use-case is to include a configuration with a dynamically generated RegistryUri
of the Middleware
section:
In a CI environment, it is unfavorable to setup a static port in the listen-uri
of the SIL Kit registry.
Instead, a port 0
advises the SIL Kit registry to let the operating system choose a random free port.
This URI then has to be used by the participants in the Middleware property RegistryUri
.
For this purpose, the --generate-configuration
CLI parameter of the SIL Kit registry creates a participant configuration file containing the dynamic RegistryUri
in the Middleware section.
By referencing this generated participant configuration in the Includes
section, the static part of the configuration (e.g., network names, logging) can be combined with the dynamic RegistryUri
.
Configuration
Includes:
SearchPathHints:
- ./ConfigSnippets/Generated/
Files:
- generated-uri.silkit.yaml
- ../common-logging.silkit.yaml
Property Name |
Description |
---|---|
SearchPathHints |
A list of paths that are used to search for included configuration files. |
Files |
A list of configuration files to be included. |