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

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.

types/Config

Cfgu

Cfgu

A generic declaration of a Config, characterized by properties like type, description, and constraints, providing a schema for configuration data.

types/Cfgu | .cfgu $schema

ConfigStore

ConfigStore

A storage engine interface for Config records, acting as a repository for configuration data.

types/ConfigStore | ConfigStore Collection

ConfigSet

ConfigSet

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

types/ConfigSet

ConfigKey

ConfigKey

A reference to a specific configuration declaration as it appears within the codebase, linking code to its configuration.

ConfigValue

An assignment to a ConfigKey in a ConfigSet, specifying the actual configuration value for a given context.

ConfigSchema

ConfigSchema

A file containing binding records that link each unique ConfigKey to its corresponding Cfgu declaration, ensuring configurations are defined and applied correctly.

types/ConfigSchema

UpsertCommand

UpsertCommand

Create, update or delete Configs from a ConfigStore.

Search UpsertCommand

EvalCommand

EvalCommand

Fetch Configs from ConfigStore on demand.

Search EvalCommand

ExportCommand

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.

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