Concepts

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 App

Configuration 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) transforms 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

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

ConfigSet

A unique path within a hierarchical data structure that groups Configs contextually, organizing configurations data logically.

core/ConfigSet

Learn more about ConfigSet

A 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.

Let’s explore an example of a ConfigSet hierarchy:

''
├── 'development'
│   └── AWS_REGION=us-east-2
└── 'production'
    ├── AWS_REGION=us-east-1
    └── 'eu-customer'
        └── AWS_REGION=eu-west-1

In this example, the 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:

''
├── 'staging'
│   ├── API_URL=https://api-staging.example.com
│   └── 'feature-flags'
│       ├── FEATURE_A_ENABLED=true
│       └── FEATURE_B_ENABLED=false
└── 'production'
    └── API_URL=https://api.example.com

In this example, the 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

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:

process.env.CONFIG;

ConfigValue

An assignment to a ConfigKey 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

A 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:

keys:
  API_KEY:
    test: validator.isString($.value)
    required: true
    description: 'API key for a 3rd party service'

In this example, the 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.

Each 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:

lodash for various utility functions. Use _ within the ConfigExpression to access lodash functions.
validator.js for string validations. Use validator within the ConfigExpression to access validator.js functions.
The JSONSchema utility class for JSON schema validations. Use JSONSchema or jsonschema within the ConfigExpression to access the utility class.
Zod for schema validations with static type inference. Use z within the ConfigExpression to access Zod functions.
Chai for assertions functions. Use assert, expect, and should respectively within theConfigExpression to access Chai functions.

Learn more about ConfigExpression

Configu uses Acorn to parse ConfigExpressions and SES to execute them in a secure and strict environment.

Example usage of ConfigExpressions in the test Cfgu property:

keys:
  ENABLE_API:
    test: validator.isBoolean($.storedValue)
    description: 'enables a 3rd party service'
  API_KEY:
    test: 'ENABLE_API === true'
    description: 'API key for a 3rd party service. Only required if ENABLE_API is true'

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! 🌟

Imagine you’re naming a variable that holds some special settings for your app—that’s your 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.

Configuration template engine

A software that replaces placeholders in configuration templates with actual values. Examples include: Jinja2, Mustache, Handlebars, Go Templates, etc.

Under the hood, Configu uses Acorn to parse configuration templates as Javascript and SES to execute it in a secure and strict environment.

Introduction

Interfaces

Integrations

Software Configuration

Configuration Abstraction

Configuration-as-Code (CaC)

Configu Concepts

Config

Cfgu

ConfigStore

ConfigSet

ConfigKey

ConfigValue

ConfigSchema

ConfigExpression

UpsertCommand

EvalCommand

ExportCommand

Connecting The Dots

Common Configuration Concepts

Environment variable

Secret

Secret Manager

Configuration deployment

Configuration file

Configuration formats

Configuration template

Configuration template engine

Introduction

Interfaces

Integrations

​Software Configuration

​Configuration Abstraction

​Configuration-as-Code (CaC)

​Configu Concepts

​Config

​Cfgu

​ConfigStore

​ConfigSet

​ConfigKey

​ConfigValue

​ConfigSchema

​ConfigExpression

​UpsertCommand

​EvalCommand

​ExportCommand

​Connecting The Dots

​Common Configuration Concepts

​Environment variable

​Secret

​Secret Manager

​Configuration deployment

​Configuration file

​Configuration formats

​Configuration template

​Configuration template engine

Software Configuration

Configuration Abstraction

Configuration-as-Code (CaC)

Configu Concepts

Config

Cfgu

ConfigStore

ConfigSet

ConfigKey

ConfigValue

ConfigSchema

ConfigExpression

UpsertCommand

EvalCommand

ExportCommand

Connecting The Dots

Common Configuration Concepts

Environment variable

Secret

Secret Manager

Configuration deployment

Configuration file

Configuration formats

Configuration template

Configuration template engine