diff --git a/doc/Pacemaker_Explained/en-US/Ap-Upgrade-Config.txt b/doc/Pacemaker_Explained/en-US/Ap-Upgrade-Config.txt index ef2d311fb5..7f1eb06f37 100644 --- a/doc/Pacemaker_Explained/en-US/Ap-Upgrade-Config.txt +++ b/doc/Pacemaker_Explained/en-US/Ap-Upgrade-Config.txt @@ -1,123 +1,130 @@ [appendix] -== Upgrading the Configuration from 0.6 == +== Upgrading the Configuration == + +This process was originally written for the upgrade from 0.6.'x' to 1.'y', +but the concepts should apply for any upgrade involving a change in +the XML schema version. indexterm:[Upgrading the Configuration] indexterm:[Configuration,Upgrading] === Perform the upgrade === ==== Upgrade the software ==== Refer to the appendix: <> ==== Upgrade the Configuration ==== As XML is not the friendliest of languages, it is common for cluster administrators to have scripted some of their activities. In such -cases, it is likely that those scripts will not work with the new 1.0 +cases, it is likely that those scripts will not work with the new XML syntax. In order to support such environments, it is actually possible to -continue using the old 0.6 syntax. +continue using the old XML syntax. The downside is, however, that not all the new features will be available and there is a performance impact since the cluster must do a non-persistent configuration upgrade before each transition. So while using the old syntax is possible, it is not advisable to continue using it indefinitely. Even if you wish to continue using the old syntax, it is advisable to -follow the upgrade procedure to ensure that the cluster is able to use -your existing configuration (since it will perform much the same task -internally). +follow the upgrade procedure (except for the last step) to ensure that the +cluster is able to use your existing configuration (since it will perform much +the same task internally). . Create a shadow copy to work with + ----- # crm_shadow --create upgrade06 ----- . Verify the configuration is valid indexterm:[Configuration,Verify]indexterm:[Verify,Configuration] + ----- # crm_verify --live-check ----- . Fix any errors or warnings . Perform the upgrade: + ----- # cibadmin --upgrade ----- . If this step fails, there are three main possibilities: .. The configuration was not valid to start with - go back to step 2 .. The transformation failed - report a bug or mailto:pacemaker@oss.clusterlabs.org?subject=Transformation%20failed%20during%20upgrade[email the project] .. The transformation was successful but produced an invalid result footnote:[ The most common reason is ID values being repeated or invalid. Pacemaker 1.0 is much stricter regarding this type of validation. ] + -If the result of the transformation is invalid, you may see a number of errors from the validation library. If these are not helpful, visit http://clusterlabs.org/wiki/Validation_FAQ and/or try the procedure described below under <> +If the result of the transformation is invalid, you may see a number of errors +from the validation library. If these are not helpful, visit the +http://clusterlabs.org/wiki/Validation_FAQ[Validation FAQ wiki page] and/or try +the procedure described below under <> + . Check the changes + ----- # crm_shadow --diff ----- + If at this point there is anything about the upgrade that you wish to fine-tune (for example, to change some of the automatic IDs) now is the time to do so. Since the shadow configuration is not in use by the cluster, it is safe to edit the file manually: + ----- # crm_shadow --edit ----- + -This will open the configuration in your favorite editor (whichever is specified by the standard +$EDITOR+ environment variable) -+ -. Preview how the cluster will react +This will open the configuration in your favorite editor (whichever is +specified by the standard *$EDITOR* environment variable) + -Test what the cluster will do when you upload the new configuration +. Preview how the cluster will react: + ------ # crm_simulate --live-check --save-dotfile upgrade06.dot -S # graphviz upgrade06.dot ------ + Verify that either no resource actions will occur or that you are happy with any that are scheduled. If the output contains actions you do not expect (possibly due to changes to the score calculations), you may need to make further manual changes. See <> for further details on how to interpret -the output of `crm_simulate` +the output of `crm_simulate` and `graphviz`. + . Upload the changes + ----- # crm_shadow --commit upgrade06 --force ----- -If this step fails, something really strange has occurred. You should report a bug. ++ +In the unlikely event this step fails, please report a bug. [[s-upgrade-config-manual]] ==== Manually Upgrading the Configuration ==== indexterm:[Configuration,Upgrade manually] -It is also possible to perform the configuration upgrade steps manually. To do this +It is also possible to perform the configuration upgrade steps manually: -Locate the 'upgrade06.xsl' conversion script or download the latest -version from -https://github.com/ClusterLabs/pacemaker/tree/master/xml/upgrade06.xsl[Git] +. Locate the +upgrade06.xsl+ conversion script provided with the source code + (the https://github.com/ClusterLabs/pacemaker/tree/master/xml/upgrade06.xsl[latest version] is available via + git). . Convert the XML blob: indexterm:[XML,Convert] + ----- # xsltproc /path/to/upgrade06.xsl config06.xml > config10.xml ----- + -. Locate the 'pacemaker.rng' script. +. Locate the +pacemaker.rng+ script. . Check the XML validity: indexterm:[Validate Configuration]indexterm:[Configuration,Validate XML] + ---- # xmllint --relaxng /path/to/pacemaker.rng config10.xml ---- The advantage of this method is that it can be performed without the cluster running and any validation errors should be more informative (despite being generated by the same library!) since they include line numbers. diff --git a/doc/Pacemaker_Explained/en-US/Ap-Upgrade.txt b/doc/Pacemaker_Explained/en-US/Ap-Upgrade.txt index dbf762262e..66f5cc5936 100644 --- a/doc/Pacemaker_Explained/en-US/Ap-Upgrade.txt +++ b/doc/Pacemaker_Explained/en-US/Ap-Upgrade.txt @@ -1,220 +1,193 @@ [appendix] [[ap-upgrade]] -== Upgrading Cluster Software +== Upgrading Cluster Software == -=== Version Compatibility === +There will always be an upgrade path from any pacemaker 1._x_ +release to any other 1._y_ release. -When releasing newer versions we take care to make sure we are -backwards compatible with older versions. While you will always be -able to upgrade from version x to x+1, in order to continue to produce -high quality software it may occasionally be necessary to drop -compatibility with older versions. - -There will always be an upgrade path from any series-2 release to any -other series-2 release. +Consult the documentation for your messaging layer +(Heartbeat or Corosync) to see whether upgrading them to a +newer version is also supported. There are three approaches to upgrading your cluster software: * Complete Cluster Shutdown * Rolling (node by node) * Disconnect and Reattach Each method has advantages and disadvantages, some of which are listed -in the table below, and you should chose the one most appropriate to +in the table below, and you should choose the one most appropriate to your needs. -.Summary of Upgrade Methodologies +.Upgrade Methods [width="95%",cols="6*",options="header",align="center"] |========================================================= |Type |Available between all software versions |Service Outage During Upgrade |Service Recovery During Upgrade |Exercises Failover Logic/Configuration |Allows change of cluster stack type indexterm:[Cluster,Switching between Stacks] indexterm:[Changing Cluster Stack] -footnote:[ -For example, switching from Heartbeat to Corosync. Consult the -Heartbeat or Corosync documentation to see if upgrading them to a -newer version is also supported. -] +footnote:[For example, switching from Heartbeat to Corosync.] |Shutdown indexterm:[Upgrade,Shutdown] indexterm:[Shutdown Upgrade] |yes |always |N/A |no |yes |Rolling indexterm:[Upgrade,Rolling] indexterm:[Rolling Upgrade] |no |always |yes |yes |no |Reattach indexterm:[Upgrade,Reattach] indexterm:[Reattach Upgrade] |yes |only due to failure |no |no |yes |========================================================= === Complete Cluster Shutdown === -In this scenario one shuts down all cluster nodes and resources and -upgrades all the nodes before restarting the cluster. +In this scenario, one shuts down all cluster nodes and resources, +then upgrades all the nodes before restarting the cluster. -==== Procedure ==== . On each node: -.. Shutdown the cluster stack (Heartbeat or Corosync) -.. Upgrade the Pacemaker software. - This may also include upgrading the cluster stack and/or the - underlying operating system. +.. Shutdown the cluster software (pacemaker and the messaging layer). +.. Upgrade the Pacemaker software. This may also include upgrading the + messaging layer and/or the underlying operating system. .. Check the configuration manually or with the `crm_verify` tool if available. . On each node: -.. Start the cluster stack. - This can be either Corosync or Heartbeat and does not need to be - the same as the previous cluster stack. +.. Start the cluster software. + The messaging layer can be either Corosync or Heartbeat and does not need to + be the same one before the upgrade. === Rolling (node by node) === -In this scenario each node is removed from the cluster, upgraded and then brought back online until all nodes are running the newest version. - -[IMPORTANT] -=========== -This method is currently broken between Pacemaker 0.6.x and 1.0.x. +In this scenario, each node is removed from the cluster, upgraded and then +brought back online until all nodes are running the newest version. -Measures have been put into place to ensure rolling upgrades always -work for versions after 1.0.0. Please try one of the other upgrade -strategies. Detach/Reattach is a particularly good option for most -people. -=========== - -==== Procedure ==== +Rolling upgrades should always be possible for pacemaker versions +1.0.0 and later. On each node: -. Shutdown the cluster stack (Heartbeat or Corosync) + +. Put the node into standby mode, and wait for any active resources + to be moved cleanly to another node. +. Shutdown the cluster software (pacemaker and the messaging layer) on the node. . Upgrade the Pacemaker software. This may also include upgrading the - cluster stack and/or the underlying operating system. -.. On the first node, check the configuration manually or with the - `crm_verify` tool if available. -.. Start the cluster stack. -+ -This must be the same type of cluster stack (Corosync or Heartbeat) -that the rest of the cluster is using. Upgrading Corosync/Heartbeat -may also be possible, please consult the documentation for those -projects to see if the two versions will be compatible. -+ -.. Repeat for each node in the cluster. + messaging layer and/or the underlying operating system. +. If this is the first node to be upgraded, check the configuration manually + or with the `crm_verify` tool if available. +. Start the messaging layer. + This must be the same messaging layer (Corosync or Heartbeat) + that the rest of the cluster is using. Upgrading the messaging layer + may also be possible; consult the documentation for those + projects to see whether the two versions will be compatible. -==== Version Compatibility ==== +[NOTE] +==== +Rolling upgrades were not always possible with older heartbeat and +pacemaker versions. The table below shows which versions were +compatible during rolling upgrades. Rolling upgrades that cross compatibility +boundaries must be performed in multiple steps (for example, +upgrading heartbeat 2.0.6 to heartbeat 2.1.3, and then upgrading again +to pacemaker 0.6.6). Rolling upgrades from pacemaker 0._x_ to 1._y_ are not +possible. .Version Compatibility Table [width="95%",cols="2*",options="header",align="center"] |========================================================= |Version being Installed |Oldest Compatible Version |Pacemaker 1.0.x |Pacemaker 1.0.0 |Pacemaker 0.7.x |Pacemaker 0.6 or Heartbeat 2.1.3 |Pacemaker 0.6.x |Heartbeat 2.0.8 |Heartbeat 2.1.3 (or less) |Heartbeat 2.0.4 |Heartbeat 2.0.4 (or less) |Heartbeat 2.0.0 |Heartbeat 2.0.0 |None. Use an alternate upgrade strategy. |========================================================= - -==== Crossing Compatibility Boundaries ==== - -Rolling upgrades that cross compatibility boundaries must be preformed -in multiple steps. For example, to perform a rolling update from -Heartbeat 2.0.1 to Pacemaker 0.6.6 one must: - -. Perform a rolling upgrade from Heartbeat 2.0.1 to Heartbeat 2.0.4 -. Perform a rolling upgrade from Heartbeat 2.0.4 to Heartbeat 2.1.3 -. Perform a rolling upgrade from Heartbeat 2.1.3 to Pacemaker 0.6.6 +==== === Disconnect and Reattach === -A variant of a complete cluster shutdown, but the resources are left -active and get re-detected when the cluster is restarted. - -==== Procedure ==== +The reattach method is a variant of a complete cluster shutdown, where the +resources are left active and get re-detected when the cluster is restarted. -. Tell the cluster to stop managing services. -+ -This is required to allow the services to remain active after the -cluster shuts down. +. Tell the cluster to stop managing services. This is required to allow the + services to remain active after the cluster shuts down. + ---- # crm_attribute -t crm_config -n is-managed-default -v false ---- -+ + . For any resource that has a value for +is-managed+, make sure it is -set to +false+ (so that the cluster will not stop it) +set to +false+ so that the cluster will not stop it (replacing $rsc_id +appropriately): + ---- # crm_resource -t primitive -r $rsc_id -p is-managed -v false ---- -+ + . On each node: -.. Shutdown the cluster stack (Heartbeat or Corosync) -.. Upgrade the cluster stack program - This may also include upgrading -the underlying operating system. +.. Shutdown the cluster software (pacemaker and the messaging layer). +.. Upgrade the Pacemaker software. This may also include upgrading the + messaging layer and/or the underlying operating system. . Check the configuration manually or with the `crm_verify` tool if available. . On each node: -.. Start the cluster stack. -+ -This can be either Corosync or Heartbeat and does not need to be the -same as the previous cluster stack. -+ +.. Start the cluster software. The messaging layer can be either Corosync or + Heartbeat and does not need to be the same one as before the upgrade. + . Verify that the cluster re-detected all resources correctly. . Allow the cluster to resume managing resources again: + ---- # crm_attribute -t crm_config -n is-managed-default -v true ---- -+ -. For any resource that has a value for +is-managed+ reset it to + +. For any resource that has a value for +is-managed+, reset it to +true+ (so the cluster can recover the service if it fails) if desired: + ---- # crm_resource -t primitive -r $rsc_id -p is-managed -v true ---- - -==== Notes ==== +[NOTE] +The oldest version of the CRM to support this upgrade type was in Heartbeat 2.0.4. [IMPORTANT] =========== Always check your existing configuration is still compatible with the version you are installing before starting the cluster. =========== - -[NOTE] -The oldest version of the CRM to support this upgrade type was in Heartbeat 2.0.4