> ## Documentation Index > Fetch the complete documentation index at: https://docs.configu.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. export const Important = () => Important read: This section is crucial for maximizing your Configu experience. Don't skip it! 🌟 ; export const CfguExt = () => .cfgu.yaml|yml|json; ## 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](https://12factor.net/config) ## 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](https://dev.to/rannn505/configuration-as-code-automating-application-configuration-45k6) | [CaC Webinar](https://www.youtube.com/live/Z_Vz8v6e-U4?si=bDao_gIo1xiLDeQS\&t=107) ## 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. [core/Config](https://github.com/configu/configu/blob/main/packages/sdk/src/Config.ts) ### Cfgu Cfgu A generic declaration of a `Config`, characterized by properties like test, description, and constraints, providing a schema for configuration data. [core/Cfgu](https://github.com/configu/configu/blob/main/packages/sdk/src/Cfgu.ts) | [.cfgu \$schema](/interfaces/.cfgu#schema) ### ConfigStore ConfigStore A storage engine interface for `Config` records, acting as a repository for configuration data. [core/ConfigStore](https://github.com/configu/configu/blob/main/packages/sdk/src/ConfigStore.ts) | [core/stores](https://github.com/configu/configu/blob/main/packages/sdk/src/stores) | [integrations/stores](https://github.com/configu/configu/blob/main/packages/integrations/stores) 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](/interfaces/.configu). Configu's interfaces [support a wide range of `ConfigStores`](https://github.com/configu/configu/blob/main/packages/integrations/stores). 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 ConfigSet A unique path within a hierarchical data structure that groups `Config`s contextually, organizing configurations data logically. [core/ConfigSet](https://github.com/configu/configu/blob/main/packages/sdk/src/ConfigSet.ts) 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: ```text theme={null} '' β”œβ”€β”€ '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: ```text theme={null} '' β”œβ”€β”€ '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 ConfigKey A reference to a specific configuration declaration as it appears within the codebase, linking code to its configuration. 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: ```javascript Node.js theme={null} process.env.CONFIG; ``` ```python Python theme={null} os.environ['CONFIG'] ``` ```C++ C++ theme={null} std::getenv("CONFIG") ``` ```Go Go theme={null} os.Getenv("CONFIG") ``` ```Rust Rust theme={null} env::var("CONFIG") ``` ```C# C# theme={null} Environment.GetEnvironmentVariable("CONFIG") ``` ```Java Java theme={null} System.getenv("CONFIG") ``` ```Ruby Ruby theme={null} ENV['CONFIG'] ``` ```Scala Scala theme={null} sys.env.get("CONFIG").value ``` ```bash Bash theme={null} $CONFIG ``` ```powershell Powershell theme={null} $env:CONFIG ``` ### 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. [core/ConfigSchema](https://github.com/configu/configu/blob/main/packages/sdk/src/ConfigSchema.ts) A `ConfigSchema` in Configu is a file with a 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: ```yaml example.cfgu.yaml theme={null} keys: API_KEY: test: validator.isString($.value) required: true description: 'API key for a 3rd party service' ``` ```json example.cfgu.json theme={null} { "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](https://lodash.com) for various utility functions. Use `_` within the `ConfigExpression` to access lodash functions. * [validator.js](https://github.com/validatorjs/validator.js) for string validations. Use `validator` within the `ConfigExpression` to access validator.js functions. * The [JSONSchema utility class](https://github.com/configu/configu/tree/main/packages/sdk/src/expressions/JSONSchema.ts) for JSON schema validations. Use `JSONSchema` or `jsonschema` within the `ConfigExpression` to access the utility class. * [Zod](https://zod.dev/) for schema validations with static type inference. Use `z` within the `ConfigExpression` to access Zod functions. * [Chai](https://github.com/chaijs/chai) for assertions functions. Use `assert`, `expect`, and `should` respectively within the`ConfigExpression` to access Chai functions. Configu uses [Acorn](https://github.com/acornjs/acorn/tree/master/acorn/) to parse `ConfigExpressions` and [SES](https://www.npmjs.com/package/ses) to execute them in a secure and strict environment. Example usage of `ConfigExpressions` in the `test` `Cfgu` property: ```yaml example.cfgu.yaml theme={null} 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' ``` ```json example.cfgu.json theme={null} { "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 UpsertCommand Create, update or delete `Configs` from a `ConfigStore`. [Search UpsertCommand](https://github.com/search?q=repo%3Aconfigu%2Fconfigu+Upsert+Command\&type=code) ### EvalCommand EvalCommand Fetch `Configs` from `ConfigStore` on demand. [Search EvalCommand](https://github.com/search?q=repo%3Aconfigu%2Fconfigu+Eval+Command\&type=code) ### ExportCommand ExportCommand Export `Configs` as configuration data in various formats and modes. [Search ExportCommand](https://github.com/search?q=repo%3Aconfigu%2Fconfigu+Export+Command\&type=code) ### Connecting The Dots 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](https://www.vaultproject.io/), [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/), [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/), [Google Secret Manager](https://cloud.google.com/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](/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](https://configu.com/blog/configuration-files-types-examples-and-5-critical-best-practices/) | [Wikipedia - Configuration file](https://en.wikipedia.org/wiki/Configuration_file) ### Configuration formats Standard formats for configuration files include [XML](https://www.w3.org/XML/), [JSON](https://www.json.org/), [YAML](https://yaml.org/), [TOML](https://toml.io/), [INI](https://en.wikipedia.org/wiki/INI_file), [Dotenv](https://github.com/motdotla/dotenv), [HCL](https://github.com/hashicorp/hcl), [Kubernetes ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/), [Terraform Variables (Tfvars)](https://www.terraform.io/docs/configuration/variables.html), and [Helm Values](https://helm.sh/docs/chart_template_guide/values_files/), 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}`, 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](https://jinja.palletsprojects.com/), [Mustache](https://mustache.github.io/), [Handlebars](https://handlebarsjs.com/), [Go Templates](https://pkg.go.dev/text/template), etc. Under the hood, Configu uses [Acorn](https://github.com/acornjs/acorn/tree/master/acorn/) to parse configuration templates as Javascript and [SES](https://www.npmjs.com/package/ses) to execute it in a secure and strict environment.