9. 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 prefixes 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 prefixes to update multiple domains within the same device (or across multiple devices). This can be done by defining hierarchical prefixes, as explained in Managing Environment-Specific Properties/Variables:

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

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 properties/variables as part of any attribute/option. DPBuddy resolves the variables right before the task/command is executed for each environment prefix (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 with multiple prefixes, e.g., “dev.fw.port”, “test.fw.port”. When you run this task with the “dev, test” prefix 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 properties/variables 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.

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

9.1.1. 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 prefix 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"/>