Skip to content

Commit

Permalink
Vulcan Installation and Deployment IA Changes (#2731)
Browse files Browse the repository at this point in the history 
* DOC-3649 Information architecture changes.

* DOC-3649 More changes for IA re-org of install docs

* New topic (unfinished) for container compatibility

* DOC-3649 Minor updates to deployment options

* DOC-3649 Remove draft container compatibility list

* DOC-3649 Change top-level deployment topics for new IA design

* DOC-3649 Mild refactoring of installation prerequisites (system requirements) topics

* Revert "DOC-3649 Change top-level deployment topics for new IA design"

This reverts commit c95644e2efa8e0ead84cd3c57936b59ee08db642.

* Revert "Revert "DOC-3649 Change top-level deployment topics for new IA design""

This reverts commit 82cad4dc79439c6f60ae0d0f402621acc572bdde.

* DOC-3649 Update cluster verification topic

* DOC-3649 Update ditamap for deployment topic changes

* DOC-3649 Merged content from deploy-with-docker-hub.dita to make universal VM and container best practices

* DOC-3649 Updated three-node bet practices

* DOC-3649 Minor updates to install-specifc security topic.

* DOC-3649 Initial pass at container IA changes (UNFINISHED)

* DOC-3649 Final cleanup of Docker changes for new install IA

* DOC-3649 Final container IA updates

* DOC-3649 Clean up deployment guidelines, minor edits to sizing guidelines.

* DOC-3649 Remove download instructions from top-level and moved uninstall instructions.

* DOC-3649 Incorporate updated ports

* DOC-3649 Update table formatting
  • Loading branch information
@eric-schneider @amarantha-k
eric-schneider authored and amarantha-k committed Aug 2, 2018
1 parent 001f43f commit 4db6dee
Show file tree
Hide file tree
Showing 23 changed files with 1,606 additions and 1,316 deletions.
10 changes: 3 additions & 7 deletions content/clustersetup/failover.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,9 @@
when a node is unavailable and then initiate a hard failover.</dd>
</dlentry>
</dl>
<p>Keep in mind that each of the Couchbase Services reacts
differently to failover. For example, if you have the
services separated on different nodes
using <xref href="services-mds.dita#concept_evc_1vz_nr"
>Multi-Dimensional Scaling (MDS</xref>), you can
failover and recover nodes separately. If
you are mixing the services on the same nodes, it is slightly more complex.
<p>Keep in mind that each of the Couchbase Services reacts differently to failover. For example,
if you have the services separated on different nodes, you can failover and recover nodes
separately. If you are mixing the services on the same nodes, it is slightly more complex.
Failover regarding all services will be discussed in this section.</p>

<section><title>Choosing a Failover Solution when Nodes are Unhealthy</title>
Expand Down
131 changes: 75 additions & 56 deletions content/install/best-practices-vm.dita
View file
Original file line number Diff line number Diff line change
@@ -1,77 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic_sg3_1fz_bx">
<title>Deployment Considerations for Virtualized or Containerized Environments</title>
<shortdesc>Virtualized platforms such as AWS, VMware, Azure, and Docker containers are popular
ways of achieving hardware scalability to complement Couchbase Server's scalability. In this
section, we describe some considerations when running Couchbase Server on a virtualized
platform. These considerations are common across any virtualized platform or container
infrastructure, and are not specific to Couchbase Server.</shortdesc>
<title>Deployment Considerations for Virtual Machines and Containers</title>
<shortdesc>Virtualized platforms such as VMware, AWS/Azure/GCP, and Docker (containers) are
popular ways of achieving hardware scalability to complement Couchbase Server's software
scalability. </shortdesc>
<body>
<p>When deploying Couchbase Server on a virtualized platform, some extra considerations should
be made.</p>
<p><b>Avoid a Single Point of Failure</b></p>
<p>Couchbase Server's resilience and high-availability are achieved through creating a cluster
of independent nodes and replicating data between them so that any individual node failure
doesn't lead to loss of access to your data. In a virtualized environment, if you were to run
multiple nodes on the same host or physical hardware, you are inadvertently re-introducing a
single point of failure. In environments where you control the VM placement, we recommend that
each Couchbase Server node runs on a different piece of physical hardware.</p>
<p><b>Sizing your Virtualized Platform</b>
doesn't lead to loss of access to your data. In a virtualized environment, if you run multiple
nodes on the same host or physical hardware, you are inadvertently re-introducing a single
point of failure. In environments where you control the virtual machine (VM) placement, it is
recommended that each Couchbase Server node runs on a different piece of physical
hardware.</p>
<p><b>Sizing a Virtualized Deployment</b>
</p>
<p>Physical environments tend to provide greater performance, predictability and simplicity over
virtualized environments. Virtualization carries much greater flexibility but does add an
additional layer of complexity which can make both sizing correctly and debugging performance
issues more difficult. We recommend that you have at least 4 cores and, if these are
virtualized, make sure these are dedicated to the VM rather than shared across multiple VMs.
For more information on the hardware requirements, see <xref href="pre-install.dita"/>. </p>
<p>Disk performance is also an important aspect - and there are many different technologies you
can choose. The general rule of thumb is to make sure that your disk has sufficient throughput
to handle the CRUD operations as well as any indexing, compaction and backup activities that
will be required.</p>
<p><b>Avoid Over-committing your Resource</b></p>
<p>One of the major benefits of virtualization is the ability to share physical resources and
even <i>over-commit</i> on these resources (meaning each VM can think it has more disk/RAM/CPU
than is actually physically available). One side effect of this is that an individual VM's
performance can vary based on what load other VMs are placing upon the physical resources. If
your application requires consistent performance, ensure that you guard against
over-committing when configuring your VMs. We recommend ensuring your Couchbase Server VMs
have dedicated physical resource and the hardware resource is not over-committed.</p>
<p><b>AutoFailover Threshold</b></p>
<p>Due to the fact the system is running virtualized on top of a hypervisor or Docker engine,
there will be a minor CPU performance overhead. In certain circumstances this can mean that
our default auto-failover timeout can be a little too sensitive. We recommend increasing the
threshold from 30 to 45 or even 60 seconds. depending how CPU-intensive your workload is.</p>
<p>The performance characteristics of physical hardware are well understood. Even though VMs
insert a lightweight layer between Couchbase Server and the underlying OS, there is still a
small overhead when running Couchbase Server on a virtual platform.</p>
<p>For stability and better performance predictability, you should dedicate at least two CPU
cores to a VM in development environments, and four CPU cores to a VM in production.</p>
<p>Disk performance is also an important factor - and there are many different technologies you
can choose. The general rule of thumb is to make sure that the disk has sufficient throughput
to handle the necessary CRUD operations, as well as any indexing, compaction, and backup
activities that will be required.</p>
<p>
<note>One of the major benefits of virtualization is the ability to share physical resources
and even <i>over-commit</i> these resources (meaning each virtual instance can think it has
more CPU, RAM, or disk space than is actually physically available). However, in an
over-committed environment, you can end up with containers competing with each other causing
unpredictable performance and sometimes stability issues.<p>For Couchbase Server, physical
resources should be dedicated to the VM, rather than shared across multiple VMs. For more
information about hardware requirements, see <xref href="pre-install.dita"/>. </p></note>
</p>
<p><b>Auto-Failover Threshold</b></p>
<p>Due to the fact that the VM is running on top of a hypervisor or container engine, there will
be a minor CPU performance overhead. In certain circumstances, the default auto-failover
timeout in Couchbase can cause some issues. It is recommended that you change the threshold
from 30 seconds (the default), to 45 or even 60 seconds, depending on how CPU-intensive your
workload is.</p>
<p><b>Live Migration</b></p>
<p>Some virtualization environments allow VMs to be migrated between physical nodes and/or
between storage backends. When moving the VM there is the potential for small pauses and
network disruption which may affect the scheduler and could trigger a failover. When changing
the backend storage, disk queues, compaction or indexing may be affected, which could have a
knock-on effect on general performance. We recommend that you use Couchbase's built-in
rebalance mechanism for maintenance. If it is absolutely necessary to perform a migration,
then disable auto-failover beforehand and be prepared for a performance impact during the
migration. Pausing / Resuming and snapshotting virtual machines can also have the same effect,
these actions should only be performed on a Couchbase Server node which has been removed from
the cluster.</p>
<section><title>Additional Considerations for Containers</title>
between storage backends. When moving the VM, there is the potential for small pauses and
network disruption, which has the potential to affect the scheduler, which in turn could
trigger a failover. When changing the backend storage, disk queues, compaction, or indexing
may be affected, which could have a knock-on effect on general performance. Therefore, it is
recommended that use Couchbase's built-in rebalance mechanism for maintenance.</p>
<p>If it is absolutely necessary to perform a migration, then disable auto-failover beforehand
and be prepared for a performance impact during the migration. Pausing, resuming, and
snapshotting virtual machines can also have the same effect. These actions should only be
performed on a Couchbase Server node which has been removed from the cluster.</p>
<section>
<title>Additional Considerations for Containers</title>
<p>This section lists the additional considerations that are applicable only to
containers.</p>
<p><b>Map Couchbase Node Specific Data to a Local Folder</b></p>
<p>A Couchbase Server Docker container writes all persistent and node-specific data to the directory <filepath>/opt/couchbase/var</filepath> by default. It is recommended to map this directory to a directory on the host file system using the <codeph>-v</codeph> option to get persistence and performance when using "docker run".</p>
<p>By mapping the directory <filepath>/opt/couchbase/var</filepath> to a directory outside the container with the <codeph>-v</codeph> option, you can delete the container and recreate it later without losing your data from Couchbase Server. You can even update to a container running a later release/version of Couchbase Server without losing your data.</p>
<p>In a standard Docker environment using a union file system, leaving <filepath>/opt/couchbase/var</filepath> inside the container results in some amount of performance degradation.</p>
<note>If you have SELinux enabled, mounting the host volumes in a container requires an extra
step. Assuming you are mounting the <filepath>~/couchbase</filepath> directory on the host
file system, you need to run the following command once before running your first container
on that host:
<codeblock>mkdir ~/couchbase &amp;&amp; chcon -Rt svirt_sandbox_file_t ~/couchbase</codeblock></note>
<p><b>Map Couchbase Node Specific Data to a Local Folder</b></p>
<p>A Couchbase Server container writes all persistent and node-specific data to
<filepath>/opt/couchbase/var</filepath> by default. It is recommended to map this
directory to a directory on the host file system using the <codeph>-v</codeph> option to get
persistence and performance when using <codeph>docker run</codeph>.</p>
<p>By mapping the directory <filepath>/opt/couchbase/var</filepath> to a directory outside the
container with the <codeph>-v</codeph> option, you can delete the container and recreate it
later without losing your data from Couchbase Server. You can even update to a container
running a later release/version of Couchbase Server without losing your data.</p>
<p>In a standard Docker environment using a union file system, leaving
<filepath>/opt/couchbase/var</filepath> inside the container results in some amount of
performance degradation.</p>
<note>If you have SELinux enabled, mounting the host volumes in a container requires an extra
step. Assuming you're mounting the <filepath>~/couchbase</filepath> directory on the host
file system, you need to run the following command once before running your first container
on that host:
<codeblock>mkdir ~/couchbase &amp;&amp; chcon -Rt svirt_sandbox_file_t ~/couchbase</codeblock></note>
<p><b>Increase ULIMIT in Production Deployments</b></p>
<p>Couchbase Server normally expects the following changes to <parmname>ulimits</parmname>:</p>
<p>Couchbase Server normally expects the following changes to
<parmname>ulimits</parmname>:</p>
<codeblock>ulimit -n 40960 # nofile: max number of open files
ulimit -c unlimited # core: max core file size
ulimit -l unlimited # memlock: maximum locked-in-memory address space</codeblock>
<p>These <parmname>ulimit</parmname> settings are necessary when running under heavy load. If you are just doing light testing and development, you can omit these settings, and everything will still work. To set the ulimits in your container, you need to run Couchbase Docker containers with the following additional <codeph>--ulimit</codeph> flags: </p><codeblock>docker run -d --ulimit nofile=40960:40960
<p>These <parmname>ulimit</parmname> settings are necessary when running under heavy load. If
you are just doing light testing and development, you can omit these settings, and
everything will still work. To set the ulimits in your container, you need to run Couchbase
Docker containers with the following additional <codeph>--ulimit</codeph> flags: </p>
<codeblock>docker run -d --ulimit nofile=40960:40960
--ulimit core=100000000:100000000 --ulimit memlock=100000000:100000000
--name db -p 8091-8094:8091-8094 -p 11210:11210 couchbase</codeblock>
<p>Since unlimited is not supported as a value, it sets the <codeph>core</codeph> and <codeph>memlock</codeph> values to 100 GB. If your system has more than 100 GB RAM, increase this value to match the available RAM on the system.</p><note>The <codeph>--ulimit</codeph> flags only work on Docker 1.6 or later.</note>
<p>Since <codeph>unlimited</codeph> is not supported as a value, it sets the
<codeph>core</codeph> and <codeph>memlock</codeph> values to 100 GB. If your system has
more than 100 GB RAM, increase this value to match the available RAM on the system.</p>
<note>The <codeph>--ulimit</codeph> flags only work on Docker 1.6 or later.</note>
</section>
</body>
</topic>
Loading

0 comments on commit 4db6dee

Please sign in to comment.