15 Managing Application Migration Between Environments

This chapter describes how to migrate Web service applications between environments, such as from development or test to production. It includes the following sections:

Overview of Web Service Application Migration

To migrate Web service applications independently between environments, such as from test to production, or in a scaled clustered environment, you must export the policies and the deployment configuration information to the new environment so that you can deploy the application. Depending on your configuration, you may also need to migrate policy configuration artifacts and policy assertion templates.

A deployment descriptor is an XML file that contains the basic deployment configuration for an application. For WebLogic Server and WebLogic Java EE Web services applications, you create a deployment plan that contains the necessary deployment descriptors for deploying the application in a new environment.

For ADF Business Components and WebCenter services, however, run-time policy changes are persisted in proprietary deployment descriptor (PDD) files: oracle-webservices.xml and oracle-webservices-client.xml. Because these files are not included in the WebLogic deployment plan or exported with any other deployment descriptors, you must export and import these PDD files separately. You must also export and import these PDD files separately if you are scaling your application in a clustered environment.

Note that the following Oracle Infrastructure Web services components provide different configuration management mechanisms.

  • For a SOA composite, Web services and Oracle WSM configurations are persisted in a composite.xml file which is included in a configuration plan used for deployment configuration. The SOA framework provides its own mechanism for composite services and configuration lifecycle and synchronizations.

  • ADF Web Service data control configuration stores connection details for WebCenter services in a connections.xml file and all post-deployment changes as customizations in the Metadata Services (MDS) repository.

The general steps for migrating a Web service application from a development or test environment to a production environment are as follows:

  1. Install and configure the production environment with the components that you need.

  2. Migrate security information, such as users and groups, the identity and policy stores, and credentials. For more information, see "Migrating Policy Configuration".

  3. Migrate policies and deployment configuration data as required. For more information, see "Migrating Policies" and "Migrating Deployment Descriptors". Modify any information that is specific to the new environment such as host name or ports.

  4. Deploy the applications in the new environment.

For information about migrating Fusion Middleware applications between environments, see "Advanced Administration: Expanding Your Environment" in Oracle Fusion Middleware Administrator's Guide.

Overview of Horizontal Policy Migration

The following steps describe a typical scenario for how to create a policy and migrate the policy horizontally through the different stages of the application development and deployment cycles.

  1. Use Oracle Enterprise Manager Fusion Middleware Control to create a policy.

    For more information, see "Creating Web Service Policies".

  2. Export the policy to a file.

    For more information, see "Migrating Policies".

  3. Copy the policy file to policy store location in the Oracle JDeveloper environment.

  4. Create a Web service in Oracle JDeveloper and attach the policy to the Web service.

    For more information, see "Using Policies with Web Services" in the "Developing with Web Services" section of the JDeveloper online help.

  5. Deploy the Web service to the staging server, and test the Web service.

    For more information, see "Developing Web Services" in the JDeveloper online help.

  6. Import the policy to the production server environment.

    For more information, see "Migrating Policies".

  7. Migrate the following information, as required:

  8. Deploy the application into the production environment, and test the Web service.

    See "Deploying Web Services Applications" and "Testing Web Services".

Sample Use Cases for Deployment Descriptor Migration

The following sections provide sample use cases for ADF Business Control or WebCenter Web Service applications for which you must migrate the PDD files.

Scaling a Deployed ADF Business Control or WebCenter Web Service Application in a Cluster

The following steps describe a sample use case for scaling a deployed ADF Business Control or WebCenter Web service application within a cluster.

  1. Deploy an ADF Business Control or WebCenter Web service application in a clustered WebLogic Server domain consisting of, for example, an Administration Server and two Managed Servers (MServer1 and MServer2). For deployment information, see Chapter 5, "Deploying Web Services Applications."

  2. Using Fusion Middleware Control or WLST, modify the policy configuration. For example, attach a policy named oracle/wss_username_token_service_policy to the Web service on MServer2. For more information, see Chapter 8, "Attaching Policies to Web Services."

    The configuration changes are persisted in the PDD files.

  3. Restart the application.

  4. Export the PDD to a JAR file using the exportJRFWSApplicationPDD command. For more information, see "Migrating Deployment Descriptors".

  5. Using the WebLogic Server Administration Console, clone a new Managed Server named MServer3 in the cluster from MServer2. For more information, see "Clone Servers" in the Oracle WebLogic Server Administration Console Help.

  6. Start the new Managed Server, MServer3.

    Note that MServer3 does not have the policy oracle/wss_username_token_service_policy attached because it was attached after the application was initially deployed.

  7. Import the JAR file containing the Oracle WSM PDD files that you created in step 4 to MServer3 using the importJRFWSApplicationPDD command. For more information, see "Migrating Deployment Descriptors".

  8. Restart the application.

Propagating Run-time Policy Changes in an ADF Business Control or WebCenter Web Service Environment

The following steps describe a sample use case for propagating run-time policy changes for an ADF Business Control or WebCenter Web service application to all servers in a cluster.

  1. Deploy an ADF Business Control or WebCenter Web service application in a clustered WebLogic Server domain consisting of, for example, an Administration Server and three Managed Servers (MServer1, MServer2, and MServer3). For deployment information, see Chapter 5, "Deploying Web Services Applications."

  2. Using Fusion Middleware Control or WLST, modify the policy configuration. For example, detach all policies from MServer2. For more information, see Chapter 8, "Attaching Policies to Web Services."

    The configuration changes are persisted in the PDD files.

  3. Restart the application.

  4. Export the PDD files from MServer2 to a JAR file using the exportJRFWSApplicationPDD command. For more information, see "Migrating Deployment Descriptors".

  5. Use the savePddToAllAppInstancesInDomain command, with the restartApp argument set to true. For more information, see "Migrating Deployment Descriptors"

    The policies are now detached from all server instances in the domain and the application is restarted.

Migrating Policies

You can export individual policies from Oracle Enterprise Manager Fusion Middleware Control. You can then copy the policy to a directory or import the policy to move it to another repository.

Note:

If you are using the Oracle RAC database, avoid switching databases when performing a bulk import of policies or metadata upload. This may cause the import to fail.

For details about exporting and importing policies using Fusion Middleware Control, see the following sections in "Managing Web Service Policies":

Alternatively, you can use the exportRepository and importRepository WLST commands to export and import the policies. The following describes the steps required:

To migrate policies using WLST commands:

  1. Export the Oracle WSM policies to a supported archive file, such as a zip file, using the exportRepository command.

    For example, to export all Oracle WSM policies to an archive named policies.zip, enter the following:

    wls:/jrfServer_domain/serverConfig> exportRepository('/tmp/policies.zip',['policies:oracle/%'])
     
    Exporting "/policies/oracle/binding_authorization_denyall_policy"
    Exporting "/policies/oracle/binding_authorization_permitall_policy"
    Exporting "/policies/oracle/binding_permission_authorization_policy"
    .
    .
    .
    Exporting "/policies/oracle/wss_username_token_over_ssl_service_policy"
    Exporting "/policies/oracle/wss_username_token_service_policy"
    Successfully exported "84" documents.
    
  2. Optionally, you can edit the archive after it has been created. If, for example, you do not want to migrate all the policies to the new environment, you can manually remove them from the archive.

  3. Move the archive to the new machine. Ensure that the Oracle WSM Policy Manager is deployed on the new machine.

  4. Import the Oracle WSM policies using the importRepository command. For example, to import the policies exported in the previous step:

    wls:/jrfServer_domain/serverConfig> importRepository('/tmp/policies.zip')
     
    Importing "META-INF/policies/oracle/binding_authorization_denyall_policy"
    Importing "META-INF/policies/oracle/binding_authorization_permitall_policy"
    Importing "META-INF/policies/oracle/binding_permission_authorization_policy"
    .
    .
    .
    Importing "META-INF/policies/oracle/wss_username_token_over_ssl_service_policy"
    Importing "META-INF/policies/oracle/wss_username_token_service_policy"
    Successfully imported "84" documents
    

For more information about these WLST commands, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Migrating Policy Configuration

The following sections describe how to migrate the configuration artifacts for Oracle WSM policies. Sections include:

Migrating Keystores

If you are using message protection policies, you need to migrate your keystores. To migrate keystores:

  1. Manually copy your keystores to the new environment.

    For Java SE applications, copy the keystore to a user-defined location. For Java EE applications, copy the keystore to the same directory as the jps-config.xml file, namely DOMAIN_HOME/config/fmwconfig.

  2. By default, the keystore is named default-keystore.jks. If you have renamed the keystore, you must configure the keystore name in the Oracle Platform Security Services keystore service instance.

For information about configuring the keystore, see "Configuring Keystores for Message Protection".

Migrating Users and Groups

Users and groups are maintained as part of the WebLogic Server security realm.

To migrate users and groups in embedded LDAP, you can migrate the data using either the Oracle WebLogic Administration Console or WLST. For a complete description of the steps required, see "Migrating Security Data" in Securing Oracle WebLogic Server.

To migrate users and groups in an LDAP store, there is no migration path. You need to recreate the users and groups and specify the assignments in the LDAP store in the new environment. See "Configuring Authentication Providers" in Securing Oracle WebLogic Server.

Migrating Credentials

There are two types of credentials maintained in the credential store that you may need to migrate:

  • Username and password

  • Keystore and encryption key passwords

The migration steps are described in the sections below.

Migrating Username and Password

If users are stored in an embedded LDAP and migrated, as described in "Migrating Users and Groups", then you simply migrate the existing credentials to the new credential store. For a complete description of the steps required, see "Migrating Security Data" in Securing Oracle WebLogic Server.

If users are stored in an LDAP store, there is no automated migration path. You need to recreate the credentials in the credential store. For more information about configuring credentials, see "Adding Keys and User Credentials to the Credential Store".

Migrating Keystores and Encryption Key Passwords

You can migrate keystores and encryption key passwords manually using the procedure described in "Migrating Credentials Manually" in "Deploying Secure Applications" in Oracle Fusion Middleware Application Security Guide.

Migrating Oracle Platform Security Services Application and System Policies

If your Web service uses authorization policies, you must migrate the Oracle Platform Security Services application and system policies that grant permissions. For more information, see "Migrating with the Script migrateSecurityStore" in "Configuring the OPSS Security Store" in Oracle Fusion Middleware Application Security Guide.

Migrating Oracle Platform Security Services Configuration

There is no automated migration path for Oracle Platform Security Services configuration. You must recreate the configuration in the new environment.

There are three types of configurations in the Oracle Platform Security Services that you may need to recreate:

  • SAML trusted assertion issuer names (applicable for all SAML policies).

    If you use the default configuration for SAML trusted issuer configuration, then no migration is required. For information about configuring SAML in the new environment, see "Configuring the SAML and Kerberos Login Modules".

  • Keystore locations and CSF key configuration for keystore and keystore password (applicable for message protection policies only).

    If you use the default configuration for keystores, then no migration is required. For information about configuring keystores in the new environment, see "Configuring Keystores for Message Protection".

  • Keytab location and service principal name (applicable to Kerberos policy).

    For information about configuring the keytab location and service principal name in the new environment, see "Configuring the SAML and Kerberos Login Modules".

Migrating SSL

There is no automated migration path for SSL configuration. You must configure SSL keystores and settings in the new environment. For more information about configuring SSL keystores and settings in the new environment, see "Configuring Keystores for SSL".

Migrating Kerberos Configuration

To migrate the Kerberos configuration:

  1. Copy the Kerberos configuration file to the new environment, matching the directory structure. The Kerberos configuration file is located in the following locations, based on your operating system:

    • UNIX: /etc/krb5.conf

    • Windows: C:\windows\krb5.ini

  2. Initialize the ticket cache with the correct credentials.

    For more information, see "Using Kerberos Tokens".

Migrating Assertion Templates

You can export individual assertion templates from Oracle Enterprise Manager Fusion Middleware Control. You can then copy the policy to a directory or import the policy to move it to another repository.

For details about exporting and importing assertion templates, see the following sections:

Migrating Deployment Descriptors

To deploy an application in a new environment, you must export the application's deployment configuration to the new environment. Refer to the following topics for information about exporting WebLogic Java EE Web services, SOA composites, and ADF data control deployment configuration:

Run-time Web service policy changes to ADF Business Control and WebCenter Web service applications are persisted in proprietary deployment descriptor (PDD) files. To preserve these policy changes in a scaled or new environment, or to propagate these changes in a domain, you must migrate the PDD files using WLST commands. The following procedure describes the steps required to migrate the PDD files.

  1. Connect to the running instance of the WebLogic Administration Server in the domain in which the application is deployed. For instructions, see "Accessing the Web Services Custom WLST Commands".

  2. Optionally, use the listWebServices(None,None,true) command to list all the Web services in all applications and composites in the domain.

    For example:

    wls:/wls-domain/serverConfig> listWebServices(None,None,true)
     
    /wls-domain/ManagedServer1/j2wbasicPolicy:
        moduleName=j2wbasicPolicy, moduleType=web, serviceName={http://namespace/}WssUsernameService
        enableTestPage: true
        enableWSDL: true
     
                JRFWssUsernamePort    http://host:port/j2wbasicPolicy/WssUsername
                enable: true
                enableREST: false
                enableSOAP: true
                maxRequestSize: -1
                loggingLevel: NULL
                security : oracle/wss_username_token_service_policy, enabled=true
            enableWSDL: true
    
              Attached policy or policies are valid; endpoint is secure.
    .
    .
    .
    

    Note:

    The listWebServices command output does not include details on SOA components, including policy attachments.

  3. Modify the policy configuration using Fusion Middleware Control or WLST. For example, to attach the policy oracle/wsmtom_policy to ManagedServer1 using WLST, enter the following command:

    wls:/wls-domain/serverConfig> attachWebServicePolicy
    ('/wls-domain/ManagedServer1/j2wbasicPolicy','j2wbasicPolicy','web',
    'WssUsernameService','JRFWssUsernamePort',
    'oracle/wsmtom_policy,')
    

    The policy change is persisted in the application PDD.

  4. Restart the application.

  5. Optionally, use the listWebServices(None,None,true) command again to verify that the policy is attached to the server instance. For example:

    wls:/wls-domain/serverConfig> listWebServices(None,None,true)
     
    /wls-domain/ManagedServer1/j2wbasicPolicy :
        moduleName=j2wbasicPolicy, moduleType=web, serviceName={http://namespace/}WssUsernameService
        enableTestPage: true
        enableWSDL: true
     
              JRFWssUsernamePort    http://host:port/j2wbasicPolicy/WssUsername
              enable: true
              enableREST: false
              enableSOAP: true
              maxRequestSize: -1
              loggingLevel: NULL
              security : oracle/wss_username_token_service_policy , enabled=true
              mtom : oracle/wsmtom_policy , enabled=true
    
             Attached policy or policies are valid; endpoint is secure.
    
  6. Export the application PDD to a JAR file using the exportJRFWSApplicationPDD WLST command.

    exportJRFWSApplicationPDD(application,pddJarFileName=None)
    

    For example, to export the PDD for the j2wbasicPolicy application using the default JAR filename, use the following command:

    wls:/wls-domain/serverConfig> exportJRFWSApplicationPDD('/wls-domain/ManagedServer1/j2wbasicPolicy', None)
    

    The default name and path to the JAR file is displayed.

    /tmp/j2wbasicPolicy-PDD-20100115-145338.jar
    
  7. If you are scaling your environment, use the WebLogic Server Administration Console to clone a new Managed Server. For more information, see "Clone Servers" in the Oracle WebLogic Server Administration Console Help.

    If you are migrating your application to a new environment, ensure that the policies and any other configuration artifacts are copied to the new environment. For more information, see "Migrating Policies" and "Migrating Policy Configuration".

  8. In a scaled environment, start the cloned Managed Server.

    Note that the oracle/wsmtom_policy is not attached to the cloned Managed Server. To do so using the listWebServices command:

    wls:/wls-domain/serverConfig> listWebServices(None,None,true)
    .
    .
    .
    /wls-domain/ClonedManagedServer/j2wbasicPolicy :
        moduleName=j2wbasicPolicy, moduleType=web,serviceName={http://namespace/}WssUsernameService
        enableTestPage: true
        enableWSDL: true
     
                JRFWssUsernamePort  http://host:port/j2wbasicPolicy/WssUsername
                enable: true
                enableREST: false
                enableSOAP: true
                maxRequestSize: -1
                loggingLevel: NULL
                security: oracle/wss_username_token_service_policy , enabled=true
    
               Attached policy or policies are valid; endpoint is secure.
    
  9. Import the application PDD to the new server, or to the new environment, using the importJRFWSApplicationPDD command.

    importJRFWSApplicationPDD(application,pddJarFileName)
    

    For example, to import the PDD JAR created in step 6 to the cloned Managed Server, use the following command:

    wls:/wls-domain/serverConfig> importJRFWSApplicationPDD
    ('/wls-domain/ClonedManagedServer/j2wbasicPolicy','/tmp/j2wbasicPolicy-PDD-20100115-145338.jar')
    application  /wls-domain/ClonedManagedServer/j2wbasicPolicy  PDD has been reset, please restart application now to uptake changes!
    
  10. Restart the application and, optionally, verify the changes by executing the listWebServices(None,None,true) command again. For example:

    wls:/wls-domain/serverConfig> listWebServices(None,None,true)
    .
    .
    .
    /wls-domain/ClonedManagedServer/j2wbasicPolicy :
        moduleName=j2wbasicPolicy, moduleType=web,serviceName={http://namespace/}WssUsernameService
        enableTestPage: true
        enableWSDL: true
     
                JRFWssUsernamePort  http://host:port/j2wbasicPolicy/WssUsername
                enable: true
                enableREST: false
                enableSOAP: true
                maxRequestSize: -1
                loggingLevel: NULL
                security:oracle/wss_username_token_service_policy , enabled=true
                mtom : oracle/wsmtom_policy , enabled=true
    
               Attached policy or policies are valid; endpoint is secure.
    
  11. Use the savePddToAllAppInstancesInDomain command to apply the policy changes (that you applied to a single server in step 9 using the importJRFWSApplicationPDD command) to all the server instances in the domain. This command is useful for propagating run-time policy changes to all servers in a cluster.

    savePddToAllAppInstancesInDomain(applicationName,pddJarFileName,restartApp=true)
    

    For example, to apply the same policy attachment to all server instances running the application in the domain, use the following command:

    wls:/wls-domain/serverConfig> savePddToAllAppInstancesInDomain('j2wbasicPolicy','/tmp/j2wbasicPolicy-PDD-20100115-145338.jar',true)
    

    The oracle/wsmtom_policy is now attached to all server instances in the domain and the application is automatically restarted.

  12. Optionally, execute the listWebServices(None,None,true) command to verify the changes were applied to all servers.

For more information about these deployment migration WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.