Introduction
Concepts
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 Configuration
Software or application configuration includes all elements that differ across deployments, such as resource handles, external service credentials, and deployment-specific values. It’s a crucial piece of the software puzzle, dictating an application’s behavior. The Twelve-Factor AppConfiguration Abstraction
Configuration tends to grow larger in size and complexity over time, making it increasingly difficult to understand and maintain. Configu addresses this by:- Separating the configuration’s structure from its data.
- Orchestrating configuration data from any source via a unified API.
- Computing configuration data, instead of manually enumerating it.
Configuration-as-Code (CaC)
Configuration-as-Code (CaC) transformssoftware 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
Configu Concepts
For a comprehensive understanding of the concepts introduced below, we encourage you to expand the “Learn more
about” sections. This will provide you with detailed explanations and insights, enhancing your grasp of Configu’s
core functionalities and design principles.
Config
A generic representation of software configuration using three properties: key, value, set. It is the core data model that powers Configu’s configuration management.
core/Config
Cfgu
A generic declaration of a Config, characterized by properties like test, description, and constraints, providing a schema for configuration data.
core/Cfgu | .cfgu $schema
ConfigStore
A storage engine interface for Config records, acting as a repository for configuration data.
core/ConfigStore | core/stores | integrations/stores
Learn more about ConfigStore
Learn more about ConfigStore
A
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.ConfigSet
A unique path within a hierarchical data structure that groups Configs contextually, organizing configurations data logically.
core/ConfigSet
Learn more about ConfigSet
Learn more about ConfigSet
A Let’s explore an example of a ConfigSet hierarchy:In this example, the In this example, the
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.ConfigSets can represent any context that requires distinct configuration values. For example, you can utilize
ConfigSets to group configurations based on regions, deployment stages, or specific feature sets. This flexibility
empowers you to structure your configuration hierarchy in a way that best fits your application’s needs.
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.ConfigKey
A reference to a specific configuration declaration as it appears within the codebase, linking code to its configuration.
Learn more about ConfigKey
Learn more about ConfigKey
A
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:ConfigValue
An assignment to aConfigKey in a ConfigSet, specifying the actual configuration value for a given context.
ConfigSchema
A file containing binding records that link each unique ConfigKey to its corresponding Cfgu declaration, ensuring configurations are defined and applied correctly.
core/ConfigSchema
Learn more about ConfigSchema
Learn more about ConfigSchema
A In this example, the
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
A JavaScript string that is evaluated during runtime. ConfigExpressions are used throughout Configu’s features to provide a robust and dynamic configuration management experience. EachConfigExpression 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:
- lodash for various utility functions. Use
_within theConfigExpressionto access lodash functions. - validator.js for string validations. Use
validatorwithin theConfigExpressionto access validator.js functions. - The JSONSchema utility class for JSON schema validations. Use
JSONSchemaorjsonschemawithin theConfigExpressionto access the utility class. - Zod for schema validations with static type inference. Use
zwithin theConfigExpressionto access Zod functions. - Chai for assertions functions. Use
assert,expect, andshouldrespectively within theConfigExpressionto access Chai functions.
Learn more about ConfigExpression
Learn more about ConfigExpression
UpsertCommand
Create, update or delete Configs from a ConfigStore.
Search UpsertCommand
EvalCommand
Fetch Configs from ConfigStore on demand.
Search EvalCommand
ExportCommand
Export Configs as configuration data in various formats and modes.
Search ExportCommand
Connecting The Dots
Important read: This section is crucial for maximizing your Configu experience. Don't skip it! 🌟
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.
Common Configuration Concepts
Environment variable
A variable whose value is set outside the program (dynamic-named value), typically through the operating system or a configuration file, to influence the program’s operation without altering its code.Secret
A piece of sensitive data that should be kept confidential, such as passwords, API keys, and certificates. Secrets are typically stored in a secure location and accessed programmatically.Secret Manager
A tool that securely stores and manages sensitive data. It provides an interface to store, retrieve, and rotate secrets, ensuring secure access to sensitive information. Examples include: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Google Secret Manager, etc.Configuration deployment
The process of deploying configuration data to a target environment. This process involves exporting configuration data from a source, transforming it into a suitable artifact, and injecting it into the target environment or service, such as shell environments, Docker containers, Kubernetes clusters, AWS Lambda functions, ECS containers, Vercel deployments, Netlify setups, and more.Check out our guides section for examples of configuration deployments.
Configuration file
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
Configuration formats
Standard formats for configuration files include XML, JSON, YAML, TOML, INI, Dotenv, HCL, Kubernetes ConfigMap, Terraform Variables (Tfvars), and Helm Values, each catering to specific use cases and environments. There are numerous other formats available as well.Configuration template
A file containing placeholders like{{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.