Configuring a reprovisioning operation in BMC Network Automation for network containers

This topic contains information about configuring a reprovisioning operation for network containers in BMC Network Automation.

Overview of the reprovisioning operation in BMC Network Automation

The reprovisioning operation is a Web service API method that allows you to update a network container structure to add new entities or update existing ones using a new revision of the container blueprint that was originally used during provisioning. The entities in question include all possible content in the container, for example, resources, segments, nodes, and so on. Currently, reprovisioning cannot be used to delete existing entities from a container, and attempts to do so by removing entities from the revised container blueprint are rejected.

You create a new revision of a container blueprint by exporting it from the database to an XML file (via the API), updating the XML file content (including, giving it a new revision number), and then reimporting it back into the database. This results in both the original and the new container blueprint being present in the database, each with a different revision number. The new revision can then be used to reprovision a container to propagate the updated content to it, as well as to provision new containers. A container can be reprovisioned repeatedly if desired, by using successive container blueprint revisions.

By default, new entities added during reprovisioning must be in an unused state initially (for example a resource which is not acquired, an action which is not applied, or a dynamic component which is disabled), otherwise the reprovision attempt is rejected. Togglable components such as ContainerNicNetworkSegment, ExternalNetworkSegment, Firewall, and LoadBalancer must not be added with <lockedFlag> set to true during reprovisioning because they are always added in a disabled state.

No resources are acquired or released during reprovisioning, nor are any actions executed to configure or unconfigure network devices, only the container structure in the database is changed. After reprovisioning you must execute a separate modify container operation to enable the newly added content, at which point the resource and device changes are executed. If a problem occurs while enabling the new content, the modify operation reverts the newly enabled components in question, back to a disabled state in an attempt to rollback the change. This default constraint of requiring the newly added content to be reversible (initially disabled and only enabled later) can be relaxed by passing in an argument to the reprovisoining operation to override this behavior.

The reprovision mechanism allows you to modify an existing container in ways not anticipated by the original container blueprint author, in order to scale it out beyond its originally intended capacity for instance. Reprovisioning is a delicate operation however that involves the modification of a production container which could have existing VMs attached, so it must be done carefully.

Recommendations

Test the reprovisioning process thoroughly in a sandbox system before trying it on a production system. Also, build as much scalability into the original container blueprint as possible, and simply enable existing dynamic components as you scale out, rather than relying on reprovisioning. The reprovision mechanism is intended to support unplanned scaling, not planned scaling.

The following container blueprint changes are propagated to a container during reprovisioning:

Revision Number Updated: The container blueprint and container now support a revision number attribute, which is initialized to zero. The value is propagated from the container blueprint to the container during reprovisioning. Attempts to reprovision a container which has a revision number greater than or equal to that of the container blueprint involved is rejected.
New Content Added: New entities found in the container blueprint are added to the container during reprovisioning. This is done not only for all top-level entities such as new resources, nodes, pairs, Virtual Routing and Forwarding (VRF) IDs, zones, and so on, but also for all nested entities such as new interfaces within an existing virtual firewall (VFW), new serviced segments within an existing LB pool type, and so on.
Existing Content Partially Modified: Certain existing entities are always at least partially updated during reprovisioning, regardless of the state of the entity in question. The updates are partial in the sense that only certain attributes within the entity in question are udpated. condition and description attributes are updated this way, along with the template attribute of a merge action, and the numVrfs attribute in the case of a node.
Existing Content Fully Modified: Other existing entities are fully updated during reprovisioning, but only if the entity in question is not already in use. The updates are full in the sense that virtually all of the attributes within the entity in question are updated (aside from the attribute which identifies the entity, such as its name). This is done for all entities.

The ContainerBlueprintService reprovisionContainer2 method

In BMC Network Automation, you use the ContainerBlueprintService reprovisionContainer2 method to reprovision a network container. The method takes the following inputs:

containerBlueprintName: The blueprint name additionally carries an optional revision number. For example, Large Gold Container Blueprint#1 specifies to reprovision a container with revision 1 of Large Gold Container Blueprint. If the revision number is not specified, the last revision of the blueprint is used.
containerName
restrictedFlag: This flag indicates whether non-reversible content should be added during container reprovisioning. For details, see Restricted Reprovisioning Mode.

Irrespective of the defaultEnabledFlag setting for the new components in the revised blueprint, the components are always added in a disabled state initially, and must be enabled by a subsequent modify operation.

The sequence that is executed when reprovisioning a container involves the following steps:

Update the container structure based on the additions or modifications in the new revision of the container blueprint.
If restrictedFlag is set to true, BMC Network Automation checks whether any of the content added would lead to resources being acquired/released, or config/unconfig actions being executed, by an ensuing "do-nothing" modify operation. If any such pending side-effects are detected, the reprovision operation is aborted because it violates the constraints of restricted mode reprovisioning.
If the above steps are successful, update the revision number of the container to the one specified in the blueprint.

If BMC Network Automation finds that the source network container contains a component that is missing from the network container blueprint used to perform the reprovisioning operation, BMC Network Automation issues an exception, and the operation is stopped. If an error occurs during this sequence, BMC Network Automation sends the error back to the caller.

If an error occurs during reprovisioning, the database transaction that is in progress is abandoned and no changes are made.

Reprovisioning network container blueprint changes example

The following example illustrates the changes that you would make to a network container blueprint to add a new NIC [AccessC] to sample dynamic container blueprint and reprovision the container.

Add the new revision number to the network container blueprint.
<revisionNum>1</revisionNum>
Add the new address pool blueprint schema.
<addressPoolBlueprint>
    <condition>-EXISTS- container.nicSegments[AccessC]</condition>
    <name>AccessC</name>
    <rangeBlueprintName>Data</rangeBlueprintName>
</addressPoolBlueprint>
Add the new vlan blueprint.
<vlanBlueprint>
    <condition>-EXISTS- container.nicSegments[AccessC]</condition>
    <vlanName>AccessC</vlanName>
    <vlanPoolName>Data</vlanPoolName>
</vlanBlueprint>

Add the new NIC segment blueprint.

<nicSegmentBlueprint xsi:type="containerNicNetworkSegmentBlueprint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <addressPoolName>AccessC</addressPoolName>
    <customerFlag>true</customerFlag>
    <defaultEnabledFlag>false</defaultEnabledFlag>
    <lockedFlag>false</lockedFlag>
    <managementFlag>false</managementFlag>
    <name>AccessC</name>
    <networkName>AccessC</networkName>
    <tag>Purpose[Application]</tag>
    <vlanName>AccessC</vlanName>
</nicSegmentBlueprint>

Add the new network path blueprint.
<networkPathBlueprint>
    <endpoint1Name>External</endpoint1Name>
    <endpoint2Name>AccessC</endpoint2Name>
    <name>External-AccessC</name>
</networkPathBlueprint>

Modify the edge node to specify a gateway address, and configure and unconfigure action items.

<addressBlueprint>
    <addressName>GatewayC</addressName>
    <addressPoolName>AccessC</addressPoolName>
    <condition>-EXISTS- container.nicSegments[AccessC]</condition>
    <gatewayFlag>true</gatewayFlag>
    <poolPosition></poolPosition>
</addressBlueprint>
 
<configureActionInfoBlueprint xsi:type="mergeActionInfoBlueprint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <condition>-EXISTS- container.nicSegments[AccessC]</condition>
    <name>Edge-C</name>
    <templateGroups>
        <item>SampleDynamicConfigureEdge-C</item>
    </templateGroups>
</configureActionInfoBlueprint>
 
<unconfigureActionInfoBlueprint xsi:type="mergeActionInfoBlueprint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <name>Edge-C</name>
    <templateGroups>
        <item>SampleDynamicUnconfigureEdge-C</item>
    </templateGroups>
</unconfigureActionInfoBlueprint>

Modify the hypervisor node to specify the port type, and configure and unconfigure action items for AccessC.

<configureActionInfoBlueprint xsi:type="mergeActionInfoBlueprint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <condition>-EXISTS- container.nicSegments[AccessC]</condition>
     <name>Access-C</name>
     <templateGroups>
         <item>SampleDynamicConfigureAccess-C</item>
     </templateGroups>
</configureActionInfoBlueprint>
 
<portTypeBlueprint>
     <name>AccessC</name>
     <nameWithinSwitch>$\{container.node.portTypes[AccessC].vlan}</nameWithinSwitch>
     <nicSegmentName>AccessC</nicSegmentName>
</portTypeBlueprint>
 
<unconfigureActionInfoBlueprint xsi:type="mergeActionInfoBlueprint" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <name>Access-C</name>
     <templateGroups>
         <item>SampleDynamicUnconfigureAccess-C</item>
     </templateGroups>
</unconfigureActionInfoBlueprint>

Add the template group SampleDynamicConfigureEdge-C.
interface vlan${container.vlans[AccessC]}
ip address
{container.node.addresses[GatewayC]} ${container.node.addresses[GatewayC].subnetMask.CIDR}
no shutdown
exit
Add the template group SampleDynamicUnconfigureEdge-C.
no vlan ${container.vlans[AccessC]}
no interface vlan${container.vlans[AccessC]}

Add the template group SampleDynamicConfigureAccess-C (shown for vswitch).

port-profile ${container.node.portTypes[AccessC].name}
   switchport mode access
   switchport access vlan ${container.node.portTypes[AccessC].vlan}
   vmware port-group ${container.node.portTypes[AccessC].vlan}
   no shutdown
   state enabled
   exit

Add the template group SampleDynamicUnconfigureAccess-C.
no port-profile ${container.node.portTypes[AccessC].name}

Note

The newly added NIC segment is in disabled state. The reprovision operation should be followed by a corresponding modify operation to enable the NIC segment.

Out-of-the-box sample reprovisioning container blueprint

Sample Dynamic Container Blueprint is a sample container blueprint that is shipped with BMC Cloud Lifecycle Management. There are two revisions of this blueprint, revision 0 and revision 1. Revision 1 adds a new NIC segment to the content, along with supporting resources and actions, all of which are initially unused. In addition, it includes actions for configuring and unconfiguring the switches as needed as and when the NIC segment is toggled. You can use the Diff icon in the container blueprint list page to examine the differences between the two revisions. After reprovisioning a container by using revision 1, you would need to execute a modify container operation to enable the new NIC segment.

Restricted Reprovisioning Mode

By default only reversible content can be added during reprovisioning; meaning content that is initially unused, and which is later enabled in a separate modify operation that can be disabled again if the modify attempt fails. However, there might be times when you want to add non-reversible content during reprovisioning as shown in the following examples:

Reprovisioning a container to add a new address pool link to an existing chain of public NAT address pools, where the new pool gets used as soon as the container is modified next, even if nothing new is enabled in the modify operation.
Reprovisioning a container to add new infrastructure to the container, which is not tied to a new dynamic component that can be enabled later.

This default constraint can be relaxed by using one of the following methods:

Passing a value of false for the restrictedFlag argument in the reprovisioning API call, which BMC Cloud Lifecycle Management passes in as true by default.
Setting the value of the restrictedReprovisioningMode property to false in the global.properties file, which BMC Network Automation sets to true by default.(See Default global.properties file in the BMC Network Automation documentation.)

If the false value is passed or set, non-reversible content can be added during reprovisioning, and the next time the container is modified, even if it is a do-nothing modify operation that does not change any toggle states of existing dynamic components, resource and network device changes are executed as needed. If anything goes wrong during the modify step however, it is not automatically rolled back and you have to recover by fixing the underlying error (for example, fixing an error in an action that is failing) and retrying the modify operation.