Documentation
¶
Index ¶
- func Build(ctx context.Context, configSourcesSettings map[string]ConfigSettings, ...) (map[string]configsource.ConfigSource, error)
- func Load(ctx context.Context, v *configparser.Parser, factories Factories) (map[string]ConfigSettings, error)
- func NewConfigSourceParserProvider(logger *zap.Logger, buildInfo component.BuildInfo, factories ...Factory) parserprovider.ParserProvider
- func NewRetrieved(value interface{}, watchForUpdateFn func() error) configsource.Retrieved
- func WatcherNotSupported() error
- type ConfigSettings
- type CreateParams
- type Factories
- type Factory
- type Manager
- type Settings
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
func Build(ctx context.Context, configSourcesSettings map[string]ConfigSettings, params CreateParams, factories Factories) (map[string]configsource.ConfigSource, error)
Build builds the ConfigSource objects according to the given ConfigSettings.
func Load ¶
func Load(ctx context.Context, v *configparser.Parser, factories Factories) (map[string]ConfigSettings, error)
Load reads the configuration for ConfigSource objects from the given parser and returns a map from the full name of config sources to the respective ConfigSettings.
func NewConfigSourceParserProvider ¶
func NewConfigSourceParserProvider(logger *zap.Logger, buildInfo component.BuildInfo, factories ...Factory) parserprovider.ParserProvider
NewConfigSourceParserProvider creates a ParserProvider that uses config sources.
func NewRetrieved ¶
func NewRetrieved(value interface{}, watchForUpdateFn func() error) configsource.Retrieved
NewRetrieved is a helper that implements the Retrieved interface.
func WatcherNotSupported ¶
func WatcherNotSupported() error
WatcherNotSupported is the a watcher function that always returns ErrWatcherNotSupported.
Types ¶
type ConfigSettings ¶
type ConfigSettings interface {
// Name gets the config source name.
Name() string
// SetName sets the config source name.
SetName(name string)
// Type sets the config source type.
Type() config.Type
}
ConfigSettings is the interface required to be implemented by the settings of all ConfigSource objects.
type CreateParams ¶
type CreateParams struct {
// Logger that the factory can use during creation and can pass to the created
// ConfigSource to be used later as well.
Logger *zap.Logger
// BuildInfo can be used to retrieve data according to version, etc.
BuildInfo component.BuildInfo
}
CreateParams is passed to Factory.Create* functions.
type Factory ¶
type Factory interface {
component.Factory
// CreateDefaultConfig creates the default configuration settings for the ConfigSource.
// This method can be called multiple times depending on the pipeline
// configuration and should not cause side-effects that prevent the creation
// of multiple instances of the ConfigSource.
// The object returned by this method needs to pass the checks implemented by
// 'configcheck.ValidateConfig'. It is recommended to have such check in the
// tests of any implementation of the Factory interface.
CreateDefaultConfig() ConfigSettings
// CreateConfigSource creates a configuration source based on the given config.
CreateConfigSource(ctx context.Context, params CreateParams, cfg ConfigSettings) (configsource.ConfigSource, error)
}
Factory is a factory interface for configuration sources.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is used to inject data from config sources into a configuration and also to monitor for updates on the items injected into the configuration. All methods of a Manager must be called only once and have a expected sequence:
1. NewManager to create a new instance; 2. Resolve to inject the data from config sources into a configuration; 3. WatchForUpdate in a goroutine to wait for configuration updates; 4. WaitForWatcher to wait until the watchers are in place; 5. Close to close the instance;
The current syntax to reference a config source in a YAML is provisional. Currently single-line:
param_to_be_retrieved: $<cfgSrcName>:<selector>[?<params_url_query_format>]
bracketed single-line:
param_to_be_retrieved: ${<cfgSrcName>:<selector>[?<params_url_query_format>]}
and multi-line are supported:
param_to_be_retrieved: | $<cfgSrcName>: <selector> [<params_multi_line_YAML>]
The <cfgSrcName> is a name string used to identify the config source instance to be used to retrieve the value.
The <selector> is the mandatory parameter required when retrieving data from a config source.
Not all config sources need the optional parameters, they are used to provide extra control when retrieving and preparing the data to be injected into the configuration.
For single-line format <params_url_query_format> uses the same syntax as URL query parameters. Hypothetical example in a YAML file:
component:
config_field: $file:/etc/secret.bin?binary=true
For multi-line format <params_multi_line_YAML> uses syntax as a YAML inside YAML. Possible usage example in a YAML file:
component:
config_field: | $yamltemplate: /etc/log_template.yaml logs_path: /var/logs/ timeout: 10s
Not all config sources need these optional parameters, they are used to provide extra control when retrieving and data to be injected into the configuration.
Assuming a config source named "env" that retrieve environment variables and one named "file" that retrieves contents from individual files, here are some examples:
component: # Retrieves the value of the environment variable LOGS_DIR. logs_dir: $env:LOGS_DIR # Retrieves the value from the file /etc/secret.bin and injects its contents as a []byte. bytes_from_file: $file:/etc/secret.bin?binary=true # Retrieves the value from the file /etc/text.txt and injects its contents as a string. # Hypothetically the "file" config source by default tries to inject the file contents # as a string if params doesn't specify that "binary" is true. text_from_file: $file:/etc/text.txt
Bracketed single-line should be used when concatenating a suffix to the value retrieved by the config source. Example:
component:
# Retrieves the value of the environment variable LOGS_DIR and appends /component.log to it.
log_file_fullname: ${env:LOGS_DIR}/component.log
Environment variables are expanded before passed to the config source when used in the selector or the optional parameters. Example:
component: # Retrieves the value from the file text.txt located on the path specified by the environment # variable DATA_PATH. The name of the environment variable is the string after the delimiter # until the first character different than '_' and non-alpha-numeric. text_from_file: $file:$DATA_PATH/text.txt
Since environment variables and config sources both use the '$', with or without brackets, as a prefix for their expansion it is necessary to have a way to distinguish between them. For the non-bracketed syntax the code will peek at the first character other than alpha-numeric and '_' after the '$'. If that character is a ':' it will treat it as a config source and as environment variable otherwise. For example:
component: field_0: $PATH:/etc/logs # Injects the data from a config sourced named "PATH" using the selector "/etc/logs". field_1: $PATH/etc/logs # Expands the environment variable "PATH" and adds the suffix "/etc/logs" to it.
So if you need to include an environment followed by ':' the bracketed syntax must be used instead:
component:
field_0: ${PATH}:/etc/logs # Expands the environment variable "PATH" and adds the suffix ":/etc/logs" to it.
For the bracketed syntax the presence of ':' inside the brackets indicates that code will treat the bracketed contents as a config source. For example:
component:
field_0: ${file:/var/secret.txt} # Injects the data from a config sourced named "file" using the selector "/var/secret.txt".
field_1: ${file}:/var/secret.txt # Expands the environment variable "file" and adds the suffix ":/var/secret.txt" to it.
If the the character following the '$' is in the set {'*', '#', '$', '@', '!', '?', '-', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9'} the code will consider it to be the name of an environment variable to expand, or config source if followed by ':'. Do not use any of these characters as the first char on the name of a config source or an environment variable (even if allowed by the system) to avoid unexpected results.
func NewManager ¶
func NewManager(parser *configparser.Parser, logger *zap.Logger, buildInfo component.BuildInfo, factories Factories) (*Manager, error)
NewManager creates a new instance of a Manager to be used to inject data from ConfigSource objects into a configuration and watch for updates on the injected data.
func (*Manager) Close ¶
Close terminates the WatchForUpdate function and closes all Session objects used in the configuration. It should be called
func (*Manager) Resolve ¶
func (m *Manager) Resolve(ctx context.Context, parser *configparser.Parser) (*configparser.Parser, error)
Resolve inspects the given configparser.Parser and resolves all config sources referenced in the configuration, returning a configparser.Parser fully resolved. This must be called only once per lifetime of a Manager object.
func (*Manager) WaitForWatcher ¶
func (m *Manager) WaitForWatcher()
WaitForWatcher blocks until the watchers used by WatchForUpdate are all ready. This is used to ensure that the watchers are in place before proceeding.
func (*Manager) WatchForUpdate ¶
WatchForUpdate must watch for updates on any of the values retrieved from config sources and injected into the configuration. Typically this method is launched in a goroutine, the method WaitForWatcher blocks until the WatchForUpdate goroutine is running and ready.
type Settings ¶
Settings defines common settings of a ConfigSource configuration. Specific config sources can embed this struct and extend it with more fields if needed. When embedded it must be with `mapstructure:"-"` tag.
func NewSettings ¶
NewSettings return a new ConfigSourceSettings with the given type.
Source Files