Skip to main content

Managing configurations

ewx-cli config moves configurations between namespaces and local directories. Configurations depend on each other (a flow needs its rules, a market adapter its transformation configuration) and most are identified by IDs that differ per namespace. The CLI resolves those dependencies, uploads in dependency order and remaps IDs, so that a release cannot leave a namespace with broken references.

The three core commands take a source and a destination, each either a namespace or a directory:

ewx-cli config download company-prd/enrx_org_001 ./configs         # namespace -> directory
ewx-cli config upload   ./configs company-prd/enrx_org_002         # directory -> namespace
ewx-cli config transfer company-prd/enrx_org_001 company-prd/enrx_org_002   # namespace -> namespace

ewx-cli config verify <namespace> checks a namespace for broken dependencies without changing anything.

Selecting configurations​

Without options a command acts on everything it finds. Two ways to narrow it down:

Per-resource options for one or two specific configurations, by name or ID:

ewx-cli config transfer company-prd/enrx_org_001 company-prd/enrx_org_002 \
  --flow VEE_power --transformation-configuration 6444763028914176 --channel-classifier POWER_INT15T

A resource file for anything larger. Create one with ewx-cli config create-resource-file <path>, which opens it in your editor. For each resource type it takes a whitelist and a blacklist, one entry per line, each being a literal ID, a name, or a regular expression on names:

resources.ini
[resources.transformation_configurations]
# 'id'
whitelist = 5617674905585664
            5645353064314880

[resources.channel_classifiers]
# 'name'
whitelist = POWER_.*
blacklist = .*_TEST

Then pass it with --resource-file resources.ini. A configuration that is both whitelisted and blacklisted is never included, nor are its dependants. When a whitelisted configuration depends on a blacklisted one, the CLI shows a conflict report and asks whether to ignore the blacklists, enforce them, review each conflict, or abort.

Dependencies and the upload overview​

Whatever you select, the CLI resolves the full dependency tree, also for a plain download, to catch configurations that are already broken at the source. It then prints an overview of everything it is about to do and asks for confirmation:

CHANNEL CLASSIFIERS
==========================================================================
DELIVERED_POWER_INTERVAL_KWH        -> DELIVERED_POWER_INTERVAL_KWH
HOURLY_DELIVERED_POWER_INTERVAL_KWH -> New

FLOWS
====================================================
VEE_power (ID: 5154610821988352) -> 5762715066826752

RULES
============================================
gap_check            -> gap_check
temporal_aggregate   -> New

-> Do you wish to continue? [y/N]:

Answering yes runs the whole plan without further questions. Configurations are uploaded in reverse dependency order: a flow only after its rules, a market adapter only after its transformation configuration, so IDs exist on the destination when dependants reference them. Pass -v to follow the individual requests.

After the run each configuration is labelled:

  • (New): created on the destination.
  • (Update): existed and was updated.
  • (Unchanged): existed and matched, so no request was made. Today only rules and transform rules get this label, compared on display name, description, code and parameters.

Every upload and transfer also records an upload cache that Upload history and rollback uses. Name it with --name <label> to find it back easily, or skip it with --no-history-cache.

Dry runs​

upload, transfer and upload-history revert accept --dry-run. A dry run does everything up to the confirmation: resolves dependencies, checks permissions, maps IDs against the destination, prints the same overview, and exits without changing anything or writing a history cache.

ewx-cli config transfer company-prd/enrx_org_001 company-prd/enrx_org_002 --flow VEE_power --dry-run

Use it to attach a release plan to a change request, or to let a pipeline validate a release. A dry run needs the same permissions as the real run, so it also proves the real run would not be blocked.

Uploading without dependencies​

--no-deps (or --no-dependencies) makes upload and transfer act on only the configurations you named, without walking the dependency tree. Useful during development to push a single changed rule without dragging along every related change.

  • The CLI still reads the direct dependencies on the destination to remap embedded references, such as the transformation configuration ID inside a market adapter.
  • A configuration can be created with --no-deps only when all of its direct dependencies already exist on the destination, or are uploaded in the same command. Otherwise the CLI aborts and lists the missing dependencies.
  • Far fewer permissions are needed, because dependencies are neither created nor updated.

Merge-aware namespace properties​

Namespace properties whose value is a JSON dictionary are merged rather than overwritten. Today this applies to market_adapters, which maps market adapter aliases to IDs:

  • New keys from your local copy are added.
  • Keys only present on the destination are kept.
  • A key defined on both sides with different values prompts for confirmation; declining aborts the upload.

To replace the whole property, dropping destination-only keys, pass --replace-namespace-property:

ewx-cli config upload ./configs company-prd/enrx_org_001 --namespace-property market_adapters --replace-namespace-property

The flag has no effect on other namespace properties, which always overwrite.

Required permissions​

Before touching the destination the CLI verifies your permissions and asks only for what the operation needs:

  • Level: read-only operations (download, verify, the source side of transfer) need viewer; writing operations (upload, the destination side of transfer) need owner, because creating a configuration requires owner-level access.
  • Scope: when you name specific configurations, only the permissions of those resource types and, with dependencies, of their dependencies are required. A whole-namespace operation needs the full set of configuration-management permissions.
  • With --no-deps: only the resource types you named are checked.

A missing permission stops the run before any change, naming the resource and the level required.

Keeping configurations in git​

A common setup is a repository per customer with the downloaded configurations directory committed, so every change is reviewed and history is kept:

  1. ewx-cli config download company-acc/enrx_org_002 ./configs --resource-file resources.ini after changing something in the acceptance namespace.
  2. Commit and review the diff.
  3. ewx-cli config upload ./configs company-prd/enrx_org_001 --dry-run, attach the plan to the change request.
  4. ewx-cli config upload ./configs company-prd/enrx_org_001 --name release-26.08 to release.

The standard-packages are deployed the same way, and pytest-bdd-ewx uses a directory in this layout to set up its test configurations. ewx-cli config describe renders the directory's dependencies as a diagram, see Describing configurations.