Gain a solid understanding of the foundational elements that drive Configu’s configuration management system. This page provides a short overview of key concepts to help you navigate and utilize Configu effectively.
software configurations
into code for consistent, reproducible environments. This approach allows configurations to be written, stored, and versioned alongside the application’s code in Git-like version control systems, streamlining deployments and fostering team collaboration.
CaC Article | CaC Webinar
software configuration
using three properties: key
, value
, set
. It is the core data model that powers Configu’s configuration management.
core/Config
Config
, characterized by properties like test, description, and constraints, providing a schema for configuration data.
core/Cfgu | .cfgu $schema
Config
records, acting as a repository for configuration data.
core/ConfigStore | core/stores | integrations/stores
Learn more about ConfigStore
ConfigStore
is a storage system for Configs
in Configu, serving as a mechanism for storing, retrieving, and managing configuration data. It can be any system or service capable of storing data, including text files, databases, secret managers, and the Configu Platform
. ConfigStores
play a crucial role in the configuration management process, enabling the seamless retrieval and management of configuration values at deployments or runtime.You can choose the most suitable ConfigStore
based on your specific needs and workflow. When using Configu’s CLI and Proxy, ConfigStores
are referenced using their type, which can also be declared as friendly names in the .configu file.Configu’s interfaces support a wide range of ConfigStores
. In case you don’t find a ConfigStore
that meets your requirements, Configu allows you to easily create your own by implementing a simple abstract class with get
and set
methods. This flexibility empowers you to extend Configu and tailor it to your specific configuration management needs.Config
s contextually, organizing configurations data logically.
core/ConfigSet
Learn more about ConfigSet
ConfigSet
in Configu is a mechanism for organizing and grouping configurations in a hierarchical structure. It serves as a path within the configuration tree, enabling you to associate specific configuration values with different contexts, such as environments, tenants, or any other use case you require.At the top of the ConfigSet hierarchy is the root set, represented by an empty string ""
or an alias of /
. The root set acts as the parent for all other sets and provides the foundation for the configuration tree. It’s important to note that the set path always starts with the root set and does not end with a ”/”.Each stored Config
is associated with a “set” property, which links it to a particular path in the ConfigSet hierarchy. When evaluating a configuration, Configu searches for the corresponding value by traversing the hierarchy from the supplied path’s last node up to the root set. This mechanism allows for seamless inheritance and overriding of configuration values, making it effortless to customize software behavior for different environments or use cases.root set
is represented by an empty string, following the convention in Configu. The root set acts as the default parent for all other sets and can be used to define global configuration values that apply to the entire configuration hierarchy.The development
set, a child of the root set, defines a single configuration value for the AWS_REGION key. When evaluating the configuration data in the development environment, Configu retrieves the us-east-2
value for the AWS_REGION
configuration key.Similarly, the production
set, also a child of the root set, specifies a different value for the AWS_REGION key. Additionally, it has a child set called eu-customer
, which further defines another value for the same configuration key. This hierarchy means Configu will fetch the appropriate values for the AWS_REGION
configuration key based on the set path, whether in the production
or production/eu-customer
environments.Let’s consider another example:root set
represents the top-level of the hierarchy.The staging
set, a child of the root set, contains configurations specific to the staging environment. It defines an API_URL
for the staging API endpoint. Additionally, it has a child set called feature-flags
, which encompasses specific feature flags and their corresponding values.The production
set, another child of the root set, includes a configuration for the API URL, representing the production API endpoint.Learn more about ConfigKey
ConfigKey
is the name given to a specific configuration as it appears in the code. It is used to identify and reference a specific configuration, and can be used to access the value of the configuration in the code.Here are some examples of how a configuration named “CONFIG” might be used as an environment variable
in various programming languages:ConfigKey
in a ConfigSet
, specifying the actual configuration value for a given context.
ConfigKey
to its corresponding Cfgu
declaration, ensuring configurations are defined and applied correctly.
core/ConfigSchema
Learn more about ConfigSchema
ConfigSchema
in Configu is a file with a .cfgu.yaml|yml|json
extension. It is a human-readable format for declaring configurations and their characteristics. It is designed to be stored in your source control alongside the code that uses these configurations, and can be treated as code as it shouldn’t contain sensitive data.The ConfigSchema
format provides a structured way to tie a ConfigKey
as it appears in the code to its Cfgu
properties, such as whether it is required or optional, and any constraints that should be applied to its value. These bindings help to ensure that configuration data is properly validated and applied, and can help to prevent misconfigurations and errors from reaching production..cfgu
files essentially set the boundaries of different domains in the code relative to the configuration they use. Developers are free to organize and structure their .cfgu
files in a way that makes sense for their specific needs and workflow. There is no limit on the number of .cfgu
files that can be created, and they can be spread across different codebases, subfolders in the same project, and different repositories.By using .cfgu
files, you can benefit from a clear and structured way to define and manage your configuration data, improving the efficiency and reliability of your software development and deployment processes, and facilitating collaboration among team members.Here is an example of a ConfigSchema
file:ConfigSchema
binds a configuration called “API_KEY”. The configuration is marked as required and has a short description.ConfigExpression
also has its own context which can be used for evaluation, that depends on the feature it’s used for. This is detailed within the relevant documentation for each feature.
All native JavaScript functions and operators are supported, allowing for complex and powerful expressions to be defined. Additionally, Configu provides a set of built-in functions and utilities to enhance ConfigExpressions which includes:
_
within the ConfigExpression
to access lodash functions.validator
within the ConfigExpression
to access validator.js functions.JSONSchema
or jsonschema
within the ConfigExpression
to access the utility class.z
within the ConfigExpression
to access Zod functions.assert
, expect
, and should
respectively within theConfigExpression
to access Chai functions.Learn more about ConfigExpression
Configs
from a ConfigStore
.
Search UpsertCommand
Configs
from ConfigStore
on demand.
Search EvalCommand
Configs
as configuration data in various formats and modes.
Search ExportCommand
ConfigKey
. Now, think of a Cfgu
as a rulebook for what those settings can be. These rules get written down in a special file called a ConfigSchema
(.cfgu), which hangs out right next to your code, keeping everything neat and tidy. When you want to update these settings, you use an UpsertCommand
to say, “Hey, I’ve got a new value for this setting!” This updates or inserts a new Config
, which is just your ConfigKey
paired with its new ConfigValue
and a label (ConfigSet
) telling you where or when this setting is being used. All of this gets saved in a magical place called a ConfigStore
.
Now, if you want to check what settings are active or make sure they’re the right ones, you use an EvalCommand
. It’s like asking, “Given all the rules and settings I have, what should this app look like right now?” This command can pull together all sorts of settings from different places (ConfigStores
and ConfigSets
) and make sure they all play nicely together, following the rules in your ConfigSchema
.
And when you’re ready to share these settings or move them somewhere else, the ExportCommand
steps in. It takes all that configuration info you’ve put together and turns it into a format you can use anywhere—like a universal translator for your app’s settings.
So, from naming a setting (ConfigKey
) to deciding what it can be (Cfgu
and ConfigSchema
), changing it (UpsertCommand
), fetching it (EvalCommand
), and sharing it (ExportCommand
), everything in Configu works together to make managing your app’s settings a breeze.
In computing, configuration files are files used to configure the parameters and initial settings for some computer programs. They are used for user applications, server processes and operating system settings.Learn more about configuration files | Wikipedia - Configuration file
{{CONFIG_KEY}}
, <CONFIG_KEY>
, ${CONFIG_KEY}
, etc., which are replaced with actual values during rendering with a template engine. Templates enable dynamic configuration generation based on context.