Skip to content

Unit

The (Config) Unit is the core unit of configuration in ConfigHub.

Config Data

Config Units store configuration data. Configuration data may originate from a variety of sources: other Units, previous revisions, live state, documentation samples, AI agents, and so on, but ConfigHub becomes the authoritative record for the configuration.

Revisions

A Config Unit maintains a sequential list of revisions of the config data. Every time the data is mutated, ConfigHub records a new revision along with who made the change, a description of the change, and other metadata.

Toolchain Type

A Config Unit (or just Unit) contains configuration data ("config data") in a single format understood by a single family of tools, known as the ToolchainType. The ToolchainType implies a family of schemas for the configuration, including the means of distinguishing elements of different types and identities (i.e., names) -- called the resource provider in the function sdk. A typical kind of configuration element is a resource, and we currently use that term for configuration elements generally.

Unit Granularity

One or more "atomic" resources or other configuration elements can be specified in a Unit. For example, it can contain a list of Kubernetes YAML resources (YAML documents) or application properties files. A Unit is always applied in a single operation. So if it contains multiple resources/elements, it is expected that the infrastructure or bridge will be able to resolve references between resources and deal with ordering of actions.

A single Config Unit cannot contain resources/elements of different formats configured using different tools, such as both Kubernetes YAML and TOML application configuration.

Here are some examples of Config Units:

  • A Kubernetes resource serialized as a YAML document
  • A single Java properties file

We recommend that you store one resource per Unit. We will likely enforce that constraint in the future.

Ingested helm charts do not currently follow this guideline in order to simplify the process of ingesting and upgrading them from the charts.

Secrets shouldn't be stored in units. See recommendations in this blog post.

Unit Release Workflow

After making changes to configuration data of a Unit, at some point you will want to synchronize those changes to the Live resources. Primarily that is achieved via a Release operation, which makes the configuration available to GitOps operators via the OCI endpoint.

Release has some prerequisites:

  1. The Unit must have an attached Target of ToolchainType OCI.
  2. That Target must be associated with a server Worker that supports ToolchainType OCI.
  3. The Unit must not have any Apply Gates, such as due to lacking required approvals, remaining placeholder values, or other failed validation function triggers.

Once these prerequisites are satisfied, the release operation may be invoked.

This is a simplified workflow compared to using git, where:

  1. configuration changes would be committed and pushed,
  2. then a pull/merge request would be opened, validated, reviewed/approved, and merged, and then
  3. the GitOps operator would eventually pull and apply the changes.

In that workflow, the PR merge is analogous to the release operation. In ConfigHub, any configuration changes made after the last release (tracked by the last applied revision) are analogous to commits pushed to an open pull request.

Approval policy can be customized via a function trigger. A simple vet-approval function is provided as an example. It takes the number of required approvers as an argument. Only organization members with permission to approve the unit can successfully invoke the approve operation. Note that any changes made to a unit effectively invalidate any prior approvals by creating new unapproved revisions.

See the change-and-apply guide for more details.