Managing WebSphere DataPower Device configurations for high availability, consistency, and control, Part 2: Application promotion strategies

This article shows you how to manage WebSphere DataPower SOA Appliance configurations for high availability, consistency, and control in a multi-device environment, including configuration methods and examples using the command-line interface, Web GUI, or XML Management Interface.

Share:

John Rasmussen (rasmussj@us.ibm.com), Senior I/T Specialist, IBM Software Services for WebSphere, IBM

John Rasmussen is a Senior IT Specialist, WebSphere DataPower and SOA, with IBM in Cambridge, MA. You can contact John at rasmussj@us.ibm.com.



Jim Brennan (jim.brennan@us.ibm.com), I/T Specialist, IBM Software Services for WebSphere, IBM

Jim Brennan is an I/T Specialist with IBM Software Services for WebSphere. He has had an extensive career in software development and middleware, including Java EE development and WebSphere Application Server configuration. He currently specializes in WebSphere DataPower SOA Appliance administration and configuration. You can contact Jim at jim.brennan@us.ibm.com.



Tamika Moody (tamikam@us.ibm.com), I/T Specialist, IBM Software Services for WebSphere, IBM

Tamika Moody is an I/T Specialist with IBM Software Services for WebSphere. She has broad experience in IBM middleware ranging from Electronic Data Interchange (EDI) to Business-to-Business (B2B) implementations. Her current focus is on emerging WebSphere technologies and WebSphere DataPower SOA Appliances. You can contact Tamika at tamikam@us.ibm.com.



01 April 2009

Introduction

This article describes migration strategies and the and promotion of IBM® WebSphere® DataPower SOA Appliance (DataPower) configurations from development through production. The article includes example configurations, migration methodologies, and automated promotion techniques.

Part 1 of this two-part series described DataPower configuration management, and is an addendum to Chapter 15, "Build and Deploy Techniques," in the WebSphere DataPower SOA Appliance Handbook from IBM Press. For further information on DataPower and the concepts described in this article, see the Resources section at the bottom of the article. Also at the bottom of the article, you can download scripts for DataPower configuration and for ANT (Another Neat Tool) migration and builds.

Introduction

DataPower devices are used for the implementation of advanced security, mediation, and integration patterns. DataPower capabilities are extensive, and are implemented via the configuration of the services and objects available via the device's management interfaces. Changes to these configurations must be done in a controlled manner to ensure quality of service in the production environment. The migration of these changes from early development through testing and eventually to production is known as the Software Development Life Cycle (SDLC).

Part 1 described many issues related to the management of configuration content and how to avoid associating configurations within particular SDLC environments. For example, the use of Host Alias objects, Static Host DNS entries, and the use of XML documents to externalize static XSLT information were presented as simple strategies to avoid creating environment affinities within configurations. These affinities often cause problems when configurations are migrated. A service may be exposed on a particular TCP port in development, but when the service is unit tested or installed in production another port may be used.

Through the presentation of three simple services, this article describes the migration of configurations through the SDLC as well as common problems and tools that you can use to mediate them. Deployment policies (introduced in DataPower firmware revision 3.6), will be shown as a powerful method of configuration property modification during migration. The article also describes strategies for dealing with keys and certificates, and XML and XSLT documents. Through the use of ANT scripts, the article shows how migration life cycles may be integrated into an automated process.

Sample configuration

The sample configuration consists of three XML firewall service objects. BookServiceRouter accepts requests for book inquiries and purchases over HTTPS, then routes those requests to either BookService1 or BookService2 depending on the contents of the incoming URL. BookService1 has higher priority and purchase requests are routed to it, while lower priority requests are routed to BookService2.

Figure 1 shows the architecture. In a typical topology, the book services would be on another device or destination, but here they are also hosted on a single device for simplicity:

Figure 1. Sample application
Figure 1

Routing determination is based on a document (identityDocument.xml) that contains the IP address and port of the service to forward requests to. It is included in a stylesheet (local:///BookServiceRouter.xsl), which is identified on a Route action within the BookServiceRouter firewall policy. This simple technique externalizes static, possibly environment-specific information from the XSLT. As identityDocument.xml may be maintained separate from the XSLT, it allows an environment-neutral configuration. You can read more about this technique in Part 1.

The identityDocument.xml document and the addresses and ports within are unique to each environment. There is one identityDocument.xml for development that uses the ports on which the XML firewall services in development are listening. There is one identityDocument.xml in Test that identifies the addresses and ports used in the testing environment, and so on. This technique provides an environment-neutral routing mechanism.

However, the services themselves must be defined with addresses and ports specific to each environment. The BookServiceRouter XML firewall in Development will listen for requests on port 3100, but the BookServiceRouter Firewall in Testing must use a different port. You ill see how to manage issues such as these using deployment policies.

This configuration is hosted within a DataPower application domain named BookService. Part 1 described how application domains may store their configuration within the device file system, or alternatively they may be defined to fetch their configuration from an off-device location such as a Software Configuration Management (SCM) system. This article will describe both instances.

The ability of an application domain to fetch its configuration enables a fault-tolerant design in which a domain will automatically refresh its configuration in the event of a controlled or uncontrolled restart. This technique provides the basis for the eventual production environment configuration and it is used in acceptance as well. Modifying the domain configuration stored in the SCM and restarting the domain provides a way to upgrade the domain's configuration.

Deployment policies

Deployment policies are used to control the acceptance and rejection of configuration objects onto the DataPower device, and to facilitate the modification of object parameters during importation. The different ports used on the XML firewalls in Development and Testing are examples of these properties, and the article will show how to manipulate them. Deployment polices may be used with all of the primary configuration import processes, such as remote application domain configuration definition and import features of the WebGUI, CLI, and XML Management Interfaces.

The deployment policy defines object filtering and modification through the definition of fine-grained configuration matching statements which may be based on the source device, domain, object type, and name, and even the value of properties within each object. Policies may be defined, for example, to allow only XML firewalls named BookServiceRouter, BookService1, or BookService2 into a configuration, and to modify the port properties of each of the XML firewalls to specified values. In summary, deployment policies provide for the ability to:

  • Limit objects that can be imported (white lists)
  • Prevent groups or named objects from being imported (black lists)
  • Modify properties of objects (mod lists)

As discussed in the sample, the XML firewalls require port modification as they are migrated into each SDLC environment. The next section describes the configuration to perform this mediation.

Sample deployment policy

The deployment policy GUI screen has two tabs that you can use to build configuration matching statements: Main and Modified Configuration. Figure 2 below is an example of the Main tab of the sample policy. You can use statements defined in the Accepted Configuration to restrict which objects are allowed into an environment by providing a white list capability. Filtered configuration statements can be used to restrict objects by providing a black list capability. In this example, the Accepted and Filtered configurations are left blank, allowing all objects within the processed configuration to be imported.

Figure 2. Accepted and filtered configuration match statements
Figure 2

As the stated goal is the modification of ports for the three sample services, you need to construct a Modification Configuration Match to assign the proper port to each Firewall Service. This requires three Configuration Match expressions and the assignment of the replacement value. Figure 3 shows the three required Modified Configuration statements with the assigned replacement values:

Figure 3. Configuration match statements with new configuration values
Figure 3

Editing one of the Configuration Match statements, as shown in Figure 4 below, assigns the configuration match expression, modification type, and value. In this example the configuration value is being changed, though insertion and deletion is also allowed:

Figure 4. Configuration match edit screen with Build button
Figure 4

Figure 4 also shows the Build button provided for the creation of the configuration match statement. The Build button provides a simplified method for match statement construction. Figure 5 below shows the matching of the XML firewall service named BookServiceRouter (via a PCRE expression), which contains a LocalPort property of any value. For information on determining property names, see Part 1 of this series or Chapter 15, "Build and Deploy Techniques," in the WebSphere DataPower SOA Appliance Handbook.

Figure 5. Configuration match expressions
Figure 5

After the deployment policy has been configured, the next step is to apply it to the import package. Figure 6 shows an example of how the deployment policy is used during the Import function in the WebGUI:

Figure 6. Apply deployment policy to import package
Figure 6

The execution of this Import Configuration action will be the instantiation of the three firewalls with modified port property values. Deployment policies are supported with other configuration import methods, such as the command-line interface (CLI) and XML Management Interface Import-Package command and the definition of external configurations for Application Domain definition. The scripts will show examples of both of these techniques.

In summary, deployment policies afford a robust methodology for the automated modification of configuration properties. They are supported by a wide variety of DataPower configuration management methods, and they provide a system-wide resource for the management of configuration variances within the SDLC.

Software development life cycle promotion

Changes will be made to DataPower configurations over time. New services will be added to application domains and others will be enhanced or removed. Sometimes an object used by multiple services such as a stylesheet policy will be modified. As these changes become available, you must merge them with the existing services and verify then through extensive testing. Eventually, they will become part of the production environment. While every organization defines the migration process based on their requirements, this article presents a methodology that uses a scripted approach to application promotion. This methodology employs a "manifest" document to describe the details of changes that have been approved for migration. It leverages the DataPower XML Management Interface for an automated and scripted approach to migration. By doing so, it provides definitive, authorized, documented control over configuration contents and facilitates a resilient production environment.

Figure 7 below shows this SDLC promotion strategy. You can see how the manifest document and deployment polices are used across the environments for the migration of objects and files (keys), and the modification of object properties on import. The deployment policies within the samples are hard-coded, but a more robust solution may use alternatives such as storing deployment polices in repositories such as WebSphere Service Registry and Repository. This configuration would allow the consumption and instantiation of the latest and greatest policies during the migration process. The following sections describe how approved objects are exported into the SCM system and merged with existing configuration objects.

Figure 7. Application lifecycles
Figure 7

Migration from development

Developers make changes within the sandbox of the development environment, and you must ensure that only tested and approved objects are exported into the SDLC process. Therefore individual services and objects are exported from development rather then exporting the entire application domain. Exporting the entire domain could result in the migration of unassociated (orphaned) and potentially disruptive objects. You can manually select objects to be exported from development, but in the example (shown in Figure 8 below), the manifest of approved services, objects, and files has been created. It is leveraged by ANT scripting tools and the DataPower XML Management Interface to identify and export approved changes to the SCM.

Various commands will be executed via the XML Management Interface. For example, export configurations (Do-Export), import configurations (Do-Import), create files (Set-File), save configurations (SaveConfig), and delete configurations (del-config). You can read more about the XML Management Interface in the DataPower product documentation, and in the IBM Redpaper: WebSphere DataPower SOA Appliances: The XML Management Interface.

Figure 8. Development change migration
Figure 8

Listing 1 demonstrates the development manifest document. In this example, the BookService1 XML firewall object is designated for export as are its required objects and files (indicated via the ref-objects and ref-files attributes.) The contents of the export will be stored in the SCM in a file named DevelopmentMigration.b64. It is actually an XML document containing the base64 encoded export in ZIP format. Keys material may be loaded from either the SCM or from Key Stores. The article will describe these use cases later when automated deployment scripting is discussed.

Listing 1. Development manifest
<?xml version="1.0" encoding="UTF-8"?>
<Manifest>
  <!-- -->
  <!-- Development Manifest  -->
  <!-- -->
  <!-- This Manifest contains a list of Service Objects and Files -->
  <!-- which have been approved for migration. -->
  <!-- These Objects and Files will overlay named equivalents  -->
  <!-- in the Testing Environment  -->
  <!-- -->
  <MigrateServiceObjects all-files="false" 
    zipFile="https://192.168.1.50:8888/DevelopmentMigration/DevelopmentMigration.zip">
  <MigrateServiceObject class="XMLFirewallService" 
      name="BookService1" ref-objects="true" ref-files="true"/>
  </MigrateServiceObjects>
  <!-- -->
  <!-- These objects will be removed from the configuration -->
  <!-- -->
  <RemoveServiceObjects>
      <RemoveServiceObject class="XMLFirewallService" name="BookServiceDeleteMe"/>
  </RemoveServiceObjects>
  <!-- -->
  <MigrateFileSystemObjects>
    <!-- -->
    <!-- Note that artifacts in certificate directories -->
    <!-- are not available for copy off the device -->
    <!-- Any Keys and/or Certs must be positioned in temporary for copy -->
    <!-- -->
    <MigrateFileSystemObject name="temporary:///BookServiceRouter-privkey.pem" 
      location="https:// 
        192.168.1.51:8888/DevelopmentMigration/BookServiceRouter-privkey.pem"/>
    <MigrateFileSystemObject name="temporary:///BookServiceRouter-sscert.pem" 
      location="https:// 
        192.168.1.51:8888/DevelopmentMigration/BookServiceRouter-sscert.pem"/>
    <!-- -->
  </MigrateFileSystemObjects>
  <!-- -->
  <!-- These files will be removed from the configuration -->
  <!-- -->
  <RemoveFileSystemObjects>
    <RemoveFileSystemObject name="temporary:///DeleteMe.xml"/>
  </RemoveFileSystemObjects>
  <!-- -->
</Manifest>

Reconstruction of the testing environment

Now that approved objects have been migrated to the SCM, they require rigorous testing. While the developer will have done unit testing, the testing environment must perform system-wide verification to ensure that new configuration changes do not affect other aspects of the application. This testing requires that the latest versions of all services, objects, and other artifacts are fetched from SCM systems or key stores.

The first phase in reconstructing the testing environment is to re-import the last approved or "known good" application domain export, which can be extracted from the SCM where it was placed during the previous round of SDLC testing. The development manifest is read to determine changes that will be imported or removed. They will overwrite any liked named objects that existed in the previous known good configuration, and new objects may be added as well. New files, including key material, can also be identified in the development manifest and will be loaded from the SCM or key store onto the testing environment. There may also be objects and files identified for deletion.

Figure 9 shows the process flow and also shows how the deployment policy is used to fine-tune object properties (ports in our example) during the configuration import process. After testing, the reconstructed domain is moved to the SCM.

Figure 9. Reconstructing the testing environment
Figure 9

Acceptance

The acceptance environment is the final phase before production and it represents not only a last best opportunity for configuration verification, but equally important, a certification of the mechanism for production migration. The construction of the acceptance and production environments is similar. Individual services were migrated from development in order to avoid migrating extraneous (orphaned) objects that were not associated with the services themselves. The acceptance and production environments will fetch their domain configurations in their entirety from the SCM. Individual files and keys that were not part of the domain export may also be uploaded from the SCM or key store and are identified via the development manifest.

Figure 10 shows the acceptance environment build process. Once again, a deployment policy is used to modify the port values used on the XML firewall services on import of the domain configuration:

Figure 10. Acceptance environment refresh
Figure 10

Production

Now that all testing has been completed, it's time to migrate the domain configuration to the production environment. As was the case with acceptance, the production environment uses the fetch domain configuration of the application domain object so that the domain will obtain (fetch) its configuration from the SCM when the device is restarted (controlled or not), or when a domain is restarted.

The application domain that was originally installed in the SCM from the testing environment is now moved to the production SCM library. The production and testing SCM libraries may be the same physical repository with separate domains for testing and production. Use the XML Management Interface to determine if any files or keys are required to be uploaded to the production domain (as designated within the development manifest), then restart the domain. The new domain configuration is fetched from the production SCM.

Figure 11 shows the production refresh process. As was the case with acceptance, a deployment policy is used to modify the port values used on the XML firewall services on import of the domain configuration.

Figure 11. Production environment refresh
Figure 11

Production devices should be individually taken out of service, upgraded, and then individually tested to ensure viability of the configuration refresh process before releasing them to the production device farm. Often echo services are created on the device to validate connectivity of interfaces and back-end resources. Additional devices can then be processed. This process may be further automated using configuration management tools such as IBM Tivoli Composite Application Manager System Edition (ITCAM SE) for WebSphere DataPower, which facilities the migration of device configuration across multiple devices.

Automated life cycle promotion

Now that the process for migrating from one environment to another has been described, how can this process be automated? This article series has described various ways to migrate configurations. While the WebGUI was the usual method, it requires manual intervention. What is typically required in most software migration processes is a more automated, repeatable, and managed process. Most organizations already have some kind of automated application promotion, typically involving scripts. For example, in a Java EE environment applications are often promoted to different SDLC environments via ANT scripts. The downloadable example scripts were written using ANT along with other open-source projects as described below.

Setting up your scripting environment

In order to run the downloadable example scripts, you will need to install ANT from Apache.org. Additional tools will be required to carry out tasks that are not natively available in ANT tasks. The following utilities must be accessible to the scripts for them to function properly:

Sending HTTPS requests

One primary function of the deployment scripts is to send SOAP requests over HTTPS to the DataPower XML Management Interface for importing and exporting configurations and copying files to the device. Since ANT does not provide a way to do this, you will need some other utility, such as the cURL utility. Copy curl.exe and the supporting libraries to a path accessible to the ANT scripts.

Base-64 encoding files

An important part of the deployment process is to copy individual files from the SCM or other server to the DataPower file system. Before copying files, they must be base64 encoded. One free and simple tool that can be installed and called from an ANT script is OpenSSL. This tool or a similar must be accessible to the ANT scripts.

Integrating with Source Control Manager (SCM)

The deployment process will integrate with the SCM system to check in the DataPower services and also get the latest version of the services to be deployed. You can use many different SCM repositories to store the configurations, each of which will require its own method for integrating with the scripts. While many installations use mission critical SCMs such as IBM Rational ClearCase, the open-source project CVS is used within our ANT scripts. Our goal is to demonstrate techniques rather than SCM procedure. ANT has specific tasks that can hook into the CVS application. To do this, copy cvs.exe file to the script location or add it to the server's path. We chose to copy this executable in the script folder itself. If you do not have CVS installed, you need to obtain an installation in order to execute the attached scripts.

Folder structure

The downloadable example scripts consist of several folders as shown in Figure 12 below. Three folders are under the top-level folder DataPowerDeploy as well as three scripts. The folders are:

  • Bin -– Contains the main scripts for the export and deployment process and the cvs.exe file
  • XML -– Contains the XML documents used in the export and deployment process, including the manifest document that must be altered to define the services and files to be deployed to the different environments
  • XSL -– Contains the XSLT stylesheets used in the scripting process for functions such as creating the XML Management SOAP request documents for exporting services and extracting the service exports from the response
Figure 12. Deployment script folder structure
Figure 12

DataPower XML Management Interface

All interaction with the DataPower device is done by sending SOAP requests to the device's XML Management Interface, which allows authenticated device configuration and administration via SOAP requests over HTTPS. This includes exporting and importing configurations and files during the migration process. You must enable this interface on all DataPower devices in all environments, which you can do using WebGUI by logging into the default domain and navigating to the XML Management Interface from the left navigation menu. The XML Management Interface must be enabled with the SOAP Configuration Management and AMP Endpoint services checked as shown in Figure 13:

Figure 13. Enabling the XML Management Interface
Figure 13

Exporting your services from the development environment

The purpose of this script is to export all services listed in the development manifest (dev_manifest.xml), shown in Listing 1 above, and store the exported configuration in the SCM system. This configuration will then be used later on in the SDLC process when these services are deployed to the testing environment in the process.

Executing the script

Within the top-level folder there is a file named exportDevServices.xml, which is an XML document is used as the driver script for exporting the services listed in the development manifest in the project. The purpose of this driver ANT script is to set environment-specific variables and then call the main script getServices_ANT.xml in the bin folder, which hides the underlying details and makes it easier to set the variables for your environment in order to create and submit the XML Management requests. Before executing the main driver script, update the development manifest within the xml folder. In addition to updating this XML file, you must update the parameters listed within the driver script:

  • domain –- Name of the development domain that the services will be exported from. In our example the domain name is BookService.
  • xmlmgmt_url –- URL of the XML Management Interface on the device that contains the development domain. The XML Management Interface must be enabled for this process to function.
  • DP_uid -– User name that will be used to submit the SOAP requests to the XML Management Interface.
  • DP_pw –- Corresponding password that will accompany the user id provided for the XML Management Interface.
  • CVS_root -– CVS root that will be used to access the CVS repository. If the repository is password protected (as it should be), the user id and password would be included in this root.
  • CVS_package -– Name of the CVS package that will contain the DataPower service and domain exports.
  • cURL_exec –- Location of curl.exe.

Now that all of the parameters have been set, you can execute the exportDevServices.xml ANT script. At a high level, this script will perform the following functions:

  1. Using development manifest as input to an XSLT stylesheet in the xsl folder, build the SOAP request that will be sent to the DataPower XML Management Interface for exporting the required services via the Do-Export command. Listing 2 shows an example of this request:
    Listing 2. do-export XML Management Interface Request
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
        <dp:request
          xmlns:dp="http://www.datapower.com/schemas/management"
          domain="BookService">
          <dp:do-export>
            <dp:object class="XMLFirewallService"
              name="BookService1" ref-objects="true" ref-files="true" />
            <dp:object class="XMLFirewallService"
              name="BookService2" ref-objects="true" ref-files="true" />
            <dp:object class="XMLFirewallService"
              name="BookServiceRouter" ref-objects="true" ref-files="true" />
          </dp:do-export>
        </dp:request>
      </soapenv:Body>
    </soapenv:Envelope>
  2. Send the SOAP request created in Step 1 to the DataPower device.
  3. Extract the base64 encoded export from the response from the SOAP request.
  4. Store the extracted export in the CVS SCM repository within the package specified in the input parameters.

Promoting from development to testing

Once the desired services are exported from the development environment and stored in the SCM repository, they can be imported into the testing environment. This process involves several XML Management SOAP requests being built and sent to the testing DataPower device to recreate the BookService domain.

Executing the script

The script provided to demonstrate this is in a file named testingDeploy.xml. Much like the driver script for the development export, this driver script is used to pass parameters to the main script for deploying the services and files to the testing environment. Many of the required parameters are the same as the previous script with one addition. A parameter named openSSL_exec provides the location of the openSSL installation used to base64-encode files to be imported into the testing domain.

In addition to these parameters, ensure that the development manifest (dev_manifest.xml) lists the files that must be copied to the new testing environment. These files will most likely be key and certificate files as they are not exported from the development environment. In this example ,these files must reside in the CVS repository, but it is strongly recommended that these files be stored in a secure key store that can be accessed by the script. Once all of the parameters are set, this script can be executed and will perform the following tasks:

  1. Delete the existing BookService domain on the testing DataPower device, by sending a SOAP request to the XML Management interface as shown in Listing 3:
    Listing 3. del-config request
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
        <dp:request
          xmlns:dp="http://www.datapower.com/schemas/management"
          domain="default">
          <dp:del-config>
            <Domain name="BookService"/>
          </dp:del-config>
        </dp:request>
      </soapenv:Body>
    </soapenv:Envelope>
  2. Import the "last known good" configuration domain export from the CVS repository, by getting the last backup of the domain in the testing environment and sending it within a SOAP request to the XML Management Interface. If this is the first deployment to the testing device, you must add a domain export to the SCM to "prime the pump." This can be an empty domain export. The base64-encoded domain export retrieved from the SCM is included in the SOAP body of the request within the input-file element. A sample request is shown in Listing 4:
    Listing 4. Import domain request
    <?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
      <env:Body>
        <dp:request xmlns:dp="http://www.datapower.com/schemas/management">
          <dp:do-import source-type="ZIP">
            <dp:input-file>UEsDBAoAAAAAA.....</dp-input-file>
          </dp:do-import>
        </dp:request>
      </env:Body>
    </env:Envelope>
  3. Export the deployment policy for the testing environment from the default domain, by sending a SOAP request to the XML Management Interface similar to the request shown in Listing 2 above.
  4. Import the deployment policy that was exported in the previous step into the testing environment BookService domain. Again, a SOAP request is built and sent to the XML Management interface to import the deployment policy. This request is similar to the request shown in Listing 4 above.
  5. Copy all files listed in the development manifest into the local file system in the testing BookService domain. This step will dynamically build an ANT script via XSLT that will base64-encode the files to be imported and then build the SOAP request to be sent to the XML Management interface that will contain the base64 encoded file. A sample of this SOAP request is shown in Listing 5:
    Listing 5. XML management request to copy a file
    <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
        <dp:request
          xmlns:dp="http://www.datapower.com/schemas/management"
          domain="BookService">
          <dp:set-file name="cert:///BookServiceRouter-privkey.pem">
            LS0tLS1CR......</dp:set-file>
        </dp:request>
      </soapenv:Body>
    </soapenv:Envelope>
  6. Import the services that were exported from the development BookService domain. This will be one base64-encoded file that was stored in CVS when the services were exported using the first script discussed -- exportDevServices.xml. This file is included in a SOAP request similar to the request shown in Listing 4 and sent to the XML Management Interface. In this request, however, it specifies the deployment policy to apply when importing the domain -- the deployment policy that was copied from the default domain in step 3. Listing 6 shows an example of this request document:
    listing 6. XML management request to save a domain configuration
    <?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
      <env:Body>
        <dp:request domain="BookService 
            xmlns:dp="http://www.datapower.com/schemas/management">
          <dp:do-import source-type="ZIP" 
              overwrite-objects="true" deployment-policy="BookService Testing">
            <dp:input-file>AS0tPS1CF...... </dp:input-file>   
          </dp:do-import>
        </dp:request>
      </env:Body>
    </env:Envelope>
  7. Delete any services specified in the development manifest document from the testing BookService domain via a SOAP request similar to the request document shown in Listing 3 above.
  8. Save the testing BookService domain configuration by sending a SOAP request to the XML Management Interface such as the one shown in Listing 7 below. This request uses the do-action operation and specifies SaveConfig as the action:
    Listing 7. XML management request to save a domain configuration
    <?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
      <env:Body>
        <dp:request domain="BookService"
          xmlns:dp="http://www.datapower.com/schemas/management">
          <dp:do-action>
             <SaveConfig/>
          </dp:do-action>
        </dp:request>
      </env:Body>
    </env:Envelope>

Upon completion of this script, the services that were exported from the development environment will now reside in the testing environment. The deployment policy will have modified the XML firewall ports, and any services or objects marked as such will be deleted.

Log in to the testing BookService domain to confirm that all of the expected services exist and have a status of "up."

Promoting to acceptance and production

Once the desired services are deployed to the testing environment and have been fully tested, they can now be migrated to the acceptance environment and then to production. Unlike the migration from development to testing, the deployment of services to the acceptance and production environments is at the domain level, to ensure that all services (and their supporting objects) within the domain are migrated as one cohesive unit just as they were tested.

When migrating to the acceptance and production environments, the domain is not imported into the DataPower device. The domain is configured to fetch the configuration from a remote location, which could be your SCM repository or some other server. This configuration is fetched by the DataPower device every time the domain (or device) is restarted. What this means is that the scripts have to simply restart the domain and the new domain in the SCM will be extracted. The deployment policy specified in the domain configuration once again modifies configuration as required.

Executing the script

The driver script for the acceptance environment deployment is the acptDeploy.xml file. The same parameters must be updated in this file as in the testing deployment driver script. Again, you must update the manifest document for this deployment, but the manifest document is specific to the acceptance environment as we are no longer listing specific services and we are including our identityDocument.xml in the file list. We have a separate file in our example named acpt_manifest for this.

Once the correct parameters are provided to the manifest document and the driver script, you can execute the script. This script will do the following tasks:

  1. Back up the testing domain and store the base64 export in the SCM repository, by calling the do-backup operation within a SOAP request that is sent to the XML Management interface such as the document shown in Listing 8:
    Listing 8. XML management request to backup a domain configuration
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
        <dp:request
          xmlns:dp="http://www.datapower.com/schemas/management"
          domain="default">
          <dp:do-backup format="ZIP">
        <dp:domain name="Testing"/>
          </dp:do-backup>
        </dp:request>
      </soapenv:Body>
    </soapenv:Envelope>
  2. Restart the target domain (acceptance or production). This will pull in the new domain configuration that is defined within the existing domain on the target device. Listing 9 shows a sample SOAP request to accomplish this:
    Listing 9. XML management request to restart a domain
    <?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
      <env:Body>
        <dp:request
          xmlns:dp="http://www.datapower.com/schemas/management">
          <dp:do-action>
            <RestartDomain>
              <Domain>BookService</Domain>
            </RestartDomain>
          </dp:do-action>
        </dp:request>
      </env:Body>
    </env:Envelope>
  3. Copy the files listed in the manifest document from the SCM repository to the target environment via a SOAP request similar to the one shown in Listing 5 above.

There you have it! In three simple steps the testing domain was deployed to the target environment, which could be the acceptance environment or your production environment. The same three steps would have been applied.

Conclusion

The migration of changes to your DataPower device configuration must be done in a controlled fashion. Testing must be done at every level to ensure that service quality is not affected. This document has presented an example of an automated methodology for the migration of changes across the SDLC from development through to production. Individual organizations may have requirements that vary from this approach; however this framework demonstrates techniques that will prove valuable in SDLC migration.


Download

DescriptionNameSize
Code sampleDWArchive.zip1.1 MB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=379780
ArticleTitle=Managing WebSphere DataPower Device configurations for high availability, consistency, and control, Part 2: Application promotion strategies
publish-date=04012009