Executing DPBuddy’s Commands against Multiple Devices/Domains

Any DPBuddy command can be executed against multiple devices and/or domains. This is done by specifying a comma-delimited list of environment names using the env option/attribute or the dp.env property, e.g.:

dpbuddy testConnection -env "dev,test"
ant test.connection -Ddp.env="dev,test"

DPBuddy executes a command against each of the devices listed, in order. You can also specify a device list using a property and then refer to this property using dp.env/env.

For example, you can define a property for multiple production devices:

all.prod.devices=prod1,prod2,prod3

You can then reference this property instead of the device list:

dpbuddy testConnection -env all.prod.devices

This allows you to define a group of devices that are always updated together.

You can also use the list of environment names to update multiple domains within the same device (or across multiple devices). This can be done by defining HOCON variables or hierarchical property prefixes:

devtest.dp.username=dpbuddy
devtest.dp.password=dpbuddy01
devtest.dp.url=devtest-dp
devtest.dev.dp.domain=dev
devtest.test.dp.domain=test

To run a command against both the “dev” and “test” domains on the “devtest” device, specify the appropriate names:

dpbuddy testConnection -env  "devtest.dev, devtest.test"

Or create a property with the pre-defined list:

devtest.all=devtest.dev, devtest.test

And then use “devtest.all” as the value for -env:

dpbuddy testConnection -env devtest.all

You can use environment-specific settings as part of any attribute/option. DPBuddy resolves variables right before the task/command is executed for each environment name (as opposed to doing it once, when the Ant file loads). This allows for easy referencing of port numbers and other execution parameters. For example, you can define the following task to check certain DataPower ports:

<dp:assertOpenPorts ports="${fw.port}"/>

“fw.port” can be defined in multiple environments, e.g., “dev.fw.port”, “test.fw.port”. When you run this task with the “dev, test” list, DPBuddy will use the “dev” port for the first run and the “test” port for the second run.

You can also use environment-specific settings from the DPBuddy CLI.

By default, DPBuddy will exit once a command fails on one of the devices. This behavior can be overridden using “dp.continue.on.error” property or the “continueOnError” option/attribute. If this property/option is set to “true”, DPBuddy will attempt to execute the command against all of the devices in the list regardless of any errors with other devices.

DPBuddy can also rollback all the devices for which the command succeeded, if one or multiple devices have failed. This function can be turned on by setting the “rollbackAllOnError” attribute/option. Note that in order for the rollback to work, the affected domains must have a defined checkpoint. DPBuddy always rolls back to the latest checkpoint.

Note that only successful devices will be rolled back. Rollback for failed devices can be turned on by using a different attribute/option, “rollbackOnError”. This option is supported by import, copy, exec and a few other commands which deal with updating the device configuration and files.

Multi-Domain Execution

Many DPBuddy commands support domainPatterns (domains) option accepting a comma-separated list of domain regexps. If multiple domains are specified, the command will be serially executed against all the domains, one by one:

# import sslSettings.xml into all domains for the default environment
dpbuddy import -file sslSettings.xml -domains ".*"

The default domain is excluded by default. To apply the command to the default domain, explicitly add it to the list:

dpbuddy import -file sslSettings.xml -domains ".*, default"

The list of commands supporting this option includes assertStatus, updateConfig, import, copy, deleteMutlipleFiles, delConfig, save, quiesce.

execTarget

execTarget performs the same function as the built-in AntCall Ant task in that it invokes another target in the same Ant project. It supports all the attributes of AntCall.

In addition, it also handles multi-device execution. If multiple devices were specified using using the env attribute or the dp.env property, execTarget will execute the target specified by the target attribute once for each device. This allows for repeating the same sequence of targets for multiple devices.

Note that you must use dp.env (or dpEnv) property name with execTarget, it does not support the dp.device alias.

execTarget can rollback the domain if the invoked target or any of its dependent targets failed.

execTarget supports all the common attributes listed in Attributes/Options for Running Commands against Multiple Devices, such as env or continueOnError.

Examples

Execute the _clean.deploy.domain target once for each device:

<target name="clean.deploy.domain"
        description="Quiesce the domain, clean it and import services">
    <!-- Execute this target for each device/environment defined in "dp.env"
    This will also execute all the dependent targets of _clean.deploy.domain
    -->
    <dp:execTarget target="_clean.deploy.domain" />
</target>

<!-- Internal target, invoked by "clean.deploy.domain" -->
<target name="_clean.deploy.domain" depends="quiesce.domain, clean.domain, deploy.domain, run.tests"/>