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
  COMPONENT_ID=$(cub component get my-app -o jq=.Component.ComponentID)
  SPACES=$(cub space list --quiet --no-headers -o name --where "ComponentID = '$COMPONENT_ID'" | 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 "ComponentID = '$COMPONENT_ID' 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: --component adds "ComponentID = '<id>'" to --where-space-field
  cub changeorder create --space my-space bump-base-image --component my-app
  cub changeorder create --space my-space bump-base-image --component my-app \
    --where-space-field "Labels.Region = 'use2'"

  # Create one governed by a change workflow. The workflow says in what order the spaces the
  # change is headed for are promoted: each stage is the spaces its selector matches among them.
  # Where the change is headed is still the change order's to say, as above.
  cub changeorder create --space my-space bump-base-image --component my-app \
    --change-workflow workflows/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                 Component (slug or UUID) whose spaces this change order is headed for: adds "ComponentID = '<id>'" to --where-space-field, which the server evaluates into its in-scope spaces
      --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)
      --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
      --dry-run                          report what the command would write, and write nothing
      --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'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-space string              filter entity containing WHERE expression to select destination spaces for bulk create (slug or UUID)
      --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
  -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)
      --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
      --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
      --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
      --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)
      --prior-revisions string           how the change order marks the units its change does not change, and the default --prior-revisions for its promotions: Include (the default), Skip or Error mark such a unit where its followers have it, or where it is released when that is later, so promoting the change does not move it, and differ in what a promotion does with a changed unit's revisions from before the change; All marks every such unit at its head, so promoting the change brings every unit up to the space it takes from. Fixed once the change order is created
      --quiet                            No default output.
      --release-prior-revisions string   what a release of the change order does with a unit's revisions from before the change -- after its last released revision, up to where the change starts: Include (the default) releases them; Error refuses, naming them and the change orders they belong to. cub release publish --prior-revisions overrides it
      --request-review strings           ask a user (username or ID) to review the change, as [<stage>:]<user>: where it stands in that stage's spaces, or with no stage in the change order's own space. Asking again re-requests the review (can be repeated or comma-separated)
      --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; Insert, Upsert, or TransformPaths, which resolve the links of that type from the spaces in scope to units outside the spaces in scope at the revision each is at when the change order is created (the links must not be AutoUpdate, and the spaces in scope must be named); 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. It takes what --where does on unit list, attributes of what a unit refers to included, as in "Space.Labels.Environment = 'prod'". 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>
      --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