Core concepts

Configurations can become increasingly complex as your application scales and integrates with multiple systems. Configfacets offers a configuration management solution designed to support standardization, reusability, and collaboration, enabling the seamless generation of configurations for both simple and advanced use cases with ease and efficiency.

Data Structures

Configfacets exposes 5 types of data structures - Data, Collection, Configuration, Service and Endpoint.

Data

Data allows you to manage static or dynamic configurations that are of low complexity. Common use cases include:

• Html or Markdown templates.
• Remote data wrapper.
• Reusable collection item.
• Reusable partial data.
• Reformat

Explore the links above to try out interactive examples.

Collection

Organize related structured data into groups that can adapt to specific scenarios. By using facets within these groups, you can efficiently filter and merge data. Common usecases include:

• i18N
• Feature flags
• FE or API or DB configurations

Configuration

Your use case might involve including a template from your community or a provider, customizing it with overrides, and generating a configuration using specific values. For instance, to generate an Istio Gateway configuration, the following resources are used:

• Gateway template from Istio provider
• Gateway overrides
• Custom values

By combining these, the gateway configuration is generated. Note: The template, overrides, and values are collections themselves, and can dynamically generate data based on the request context.

Service

While the configuration resource explained above generates a single configuration, the service resource creates a set of configurations. For example, an application may need to interact with multiple services like a database, API, frontend, and log collection service to function smoothly. Each of these services typically requires multiple configurations.The configfacets service resource is designed to support such use cases.

Additionally, it manages dependencies between service resources. If any dependencies exist, their configurations are generated first, added to the list, and then followed by this service’s configurations. It accepts two query parameters:

• format: json or yaml
• client: k8s or general

For instance, consider Example Inc., which needs to set up an Istio service. This setup requires configuring both the Gateway and modifying the load balancer to listen on NodePort. The service resource provides these configurations in a single, unified resource.

Variables

Configfacets variables are enclosed in double curly braces: {{ <variable_name> }}. Multiple variables can be used within a single line, such as:

image: "{{ rabbitmq.image }}:{{ rabbitmq.version }}"

Additionally, variables support nesting, allowing for more dynamic and flexible configurations.

Refer to this interactive example for a detailed demonstration.

Global Variables

Global variables should be formatted as __<variable_name>__. These variables are replaced first before any value substitutions are initiated. Refer to the example for more details.

Facets

Configfacets utilize facets to identify and merge collection items effectively. When a user queries the application configuration with:

{
    "facets": [
        "env:prod",
        "cluster:aws",
        "region:east"
    ]
}

We generate all possible facet combinations, starting from the least specific to the most specific match. Using the ["master"] collection item (if available) or an empty object {} as the base, we recursively merge matching collection items with previously merged values.

Merge Sequence:

1. Base Data → ["master"] (if available)
2. Single Facet Matches → ["region:east"], ["cluster:aws"], ["env:prod"]
3. Two-Facet Combinations → ["cluster:aws", "region:east"], ["env:prod", "region:east"], ["env:prod", "cluster:aws"]
4. Full Match → ["env:prod", "cluster:aws", "region:east"]

Each subsequent merge overwrites the previous values where applicable. This ensures that more specific facet combinations take precedence over generic ones.

Best Practices:

Organize configuration values from generic to specific, leveraging facet combinations for efficient data storage.

For example, if an aws production cluster has a single Redis instance shared across both east and west data centers, instead of duplicating the configuration, we store it under a more generic collection item:

"facets": ["env:prod", "cluster:aws"]

This minimizes redundancy while maintaining flexibility in configuration management.

Execution Settings

Configfacets provides flexible controls to manage the execution flow for each collection.

{
    "object_merge_recursive": true,
    "array_rm_duplicates": true
}

object_merge_recursive

• Enabled (true): Merges collection items recursively, ensuring deeper data integration. See the example for reference..
• Disabled (false): Overwrites the values of the last merged collection item instead of merging them. See the example for reference.

array_rm_duplicates

• Enabled (true): Removes array item duplicates on merge. See the example for reference..
• Disabled (false): Retains array item duplicates. See the example for reference..