Skip to content

Link

Infrastructure resources often have dependencies on other resources in the sense that information about one resource is necessary in order to configure another resource. For example an AWS load balancer needs to know the subnet IDs of the VPC it should route traffic to. When dependent resources are kept together in a single Config Unit, the infrastructure can usually resolve these dependencies by itself. But sometimes you want to modularize and keep them separate. ConfigHub supports this by using multiple Config Units and you use Links to express these dependencies between Config Units.

In general, Links indicate that configuration data should be propagated from the target of the Link, called the upstream unit, to the source of the Link, called the downstream unit -- the Link direction is the opposite of the direction that data flows. Downstream units link to upstream units that they depend upon. The dependency also sequences apply and destroy actions.

In Kubernetes, data propagation manifests mainly in the form of static resource references. For example, for Units containing Kubernetes Namespace-scoped resources such as Deployment and Service, the metadata.namespace fields of those resources can be set via the needs/provides mechanism by linking their Unit to a Unit containing a Kubernetes Namespace.

The UpdateType field determines the operation performed using the Link:

  • None: No data propagation is performed. Used solely to express a dependency for sequencing apply and destroy actions. AutoUpdate must be false.
  • UpgradeUnit: Merges upstream configuration data into the downstream unit and keeps the downstream unit's UpstreamUnitID and UpstreamRevisionNum in sync with the Link. This type is automatically created when cloning a unit and is used by the upgrade mechanism. A unit may have at most one outgoing UpgradeUnit Link.
  • MergeUnits: Like UpgradeUnit, but without updating the unit's UpstreamUnitID and UpstreamRevisionNum. More flexible: a unit may have any number of incoming and outgoing MergeUnits Links. Can pull from LiveState when UseLiveState is true.
  • Insert: Inserts the entire configuration data of the upstream unit as a string value at a specific path in the downstream unit, identified by a single Binding. Useful for embedding structured data (such as JSON policies) into a field of a resource in a different format.
  • NeedsProvides (default): Needed values in the downstream unit are matched with provided values from the upstream unit. See needs/provides for details. If UpdateType is empty, it defaults to NeedsProvides.

Automatic creation

When a unit is cloned, ConfigHub automatically creates an UpgradeUnit Link from the new clone (downstream) to the original unit (upstream). This Link records which upstream revision was last merged and includes a WhereMutation filter so that upgrade operations only overwrite mutations that originated from the upstream, preserving local customizations.

Resolution

For all Link types that propagate data (all except None), configuration data can be updated in two ways:

  • Automatic: When AutoUpdate is true, the downstream unit is automatically updated when the upstream unit changes. AutoUpdate must be false for UpdateType None.
  • Manual: The downstream unit is updated with a resolve parameter specifying the Link or Links to resolve. When resolving all Links (Link:*), None Links are skipped.

For UpgradeUnit Links, resolution can also be triggered via the --upgrade flag, which uses the Link's WhereMutation filter if one is present.

To preview what a resolve operation will do before committing the change, use --dry-run.

Bindings

Bindings record which values are propagated by a Link. Their structure and requirements vary by Link type:

  • NeedsProvides: After resolution (automatic or manual), Bindings are stored on the Link recording which needed attributes in the downstream unit were matched to provided attributes in the upstream unit. Bindings can also be specified manually with AutoUpdate false to propagate values to or from non-standard locations. Each Binding specifies DataType (string, int, or bool), ProvidedResource, ProvidedPath, NeededResource, and NeededPath.
  • Insert: Requires exactly one Binding specifying NeededResource.ResourceName, NeededResource.ResourceType, and NeededPath to identify where the upstream data is inserted. ProvidedResource and ProvidedPath must not be specified. AutoUpdate in the Binding must be false.
  • MergeUnits, UpgradeUnit, None: Must not have Bindings.

In addition to common metadata fields (DisplayName, Slug, Labels, Annotations), Links have the following fields:

Field Description
FromUnitID The downstream (consumer) unit. The Link must be in the same space as this unit.
ToUnitID The upstream (producer) unit.
ToSpaceID The space of the upstream unit. May differ from the Link's space for cross-space links.
UpdateType The operation type: None, UpgradeUnit, MergeUnits, Insert, or NeedsProvides. Defaults to NeedsProvides if empty.
AutoUpdate If true, automatically update the downstream unit when the upstream unit changes. Must be false for None.
UseLiveState If true, use the LiveState of the upstream unit rather than Data as the source.
UpstreamLastMergedRevisionNum The revision (or UnitAction) number of the last merged upstream change.
DownstreamLastMergedRevisionNum The revision number of the downstream unit created by the last merge.
WhereMutation A filter expression that controls which downstream mutations can be overwritten during merge operations. Only for MergeUnits and UpgradeUnit.
WhereResource A filter expression that selects which upstream resources are eligible for propagation.
Bindings The attribute bindings for NeedsProvides and Insert Links. See Bindings.