cub link create
cub link create
Create a new link or bulk create (copy) links
Synopsis
Create a new link between two units or bulk create links by copying existing links.
SINGLE LINK CREATION:
Create a single link between two units. Links define relationships between units and can be used to establish dependencies or connections between resources.
A link can be created:
- Between units in the same space
- Between units across different spaces (by naming the to unit as
/ , or by specifying the to space)
BULK LINK CREATION (COPY):
When no positional arguments are provided with --where or --filter plus at least --reverse or --from-downstream-where, bulk create mode is activated. This mode copies existing links and retargets their From and/or To units using downstream UpgradeUnit links.
A copy starts with no merge history and no delete gates of its own: the source link's merged-revision pointers name revisions of the units it connects, which a retargeted copy does not share. An UpgradeUnit copy is set to its new units' current revisions instead. --make-current is rejected here because its values are per-link; pass --upstream-last-merged-revision / --downstream-last-merged-revision if the copies need specific pointers, or run cub link update --make-current on them afterward.
Single Link Examples:
# Create a link between a deployment and its namespace in the same space
cub link create --space my-space -o json to-ns my-deployment my-ns --wait
# Create a link for a complex application to its namespace
cub link create --space my-space -o json headlamp-to-ns headlamp my-ns --wait
# Create a link between a cloned unit and a namespace
cub link create --space my-space -o json clone-to-ns my-clone my-ns --wait
# Create a link to a namespace in another space, spelled either way. The link is created in
# --space, where the from unit is
cub link create --space my-space dep-to-ns my-deployment platform/my-ns
cub link create --space my-space dep-to-ns my-deployment my-ns platform
# Roll a workload when its ConfigMap changes: hash the ConfigMap's data, and write the hash
# to an annotation of the pod template. A place in a unit is <resource-type>:<resource-name>:<path>
cub link create --space my-space config-hash my-deployment my-configmap \
--update-type TransformPaths --auto-update \
--upstream-getter 'configHash=get-hash data' \
--downstream-path 'apps/v1/Deployment:default/web:spec.template.metadata.annotations.confighub~1com/Hash={{.Params.configHash}}'
# Copy a value from the upstream unit, as an integer computed with CEL
cub link create --space my-space replicas my-canary my-deployment --update-type TransformPaths \
--upstream-path 'replicas=apps/v1/Deployment:default/web:spec.replicas' \
--downstream-path 'apps/v1/Deployment:default/web-canary:spec.replicas=int:cel:params.replicas / 10'
# Set an image tag from a value in the upstream unit by running a function on the downstream
# unit. An argument that uses an upstream value is prefixed template: or cel:; here the prefix
# is followed by an image reference, which begins with its own ':'
cub link create --space my-space app-image my-deployment registry/my-image --update-type TransformPaths \
--upstream-path 'tag=registrybot.confighub.com/v1alpha3:my-image:streams.stable.tag' \
--downstream-setter 'set-image-reference-by-uri ghcr.io/example/app template::{{.Params.tag}}'
# State the binding of a NeedsProvides link: where the downstream unit needs a value, then
# where the upstream unit provides it
cub link create --space my-space subnet-to-rt subnet route-table --auto-update \
--manual-binding 'example.com/v1/Subnet:/public-2:spec.routeTableRef.name=example.com/v1/RouteTable:/public-rt:metadata.name'
Bulk Create (Copy) Examples:
# Copy outgoing links from prod-v1 units to their downstream copies in prod-v2
cub link create --where "Space.Slug = 'prod-v1' AND ToSpaceID != SpaceID AND UpdateType != 'UpgradeUnit'" \
--from-downstream-where "UpdateType = 'UpgradeUnit' AND Space.Slug = 'prod-v2'"
# Also retarget the To units to their downstream copies
cub link create --where "Space.Slug = 'prod-v1' AND ToSpaceID != SpaceID" \
--from-downstream-where "UpdateType = 'UpgradeUnit' AND Space.Slug = 'prod-v2'" \
--to-downstream-where "UpdateType = 'UpgradeUnit' AND Space.Slug = 'prod-v2'"
# Reverse cross-space UpgradeUnit links (create the link in the To unit's space)
cub link create --where "Space.Slug = 'prod-v2' AND UpdateType = 'UpgradeUnit'" --reverse
cub link create [<link slug> <from unit slug> <to unit slug> [<to space slug>]] [flags]
Options
--allow-exists Allow creation of resources that already exist
--annotation strings annotations in key=value format; can separate by commas and/or use multiple instances of the flag
--auto-update enable automatic downstream unit updates when upstream changes; a link created with no --update-type gets this without asking
--clearance stringArray class of guarded reason this link's merges are cleared for, as KEY, KEY=VALUE[;VALUE...], KEY!=VALUE[;VALUE...], or !KEY to refuse any path carrying KEY (repeatable). Pass an empty value to clear
--delete-gate strings delete gates in key[=true] format; can separate by commas and/or use multiple instances of the flag
--display-name string friendly name for the entity, which need not be unique or URL-safe; an entity without one is shown by its slug
--downstream-last-merged-revision int set DownstreamLastMergedRevisionNum explicitly: the downstream revision the last merge produced
--downstream-path stringArray value a TransformPaths link writes to the downstream unit, as [<key>=]<resource-type>:<resource-name>:<path>=[<data-type>:][<evaluator>:]<expression> (repeatable). The evaluator is template, the default, or cel; the data type is string, the default, int or bool. The upstream values the expression refers to are recorded as its parameters. The key identifies the entry when two versions of the link are merged
--downstream-setter stringArray function a TransformPaths link runs on the downstream unit, as [<key>=]<function> [<argument>...] (repeatable), the function written as on the cub function do command line. An argument prefixed template: or cel: is evaluated before the function runs, and may refer to the upstream values, as in template:{{.Params.tag}}; those it refers to are recorded as the setter's parameters
--dry-run report what the command would write, and write nothing
--filename string Read the ConfigHub entity's fields, as YAML or JSON, from file, URL (https://), or stdin (-), as --from-stdin does; mutually exclusive with --from-stdin
--filter string Filter entity to apply to the list. Specify as 'space/filter' for cross-space filters or just 'filter' for current space. Supports both slugs and UUIDs. The filter will be combined with any --where clause using AND logic. Examples: "production-filters/security-check", "my-filter-uuid", "validation-rules"
--filter-unit string filter, by slug or UUID, over Units selecting those to create from, with --from-backing-units
--from-backing-units create a Link from each ConfigHub/YAML Unit --where-unit, --filter-unit and --space select that describes one, in the Unit's space, with the Unit as its backing Unit
--from-downstream-where string where expression to find downstream UpgradeUnit links from each source link's FromUnit; creates one copy per match
--from-stdin Read the ConfigHub entity's fields, as YAML or JSON, from stdin; merged with command arguments on create, and merged with command arguments and existing entity on update. A field the entity does not have, or one only the server sets, is refused; cub <entity> explain lists the fields
--guard stringArray reason to record on the paths this link's resolve writes, as KEY=VALUE (repeatable). A later operation must be cleared for it before overwriting those paths, the link's next resolve included, so --clearance has to cover it; refused on UpgradeUnit and MergeUnits links, whose guards propagate from upstream. Pass an empty value to clear
-h, --help help for create
--hidden-reason string hide the entity, giving the reason as a name such as Archived: lists and bulk operations leave it out unless --include-hidden names the reason (use '-' to clear, which shows the entity again)
--include-hidden string[="*"] Also select hidden entities, to list or to act on: those hidden for the given HiddenReasons, comma-separated, as in --include-hidden=BackingUnit, or for any reason when given no value or "*". ConfigHub/YAML Units, which hold the configuration of other entities, are hidden with the reason BackingUnit. A --where naming entities by Slug or ID selects them whether hidden or not
--label strings labels in key=value format; can separate by commas and/or use multiple instances of the flag
--link strings target specific links by slug or UUID for bulk create (can be repeated or comma-separated)
--make-current set link revision numbers to current unit revisions; on create this skips the initial merge, on update it re-points the link at what the units now hold
--manual-binding stringArray binding stated for the link, as [<key>[:<attribute-name>]=]<needed <resource-type>:<resource-name>:<path>>[=[<data-type>:]<provided <resource-type>:<resource-name>:<path>>] (repeatable): the place in the downstream unit that needs a value, then the place in the upstream unit that provides it. The data type is string by default. An Insert link's one binding gives only the needed place, optionally followed by =<data-type>
--merge-enable-subtraction also subtract the downstream unit's local differences from the patch when resolving this link, on top of the stored path protection that preserves overrides by default
--no-auto-update disable automatic downstream unit updates; a link that does not update itself instead reports Stale when its upstream moves past it
--no-merge-enable-subtraction return this link to the default: no subtraction step
--no-protect return this link to the default: its resolve claims nothing it writes
--no-squash return this link to the default: its resolve walks the range
-o, --output string Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
--patch-existing with --from-backing-units, patch a Link a selected Unit already backs with what the Unit holds that it has not taken yet, rather than report that the Unit backs it
--permission strings permission in format Action:UserIDOrUsername, Action:group:GroupSlugOrID for a group you belong to, or Action:serviceaccount:ServiceAccountSlugOrID (e.g., Manage:user@example.com, View:group:platform, View:serviceaccount:deploy-bot, can be repeated)
--protect record the paths this link's resolve writes as protected local overrides, so a later merge from upstream does not overwrite them; refused on UpgradeUnit and MergeUnits links
--quiet No default output.
--reverse swap FromUnit and ToUnit directions of copied links (for cross-space link reversal)
--set stringArray set a field of the Link by its path, as <path>=<value> (repeatable). A path is field names separated by dots; a list element is addressed as ?<key>=<value> or by position, as in Stages.?Name=prod.WhereSpace, and is added if it is not there. A list of plain values separates them with ';'; an object or a list of objects is given as YAML or JSON. A reference is given as it is elsewhere, by slug, <space>/<slug> or ID. With --patch, only a path with no list element in it
--squash merge this link's range as one rebased diff in one revision instead of walking it: by default a resolve re-runs the upstream's recorded function invocations against the downstream unit where it can, and records one revision per upstream revision that has an effect; only meaningful for UpgradeUnit and MergeUnits links
--timeout string completion timeout as a duration with units, such as 10s or 2m (default "10m0s")
--to-downstream-where string where expression to find downstream UpgradeUnit link from each source link's ToUnit; exactly one match required
--transform-invocation string Invocation slug (or space/slug, or UUID) whose function transforms upstream data before it is inserted or upserted; only valid with --update-type Insert or Upsert
--unset stringArray clear a field of the Link by its path, or remove the list element the path ends at (repeatable)
--update-type string link update type (NeedsProvides, MergeUnits, UpgradeUnit, None, Insert, Upsert, or TransformPaths); the default is a NeedsProvides link that updates itself
--upstream-getter stringArray function a TransformPaths link runs on the upstream unit for a value, as <name>=<function> [<argument>...] (repeatable), the function written as on the cub function do command line. An argument prefixed template: or cel: is evaluated before the function runs; the getter runs before there are upstream values, so it cannot refer to them
--upstream-last-merged-revision int set UpstreamLastMergedRevisionNum explicitly: the upstream revision the link is treated as merged through
--upstream-path stringArray value a TransformPaths link reads from the upstream unit, as <name>=<resource-type>:<resource-name>:<path> (repeatable). The name is what an expression or a setter refers to it by, as .Params.<name> in a template and params.<name> in CEL
--verbose Detailed output, additive with default output
--wait wait for completion (default true)
--where string Filter expression using SQL-inspired syntax. Supports conjunctions with AND. String operators: =, !=, <, >, <=, >=, LIKE, NOT LIKE, ILIKE, ~~, !~~, ~, ~*, !~, !~*. Pattern matching with LIKE/ILIKE uses % and _ wildcards. Regex operators (~, ~*, !~, !~*) support POSIX regular expressions. A related entity is referenced by prefix, as in "UpstreamUnit.Slug = 'base'"; when the reference names a list, a * segment matches any element, as in "FromLink.*.Slug = 'upgrade-app'". Examples: "Slug LIKE 'app-%'", "DisplayName ILIKE '%backend%'", "Slug ~ '^[a-z]+-[0-9]+$'"
--where-mutation string where expression selecting mutations of the downstream unit whose paths this link's merges must not overwrite; unioned with the unit's stored path protection, so it protects more and never re-opens a path the unit claimed
--where-resource string where expression to select upstream resources for propagation
--where-unit string where expression over Units selecting those to create from, with --from-backing-units
--with-backing-units give each Link the bulk operation writes a backing Unit if it has none: a ConfigHub/YAML Unit holding its configuration, kept in step with it
Options inherited from parent commands
--component string the Component of --variant, when that names the variant alone; --variant <component>/<variant> says the same in one flag
--context string The context to use for this command
--debug Debug output
--space string space to operate in, by slug or UUID. Omitted, a list or bulk operation spans the organization and a single entity is named as <space>/<slug>; "*" means the same as omitting it
--variant string variant to operate in, as <component>/<variant>, or as <variant> with --component: the space naming that Component whose Variant label is <variant>. The same scope as --space, named by what it is rather than by the space's slug; the two cannot be combined
SEE ALSO
- cub link - Link commands