This chapter describes the preliminary steps to complete before you can configure a patching workflow, including installing and patching a new Oracle Home, installing a new Java version, or installing updated applications on each node. It also describes the restrictions for ZDT Patching.
This chapter contains the following sections:
Prior to preparing for and creating a ZDT patching workflow, keep the following restrictions in mind:
If the Administration Server will be included in the workflow, you must use Node Manager to start it. Do not start the Administration Server using the startWebLogic command in the domain's bin directory. For more information, see Using Node Manager to Start the Administration Server.
The Managed Servers that are included in the workflow must be part of a cluster, and the cluster must span two or more nodes.
The Administration Server must be on a different node than any of the Managed Servers being updated.
Each node involved in the workflow must have its own Node Manager running, including the node on which the Administration Server resides.
If updating to a patched Oracle Home, the current Oracle Home must be installed locally on each node that will be included in the workflow. Although it is not required, Oracle also recommends that the Oracle Home be in the same location on each node.
If on a given node there are Managed Servers that belong to different clusters, and those clusters are sharing the same Oracle Home, if you are including one of those clusters in a workflow, you must also include the other cluster in the workflow. For example, if Node 1 has Managed Server 1 in Cluster 1 and Managed Server 2 in Cluster 2, and both Cluster 1 and Cluster 2 share the same Oracle Home, if you include Cluster 1 in the workflow, you must also include Cluster 2. This applies to Java Home, Oracle Home and application update rollouts.
The domain directory must reside outside of the Oracle Home directory.
Coherence applications (GAR files) are not supported by the WLST rolloutApplications command or the Applications function of ZDT in the WebLogic Server Administration Console.
(Windows only) When using WLST to initiate a rollout of a new Oracle Home, you cannot run WLST from any Oracle Home that will be updated as part of the workflow. Instead, use one of the following options:
Run WLST from an Oracle Home on a node that will not be included in the workflow. This Oracle Home must be the same version as the Oracle Home that is being updated on other nodes.
Run WLST from another Oracle Home that is not part of the domain being updated. This Oracle Home must be the same version as the Oracle Home that is being updated. It can reside on any node, including the Administration Server node for the domain being updated.
Use the WebLogic Server Administration Console to initiate the workflow.
(Windows only) Windows file locks may pose problems during the ZDT rollout operations. You must attempt to rectify these common file handle lock issues before executing a rollout on Windows to avoid rollout failure:
When deploying an application using the Administration Console, the Administration Server may hold a lock on the application source file. If this lock is not released, it could prevent subsequent application rollouts from functioning properly. To release the lock, you must log out of the Administration Console anytime after deploying the application and before initiating the rollout.
Using the WLST client on the Administration Server will cause the Oracle Home directory to be locked. This will cause any rollout, including a domain rollout, on that node to fail. To avoid this, use a WLST client installed on a node that is not targeted by the rollout, or initiate the rollout using the Administration Console.
Opening command terminals or applications residing in any directory under Oracle Home may cause a file lock. As a result, you will be unable to update that particular Oracle Home.
Any command terminal or application that happens to reference the application source file or a jar file may cause a file lock, making it impossible to update that particular application.
All ZDT rollouts require a restart of the servers that are included in the rollout. One of the features of the rollout is detection and handling of singleton services, such as JTA and JMS. If there are singleton services in your environment, service migration is configured for them as described in "Service Migration" in Administering Clusters for Oracle WebLogic Server. If a service is configured for migration the migration policy is exactly-once, then the service automatically migrates during a graceful shutdown of a server. If, however, the migration policy for a service is manual or failure-recovery, you must take steps to ensure that it is migrated safely during server shutdown. To do this:
Create a JSON file to define migration properties for such services, as described in this section
Configure the rollout to use the JSON file as described in Chapter 3, "Configuring and Monitoring Workflows."
The JSON file must start with the following line:
{"migrations":[
Each singleton service migration that you need to migrate is defined using the parameters described in the following table.
| Parameter | Description |
|---|---|
source |
The name of the source server from which the service is to be migrated. This parameter is required. |
destination |
For migrationType of jms, jta, or all, the name of the destination server to which the service is to be migrated.
For This parameter is required if the |
migrationType |
The type of migration, which can be one of the following types:
|
failback |
If set to true, a fail back is performed. Failback restores a service to its original hosting server, that is, the server on which it was running before the rollout.
The default value is Note: A JTA service automatically fails back when it is invoked for migration. Therefore, do not use the |
The following sample JSON file shows how to define various migration scenarios.
{"migrations":[
# Migrate all JMS migratable targets on server1 to server2. Perform a fail back
# if the operation fails.
{
"source":"server1",
"destination":"server2",
"migrationType":"jms",
"failback":"true"
},
# Migrate only JTA services from server1 to server3. Note that JTA migration
# does not support the failback option, as it is not needed.
{
"source":"server1",
"destination":"server3",
"migrationType":"jta"
},
# Disable all migrations from server2
{
"source":"server2",
"migrationType":"none"
},
{
# Migrate all services (for example, JTA and JMS) from server 3 to server1 with
# no failback
"source":"server3",
"destination":"server1",
"migrationType":"all"
},
# Use Whole Server Migration to migrate server4 to the node named machine 5 with
# no failback
{
"source":"server4",
"destination":"machine5",
"migrationType":"server"
}
]}
Note:
ZDT rollouts allows you to specify whether a singleton service should be migrated or simply shutdown during patching. It also provides support for a user to migrate a service to a different server instance on the same machine. However, Oracle recommends that you always specify migration of services to a server on a different machine and never on the same machine. This is because, all servers on a machine experience shutdown during a rollout which may cause unavoidable downtime for users.This section describes how to prepare for rolling out a patched Oracle Home to your Managed Servers. There are two ways to do this:
You can use the OPatchAuto tool to automatically clone your Oracle Home, patch it, and create a patched Oracle Home archive. You can then use OPatchAuto to distribute the patched Oracle Home archive to the nodes in your domain. Oracle recommends using this approach as it is more automated. See the following sections for details:
You can manually create the second Oracle Home, use OPatch to apply patches to it, use copyBinary to create an archive of the patched Oracle Home, and then copy the archive to the nodes in your domain. See the following sections for details:
In both cases, the preparation process does not require you to shut down any of your Managed Servers, so there is no impact on the availability of your applications.
Note:
If your domain includes Fusion Middleware products other than WebLogic Server (such as SOA or WebCenter), and you have patched those applications in your Oracle Home, if you want to preserve currently active sessions while doing the rollout, ensure that the patched versions are compatible with ZDT patching. For example, the applied patches should have limited changes to session shape and should be backward-compatible with other Fusion Middleware products that are running in the domain.This section describes how to create a clone of your existing Oracle Home, patch it, and create an archive of the patched Oracle Home using the OPatchAuto tool. the patches you want to apply must already have been downloaded to your patch_home directory using OPatch.
To create a patched Oracle Home archive, enter the following commands. You must run this command from the ORACLE_HOME from which you want to create the image. This command creates a clone of your unpatched Oracle Home, applies the patches in the specified patch_home directory, and then creates the patched archive.
cd ORACLE_HOME/OPatch/auto/core/bin opatchauto.sh apply patch_home -create-image -image-location path -oop
The following table describes the parameters in this command:
| Parameter | Description |
|---|---|
patch_home |
The OPatch ${PATCH_HOME} directory where the patches you want to apply are stored. |
-create-image |
Indicates that you want to create an image of the ORACLE HOME directory. The image will include the patches in patch_home. |
-image-location path |
Specify the full path and file name of the image JAR file to create. For example:
|
-oop |
Indicates that this is an out-of-place patching archive. |
After creating a patched archive, use OPatchAuto to distribute the archive to each node that will be included in the Oracle Home patching workflow.
To distribute the archive use the following command:
cd ORACLE_HOME/OPatch/auto/core/bin opatchauto.sh apply -plan wls-zdt-push-image -image-location path -wls-zdt-host adminserver:port -wls-zdt-target target -wls-zdt-remote-image path -wallet path -walletPassword password
The following table describes the parameters in this command:
| Parameter | Description |
|---|---|
-plan |
Indicates the type of operation to be performed by opatchauto apply. For distributing a patched Oracle Home for ZDT, always specify wls-zdt-push-image as the value for this parameter. |
-image-location path |
Specify the full path and file name of the image JAR file to distribute. For example:
|
-wls-zdt-host adminserver:port |
Specify the Administration Server hostname and port number for the domain to which you are distributing the archive. The archive will be distributed to this node. |
-wls-zdt-target target |
Specify a cluster or a comma-separated list of clusters that will be included in the rollout. The archive will be distributed to all nodes on which these clusters are configured. |
-wls-zdt-remote-image path |
The full path to the archive file you want to create on each node to be included in the ZDT rollout. This does not have to be the same file name as the original archive. For example:
|
-wallet path |
The full path to a wallet directory that was created using configWallet.sh or configWallet.cmd. For example:
|
-walletPassword password |
The password for the specified wallet, if needed. For example:
|
After completing these steps, you are ready to create a workflow that includes patching your Oracle Home. See Chapter 3, "Configuring and Monitoring Workflows."
Note:
If you want to also update your Java version or applications using the same patching workflow, perform the preparation steps for those upgrades first before you create the workflow.To manually create a patched Oracle Home, you must first create a copy of your existing Oracle Home using copyBinary and pasteBinary.
Notes:
Oracle recommends that you create and patch the second Oracle Home on a non-production machine so that you can test the patches you apply, but this is not required. The following steps must be performed on the node where you will patch the new Oracle Home. The Oracle Home on that node must be identical to the Oracle Home you are using for your production domain.To create the second Oracle Home to which you will apply patches:
Change to the following directory, where ORACLE_HOME is the Oracle Home you want to patch.
cd ORACLE_HOME/oracle_common/bin
Execute the following command, where archive is the full path and filename of the archive file to create, and oracle_home is the full path to your existing Oracle Home. Note that $JAVA_HOME must be defined as the Java home that was used for your Oracle Home installation:
UNIX
./copyBinary.sh -javaHome $JAVA_HOME -archiveLoc archive -sourceOracleHomeLoc oracle_home
Windows
copyBinary.cmd -javaHome %JAVA_HOME% -archiveLoc archive -sourceOracleHomeLoc oracle_home
For example, the following command creates the Oracle Home archive wls1221.jar in network location /net/oraclehomes/ using the Oracle Home located at /u01/oraclehomes/wls1221:
./copyBinary.sh -javaHome $JAVA_HOME -archiveLoc /net/oraclehomes/wls1221.jar -sourceOracleHomeLoc /u01/oraclehomes/wls1221
Execute the following command to create the second Oracle Home, where archive is the full path and filename of the archive file you created, and patch_home is the full path to the new Oracle Home to which you will apply patches. Note that $JAVA_HOME must be defined as the Java home that was used for your original Oracle Home installation:
UNIX
./pasteBinary.sh -javaHome $JAVA_HOME -archiveLoc archive -targetOracleHomeLoc patch_home
Windows
pasteBinary.cmd -javaHome %JAVA_HOME% -archiveLoc archive -targetOracleHomeLoc patch_home
For example, the following command creates the Oracle Home wls1221_patched in /u01/oraclehomes/ using the archive /net/oraclehomes/wls1221.jar:
./pasteBinary.sh -javaHome $JAVA_HOME -archiveLoc /net/oraclehomes/wls1221.jar -targetOracleHomeLoc /u01/oraclehomes/wls1221_patched
To patch the second Oracle Home, use the OPatch tool to apply individual patches, bundle patches, security patch updates, or patch set updates to the second, offline Oracle Home. Prior to applying a particular patch or group of patches, ensure that all prerequisite patches have already been applied.
For detailed information about how to prepare for and patch an Oracle Home using OPatch, see Patching with OPatch.
Once you have created the patched Oracle Home, use the following steps to create an Oracle Home archive and copy it to each node that will be involved in the rollout:
Change to the following directory, where ORACLE_HOME is the patched Oracle Home you created in the previous section.
cd ORACLE_HOME/oracle_common/bin
Execute the following command, where archive is the full path and filename of the archive file to create, and patched_home is the full path to the patched Oracle Home you created in the previous section. Note that $JAVA_HOME must be defined as the Java home that was used for your current Oracle Home installation.:
UNIX
./copyBinary.sh -javaHome $JAVA_HOME -archiveLoc archive -sourceOracleHomeLoc patched_home
Windows
copyBinary.cmd -javaHome %JAVA_HOME% -archiveLoc archive -sourceOracleHomeLoc patched_home
For example, the following command creates the Oracle Home archive wls1221.11.jar in network location /net/oraclehomes/ using a patched Oracle Home located at /01/oraclehomes/wls1221_patched:
./copyBinary.sh -javaHome $JAVA_HOME -archiveLoc /net/oraclehomes/wls_1221.11.jar -sourceOracleHomeLoc /u01/oraclehomes/wls1221_patched
On each node that will be included in the patching workflow, copy the archive file to the parent folder of the Oracle Home that you want to replace. For example, if the archive is in network location /net/oraclehomes/wls_1221.11.jar and the Oracle Home to be replaced is located in /u01/oraclehomes/wls1221:
cp /net/oraclehomes/wls1221.11.jar /u01/oraclehomes/
If you are copying to a large number of nodes, you can use third-party software distribution applications to perform this step.
After completing these steps, you are ready to create a workflow that includes patching your Oracle Home. See Chapter 3, "Configuring and Monitoring Workflows."
Note:
If you want to also update your Java version or applications using the same patching workflow, perform the preparation steps for those upgrades first before you create the workflow.This section describes how to prepare for upgrading to a newer version of Java. Preparation does not require you to shut down Managed Servers, so there will be no interruption to application availability.
To upgrade to a new version of Java:
Prior to installing the new Java version, ensure that the Node Manager and Managed Servers are running on all nodes on which you plan to install the new version. This prevents the Java installer from changing the existing Java Home path.
On each node to be included in the upgrade, install the new Java version to the same path on each node. The full path to the new Java version must be the same on each node for the upgrade to be successful.
After copying the new Java version to each node, you are ready to create a workflow that includes upgrading to a new Java Home. See Chapter 3, "Configuring and Monitoring Workflows."
This section describes how to prepare for updating to new applications using a ZDT workflow. It contains the following sections:
Applications deployed across Managed Servers can be deployed using one of three staging modes, which indicate how the application will be distributed and kept up-to-date. These are stage mode, no-stage mode and external-stage mode.
How you prepare for an application update workflow depends on the mode you used when you staged the application. The following table describes how to prepare for an application update based on the staging mode that you use to deploy the application.
Table 2-1 Preparing for an Application Update Based on Staging Mode
| Staging Mode | Required Preparation and Result |
|---|---|
|
Stage |
Place a copy of the updated application directory on the domain's Administration Server. Result: The workflow will replace the original application directory on the Administration Server and WebLogic Server will copy it to each Managed Server. |
|
No-stage |
Place a copy of the updated application directory on each node that will be affected. This directory must be in the same location on each node. Result: The workflow will update each node in turn by replacing the existing application directory with the updated application directory, and will move the original application directory to the specified backup location. |
|
External stage |
Place a copy of the updated application directory on each node that will be affected. This directory must be in the same location on each node. Result: The workflow will detect that the application is an external-stage application, figure out the correct path for the stage directory for each Managed Server on the node, copy the updated application to that location, and move the original application to the specified backup location. |
For detailed information about the various staging modes, see "Staging Mode Descriptions and Best Practices" in Deploying Applications to Oracle WebLogic Server.
You can update one or more applications in your domain with a single workflow. Application updates are accomplished by creating a JSON file that, for each application, defines:
the application name (applicationName)
the path and file name for the updated application archive (patchedLocation)
the path and file to which you want to back up the original application archive (backupLocation)
When configuring the workflow either using WLST or the WebLogic Server Administration Console, you specify the file name of the JSON file to use for the update.
The following example shows the structure of a JSON file that is intended to update two applications, MyApp and AnotherApp, to a new version. You can use a single JSON file to update as many applications as necessary.
Example 2-1 Example JSON File for Updating Multiple Applications
{"applications":[
{
"applicationName":"MyApp",
"patchedLocation":"/u01/applications/MyAppv2.war",
"backupLocation": "/u01/applications/MyAppv1.war"
},
{
"applicationName":"AnotherApp",
"patchedLocation":"/u01/applications/AnotherAppv2.war",
"backupLocation": "/u01/applications/AnotherAppv1.war"
}
]}
After copying the updated application to all required locations and creating the JSON file, you are ready to create a workflow that includes application updates. See Chapter 3, "Configuring and Monitoring Workflows."