Use step macros
You can define new step primitives by using predefined step primitives such as
os-script. These are called step macros. After you define a step macro, you can refer to it by name, as you refer to a predefined step. You can reuse built-in steps and customize them for your system. Step macros can include one or more parameters of any valid Deploy type.
You define step macros in the
XL_DEPLOY_SERVER_HOME/ext/xl-rules.xml file. Step macros are registered with the Deploy step registry at startup.
Important: You can only configure one step in a step macro.
This is an example of a simple step macro definition. This XML defines a step macro with the name
wait-for-ssh-connection that wraps a
<step-macro name="wait-for-ssh-connection"> <steps> <wait> <order>60</order> <description>Wait for 25 seconds to make sure SSH connection can be established</description> <seconds>25</seconds> </wait> </steps> </step-macro>
To refer to the step with a name that is relevant to your system, wrap the
wait step in a step macro.
To use the
wait-for-ssh-connection step, refer to it in the
<rule name="ec2-wait" scope="deployed"> <conditions> <type>ec2.InstanceSpec</type> <operation>CREATE</operation> </conditions> <steps> <wait-for-ssh-connection/> </steps> </rule>
For each deployed of type
ec2.InstanceSpec, Deploy will add a wait step to the plan.
wait-for-ssh-connection step macro defined above is static. For each instance, it will add a 25-second wait time. You can make it dynamic by defining parameters in the step macro definition. Example: If you want to use the SSH wait time defined on the deployed instead of a hard-coded value, change the step macro definition:
<step-macro name="wait-for-ssh-connection"> <parameters> <parameter name="sshWaitTime" type="integer" description="Time to wait"/> </parameters> <steps> <wait> <order>60</order> <description expression="true">"Wait for %d seconds to make sure SSH connection can be established" % (macro['sshWaitTime'])</description> <seconds expression="true">macro['sshWaitTime']</seconds> </wait> </steps> </step-macro>
In this example:
sshWaitTimeparameter of type integer was added. The valid types for a step macro parameter are
secondsboth refer to the
sshWaitTime. Deploy will place the value of
sshWaitTimein a dictionary with the name
secondsare marked as expressions so that they are evaluated by the Jython engine.
To refer the
wait-for-ssh-connection step, add this rule:
<rule name="ec2-wait" scope="deployed"> <conditions> <type>ec2.InstanceSpec</type> <operation>CREATE</operation> </conditions> <steps> <wait-for-ssh-connection> <sshWaitTime>25</sshWaitTime> </wait-for-ssh-connection> </steps> </rule>
The value of
sshWaitTime will be determined from the deployed. The Jython engine will evaluate the
deployed.sshWaitTime and set the
sshWaitTime parameter. Every deployed can have its own
sshWaitTime value that will be used as the wait time.
You can also use step macros in script rules. Example:
step = steps.wait_for_ssh_connection(sshWaitTime=25) context.addStep(step)