Confd Auto Upgrade Tool

The confd-auto-upgrade tool is a simple utility to automatically migrate the confd configuration schema between different versions of the Director. Starting with version 1.12.0, it is possible to automatically apply the necessary configuration changes in a controlled and predictable manner. While this tool is intended to help transition the configuration format between the different versions, it is not a substitute for proper backups, and while downgrading to an earlier version, it may not be possible to recover previously modified or deleted configuration values.

When using the tool, both the “from” and “to” versions must be specified. Internally, the tool will calculate a list of migrations which must be applied to transition between the given versions, and apply them, outputting the final configuration to standard output. The current configuration can either be piped in to the tool via standard input, or supplied as a static file. Providing a “from” version which is later than the “to” version will result in the downgrade migrations being applied in reverse order, effectively downgrading the configuration to the lower version.

For convenience, the tool is deployed to the ACD Nodes automatically at install time as a standard Podman container, however since it is not intended to run as a service, only the image will be present, not a running container.

Performing the Upgrade

In the following example scenario, a system with version 1.10.1 has been upgraded to 1.14.0. Before upgrading a backup of the configuration was taken and saved to current_config.json.

Using the image and tag as determined in the above section. Issue the following command:

cat current_config.json | \
  podman run -i --rm images.edgeware.tv/acd-confd-migration:1.14.0 \
  --in - --from 1.10.1 --to 1.14.0 \
  | tee upgraded_config.json

In the above example, the updated configuration is saved to upgraded_config.json. It is recommended to manually verify the generated configuration, and after which apply the config to confd by using cat upgraded_config.json | confcli -i.

It is also possible to combine the two commands, by piping the output of the auto-upgrade tool directly to confcli -i. E.g.

cat current_config.json | podman run ... | tee upgraded_config.json | confcli -i

This will save a backup of the upgraded configuration to upgraded_config.json and at the same time apply the changes to confd immediately.

Downgrading the Configuration

The steps for downgrading the configuration are exactly the same as for upgrade except for the --from and --to versions should be swapped. E.g. --from 1.14.0 --to 1.10.1. Keep in mind however, that during an upgrade some configuration properties may have been deleted or modified, and while downgrading over those steps, some data loss may occur. In those cases, it may be easier and safer to simply restore from backup. In most cases where configuration properties are removed during upgrade, the corresponding downgrade will simply restore the default values of those properties.