| Upgrade Tool 1.2. Name(s) and e-mail address of Document Author(s)/Supplier: Bobby Bissett: bobby.bissett@oracle.com 1.3. Date of This Document: 05/17/2010 2. Project Summary 2.1. Project Description: A tool to assist users in upgrading a domain to be used with a GlassFish Server Open Source Edition 3.1. Upgrades can be performed without the tool as well. See technical description below for more details. 2.2. Risks and Assumptions: 2.2.1. Tightly coupled to asadmin script through Runtime#exec call. Upgrade tool needs to parse asadmin output. If the format of the output changes, the upgrade tool needs to adjust. 2.2.2. Actual upgrade process depends on all modules to implement their part of changing the domain configuration. 2.2.3. Not all desired tasks fall under an existing module (e.g., features present in v2.1 that are not in 3.1). 2.2.4. It is assumed that something in the upgrade process will inform users of information that cannot be upgraded and/or manual steps that the users should take. This includes information that cannot be handled by a relevant module as well as configuration info that isn't covered by a specific module (2.2.3). 2.2.5. While the upgrade tool attempts to copy 3rd party jars from glassfish_home/lib to the newer version, this cannot always be done automatically. Users should always do this manually when upgrading through the asadmin command. 2.2.6 Upgrades are supported from GF versions 2.1.X through 3.0.X to 3.1. An upgrade from v2 should also work, but support is focused on 2.1.X. When upgrading from a version earlier than GFv2, a domain must first be upgraded to 2.1.X before being upgraded to 3.1. 3. Problem Summary 3.1. Problem Area: Upgrade in general allows users to move their existing domains, including settings, applications, realms, pools, etc., to a newer version of GlassFish without having to recreate manually all of the work. 3.2. Justification: To allow users to move to newer versions of GlassFish easily. 4. Technical Description: 4.1. Details: This one pager covers specifically the upgrade tool, which simply copies a domain and wraps asadmin to perform the upgrades. This section, however, covers the general upgrade information as well as the tool. (Some of this information will be repeated in the upgrade dashboard page for the convenience of module owners.) GlassFish 3.1 is being implemented as a set of OSGi bundles. Having component bundles that can run standalone or be mixed and matched with other components to create new products and profiles means each component must be aware of its domain configuration requirments. When an upgrade is occurring, each component must be able to evaluate the relevant configuration information, transform the data to its current needs if possible and report issues that require manual intervention. Modules should also log any changes made in the configuration when making them. There is no specific logging configuration for upgrade. Modules should use the same logger they normally do. Use INFO level for logging the changes made, and continue to use WARNING and SEVERE for warnings and errors if they happen. For a module to implement its part of upgrade, implement the org.glassfish.api.admin.config.ConfigurationUpgrade interface and include a @PostConstruct annotated method and injected Config object. Since this was implemented in 3.0 by most modules, there are plenty of examples in the source code. The dashboard page will include more details for module owners, though the interface itself is defined in the core module. For the user an upgrade can be performed in two ways (this applies more to asadmin but is captured here for completeness):
- asadmin start-domain --upgrade: This will enter upgrade mode in the server, send all logging information to std out/err, and stop the server after the upgrade.
- asadmin start-domain (without --upgrade): The server will detect if a domain needs to be upgraded before continuing to start the domain.
The upgrade tool can be launched in GUI or command line mode with the asupgrade or asupgrade.bat files. It does the following:
- Collect location of source domain and target domains directories.
- Collect the master password of the domain if needed (i.e., it is not the default and the --savemasterpassword option was not used when setting it).
- Check to see if the source domain is from a supported version.
- Attempt to copy 3rd party jars from source server to target server (source_domain/../../lib to target_domains/../lib).
- Copy source domain to the target domains directory. If there is already a domain there with the same name, the tool will ask the user if it's ok to move it and then rename it.
- Call asadmin start-domain --upgrade to perform the upgrade.
- Parse the process output and report possible problems during the upgrade.
- The tool will create an upgrade.log file for reporting.
Open issues and questions from other leads have been moved to the 3.1 upgrade dashboard page. 4.2. Bug/RFE Number(s): "List any Bug(s)/RFE(s) which will be addressed by this proposed change." It's not really a change, but here are the open upgrade tool issues. There is a security issue to be solved when the server's master password must be collected from the tool and passed to asadmin. Currently the simple workaround is to set the domain's master password with the --savemasterpassword option. Internal issue 6944744 – needs java.net issue to track as well. This issue 11753 tracks open issues from going to v2 to v3.1. 4.3. In Scope: Side-by-side upgrades are supported from GlassFish v2.1.X (all profiles), v3 Prelude, and 3.0.X. Other tools such as the installer can call asupgrade as part of their operation. See below for more details. Because modules only handle the upgrade of features related to that module, there is no current mechanism for detecting things that cannot be upgraded (e.g., the addons directory in v2). While the upgrade tool can't be expected to handle this, there should be some code in GlassFish that can. While the method is still TBD, one suggestion is to implement a small service involved during upgrades just for catching these situations. This will have to be handled somehow – adding it here as part of upgrade's purview. 4.4. Out of Scope: In 3.0, it was declared in the one pager that the upgrade tool could be called from within other scripts and the installer. This is not necessary for some cases because the scripts/installer can simply call asadmin to start the server. The upgrade will happen automatically. For in-place upgrades, for instance, the upgrade tool will not be needed. For installers that look for previous installations, they could call the upgrade tool or simply copy the older domain from one location to another. It is not expected that output from the upgrade tool is useful to a script (human readable only). In-place upgrades are not supported without some other tool (e.g. the update center), as the code that performs the upgrade must first be present in order to run. One of the goals of a side-by-side upgrade is that the original server should be left untouched. For this reason, and because an upgrade can happen with a simple "asadmin start-domain --upgrade --domaindir somedir" it is recommended that users not give their v2 domains/domainX directory as the value of the --domaindir option. Rather, the upgrade should be performed on a copy of the domain (this is what the asupgrade tool does). Rolling upgrade of applications in a cluster. Though it shares a name, this is covered under the deployment module and is not part of domain configuration upgrade. 4.5. Interfaces: 4.5.1 Public Interfaces Not new, but upgrade tool exposes a GUI and command line interface through the asupgrade script. 4.5.2 Private Interfaces N/A 4.5.3 Deprecated/Removed Interfaces: N/A 4.6. Doc Impact: Will require incremental changes from 3.0. 4.7. Admin/Config Impact: N/A 4.8. HA Impact: High Availability or Clustering aspects will be most impacted as they need to implement their portion of the upgrade contract. 4.9. I18N/L10N Impact: Modules must implement their own code properly for l10n support. 4.10. Packaging, Delivery & Upgrade: 4.10.1. Packaging Upgrade tool already packaged along with asupgrade script. 4.10.2. Delivery "What impact will this proposal have on product installation?" None specifically, but an installer could start the upgrade tool to upgrade an existing domain to the new app server installation. 4.10.3. Upgrade and Migration: See rest of doc. 4.11. Security Impact: No specific security impact beyond collecting master password to pass to asadmin. 4.12. Compatibility Impact N/A List any requirements on upgrade tool and migration tool. 4.13. Dependencies: An internal dependency is a dependency on a project, module,
component or product that is within the GlassFish project.
An external dependency is a dependency on a project, component
or product that resides outside of the GlassFish project. 4.13.1 Internal Dependencies Strongly tiled to asadmin command line options, output, and mechanism to read password on std in stream. 4.13.2 External Dependencies
- JavaHelp for built-in help documentation. There has not been a release of JavaHelp since 2007.
- Depends on almost every module in GlassFish to perform upgrades.
4.14. Testing Impact: No automated testing so far. We want to use the new testing harness being worked on for clustering to test upgrades. The harness must be able to stop and start an instance to perform an upgrade. 5. Reference Documents: Upgrade schedule page Upgrade dashboard 6. Schedule: 6.1. Projected Availability: The upgrade tool is already present, and all 3.0 features should already have implemented upgrade. New features (Clustering) should implement upgrade by M4.
|
