cub variant create

Create a variant by cloning a space and its units

Synopsis

Create a variant of an upstream space by cloning the space and all of its units into a new downstream space.

This is a convenience command that combines two bulk operations: 1. Clone the upstream space (like "cub space create" in bulk mode), setting the new space's "Variant" label to . 2. Clone every unit from the upstream space into the new space (like "cub unit create" in bulk mode), linking each clone to its upstream unit.

The first argument is the variant name, which becomes the value of the "Variant" label on the new space. The second argument is the slug (or UUID) of the upstream space to clone from. The upstream space is expected to have labels such as Component, Layer, Owner, Environment, Region, and Variant, and may have a "TargetID" annotation referencing the default target for the space, but none of these are required.

The new space's labels are inherited from the upstream space, with "Variant" overridden to . Use --environment and --region to add or change the "Environment" and "Region" labels, since some values (like Region) commonly differ between variants. The other well-known labels (Component, Layer, Owner) are inherited and can be overridden with --variant-labels.

The new space's slug is derived from --space-pattern, a Go template evaluated over the cloned space's labels (and .SourceEntitySlug for the upstream slug). For example, using the Component label as a prefix and the Variant label as a suffix: "template:{{.Labels.Component}}-{{.Labels.Variant}}". If --space-pattern is omitted, the server derives the slug from the variant labels.

The following are copied from the upstream space to the new space: WhereTrigger, TriggerFilterID, Permissions, and DeleteGates.

Metadata flags are split by what they target, space vs. unit (mirroring "install upload"): --space-annotation / --space-delete-gate set on the new space, merged onto the values copied from the upstream space. --unit-annotation / --unit-delete-gate / set on every cloned unit, merged onto each clone's --unit-destroy-gate copied values. Destroy gates are unit-only (spaces have no destroy gates). Use --unit-delete-gate critical to protect a prod variant's units. --wait wait for the cloned units' triggers to finish (default true); pass --wait=false to return as soon as the clone is queued.

To automatically customize the cloned units, create PostClone triggers and select them via the upstream space's WhereTrigger or TriggerFilterID so that they are copied to the downstream space and run during the clone. Trigger arguments can reference space metadata in Go templates, such as "template:{{.SpaceLabels.Region}}" or "template:{{.SpaceAnnotations.host}}" — set the latter with --space-annotation. Any other changes can be made after the clone completes.

Examples:

  # Clone a space into a "test" variant. With Component=website inherited and Variant overridden to
  # "test", the name pattern produces the slug "website-test".
  cub variant create test website-prod \
    --space-pattern "template:{{.Labels.Component}}-{{.Labels.Variant}}"

  # Clone into a regional staging variant, overriding the Environment and Region labels.
  cub variant create staging website-prod --environment Staging --region us-east2

  # Point the cloned units at a target and stamp the new space's TargetID annotation.
  cub variant create test website-prod --target website-test/cluster

  # Set a space annotation a PostClone trigger reads, and protect the prod clones with a delete gate.
  cub variant create prod website-base \
    --space-annotation host=website.prod.example.com \
    --unit-delete-gate critical --unit-destroy-gate critical

cub variant create <variant-name> <upstream-space> [flags]

Options

      --allow-exists                Allow creation of resources that already exist
      --environment string          set the "Environment" label on the new space (example: "Prod")
  -h, --help                        help for create
      --namespace string            run set-namespace with this value on the cloned Kubernetes/YAML units, replacing the placeholder namespace from the upstream (e.g. a base uploaded with --namespace confighubplaceholder)
  -o, --output string               Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --quiet                       No default output.
      --region string               set the "Region" label on the new space (example: "us-east2")
      --space-annotation strings    annotation key=value to set on the new space (repeatable); merged onto the annotations copied from the upstream space. PostClone trigger args can read these via {{.SpaceAnnotations.<key>}}. "TargetID" is reserved (use --target)
      --space-delete-gate strings   delete gate key[=true] to set on the new space (repeatable); merged onto the delete gates copied from the upstream space
      --space-pattern string        a pattern string for the new space's slug, prefix 'template:' to use a Go template with .SourceEntitySlug for the upstream slug and .Labels for the cloned space's labels, example: 'template:{{.Labels.Component}}-{{.Labels.Variant}}'
      --target string               target for the cloned units, in <target-slug> or <space-slug>/<target-slug> form; also sets the TargetID annotation on the new space
      --timeout string              completion timeout as a duration with units, such as 10s or 2m (default "10m0s")
      --unit-annotation strings     annotation key=value to set on every cloned unit (repeatable); merged onto each unit's copied annotations
      --unit-delete-gate strings    delete gate key[=true] to set on every cloned unit (repeatable); e.g. --unit-delete-gate critical to protect a prod variant
      --unit-destroy-gate strings   destroy gate key[=true] to set on every cloned unit (repeatable); destroy gates are unit-only (spaces have no destroy gates)
      --variant-labels strings      additional variant labels for the new space in the format key1=value1,key2=value2 (the Variant label is always set from <variant-name>)
      --verbose                     Detailed output, additive with default output
      --wait                        wait for completion (default true)

Options inherited from parent commands

      --context string   The context to use for this command
      --debug            Debug output

cub variant create