Skip to content

cub changeorder create

cub changeorder create

Create a new changeorder or bulk create changeorders

Synopsis

Create a new changeorder or bulk create multiple changeorders by cloning existing ones.

SINGLE CHANGEORDER CREATION:

Create a new changeorder to record an entity changeorder specification.

Examples: 

  # Create a change order
  cub changeorder create --space my-space bump-base-image --description "Bump the base image to 1.42"

  # Create one that says where it is headed: the spaces it propagates into
  cub changeorder create --space my-space bump-base-image --description "Bump the base image" \
    --in-scope-space staging,prod-use2,prod-usw2

  # The list is a list, so work it out however you like and pass the answer
  SPACES=$(cub space list --quiet --no-headers -o name --where "Labels.Component = 'my-app'" | paste -sd, -)
  cub changeorder create --space my-space bump-base-image --in-scope-space "$SPACES"

  # Or let the server work the list out from a where expression, a Filter over Spaces, or both
  # (ANDed). The server records the spaces they select, and works them out again when either
  # changes or on "cub changeorder update --refresh-spaces"
  cub changeorder create --space my-space bump-base-image \
    --where-space-field "Labels.Component = 'my-app' AND Labels.Region = 'use2'"
  cub changeorder create --space my-space bump-base-image \
    --space-filter platform/prod-spaces --where-space-field "Labels.Region = 'use2'"

  # Or say it by component, which selects the same spaces without listing them
  cub changeorder create --space my-space bump-base-image --component my-app

  # Create one governed by a change workflow. The workflow says what each stage selects and
  # in what order; where the change is headed is the component's spaces, defaulting to the
  # component of the space it is created in.
  cub changeorder create --space my-space bump-base-image \
    --change-workflow workflows/my-app-main-line

  # End it at an existing boundary rather than at each unit's head. The tag is read to find
  # each unit's end revision; the change order marks with tags of its own.
  cub changeorder create --space my-space bump-base-image --end-tag my-space/release-42-end

  # Create one that propagates by running an invocation rather than by following links. The
  # change has not been made anywhere yet: "cub variant promote <space> --change-order" runs
  # the invocation in each space in scope, and the change order's tags record where it has.
  cub changeorder create --space my-space bump-api-image \
    --update-type Invoke --invocation platform/set-api-image \
    --in-scope-space staging,prod-use2,prod-usw2

  # The same, over a parameterized invocation and only the units it should reach. The
  # invocation is reusable -- it declares the tag as a parameter -- and the change order
  # supplies the tag for this rollout, the same one in every space.
  cub changeorder create --space my-space bump-api-image \
    --update-type Invoke --invocation platform/set-api-image --param tag=:1.27.3 \
    --where-unit "Labels.tier = 'frontend'" \
    --in-scope-space staging,prod-use2,prod-usw2

  # Create a changeorder from JSON
  cub changeorder create --space my-space -o json my-changeorder --from-stdin < changeorder.json

BULK CHANGEORDER CREATION:

When no positional arguments are provided, bulk create mode is activated. This mode clones existing changeorders based on filters and creates multiple new changeorders with optional modifications.

Bulk Create Examples: 

  # Clone all changeorders matching a pattern with name prefixes
  cub changeorder create --where "Description LIKE '%release%'" --name-prefix archive- --dest-space archive-space

  # Clone specific changeorders to multiple spaces
  cub changeorder create --changeorder my-changeorder --dest-space dev-space,staging-space

  # Clone changeorders using a where expression for destination spaces
  cub changeorder create --where "Description LIKE 'Release%'" --where-space "Labels.Environment IN ('dev', 'staging')"

  # Clone changeorders with modifications via JSON patch
  echo '{"Description": "Archived changeorder"}' | cub changeorder create --where "CreatedAt < '2024-01-01'" --name-prefix old- --from-stdin

cub changeorder create [<slug> [--description <description>]] [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
      --change-workflow string     identifier (slug, space/slug, or UUID) of the ChangeWorkflow to promote the ChangeOrder under
      --changeorder strings        target specific changeorders by slug or UUID for bulk create (can be repeated or comma-separated)
      --component string           filter for Component of the Variants to be promoted, defaults to containing Space's Component.
      --delete-gate strings        delete gates in key[=true] format; can separate by commas and/or use multiple instances of the flag
      --description string         human-readable description of the change
      --dest-space strings         destination spaces for bulk create (can be repeated or comma-separated)
      --end-tag string             tag (slug, space/slug, or UUID) marking the last revision of each unit to promote; without one, each unit's head revision is the end. The change order always creates its own start and end tags -- this one is read to find the boundary, recorded as AdoptedEndTagID, and never written to, since the change order also marks the units it carries no changes for
      --filename string            Read the ConfigHub entity JSON from file, URL (https://), or stdin (-); 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-space string        filter entity containing WHERE expression to select destination spaces for bulk create (slug or UUID)
      --from-stdin                 Read the ConfigHub entity JSON (e.g., retrieved with cub <entity> get --quiet --json) from stdin; merged with command arguments on create, and merged with command arguments and existing entity on update
  -h, --help                       help for create
      --in-scope-space strings     spaces (slug or UUID) this change order propagates into, stored on it as InScopeSpaceIDs (can be repeated or comma-separated); without any, wherever its links reach is where it is headed
      --invocation string          invocation (slug, space/slug, or UUID) to run in each space in scope; required with --update-type Invoke and refused otherwise. Naming it on the change order is what holds every space to the same update -- the invoke API takes what it runs from here. Immutable once set
      --label strings              labels in key=value format; can separate by commas and/or use multiple instances of the flag
      --name-pattern string        a pattern string for name generation of clones, prefix 'template:' to use a Go template with .SourceEntitySlug to access the original ChangeOrder and .Labels to access variant labels, example: 'template:{{.SourceEntitySlug}}-{{.Labels.env}}'
      --name-prefix strings        name prefixes for bulk create (can be repeated or comma-separated)
  -o, --output string              Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --param stringArray          value for one of the invocation's declared parameters, as name=value (can be repeated). One set for the whole change order, since a value that differed by space would make each variant a different change
      --quiet                      No default output.
      --space-filter string        filter over Spaces (slug, space/slug, or UUID) selecting where this change order is headed, ANDed with --where-space-field
      --unit-filter string         filter entity (slug, space/slug, or UUID, with From=Unit) narrowing the same selection as --where-unit, conjoined with it. Only for --update-type Invoke
      --update-type string         how the change order propagates: UpgradeUnit (the clone lineage, the default) or MergeUnits, which follow links and take the change from revisions the source unit already has, or Invoke, where the change is one invocation run in each space in scope and is made after the change order is created
      --variant-labels strings     labels for bulk create in the format of key1=value1|value2,key2=value1|value2|value3
      --verbose                    Detailed output, additive with default output
      --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-space string         where expression to select destination spaces for bulk create
      --where-space-field string   where expression over Spaces selecting where this change order is headed, stored on it as WhereSpace and ANDed with --space-filter; the server records the spaces they select as its in-scope spaces
      --where-unit string          where expression selecting which units of each space in scope the change order covers; without one it covers every unit. Only for --update-type Invoke. Unlike the spaces, this is asked again on every read, so a unit added to a space afterwards counts as not having had the invocation run on it

Options inherited from parent commands

      --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>

SEE ALSO