| <!DOCTYPE html> |
| <html> |
| <head> |
| <title>Apache BookKeeper™ - Upgrade</title> |
| |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| |
| <link rel="stylesheet" href="/css/normalize.css"> |
| <link rel="stylesheet" href="/css/tippy.css"> |
| <link rel="stylesheet" href="/css/style.css"> |
| |
| <link rel="shortcut icon" href="/img/favicon.ico"> |
| |
| <script src="/js/tippy.min.js"></script> |
| |
| <script type="text/javascript"> |
| var shiftWindow = function() { scrollBy(0, -25); }; |
| window.addEventListener("hashchange", shiftWindow); |
| window.addEventListener("pageshow", shiftWindow); |
| function load() { if (window.location.hash) shiftWindow(); } |
| </script> |
| </head> |
| <body class="body"> |
| <main class="main"> |
| |
| <nav class="navbar bk-topnav"> |
| <div class="navbar-brand"> |
| <a class="navbar-item bk-brand" href="/"> |
| Apache BookKeeper™ |
| </a> |
| |
| <div class="navbar-burger burger" data-target="bkNav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </div> |
| </div> |
| |
| <div id="bkNav" class="navbar-menu"> |
| <div class="navbar-start"> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link">Documentation</a> |
| <div class="navbar-dropdown is-boxed"> |
| <a class="navbar-item" href="/docs/latest/overview/overview"> |
| Version 4.14.0-SNAPSHOT |
| <span class="tag is-warning">Development</span> |
| </a> |
| <a class="navbar-item" href="/docs/latest/api/javadoc"> |
| <span class="icon bk-javadoc-icon"> |
| <img src="/img/java-icon.svg"> |
| </span> |
| Javadoc |
| </a> |
| <hr class="dropdown-divider"> |
| |
| <a class="navbar-item" href="/docs/4.13.0/overview/overview"> |
| Release 4.13.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.12.1/overview/overview"> |
| Release 4.12.1 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.12.0/overview/overview"> |
| Release 4.12.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.11.1/overview/overview"> |
| Release 4.11.1 |
| |
| <span class="tag is-success">Stable</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.11.0/overview/overview"> |
| Release 4.11.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.10.0/overview/overview"> |
| Release 4.10.0 |
| |
| </a> |
| |
| |
| <a class="navbar-item" href="/archives/docs/r4.9.2"> |
| Release 4.9.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.9.1"> |
| Release 4.9.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.9.0"> |
| Release 4.9.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.8.2"> |
| Release 4.8.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.8.1"> |
| Release 4.8.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.8.0"> |
| Release 4.8.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.3"> |
| Release 4.7.3 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.2"> |
| Release 4.7.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.1"> |
| Release 4.7.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.0"> |
| Release 4.7.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.6.2"> |
| Release 4.6.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.6.1"> |
| Release 4.6.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.6.0"> |
| Release 4.6.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.5.1"> |
| Release 4.5.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.5.0"> |
| Release 4.5.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.4.0"> |
| Release 4.4.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.3.2"> |
| Release 4.3.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.3.1"> |
| Release 4.3.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.3.0"> |
| Release 4.3.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.4"> |
| Release 4.2.4 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.3"> |
| Release 4.2.3 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.2"> |
| Release 4.2.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.1"> |
| Release 4.2.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.0"> |
| Release 4.2.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.1.0"> |
| Release 4.1.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.0.0"> |
| Release 4.0.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| </div> |
| </div> |
| |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link">Community</a> |
| <div class="navbar-dropdown is-boxed"> |
| <a class="navbar-item" href="/community/mailing-lists">Mailing lists</a> |
| <a class="navbar-item" href="/community/slack">Slack</a> |
| <a class="navbar-item" href="https://github.com/apache/bookkeeper/issues">Github Issues</a> |
| <a class="navbar-item" href="/community/releases">Release Management</a> |
| <a class="navbar-item" href="/community/meeting">Community Meetings</a> |
| <hr class="dropdown-divider"> |
| <a class="navbar-item" href="/community/contributing">Contribution Guide</a> |
| <a class="navbar-item" href="/community/coding_guide">Coding Guide</a> |
| <a class="navbar-item" href="/community/testing">Testing Guide</a> |
| <a class="navbar-item" href="/community/issue-report">Issue Report Guide</a> |
| <a class="navbar-item" href="/community/release_guide">Release Guide</a> |
| <hr class="dropdown-divider"> |
| <a class="navbar-item" href="/community/presentations">Presentations</a> |
| <a class="navbar-item" href="/community/bookkeeper_proposals">BookKeeper Proposals</a> |
| </div> |
| </div> |
| |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link">Project</a> |
| <div class="navbar-dropdown is-boxed"> |
| <a class="navbar-item" href="/project/who">Who are we?</a> |
| <a class="navbar-item" href="/project/bylaws">Bylaws</a> |
| <a class="navbar-item" href="http://www.apache.org/licenses/">License</a> |
| <hr class="dropdown-divider"> |
| <a class="navbar-item" href="/project/privacy">Privacy policy</a> |
| <a class="navbar-item" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="navbar-item" href="http://www.apache.org/foundation/thanks.html">Thanks</a> |
| </div> |
| </div> |
| </div> |
| |
| <div class="navbar-end"> |
| <div class="navbar-item"> |
| <div class="field is-grouped"> |
| <p class="control"> |
| <a class="button bk-twitter" href="https://twitter.com/asfbookkeeper"> |
| <span class="icon"> |
| <i class="fa fa-twitter"></i> |
| </span> |
| <span>Twitter</span> |
| </a> |
| </p> |
| <p class="control"> |
| <a class="button" href="https://github.com/apache/bookkeeper"> |
| <span class="icon"> |
| <i class="fa fa-github"></i> |
| </span> |
| <span>GitHub</span> |
| </a> |
| </p> |
| <p class="control"> |
| <a class="button is-primary" href="/releases"> |
| <span class="icon"> |
| <i class="fa fa-download"></i> |
| </span> |
| <span>Download</span> |
| </a> |
| </p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <div class="bk-docs-container"> |
| <div class="columns is-gapless"> |
| <div class="column is-2 is-hidden-mobile"> |
| <div class="container"> |
| |
| <aside class="sidebar"> |
| |
| <a class="button is-info"> |
| Version: 4.11.0 |
| </a> |
| <hr /> |
| |
| <p> |
| Getting started |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../getting-started/installation"> |
| Installation |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../getting-started/run-locally"> |
| Run bookies locally |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../getting-started/concepts"> |
| Concepts and architecture |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Deployment |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../deployment/manual"> |
| Manual deployment |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../deployment/dcos"> |
| BookKeeper on DC/OS |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../deployment/kubernetes"> |
| BookKeeper on Kubernetes |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Administration |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../admin/bookies"> |
| BookKeeper administration |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/autorecovery"> |
| AutoRecovery |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/metrics"> |
| Metric collection |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/upgrade"> |
| Upgrade |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/http"> |
| BookKeeper Admin REST API |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/decomission"> |
| Decommissioning Bookies |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| API |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../api/overview"> |
| Overview |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/ledger-api"> |
| Ledger API |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/ledger-adv-api"> |
| Advanced Ledger API |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/distributedlog-api"> |
| DistributedLog |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/javadoc"> |
| Java API Docs |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Security |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../security/overview"> |
| Overview |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../security/tls"> |
| TLS Authentication |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../security/sasl"> |
| SASL Authentication |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../security/zookeeper"> |
| ZooKeeper Authentication |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Development |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../development/protocol"> |
| BookKeeper protocol |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Reference |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../reference/config"> |
| Configuration |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../reference/cli"> |
| Command-line tools |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../reference/metrics"> |
| Metrics |
| </a> |
| </li> |
| |
| </ul> |
| |
| </aside> |
| |
| |
| </div> |
| </div> |
| |
| <div class="column is-8 bk-docs-block"> |
| <header class="docs-title"> |
| <nav class="level bk-level"> |
| <div class="level-left"> |
| <div class="level-item"> |
| <h1 class="title">Upgrade</h1> |
| </div> |
| </div> |
| |
| </nav> |
| |
| |
| </header> |
| |
| <hr /> |
| |
| <div class="content"> |
| <section class="bk-main-content"> |
| <blockquote> |
| <p>If you have questions about upgrades (or need help), please feel free to reach out to us by <a href="/community/mailing-lists">mailing list</a> or <a href="/community/slack">Slack Channel</a>.</p> |
| </blockquote> |
| |
| <h2 id="overview">Overview</h2> |
| |
| <p>Consider the below guidelines in preparation for upgrading.</p> |
| |
| <ul> |
| <li>Always back up all your configuration files before upgrading.</li> |
| <li>Read through the documentation and draft an upgrade plan that matches your specific requirements and environment before starting the upgrade process. |
| Put differently, don’t start working through the guide on a live cluster. Read guide entirely, make a plan, then execute the plan.</li> |
| <li>Pay careful consideration to the order in which components are upgraded. In general, you need to upgrade bookies first and then upgrade your clients.</li> |
| <li>If autorecovery is running along with bookies, you need to pay attention to the upgrade sequence.</li> |
| <li>Read the release notes carefully for each release. They contain not only information about noteworthy features, but also changes to configurations |
| that may impact your upgrade.</li> |
| <li>Always upgrade one or a small set of bookies to canary new version before upgraing all bookies in your cluster.</li> |
| </ul> |
| |
| <h2 id="canary">Canary</h2> |
| |
| <p>It is wise to canary an upgraded version in one or small set of bookies before upgrading all bookies in your live cluster.</p> |
| |
| <p>You can follow below steps on how to canary a upgraded version:</p> |
| |
| <ol> |
| <li>Stop a Bookie.</li> |
| <li>Upgrade the binary and configuration.</li> |
| <li>Start the Bookie in <code class="highlighter-rouge">ReadOnly</code> mode. This can be used to verify if the Bookie of this new version can run well for read workload.</li> |
| <li>Once the Bookie is running at <code class="highlighter-rouge">ReadOnly</code> mode successfully for a while, restart the Bookie in <code class="highlighter-rouge">Write/Read</code> mode.</li> |
| <li>After step 4, the Bookie will serve both write and read traffic.</li> |
| </ol> |
| |
| <h3 id="rollback-canaries">Rollback Canaries</h3> |
| |
| <p>If problems occur during canarying an upgraded version, you can simply take down the problematic Bookie node. The remain bookies in the old cluster |
| will repair this problematic bookie node by autorecovery. Nothing needs to be worried about.</p> |
| |
| <h2 id="upgrade-steps">Upgrade Steps</h2> |
| |
| <p>Once you determined a version is safe to upgrade in a few nodes in your cluster, you can perform following steps to upgrade all bookies in your cluster.</p> |
| |
| <ol> |
| <li>Determine if autorecovery is running along with bookies. If yes, check if the clients (either new clients with new binary or old clients with new configurations) |
| are allowed to talk to old bookies; if clients are not allowed to talk to old bookies, please <a href="../../reference/cli/#autorecovery-1">disable autorecovery</a> during upgrade.</li> |
| <li>Decide on performing a rolling upgrade or a downtime upgrade.</li> |
| <li>Upgrade all Bookies (more below)</li> |
| <li>If autorecovery was disabled during upgrade, <a href="../../reference/cli/#autorecovery-1">enable autorecovery</a>.</li> |
| <li>After all bookies are upgraded, build applications that use <code class="highlighter-rouge">BookKeeper client</code> against the new bookkeeper libraries and deploy the new versions.</li> |
| </ol> |
| |
| <h3 id="upgrade-bookies">Upgrade Bookies</h3> |
| |
| <p>In a rolling upgrade scenario, upgrade one Bookie at a time. In a downtime upgrade scenario, take the entire cluster down, upgrade each Bookie, then start the cluster.</p> |
| |
| <p>For each Bookie:</p> |
| |
| <ol> |
| <li>Stop the bookie.</li> |
| <li>Upgrade the software (either new binary or new configuration)</li> |
| <li>Start the bookie.</li> |
| </ol> |
| |
| <h2 id="upgrade-guides">Upgrade Guides</h2> |
| |
| <p>We describes the general upgrade method in Apache BookKeeper as above. We will cover the details for individual versions.</p> |
| |
| <h3 id="46x-to-470-upgrade">4.6.x to 4.7.0 upgrade</h3> |
| |
| <p>There isn’t any protocol related backward compabilities changes in 4.7.0. So you can follow the general upgrade sequence to upgrade from 4.6.x to 4.7.0.</p> |
| |
| <p>However, we list a list of changes that you might want to know.</p> |
| |
| <h4 id="common-configuration-changes">Common Configuration Changes</h4> |
| |
| <p>This section documents the common configuration changes that applied for both clients and servers.</p> |
| |
| <h5 id="new-settings">New Settings</h5> |
| |
| <p>Following settings are newly added in 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Default Value</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>allowShadedLedgerManagerFactoryClass</td> |
| <td>false</td> |
| <td>The allows bookkeeper client to connect to a bookkeeper cluster using a shaded ledger manager factory</td> |
| </tr> |
| <tr> |
| <td>shadedLedgerManagerFactoryClassPrefix</td> |
| <td><code class="highlighter-rouge">dlshade.</code></td> |
| <td>The shaded ledger manager factory prefix. This is used when <code class="highlighter-rouge">allowShadedLedgerManagerFactoryClass</code> is set to true</td> |
| </tr> |
| <tr> |
| <td>metadataServiceUri</td> |
| <td>null</td> |
| <td>metadata service uri that bookkeeper is used for loading corresponding metadata driver and resolving its metadata service location</td> |
| </tr> |
| <tr> |
| <td>permittedStartupUsers</td> |
| <td>null</td> |
| <td>The list of users are permitted to run the bookie process. Any users can run the bookie process if it is not set</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h5 id="deprecated-settings">Deprecated Settings</h5> |
| |
| <p>There are no common settings deprecated at 4.7.0.</p> |
| |
| <h5 id="changed-settings">Changed Settings</h5> |
| |
| <p>There are no common settings whose default value are changed at 4.7.0.</p> |
| |
| <h4 id="server-configuration-changes">Server Configuration Changes</h4> |
| |
| <h5 id="new-settings-1">New Settings</h5> |
| |
| <p>Following settings are newly added in 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Default Value</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>verifyMetadataOnGC</td> |
| <td>false</td> |
| <td>Whether the bookie is configured to double check the ledgers’ metadata prior to garbage collecting them</td> |
| </tr> |
| <tr> |
| <td>auditorLedgerVerificationPercentage</td> |
| <td>0</td> |
| <td>The percentage of a ledger (fragment)’s entries will be verified by Auditor before claiming a ledger (fragment) is missing</td> |
| </tr> |
| <tr> |
| <td>numHighPriorityWorkerThreads</td> |
| <td>8</td> |
| <td>The number of threads that should be used for high priority requests (i.e. recovery reads and adds, and fencing). If zero, reads are handled by Netty threads directly.</td> |
| </tr> |
| <tr> |
| <td>useShortHostName</td> |
| <td>false</td> |
| <td>Whether the bookie should use short hostname or <a href="https://en.wikipedia.org/wiki/Fully_qualified_domain_name">FQDN</a> hostname for registration and ledger metadata when useHostNameAsBookieID is enabled.</td> |
| </tr> |
| <tr> |
| <td>minUsableSizeForEntryLogCreation</td> |
| <td>1.2 * <code class="highlighter-rouge">logSizeLimit</code></td> |
| <td>Minimum safe usable size to be available in ledger directory for bookie to create entry log files (in bytes).</td> |
| </tr> |
| <tr> |
| <td>minUsableSizeForHighPriorityWrites</td> |
| <td>1.2 * <code class="highlighter-rouge">logSizeLimit</code></td> |
| <td>Minimum safe usable size to be available in ledger directory for bookie to accept high priority writes even it is in readonly mode.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h5 id="deprecated-settings-1">Deprecated Settings</h5> |
| |
| <p>Following settings are deprecated since 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>registrationManagerClass</td> |
| <td>The registration manager class used by server to discover registration manager. It is replaced by <code class="highlighter-rouge">metadataServiceUri</code>.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h5 id="changed-settings-1">Changed Settings</h5> |
| |
| <p>The default values of following settings are changed since 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Old Default Value</th> |
| <th>New Default Value</th> |
| <th>Notes</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>numLongPollWorkerThreads</td> |
| <td>10</td> |
| <td>0</td> |
| <td>If the number of threads is zero or negative, bookie can fallback to use read threads for long poll. This allows not creating threads if application doesn’t use long poll feature.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h4 id="client-configuration-changes">Client Configuration Changes</h4> |
| |
| <h5 id="new-settings-2">New Settings</h5> |
| |
| <p>Following settings are newly added in 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Default Value</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>maxNumEnsembleChanges</td> |
| <td>Integer.MAX_VALUE</td> |
| <td>The max allowed ensemble change number before sealing a ledger on failures</td> |
| </tr> |
| <tr> |
| <td>timeoutMonitorIntervalSec</td> |
| <td>min(<code class="highlighter-rouge">addEntryTimeoutSec</code>, <code class="highlighter-rouge">addEntryQuorumTimeoutSec</code>, <code class="highlighter-rouge">readEntryTimeoutSec</code>)</td> |
| <td>The interval between successive executions of the operation timeout monitor, in seconds</td> |
| </tr> |
| <tr> |
| <td>ensemblePlacementPolicyOrderSlowBookies</td> |
| <td>false</td> |
| <td>Flag to enable/disable reordering slow bookies in placement policy</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h5 id="deprecated-settings-2">Deprecated Settings</h5> |
| |
| <p>Following settings are deprecated since 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>clientKeyStoreType</td> |
| <td>Replaced by <code class="highlighter-rouge">tlsKeyStoreType</code></td> |
| </tr> |
| <tr> |
| <td>clientKeyStore</td> |
| <td>Replaced by <code class="highlighter-rouge">tlsKeyStore</code></td> |
| </tr> |
| <tr> |
| <td>clientKeyStorePasswordPath</td> |
| <td>Replaced by <code class="highlighter-rouge">tlsKeyStorePasswordPath</code></td> |
| </tr> |
| <tr> |
| <td>clientTrustStoreType</td> |
| <td>Replaced by <code class="highlighter-rouge">tlsTrustStoreType</code></td> |
| </tr> |
| <tr> |
| <td>clientTrustStore</td> |
| <td>Replaced by <code class="highlighter-rouge">tlsTrustStore</code></td> |
| </tr> |
| <tr> |
| <td>clientTrustStorePasswordPath</td> |
| <td>Replaced by <code class="highlighter-rouge">tlsTrustStorePasswordPath</code></td> |
| </tr> |
| <tr> |
| <td>registrationClientClass</td> |
| <td>The registration client class used by client to discover registration service. It is replaced by <code class="highlighter-rouge">metadataServiceUri</code>.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h5 id="changed-settings-2">Changed Settings</h5> |
| |
| <p>The default values of following settings are changed since 4.7.0.</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Old Default Value</th> |
| <th>New Default Value</th> |
| <th>Notes</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>enableDigestTypeAutodetection</td> |
| <td>false</td> |
| <td>true</td> |
| <td>Autodetect the digest type and passwd when opening a ledger. It will ignore the provided digest type, but still verify the provided passwd.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h3 id="47x-to-48x-upgrade">4.7.x to 4.8.X upgrade</h3> |
| |
| <p>In 4.8.x a new feature is added to persist explicitLac in FileInfo and explicitLac entry in Journal. (Note: Currently this feature is not available if your ledgerStorageClass is DbLedgerStorage, ISSUE #1533 is going to address it) Hence current journal format version is bumped to 6 and current FileInfo header version is bumped to 1. But since default config values of ‘journalFormatVersionToWrite’ and ‘fileInfoFormatVersionToWrite’ are set to older versions, this feature is off by default. To enable this feature those config values should be set to current versions. Once this is enabled then we cannot rollback to previous Bookie versions (4.7.x and older), since older version code would not be able to deal with explicitLac entry in Journal file while replaying journal and also reading Header of Index files / FileInfo would fail reading Index files with newer FileInfo version. So in summary, it is a non-rollbackable feature and it applies even if explicitLac is not being used.</p> |
| |
| <h3 id="45x-to-46x-upgrade">4.5.x to 4.6.x upgrade</h3> |
| |
| <p>There isn’t any protocol related backward compabilities changes in 4.6.x. So you can follow the general upgrade sequence to upgrade from 4.5.x to 4.6.x.</p> |
| |
| <h3 id="44x-to-45x-upgrade">4.4.x to 4.5.x upgrade</h3> |
| |
| <p>There isn’t any protocol related backward compabilities changes in 4.5.0. So you can follow the general upgrade sequence to upgrade from 4.4.x to 4.5.x. |
| However, we list a list of things that you might want to know.</p> |
| |
| <ol> |
| <li>4.5.x upgrades netty from 3.x to 4.x. The memory usage pattern might be changed a bit. Netty 4 uses more direct memory. Please pay attention to your memory usage |
| and adjust the JVM settings accordingly.</li> |
| <li><code class="highlighter-rouge">multi journals</code> is a non-rollbackable feature. If you configure a bookie to use multiple journals on 4.5.x you can not roll the bookie back to use 4.4.x. You have |
| to take a bookie out and recover it if you want to rollback to 4.4.x.</li> |
| </ol> |
| |
| <p>If you are planning to upgrade a non-secured cluster to a secured cluster enabling security features in 4.5.0, please read <a href="../../security/overview">BookKeeper Security</a> for more details.</p> |
| |
| </section> |
| |
| |
| </div> |
| </div> |
| |
| <div class="column is-2 is-hidden-mobile"> |
| |
| |
| <div class="toc"> |
| <h2 class="title">Upgrade</h2> |
| <ul class="section-nav"> |
| <li class="toc-entry toc-h2"><a href="#overview">Overview</a></li> |
| <li class="toc-entry toc-h2"><a href="#canary">Canary</a> |
| <ul> |
| <li class="toc-entry toc-h3"><a href="#rollback-canaries">Rollback Canaries</a></li> |
| </ul> |
| </li> |
| <li class="toc-entry toc-h2"><a href="#upgrade-steps">Upgrade Steps</a> |
| <ul> |
| <li class="toc-entry toc-h3"><a href="#upgrade-bookies">Upgrade Bookies</a></li> |
| </ul> |
| </li> |
| <li class="toc-entry toc-h2"><a href="#upgrade-guides">Upgrade Guides</a> |
| <ul> |
| <li class="toc-entry toc-h3"><a href="#46x-to-470-upgrade">4.6.x to 4.7.0 upgrade</a> |
| <ul> |
| <li class="toc-entry toc-h4"><a href="#common-configuration-changes">Common Configuration Changes</a> |
| <ul> |
| <li class="toc-entry toc-h5"><a href="#new-settings">New Settings</a></li> |
| <li class="toc-entry toc-h5"><a href="#deprecated-settings">Deprecated Settings</a></li> |
| <li class="toc-entry toc-h5"><a href="#changed-settings">Changed Settings</a></li> |
| </ul> |
| </li> |
| <li class="toc-entry toc-h4"><a href="#server-configuration-changes">Server Configuration Changes</a> |
| <ul> |
| <li class="toc-entry toc-h5"><a href="#new-settings-1">New Settings</a></li> |
| <li class="toc-entry toc-h5"><a href="#deprecated-settings-1">Deprecated Settings</a></li> |
| <li class="toc-entry toc-h5"><a href="#changed-settings-1">Changed Settings</a></li> |
| </ul> |
| </li> |
| <li class="toc-entry toc-h4"><a href="#client-configuration-changes">Client Configuration Changes</a> |
| <ul> |
| <li class="toc-entry toc-h5"><a href="#new-settings-2">New Settings</a></li> |
| <li class="toc-entry toc-h5"><a href="#deprecated-settings-2">Deprecated Settings</a></li> |
| <li class="toc-entry toc-h5"><a href="#changed-settings-2">Changed Settings</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toc-entry toc-h3"><a href="#47x-to-48x-upgrade">4.7.x to 4.8.X upgrade</a></li> |
| <li class="toc-entry toc-h3"><a href="#45x-to-46x-upgrade">4.5.x to 4.6.x upgrade</a></li> |
| <li class="toc-entry toc-h3"><a href="#44x-to-45x-upgrade">4.4.x to 4.5.x upgrade</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| |
| |
| |
| </div> |
| </div> |
| </div> |
| |
| |
| |
| <div id="entry-popover-html" class="popover-template"> |
| <p>An entry is a sequence of bytes (plus some metadata) written to a BookKeeper ledger. Entries are also known as records.</p> |
| |
| </div> |
| |
| <div id="ledger-popover-html" class="popover-template"> |
| <p>A ledger is a sequence of entries written to BookKeeper. Entries are written sequentially to ledgers and at most once, giving ledgers append-only semantics.</p> |
| |
| </div> |
| |
| <div id="bookie-popover-html" class="popover-template"> |
| <p>A bookie is an individual BookKeeper storage server.</p> |
| |
| <p>Bookies store the content of ledgers and act as a distributed ensemble.</p> |
| |
| </div> |
| |
| <div id="rereplication-popover-html" class="popover-template"> |
| <p>A subsystem that runs in the background on bookies to ensure that ledgers are fully replicated even if one bookie from the ensemble is down.</p> |
| |
| </div> |
| |
| <div id="striping-popover-html" class="popover-template"> |
| <p>Striping is the process of distributing BookKeeper ledgers to sub-groups of bookies rather than to all bookies in a BookKeeper ensemble.</p> |
| |
| <p>Striping is essential to ensuring fast performance.</p> |
| |
| </div> |
| |
| <div id="striped-popover-html" class="popover-template"> |
| <p>Striping is the process of distributing BookKeeper ledgers to sub-groups of bookies rather than to all bookies in a BookKeeper ensemble.</p> |
| |
| <p>Striping is essential to ensuring fast performance.</p> |
| |
| </div> |
| |
| <div id="journal-popover-html" class="popover-template"> |
| <p>A journal file stores BookKeeper transaction logs.</p> |
| |
| </div> |
| |
| <div id="fencing-popover-html" class="popover-template"> |
| <p>When a reader forces a ledger to close, preventing any further entries from being written to the ledger.</p> |
| |
| </div> |
| |
| <div id="record-popover-html" class="popover-template"> |
| <p>A record is a sequence of bytes (plus some metadata) written to a BookKeeper ledger. Records are also known as entries.</p> |
| |
| </div> |
| |
| |
| <script type="text/javascript"> |
| |
| tippy('#entry-popover', { |
| html: '#entry-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#ledger-popover', { |
| html: '#ledger-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#bookie-popover', { |
| html: '#bookie-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#rereplication-popover', { |
| html: '#rereplication-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#striping-popover', { |
| html: '#striping-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#striped-popover', { |
| html: '#striped-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#journal-popover', { |
| html: '#journal-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#fencing-popover', { |
| html: '#fencing-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#record-popover', { |
| html: '#record-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| </script> |
| |
| </main> |
| |
| <footer class="footer"> |
| <div class="container"> |
| <div class="content has-text-centered"> |
| <p> |
| Copyright © 2016 - 2021 <a href="https://www.apache.org/">The Apache Software Foundation</a>,<br /> licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, version 2.0</a>. |
| </p> |
| <p> |
| Apache BookKeeper, BookKeeper®, Apache®, the Apache feature logo, and the Apache BookKeeper logo are either registered trademarks or trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| </div> |
| </footer> |
| |
| </body> |
| |
| <script src="/js/app.js"></script> |
| |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| http://www.apache.org/licenses/LICENSE-2.0 |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <script> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-104419626-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| |
| |
| </html> |
