Written Tutorial

Problem

During a rolling upgrade, some servers will have the original version, while others will have the new version but act as if they still had the old. Generate a report showing which servers have which actual and effective versions.

Solution

Applies to MarkLogic versions 8.0-6+

xquery version "1.0-ml";

import module namespace admin="http://marklogic.com/xdmp/admin" at "/MarkLogic/admin.xqy";

declare namespace hosts = "http://marklogic.com/manage/hosts";
declare namespace http = "xdmp:http";

<hosts>
  <cluster-version>{admin:cluster-get-effective-version(admin:get-configuration())}</cluster-version>
  {
    for $id in xdmp:hosts()
    let $response := 
      xdmp:http-get(
        "http://localhost:8002/manage/v2/hosts/" || $id || "?view=status&amp;format=xml",
        <options xmlns="xdmp:http">
          <authentication method="digest">
            <username>admin</username>
            <password>admin</password>
          </authentication>
          <headers>
            <content-type>application/json</content-type>
          </headers>
        </options>)
    return
      if ($response[1]/http:code = 200) then
        <host>
          <name>{$response[2]/hosts:host-status/hosts:name/fn:string()}</name>
          <this-host-software-version>{$response[2]/hosts:host-status/hosts:version/fn:string()}</this-host-software-version>
          <this-host-effective-version>{$response[2]/hosts:host-status/hosts:effective-version/fn:string()}</this-host-effective-version>
        </host>
      else
        <host>
          <name>{xdmp:host-name($id)}</name>
          <code>{$response[1]/http:code/fn:string()}</code>
        </host>
  }
</hosts>

This produces output like this:

<hosts>
  <cluster-version>8000600</cluster-version>
  <host>
    <name>ml3.local</name>
    <this-host-software-version>8.0-6</this-host-software-version>
    <this-host-effective-version>8000600</this-host-effective-version>
  </host>
  <host>
    <name>ml1.local</name>
    <this-host-software-version>8.0-6</this-host-software-version>
    <this-host-effective-version>8000600</this-host-effective-version>
  </host>
  <host>
    <name>ml2.local</name>
    <this-host-software-version>8.0-6</this-host-software-version>
    <this-host-effective-version>8000600</this-host-effective-version>
  </host>
</hosts>

Required Privileges:

• http://marklogic.com/xdmp/privileges/manage
• http://marklogic.com/xdmp/privileges/admin-module-read

Discussion

Rolling upgrades allows a single cluster to roll forward incrementally to a new release. This is done by taking down one node at a time, upgrading that node, and bringing it back up. When the node is re-started, it will talk to the rest of the cluster in the lowest level of the other nodes in the cluster. When the last server in the cluster gets upgraded, then all nodes switch over to the new version.

To see the current state of upgrades across a cluster, we need to ask each of the servers for some data — there’s no function we can run on one server that will tell us the version running on another. To get the information we want, we send a Management API request to each of the hosts asking for current status, then extract the version information.

When we send the HTTP request, we get back a 2-item sequence. The first item gives details on the response itself — response code, and so on. The second item has the content of the response. If XML produced by the recipe has a <code> element in it, that is the HTTP error code from the REST call.