Uniform Bootstrap Operation

Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History


Project/Component Working Name:

Unibrow: Uniform Bootstrap Operation

(UNIBROw comes from UNIform BootstRap Operation)

Name of Document Author/Supplier:

Matt Ingenthron <matt@couchbase.com>

Date of this Document:

28 August 2013

Proposal Status:


Name of Major Document Customer(s)/Consumer(s):

SDK Development Team


couchbase@googlegroups.com mailing list

Project Summary:

Change the bootstrapping of all clients to have consistent behavior.  Allow for both deterministic and random bootstrapping from a cluster and for dynamic updates to the bootstrap list past the initial list supplied by the application developer/operator.

Project Description:

Current bootstrapping can vary from client to client.  Project CCCP will get to a much more regular and long-term-supportable approach, but it would be good to have a short term approach to cover a few things.  First, it would be good for all client libraries to handle bootstrapping in the same way.  Second, currently there are some situations where random bootstrapping, by which we mean selecting a bootstrap node at random, is preferred to deterministic bootstrapping.  Some clients support this already and do it by default, where other clients do only deterministic bootstrapping.  Third, we want the ability to change the bootstrap list without a restart of an application.  It is somewhat complicated from a maintenance perspective to do a complete cluster swap currently, as the application needs to be reconfigured/restarted first.  Notably, the Java client can't currently handle a complete cluster swap and has no (built-in) method of configuration which can be done dynamically.

Risks and Assumptions:

The UNIBROw project assumes that it can be delivered over the regular release cycle of the client libraries.  It also has no dependencies on changes to the Couchbase Cluster.

Business Summary

Problem Area:

See description above.


The market is any deployment which may likely need to do a full cluster swap.  This is quite possible in cloud deployments.  For instance, at one point Amazon asked all of their customers in a given region to "move" to new instances.  They gave some notice, but it was still intrusive.  This kind of use case can come up with clusters for version upgrades, deployments in certain environments, etc.

How will you know when you are done?

The changes and feature tests will be integrated in each client library and tested.

Situational tests around full cluster tests will be carried out.

Technical Description


This project would be a simple set of changes per client library.  In the end, each client library must have a way to configure...

  1. A list of bootstrap URIs (this already exists)
  2. A way to configure the client to use those URIs either...
    1. In order supplied (thus, every client will deterministically have the same configuration)
    2. In a random order (thus, clients could end up in different places if not all of the URIs go to the same cluster)
  3. A configuration file approach, idiomatic to the platform (i.e. yaml for Ruby, properties files for Java) which can allow for the reconfiguration of URIs without restarting the application.

Issues/Issues to be Opened:

jiraissues: Unable to determine if sort should be enabled.

Other Solutions Previously Considered:

Project CCCP is the long term solution which has been accepted, but requires a bigger set of changes.

In Scope:

Phase one, changes to libcouchbase, the Java client and the Python client.  Phase two, changes to the PHP client, the Ruby client and the node.js client.

Out of Scope:

Changes to moxi to be UNIBROw compliant.

Any testing with load balancers for traffic.

Any attempt to compensate for misconfigured or unusual DNS/hostname configurations. In the current implementation, the cluster and cluster configuration control node hostnames (or IP addresses, which we unfortunately default to) and publish this via the configuration. A consistent set of name resolution for the hosts participating in the cluster and client-side application logic are expected.  Note MB-8985 covers documentation changes for this.


New configuration options for either random or ordered selection of a URI.

Configuration files to be defined/documented per client library.

Doc Impact:

Updates to each client library's documentation on how to use the new configuration options and the new configuration files.

Admin/Config Impact:

To migrate to the new approach, software developers may need to make changes to their client configuration and/or software. The specific changes are not to be covered in the scope of this document.

There is no administration impact anticipated, other than possibly needing to deploy new client libraries and optionally enable this functionality with new configuration files and/or small code changes.

Packaging and Delivery Impact:

New dot-minor versions of all components mentioned would be required. Given that no existing interfaces are expected to be removed, there is no additional impact over a regular dot-minor upgrade.

Security Impact:

None, though documentation should indicate the proper permissions for configuration files.



Reference Documents:


Resources and Schedule

Projected Availability:

Phase one in mid September.  Phase two as other SDKs are updated.

Cost of Effort:

Estimated as a day or two per client library, plus changes to SDKQE test cycles which are just in number of arguments.

Prototype Availability

Prototype Availability:

This project is small enough that no prototype is required.

Prototype Cost:

Not applicable.


Initial publication for REVIEW on 27 August, 2013.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.