Chapter 4 Unrestrictive Host Locking

This release of the N1 Service Provisioning System provides new functionality in the area of host locking. In previous releases, the N1 Service Provisioning System locked a host while executing steps on that host. To prevent plans interfering with each other, no other plans or subplans could be executed against a host while the host was locked by a plan. Now, you can elect to use less restrictive host locking.

The implicitLocking Attribute

The <simpleSteps> element has been modified to accept a new attribute, called implicitLocking. Attributes for the <simpleSteps> element are now as follows:

executionMode

An optional attribute already part of the N1 Service Provisioning System, that indicates whether the contained steps should be executed in a series or in parallel over the target hosts. The legal values are PARALLEL and SERIES. If the executionMode attribute is omitted, the value is PARALLEL.

limitToHostSet

An optional attribute already part of the N1 Service Provisioning System, that specifies the name of the host set that contains the hosts that can be valid targets for this plan. If this attribute is omitted, all hosts can be valid targets. Otherwise, the targets that you specify must be a subset of the hosts that are contained in the named host set.

If the targets include a host that is not contained in the named host set, the plan issues a runtime error. If you specify a name that does not correspond to an existing supported host set, the plan also issues a runtime error. If the specified host set is defined by a plug-in, the pluginName must be prefixed to the host set name, such as pluginName#hostSetName. These plan runtime errors are reported during validation before the preflight starts.

implicitLocking

A new attribute for the release of N1 Service Provisioning System. The implicitLocking attribute indicates what type of host locking to use for the contained steps. If the implicitLocking attribute is omitted, the value is set to TRUE, so no other plans or subplans can be executed against that host until the steps enclosed in the <simpleSteps> element have completed. If a plan is retargeted to another host, this retargeted host is also locked until the completion of the retargeted step.

If the implicitLocking attribute is set to false, the browser interface displays the following new message for a retarget step:

connect and check hosts

If the implicitLocking attribute is set to FALSE, no hosts are locked by a plan during the completion of the <simpleSteps> element, including retargeted hosts, unless a lockHost step is used.

The lockHost Step

The lockHost step indicates that the target host should be locked for the duration of the step. The lockHost step can be a child of the following steps:

• The <call> step

• The <retarget> step

• The <install> step

• The <uninstall> step

• The <catch> step

• The <finally> step

• The <then> step

• The <else> step

• The <block> step of the <try> step

The lockHost step has one child element. See Attributes and Child Elements of the lockHost Step for more information on the child element of the lockHost step.

If the lockHost steps contain a retargeted step, the host to which the step is retargeted is also locked. Execution is suspended until the required lock is obtained. The lock is released at the conclusion of the lockHost step regardless of whether the steps succeed or fail.

If the lockHost steps do not contain a retargeted step, the inner lockHost steps would lock the host on which the step is executed. A nested lockHost step does not block waiting for a parent lockHost step issued as part of the same plan.

Attributes and Child Elements of the lockHost Step

The lockHost step has the following optional attribute:

It is not possible to lock a physical host and all its virtual hosts with a single lockHost step.

The lockHost step is used to lock a target host for the duration of a step when the implicitLocking attribute of the <simpleSteps> element is set to FALSE. The lockHost step can also be used when the implicitLocking attribute of the <simpleSteps> element is set to TRUE.

If a plan is executed on a virtual host and the implicitLocking attribute of the <simpleSteps> element is set to TRUE, the virtual host is locked. If the plan includes a lockHost step with the lockingMode attribute set to PHYSICAL, the physical host is also locked, but the virtual host is not unlocked. The virtual host is not unlocked because implicitLocking attribute of the <simpleSteps> element is still set to TRUE.

The host locking in this case is the union of both the implicitLocking attribute of the <simpleSteps> element and the lockHost step.

<steps> Element

The lockHost step has one child element: steps. The steps element can contain zero or more steps, and indicates which steps to execute while the host is locked. Any shared step or simple plan step is permitted.

The lockHost step and its child steps are visible in the Plan Run History section of the browser user interface.

Elements Modified By Introduction of the lockHost Step

With the introduction of the lockHost step, several elements described in the Sun N1 Service Provisioning System 5.2 XML Schema Reference Guide gain a new attribute: the requireLocking attribute. The requireLocking attribute is designed to safeguard a component against use in an unlocked environment.

Examples of the lockHost Step

Example 4–1 Nested lockHost Steps

It is possible to specify nested lockHost steps. You can also specify a lockingMode attribute for each nested lockHost step:

1st group of steps
    <lockHost lockingMode="PHYSICAL">
      2nd nested group of steps
      <lockHost lockingMode="VIRTUAL">
        3rd nested group of steps
      </lockHost>
      4th nested group of steps
    </lockHost>
    5th nested group of steps

In the above example, no hosts are locked for the 1st group of steps, since there are no locks: the lockHost step has not been used.

Only the physical host is locked for 2nd group of steps, because the lockHost step has been used with the lockingMode attribute set to PHYSICAL.

Both the physical and the virtual host are locked for the 3rd group of steps, because a lockHost step has been used with the lockingMode attribute set to VIRTUAL and the physical lock has not yet been closed.

Only the physical host is locked for 4th group of steps, because the virtual lock has been closed. No hosts are locked for the 5th group of steps, because the physical lock has now been closed.

Example 4–2 Simple Usage of the lockHost Step

Here is a simple example of the lockHost step:

  <simpleSteps implicitLocking="false">
    <pause delaySecs="1"/>
    <lockHost>
      <pause delaySecs="1"/>
    </lockHost>
  </simpleSteps>

Note that implicitLocking is set to false. To lock the host in the above simple example, the lockHost step would therefore be required. Since the lockingMode attribute is omitted, both the physical host and any virtual host are locked, if the plan is executed on a virtual host. If the plan is executed on a physical host, the physical host only would be locked as there is no virtual host to lock.

Example 4–3 The lockHost Step with a Retargeted Step

Here is a more complex example of the lockHost step including a retargeted step:

  <simpleSteps implicitLocking="false">
    <pause delaySecs="1"/>
    <lockHost lockingMode="VIRTUAL">
      <pause delaySecs="1"/>
      <retarget host="newhost">
        <pause delaySecs="2"/>
      </retarget>
    </lockHost>
   <pause delaySecs="3"/>
  </simpleSteps>

In this example:

• implicitLocking is set to false, so if the plan is executed on host1, neither newhost nor host1 are locked initially.

• When the lockHost step is executed, host1 is locked. The first pause step is executed before host1 is locked.

• If host1 is already locked, the plan does not act on host1 until host1 becomes available.

• newhost is locked when the retarget step is executed. The lock on host1 is not released, so both hosts are now locked. If locking newhost would result in a deadlock, then an error is thrown. Depending in the configuration, the error message is either Deadlock detected when initial host X tried locking host Y. That lock is already held by host Z or Locking the host results in a deadlock

• The lock on newhost is released on completion of the retarget step.

• The lock on host1 is released on completion of the lockHost step.

• The 1 second and 3 second pause steps are executed on an unlocked host; the 2 second pause step is executed on a locked host.

• The lockingMode is set to VIRTUAL, so only the virtual host to which the retarget step is aimed is locked.

Contrast the above example with this:

 <simpleSteps implicitLocking="false">
    <pause delaySecs="1"/>
      <pause delaySecs="1"/>
      <retarget host="newhost">
        <lockHost>
          <pause delaySecs="2"/>
        </lockHost>
      </retarget>
    <pause delaySecs="3"/>
  </simpleSteps>

Here, only newhost is locked, and only on the execution of the lockHost step inside the retarget step. The retargeted host is not locked when the retarget step is executed. Only the 2 second pause step is executed on a locked host.

Example 4–4 The Interaction of the requireLocking Attribute and the lockHost Step

For clarity, several mandatory component attributes are omitted from this example.

  <component name="comp1"...>
   <installList>
      <installSteps name="installA">
        <pause delaySecs="1">
      </installSteps>
    </installList>
  </component>

The installA installSteps element does not specify the requireLocking attribute. The requireLocking attribute is therefore set to true, by default. Executing the following plan would therefore cause a preflight error:

    <simpleSteps implicitLocking="false">
      <install blockName="installA">
        <component path="/" name="comp1"/>
      </install>
    </simpleSteps>

The plan indicates that locking should be disabled by specifying the implicitLocking attribute with a value of false. The plan attempts to operate on a component using a block that requires locking without locking the host. The install block executed by the plan does not specify the lockingMode attribute, which means that the block requires the host to be locked upon execution. The plan could be changed to explicitly lock the host before installing the component:

   <simpleSteps implicitLocking="false">
     <lockHost>
       <install blockName="installA">
         <component path="/" name="comp1"/>
       </install>
     </lockHost>
   </simpleSteps>

Here is an simplified sample of a component that does not always require the host to be locked:

  <component name="comp2"...>
    <installList>
      <installSteps name="installA" requireLocking="false">
        <pause delaySecs="1">
     </installSteps>
      <uninstallSteps name="uninstallB" requireLocking="true">
        <pause delaySecs="1">
      </uninstallSteps>
      <control name="controlC">
        <pause delaySecs="1">
      </control>
    </installList>
  </component>

In the above simplified sample:

• The install block, installA, does not require the host to be locked

• uninstallB and controlC both require the host to be locked. uninstallB states the explicit requirement while controlC does not, but the default value if unspecified is true.

The following plan is provides an example of legal operation with this component:

  <simpleSteps implicitLocking="false">
    <install blockName="installA">
      <component path="/" name="comp1"/>
    </install>
    <lockHost>
      <call blockName="controlC">
        <installedComponent path="/" name="comp1" =installPath="/tmp"/>
      </call>
      <uninstall blockName="uninstallB">
        <installedComponent name="comp1"/>
      </uninstall>
    </lockHost>
  </simpleSteps>

A component block that does not require the host to be locked can be called while the host is locked; the install step above could legally be moved inside the lockHost step. Neither the uninstall nor the call, however, could be moved outside the lockHost step.