Components

A Component is a logical piece of software — an application, a service, a workload, or a piece of infrastructure — together with the configuration that describes how it runs. A component is not tied to any particular deployment. The same component is typically deployed many times: in different environments, regions, clusters, or tenants. Each of those deployments has its own complete copy of the component's configuration, and each such copy is a variant of the component.

Components and variants are the primary way to think about and organize configuration in ConfigHub. Lower-level entities such as Spaces and Units implement them, as described in How components are represented below.

Variants: bases and deployments

A component has one or more variants. Every variant contains the full configuration for the component, differing from its sibling variants only in deployment-specific details such as replica counts, resource limits, hostnames, and credentials. A variant is one of two kinds:

• A base is a variant that is not meant to be deployed. It exists to be cloned into other variants. A base contains complete configuration, but deployment-specific values are typically left as placeholders to be filled in downstream. A base has no Target attached: there is nothing live to diff it against or apply it to.
• A deployment is a variant that is meant to be deployed to a Target. It is typically cloned from a base, with the placeholders replaced by concrete values specific to its target. Because a deployment has a target, every resource in it can be released and applied to live infrastructure. Each resource then has a globally unique live address (for Kubernetes: cluster, API version, kind, namespace, and name).

A component can have multiple bases as well as multiple deployments. For example, a component might have a root base, plus a prod base and a non-prod base cloned from it, each capturing the policies of its environment class, with the actual deployments cloned from those. The relationships must be a tree structure. A single base or deployment variant can only have one upstream variant.

Propagating change between variants

Variants of a component can be related to each other in upstream/downstream relationships. When a variant is cloned from another — a deployment from a base, or a staging deployment promoted onward to production — ConfigHub records the relationship and uses it to propagate later changes with a "smart" merge that preserves each downstream variant's local customizations.

This is what turns a set of variants into a change flow: edit the base once, then upgrade each downstream variant to pick up the change, releasing each deployment as it is approved. See the variants guide for the mechanics, and tracking and promoting changes for declaring the order those hops happen in and following one named change along it.

Upstream relationships are not required. Two variants of the same component can be unrelated, in which case propagating a change between them is a manual exercise.

One component or two?

Variants of a component are meant to be alike: the same logical software, adapted to different deployment contexts. If two variants differ wildly — different resource types, different topology, little shared configuration — they probably do not represent the same piece of software and should be split into separate components. The test is whether a change to the component would normally need to flow to all of its variants.

The component/target matrix

A useful mental model is a matrix with components on one axis and deployment targets (environments, regions, clusters) on the other. Each populated cell is a deployment variant; the bases sit alongside as the sources the deployments are cloned from.

Component	Base	Dev	Staging	Prod (us)	Prod (eu)
web-app	✓	✓	✓	✓	✓
inference-engine	✓	✓		✓
docs-site	✓			✓

The matrix is not always fully populated. In this example the inference engine is only deployed in one production region even though the web app that uses it runs in both.

Dependencies between components

Components can depend on each other — a web app depends on an inference engine, an application depends on a database. Concretely, the dependency is between deployments: the web app's prod deployment needs the endpoint of the inference engine's prod deployment. In ConfigHub these dependencies are represented as Links between the underlying units, which can resolve placeholders in the dependent configuration from values provided by the dependency. See managing dependencies.

How components are represented

A component is not a stored entity in ConfigHub. It is a convention built from spaces and labels:

• Each variant is implemented as a Space. The set of Units in the space is the totality of the configuration for that variant.
• The component is the group of spaces that share the same Component label value. The Variant label names each variant within the component, and the recommended space slug convention is {{.Labels.Component}}-{{.Labels.Variant}} (for example, web-app-prod-us). Additional well-known labels — Environment, Region, Layer, Owner — capture the other dimensions of the matrix. See metadata.
• Whether a variant is a base or a deployment is determined by if it has a target: no target means base.
• Upstream/downstream relationships between variants are maintained per unit, via each cloned unit's upstream reference and its UpgradeUnit Link.

Because the implementation is spaces, units, and labels, everything in ConfigHub that operates on those — filters, bulk operations, triggers, views, and permissions — works across components and variants. For example, a filter on Labels.Component = 'web-app' selects every variant of the web app, and a filter on Labels.Environment = 'prod' cuts across components to select every production deployment.

Working with components

The cub variant commands operate at the variant level:

• cub variant upload seeds a base from rendered manifests, setting the Component and Variant labels.
• cub variant create clones a variant into a new downstream variant, attaching a target to make it a deployment.
• cub variant promote upgrades a downstream variant with the changes made upstream since it was created or last promoted.

In the ConfigHub UI, the Components view shows each component's variants and their promotion tree, with pending upgrades and unapplied changes surfaced per deployment.

See the variants guide for the full workflow.