PK
vLoa, mimetypeapplication/epub+zipPK vL OEBPS/content.opf
Administering Zero Downtime Patching Workflows
12c (12.2.1.1.0)
E69724-01
June 2016
This document describes how to create workflows to move a domain from an existing Oracle Home to a patched Oracle Home, update to a new Java version, update applications in a domain, or perform a rolling restart without any loss of service.
Oracle Fusion Middleware Administering Zero Downtime Patching Workflows, 12c (12.2.1.1.0)
E69724-01
Copyright © 2016, 2016, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.
Note:
Prior to initiating the update process, you must have completed all appropriate preparation steps for the type of update you are doing, as described in Preparing for Zero Downtime Patching.
For Windows-based domains, prior to initiating a workflow to update an Oracle home, on each node, ensure that there are no locked directories or files in the Oracle home being updated, as this can prevent the Oracle home from being moved to the specified backup directory. A directory can be locked by something as simple as having a DOS command window open to that directory. A file can be locked by having it open in an application.
This chapter includes the following sections:
When you roll out a new Oracle home using either WLST or the Administration Console, you must ensure that the patched Oracle home is first rolled out to the Administration Server. There are two approaches you can take to do this:
Use one workflow to roll out the patched Oracle home to the Administration Server, and then use a second workflow to roll out the patched Oracle home to your clusters. Oracle recommends using this approach, but it is not required.
In this scenario:
If using WLST, you would execute either the rolloutOracleHome
or rolloutUpdate
command, and specify the name of the Administration Server as the target. You would then execute rolloutOracleHome
or rolloutUpdate
again, and specify cluster targets.
If using the WebLogic Server Administration Console, you would create one workflow from the Servers tab and select your Administration Server as the target. After that workflow completes, you would create a second workflow from the Clusters tab and select the clusters to include.
Use only one workflow to roll out the patched Oracle home to the entire domain. The workflow will automatically roll out the patched Oracle home first before rolling it out to the target clusters.
In this scenario:
If using WLST, you would execute either the rolloutOracleHome
or rolloutUpdate
command, and specify the domain name as the target.
If using the Administration Console, you would create one workflow from the Domain tab.
If the Administration Server will be included in a workflow, then you can start the Administration server using either the startWebLogic
script or the Node Manager. The Administration Server will be automatically restarted during the rollout operation if the specified target for the rollout is a domain. However, when the rollout operation restarts the Administration Server, you might experience a brief downtime when you will not be able to connect to either WLST or Administration Console. As a workaround, you must wait and then reconnect when the Administration Server has reached the RUNNING state in order to receive updates on the progress of the rollout operation.
To start the Administration Server before you initiate the rollout operation, you can start the Administration server in one of the following ways:
Using the startWebLogic
script
If there is no Node Manager configured for the Administration Server, then you can start the Administration Server by using the startWebLogic
script. To start the Administration Server using this script, see “Starting an Administration Server with a Startup Script” in Administering Server Startup and Shutdown for Oracle WebLogic Server.
Using the Node Manager
If a Node Manager is configured for the Administration Server, then you must start the Administration Server using the Node Manager. To start the Administration Server using the Node Manager, perform the following steps:
For more information, see "Starting the Administration Server Using Node Manager" in Administering Node Manager for Oracle WebLogic Server.
This section describes how to initiate and monitor rollout workflows for applying a patched Oracle home to the nodes in your domain. You can use this approach only if the workflow is applying a patched Oracle home. If you want to include a Java version update or application update in the workflow, then you must use WLST or the Administration Console.
This section contains the following topics:
Note:
When using OPatchAuto to initiate a workflow, you must use the Administration Console to monitor the progress of the workflow. See Monitoring and Managing Workflows.
Use the following commands to initiate a workflow using OPatchAuto:
cd ORACLE_HOME/OPatch/auto/core/bin opatchauto.sh apply -plan wls-zdt -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 the opatchauto apply
command:
Parameter | Description |
---|---|
| Indicates the type of operation to be performed by |
| Specify the full path and file name of the image JAR file that contains the patched Oracle home to use for the rollout. For example:
|
| Specify the Administration Server host name and port number for the domain you are rolling out the patched Oracle home to. |
| For
When rolling out the archive, you must specify the same target as you specified when you distributed the archive that you are using for the rollout. |
| The full path to the directory to use for backing up your existing Oracle home. For example:
|
| The full path to the archive file that 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:
|
| The full path to a wallet directory that was created using
|
| The password for the specified wallet, if needed. For example:
|
If an Oracle home rollout failed and you want to resume it, use the following commands:
cd ORACLE_HOME/OPatch/auto/core/bin opatchauto.sh resume -session workflow_id -walletPassword password
The following table describes the parameters in the opatchauto resume
command:
Parameter | Description |
---|---|
| Specify the workflow ID of the workflow to roll back. |
| The full path to a wallet directory that was created using
|
| The password for the specified wallet, if needed. For example:
|
You can use OPatchAuto to revert a rollout that has failed or stopped, as well as to revert a completed workflow. If the rollout has failed or stopped, OPatchAuto will revert it starting with the last successfully completed step. If the rollout has completed, then OPatchAuto will initiate a new rollout, using the backed up Oracle home as the Oracle home to roll out.
Use the following commands to revert a rollout:
cd ORACLE_HOME/OPatch/auto/core/bin opatchauto.sh rollback -session workflow_id -walletPassword password
The following table describes the parameters in the opatchauto rollback
command:
Parameter | Description |
---|---|
| Specify the workflow ID of the workflow to roll back. |
| The full path to a wallet directory that was created using
|
| The password for the specified wallet, if needed. For example:
|
This section describes the WLST commands that you can use to initiate workflows to update your Managed Servers, partitions, or resource groups, and provides sample WLST scripts demonstrating various workflow (rollout) scenarios.
Note:
When using the WLST rolloutOracleHome
or rolloutUpdate
commands to initiate a rollout of a new Oracle home for a Windows-based domain, you cannot run WLST from any Oracle home that will be updated as part of the workflow. For more information, see ZDT Patching Restrictions.
Use the following WLST commands to perform automated rolling updates of your servers. You must execute these commands from the Administration Server for the target domain.
rolloutOracleHome
— Rolls out a patched Oracle home to your Managed Servers or reverts your Managed Servers to a previous Oracle home. The patched Oracle home archive that you use in this command can be one that was created either using opatchauto
or the copyBinary
and pasteBinary
commands.
rolloutJavaHome
— Updates your Managed Servers to use a new Java version.
rolloutUpdate
— Updates your Managed Servers to use a patched Oracle home and a new Java version. The patched Oracle home archive that you use in this command can be one that was created either using opatchauto
or the copyBinary
and pasteBinary
commands.
rolloutApplications
—Updates specified applications that are running on your Managed Servers, partitions, or resource groups.
Note:
When specifying paths for Windows in rollout commands, you must use backslashes instead of forward slashes. To avoid unnecessary errors, ensure that the backslashes are escaped. (For example, C:\\myhome\\files\\apps.json
). For more information, see "Syntax for WLST Commands" in Understanding the WebLogic Scripting Tool.
When you execute one of these WLST commands, the command determines which servers need to be updated and in which order, and creates a patching workflow that will update them safely. This workflow includes:
Performing a graceful shutdown of Managed Servers, partitions, or resource groups one at a time. This does not include Managed Servers that are currently in ADMIN or STANDBY mode. This includes migration of singleton services if the migrationProperties
option is included in the rollout command. The ADMIN and STANDBY modes are not supported for rolling out application updates to partitions or resource groups.
Replacing the Oracle home directory (if applicable)
Replacing the Java home directory (if applicable)
Replacing application directories (if applicable)
Restarting Node Manager on the node
Restarting the Managed Servers on the node
Table 3-1 describes the parameters available for the WLSTrollout
commands.
Table 3-1 Arguments for WLST rollout Commands
Argument | Description |
---|---|
| Required for all Specifies which Managed Servers, partitions, or resource groups will be included in the update.
Note: Typically, you should specify a server target only when updating the Administration Server. Oracle recommends that you not update individual Managed Servers in most cases as sessions may not be preserved and downtime for users may not be avoided. However, one situation in which you can safely specify Managed Server targets is if you have added one or more new Managed Servers and they are not at the same Java version as your other Managed Servers. |
| Applies only to and is required for the Specifies the location of the Oracle home archive (JAR file) or local Oracle home directory to roll out, thereby replacing the existing Oracle home. |
| Applies only to and is required for the Specifies the full path of the directory to which the existing Oracle home will be moved. This effectively renames the original Oracle home. For example, if your original Oracle home is |
| Optional. Applies only to the |
| Applies to and is required for the Sp ecifies the location of the new Java home to use. |
| Applies to and is required for the Specifies the full path to the JSON file that defines one or more application names, application archive locations, and application backup locations. |
| The following options can be included in
|
You can also use WLST to monitor the progress of a workflow. For more information, see Monitoring Workflow Progress.
Use the rolloutOracleHome
command if you only want to do one of the following tasks:
Update your Administration Server to use a patched Oracle home.
Update your entire domain (Administration Server and clustered Managed Servers) to use a patched Oracle home.
Update clustered Managed Servers to use a patched Oracle home.
Revert your Administration Server, clustered Managed Servers, or domain to use the previous unpatched Oracle home.
rolloutOracleHome
has the following syntax:
rolloutOracleHome(target, rolloutOracleHome, backupOracleHome, [isRollback], [options])
This command supports the isDryRun
, autoRevertOnFailure
, and isSessionCompatible
options. For information about these options, see Using WLST to Initiate and Monitor Workflows.
The following example shows how to roll out a new Oracle home to the domain mydomain
. The JAR file for the patched Oracle home is located at /net/wls/wls_patched.jar
. The original Oracle home will be moved (renamed) to /u01/Oracle_Home_backup
. The process will not automatically revert if it fails.
connect('adminname', 'adminpassword', 't3://hostname:port') domain='/domains/mydomain' progress=rolloutOracleHome(domain, '/net/wls/wls_patched.jar', '/u01/Oracle_Home_backup', autoRevertOnFailure=FALSE)
Note:
Specifying a local Oracle home directory in therolloutOracleHome
command is not supported when you are rolling out a new Oracle home. For more information, see ZDT Patching Restrictions.. Use the rolloutJavaHome
command if you only want to do one of the following tasks:
Update your Administration Server to use a new Java version.
Update your entire domain (Administration Server and Managed Servers) to use a new Java version.
Update your Managed Servers to use a new Java version.
Revert your Administration Server, Managed Servers, or domain to use the previous Java version.
rolloutJavaHome
has the following syntax:
rolloutJavaHome(target, javaHome, [options])
This command supports the isDryRun
and autoRevertOnFailure
options. For information about these options, see Using WLST to Initiate and Monitor Workflows.
The following example shows how to roll out a new Java home to clusters Cluster1
, Cluster2
, Cluster3
. The new Java home location is /u01/jdk1.8.0_50
. The autoRevertOnFailure
option is not included in this example; therefore, the workflow will automatically revert if the process fails.
connect('adminname', 'adminpassword', 't3://hostname:port') clusters='Cluster1,Cluster2,Cluster3' progress=rolloutJavaHome(clusters, '/u01/jdk1.8.0_50')
Use the rolloutUpdate
command if you only want to do one of the following tasks:
Update your Administration Server to use both a patched Oracle home and a new Java version.
Update your entire domain (Administration Server and clustered Managed Servers) to use both a patched Oracle home and a new Java version.
Update your Managed Servers to use both a patched Oracle home and a new Java version.
Revert your Administration Server, Managed Servers, or domain to the previous Oracle home and previous Java version.
rolloutUpdate
has the following syntax:
rolloutUpdate(target, rolloutOracleHome, backupOracleHome, [isRollback], [javaHome], [options])
This command supports the isDryRun
, autoRevertOnFailure
, and isSessionCompatible
options. For information about these options, see Using WLST to Initiate and Monitor Workflows.
The following example shows how to roll out a new Oracle home and a new Java home to the Administration Server. The JAR file for the patched Oracle home is located at /net/wls/wls_patched.jar
. The original Oracle home will be moved (renamed) to /u01/Oracle_Home_backup
. The new Java home location is /u01/jdk1.8.0_50. The autoRevertOnFailure
option is not included in this example; therefore, the workflow will automatically revert if the process fails.
connect('adminname', 'adminpassword', 't3://hostname:port') server='AdminServer' progress=rolloutUpdate(server, '/net/wls/wls_patched.jar', '/u01/Oracle_Home_backup', '/u01/jdk1.8.0_50')
Use the rolloutApplications
command if you want to do one of the following tasks:
Update your Managed Servers to use a new version of one or more applications.
Revert your Managed Servers to the previous version of one or more applications.
Update your partition to use a new version of one or more applications.
Update your resource group to use a new version of one or more applications.
rolloutApplications
has the following syntax:
rolloutApplications(target, applicationProperties, [options])
This command supports the isDryRun
, autoRevertOnFailure
, and isSessionCompatible
options. For information about these options, see Using WLST to Initiate and Monitor Workflows.
The following example shows how to roll out the applications defined in the JSON-formatted application properties file /u01/scratch/app_update.json
to all clusters Cluster1
, Cluster2
, Cluster3
on a UNIX system.
connect('adminname', 'adminpassword', 't3://hostname:port') clusters='Cluster1,Cluster2,Cluster3' progress=rolloutApplications(clusters, '/u01/scratch/app_update.json')
After a successful rollout, if you want to roll back to the previous Oracle home, Java home, or application version, you must perform the following two steps to complete the rollback operation:
Use the rolloutUpdate
command to roll back to the previous Oracle home and Java home. However, you must keep the following restrictions in mind before you execute the rolloutUpdate
command to roll back:
You must specify the backed up Oracle home as the Oracle home directory to roll out. This directory should be the backup directory from the previous rollout.
Once you specify the backup Oracle home directory as the Oracle home directory to roll back to, you must not specify the new Java home in the command. The Java home will be automatically rolled back to the original Java home that was used in the previous Oracle home that you have specified to roll back to.
Use the rolloutApplications
command to rollback to the previous application version by specifying the old application archive in the json file. For more information about using this command, see Rolling Out Updated Applications
The following example shows how to roll back to the previous Oracle home, Java home and applications. In this example, myDomain
is the name of the domain to roll back to, /pathto/unpatchedOracleHomeBackup/
is the location of the backup Oracle home directory from the previous rollout, /pathto/unpatchedOracleHomeBackup1/
is the path of the directory to which the existing Oracle home will be moved. To enable the roll back operation, the isRollback
parameter must be set to true
as shown in the example:
rolloutUpdate('myDomain', '/pathto/unpatchedOracleHomeBackup/', '/pathto/unpatchedOracleHomeBackup1/', 'true')
Use the rollingRestart
command if you want to do one of the following tasks:
Initiate a rolling restart of all servers in a domain.
Initiate a rolling restart of all servers in a specific cluster or clusters.
Initiate a rolling restart of all partitions in a cluster on a server.
The rolling restart of a partition involves restarting the partitions in a cluster on each server in a sequential manner in such a way that it does not affect other partitions across the cluster or server. Both the WebLogic Server administrator and the partition administrator can perform the rolling restart of partitions on a server.
rollingRestart
has the following syntax:
rolloutRestart(target, [options])
The following example shows how to perform a rolling restart of all servers in Cluster1
and Cluster2
.
connect('adminname', 'adminpassword', 't3://hostname:port') clusters='Cluster1,Cluster2' progress=rollingRestart(clusters)
Each rollout
command returns a WorkFlowTaskRuntimeMBean
that you can use to poll the current status of the workflow. To monitor the progress of a rollout, use a rollout
command in the following format:
progress=rollout_command
For example, use this command if you are rolling out a new Oracle home:
progress=rolloutOracleHome(DomainA, '/net/patched/wls1221p.jar', '/net/backups/wls1221', autoRevertOnFailure=FALSE)
You can then use the methods of the WorkflowTaskRuntimeMBean
to return information about the workflow. For more information, see WorkflowTaskRuntimeMBean
in the MBean Reference for Oracle WebLogic Server. Here are some examples:
progress.getWorkflowId()
Returns the ID of the workflow.
progress.getProgressString()
'Workflow wf0011 Running: 13/36'
Returns a human-readable message containing information about the current workflow progress. In this example, workflow wf0011
is currently running and has completed 13 of the 36 workflow commands.
progress.getStatus()
STARTED
Returns the current status of the workflow, which can be STARTED
, SUCCESS
, RETRY
, REVERTING
, FAIL
, REVERTED
, REVERT_FAIL
, CANCELED
, or REVERT_CANCELED
.
The following Python script segment demonstrates one way to use the progress object to monitor a workflow and output the progress of a rollout task. Sample output is shown after the script.
# Print the starting information
rolloutName = progress.getName()
startTime = progress.getStartTime()
print "Started rollout task \"" + rolloutName + "\" at " + str(startTime)
# Check the state every 2 minutes
domainRuntime()
cd('RolloutService/rollout-service/ActiveWorkflows')
cd(progress.getWorkflowId())
while(get('Running')==1):
progressString = progress.getProgressString()
print progressString
time.sleep(120)
# Print the ending information
endTime = progress.getEndTime()
state = progress.getState()
print "rollout \"" + rolloutName + "\" finished with state
Output
Started rollout task "Domain1Rollout" at 2014-07-22 07:29:06.528971
Running step 1 of 9
Running step 2 of 9
Running step 3 of 9
Running step 4 of 9
Running step 5 of 9
Running step 6 of 9
Running step 7 of 9
Running step 8 of 9
Running step 9 of 9
rollout "Domain1Rollout" finished with state "SUCCESS" at
2014-07-22 07:47:15.538299
A workflow can stop in either the executing or reverting direction for the following reasons:
The workflow failed while executing, with the autoRevertOnFailure
option set to FALSE
.
The workflow was manually canceled.
An unrecoverable error occurred during a revert operation.
When a workflow is stopped, you can resolve any errors manually. You can then set the workflow to continue to execute or revert by using the following methods on the RolloutServiceRuntimeMBean
:
Method | Description |
---|---|
| Takes a progress object that is eligible to be resumed and resumes it in the execute direction. If the last successful operation on the workflow was an execute, then the execute will resume with the next execute step. If the last successful operation on the workflow was a revert, then the execute will resume by executing that revert step. |
| Takes a progress object that is eligible to be resumed and resumes it in the revert direction. If the last successful operation on the workflow was an execute, then the revert will resume with that step. If the last successful operation on the workflow was a revert, then the revert will resume by reverting the next step in the revert sequence. |
| Returns |
This section describes several WLST commands that you may find useful.
To get a list of completed workflows:
wls:/domain_name/domainRuntime/RolloutService/rollout-service> completeWfs=
cmo.getCompleteWorkflows()
To get a list of active workflows:
wls:/domain_name/domainRuntime/RolloutService/rollout-service> activeWfs = cmo.getActiveWorkflows()
To look up a workflow by ID and retrieve its status:
wls:/domain_name/domainRuntime/RolloutService/rollout-service> progress=cmo.getWorkflowTask('workflow_id') wls:/Domain1221/domainRuntime/RolloutService/rollout-service> progress.getStatus()
To cancel a running workflow:
wls:/domain_name/domainRuntime/RolloutService/rollout-service> progress=cmo.getWorkflowTask('workflow_id') wls:/domain_name/domainRuntime/RolloutService/rollout-service> progress.cancel()
To delete a completed workflow:
wls:/domain_name/domainRuntime/RolloutService/rollout-service> cmo.deleteWorkflow('workflow_id')
This section contains a sample WLST script that illustrates how to perform a rolling restart of all servers in a cluster called cluster1
with single service migration. In this script, the following arguments are defined:
username
— The WebLogic Server administrator user name.
password
— The WebLogic Server administrator password.
adminURL
— The host name and port number of the domain's Administration Server.
target
— The target or targets for the operation. See Table 3-1.
options
— The rollout option or options for the operation. See Table 3-1.
The following example shows a sample WLST script for a rollout operation.
import sys, socket import os import time from java.util import Date from java.text import SimpleDateFormat argUsername = sys.argv[1] argPassword = sys.argv[2] argAdminURL = sys.argv[3] argTarget = sys.argv[4] argTarget = sys.argv[5] try: connect(argUsername, argPassword, argAdminURL) progress = rollingRestart(argTarget, argTarget) lastProgressString = "" progressString=progress.getProgressString() # for testing progressString="12 / 12" steps=progressString.split('/') while not (steps[0].strip() == steps[1].strip()): if not (progressString == lastProgressString): print "Completed step " + steps[0].strip() + " of " + steps[1].strip() lastProgressString = progressString java.lang.Thread.sleep(1000) progressString=progress.getProgressString() steps=progressString.split('/') if(len(steps) == 1): print steps[0] break; if(len(steps) == 2): print "Completed step " + steps[0].strip() + " of " + steps[1].strip() t = Date() endTime=SimpleDateFormat("hh:mm:ss").format(t) print "" print "RolloutDirectory task finished at " + endTime print "" state = progress.getStatus() error = progress.getError() stateString = '%s' % state if stateString != 'SUCCESS': #msg = 'State is %s and error is: %s' % (state,error) msg = "State is: " + state raise(msg) elif error is not None: msg = "Error not null for state: " + state print msg #raise("Error not null for state: %s and error is: %s" + (state,error)) raise(error) except Exception, e: e.printStackTrace() dumpStack() raise("Rollout failed") exit()
To execute this script, save it in a Python (.py
) file and then enter commands similar to this. If you are running WLST on Windows, see ZDT Patching Restrictions, for important information about using WLST on Windows.
$ORACLE_HOME/oracle_common/common/bin/wlst.sh /u01/scripts/rollout/RollingRestart.py username password t3://hostname:port cluster1 "migrationProperties=/u01/json/mig.txt"
This section describes how to create and monitor a patching workflow that rolls out a patched Oracle home, a new Java version, new application versions, or any combination of these tasks. It contains the following sections: