Skip to content

DOC-12540 AVX2 requirements #3917

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: release/8.0
Choose a base branch
from
Open

DOC-12540 AVX2 requirements #3917

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
518fe54
* Removed the vector-search specific language around the AVX2 require…
ggray-cb Oct 10, 2025
e892b9d
Deleting unneeded files
ggray-cb Oct 10, 2025
22c187b
Removing deprecated notice for AVX2 because it is actually a requirem…
ggray-cb Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 101 additions & 122 deletions modules/install/pages/pre-install.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= System Resource Requirements
:description: Although resource requirements will largely depend on the size and resource demands of your Couchbase deployment, there are some minimum and recommended specifications that you should follow.
:description: Although resource requirements depend on the size and resource demands of your Couchbase deployment, there are some minimum and recommended specifications that you should follow.

[abstract]
{description}
Expand All @@ -9,25 +9,66 @@
Couchbase Server can run on x86 and ARM processors (including Apple Silicon processors).
This section explains the minimum requirements for of these platforms.


[#x86-processors]
=== x86 Processors


[#avx2-requirements]
.deprecation notice
[IMPORTANT]
====
The use of older x86 processors that do not implement the https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#AVX2[Advanced Vector Extensions 2 (AVX2)] instruction set are deprecated in Couchbase Server 7.6.x.
Future versions will require processors that have AVX2 support.
This requirement is only for x86 processors--ARM processors have a separate set of vector instructions.
Couchbase Server has the following requirements when running on x86 processors:

|===
| Node Use | CPU | RAM | Storage

| *Minimum Production Use*
| 2 GHz 2-core x86_64 CPU supporting SSE4.2 and AVX2 (see <<avx2-requirement-for-x86-processors>> for more information)
| 4 GiB (physical)
| 8 GiB (block-based; HDD, SSD, EBS, iSCSI)

| *Recommended Production Use*
| 3 GHz 4-core x86_64 CPU supporting SSE4.2 and above and AVX2 or above
| 16 GiB (physical) and above
| 16 GiB and above (SSD)

| *Using XDCR and Views*
| 3 GHz 6-core x86_64 CPU supporting SSE4.2 and AVX2
| 16 GiB (physical) and above
| 16 GiB and above (SSD)

| *Minimum for Backup Administration Nodes*
| 3 GHz 4-core x86_64 CPU supporting SSE4.2 and above and AVX2
| 8GiB RAM
| 16 GiB and above (SSD)

| *Recommended for Backup Administration Nodes*
| 3 GHz 16-core core x86_64 CPU supporting SSE4.2 and above and AVX2
| 16GiB RAM
| 16 GiB and above (SSD)

| *Minimum for Development and Testing*
| 1 GHz single core x86_64 CPU supporting SSE4.2 and AVX
| 1 GiB free beyond operating system requirements
| 8 GiB

|===

NOTE: For all storage configuration, network file systems such as CIFS and NFS are not supported.

The recommendations in the table ae a baseline that do not take into account the services you will run on your nodes.
Copy link

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected spelling of 'ae' to 'are'.

Suggested change
The recommendations in the table ae a baseline that do not take into account the services you will run on your nodes.
The recommendations in the table are a baseline that do not take into account the services you will run on your nodes.

Copilot uses AI. Check for mistakes.

Each service adds its own requirements.
See xref:sizing-general.adoc[] to see the additional requirements for each service.

[#avx2-requirement-for-x86-processors]
==== Instruction Set Requirements for x86 Processors

On x86 platforms, Couchbase Server requires processors that have SSE4.2 and AVX2 support.
AVX2 (Advanced Vector Extensions 2) was introduced later than SSE4.2.
The earliest processors that support AVX2 instructions include:

* Intel 4th generation (Haswell) Core processors released in 2013.
* Intel 11th generation (Tiger Lake) Celeron and Pentium processors released in 2020.
* AMD Excavator processors released in 2015.

Processors from these or later generations will be required to run Couchbase Server in the future.
See the Wikipedia page https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#CPUs_with_AVX2[CPUs with AVX2^] for more detail about the processors that support this instruction set.

On Linux, you can tell if your processor has the AVX2 instructions by executing the following command:

Expand All @@ -37,132 +78,70 @@ grep -q -i 'avx2' /proc/cpuinfo && \
echo "Processor has AVX2" || echo "AVX2 not found"
----

If the command returns the text `Processor has AVX2`, your processor is supported in future Couchbase Server releases.
If the command returns `AVX2 not found`, your processor does not have AVX2 instructions and will not be supported in future Couchbase Server versions.
====


Couchbase Server has the following requirements when running on x86 processors.


[cols="80,180,180"]
|===
| | Minimum Specifications<<#note1,*>> | Recommended Specifications<<#note2,**>>

| *CPU*
| 2 GHz dual core x86_64 CPU supporting SSE4.2

xref:vector-search:vector-search.adoc[Vector Search] requires a CPU supporting Advanced Vector Extensions 2 (AVX2) instructions.
See <<vector_cpu_requirements>> for more information.



| 3 GHz quad core x86_64 CPU supporting SSE4.2 and above

3 GHz six core x86_64 CPU supporting SSE4.2 when using Cross Datacenter Replication (XDCR) and Views

| *RAM*
| 4 GiB (physical)
| 16 GiB (physical) and above

| *Storage (disk space)*
a|
8 GiB (block-based; HDD, SSD, EBS, iSCSI)

Network file systems such as CIFS and NFS are not supported.
a|
16 GiB and above (SSD)

Network file systems such as CIFS and NFS are not supported.

3+a|
[IMPORTANT]
.Backup Nodes
=====
If the node is used for administering backups, then be aware that the resource requirements will be higher.

The minimum hardware requirement is four CPU cores and 8GiB RAM.

The recommended hardware is sixteen CPU cores, 16GiB RAM, and SSD disks.
If the command returns the text `Processor has AVX2`, your processor meets Couchbase Server's AVX2 requirement.
If the command returns `AVX2 not found`, your processor does not have AVX2 instructions is not supported.
Copy link

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence has incorrect grammar. It should read 'your processor does not have AVX2 instructions and is not supported' or 'your processor does not have AVX2 instructions, so it is not supported'.

Suggested change
If the command returns `AVX2 not found`, your processor does not have AVX2 instructions is not supported.
If the command returns `AVX2 not found`, your processor does not have AVX2 instructions and is not supported.

Copilot uses AI. Check for mistakes.

Couchbase Server refuses to start on x86 that do not have AVX2 features.

=====


|===
NOTE: The Rosetta feature of MacOS lets you run x86 binaries on Apple Silicon.
Rosetta in versions of MacOS earlier than Sequoia (version 15, released in September of 2024) does not implement the AVX2 instructions.
While Rosetta in MacOS Sequoia does support AVX2 instructions, running on this platform may result in slower performance because the instructions are emulated instead of being native.
For the best performance on Apple Silicon systems, use the native Apple Silicon build of Couchbase Server instead of the x86 build running in Rosetta.

=== ARM Processors

Couchbase Server has the following requirements when running on ARM-based platforms.

Couchbase Server has the following requirements when running on ARM-based platforms:

[cols="80,180,180"]
|===
| | Minimum Specifications<<#note1,*>> | Recommended Specifications<<#note2,**>>

| *CPU*
| 2 Ghz dual core 64bit ARM v8 CPU
| 2.5 Ghz quad core 64bit ARM v8 CPU

| *RAM*
| 4 GiB (physical)
| 16 GiB (physical) and above

| *Storage (disk space)*
a|
8 GiB (block-based; HDD, SSD, EBS, iSCSI)

Network file systems such as CIFS and NFS are not supported.
a|
16 GiB and above (SSD)

Network file systems such as CIFS and NFS are not supported.

3+a|
[IMPORTANT]
.Backup Nodes
=====
If the node is used for administering backups, then be aware that the resource requirements will be higher.

The minimum hardware requirement is four CPU cores and 8GiB RAM.

The recommended hardware is sixteen CPU cores, 16GiB RAM, and SSD disks.
=====

| Node Use | CPU | RAM | Storage

| *Minimum Production Use*
| 2 Ghz dual core 64-bit ARM v8 CPU
| 4 GiB (physical)
| 8 GiB (block-based; HDD, SSD, EBS, iSCSI)

| *Recommended Production Use*
| 2.5 Ghz 4-core 64-bit ARM v8 CPU
| 16 GiB (physical) and above
| 16 GiB and above (SSD)

| *Using XDCR and Views*
| 2.5 Ghz 6-core 64-bit ARM v8 CPU
| 16 GiB (physical) and above
| 16 GiB and above (SSD)

| *Minimum for Backup Administration Nodes*
| 2.5 Ghz 4-core 64-bit ARM v8 CPU
| 8GiB RAM
| 16 GiB and above (SSD)

| *Recommended for Backup Administration Nodes*
| 2.5 Ghz 16-core 64-bit ARM v8 CPU
| 16GiB RAM
| 16 GiB and above (SSD)

| *Minimum for Development and Testing*
| 1 GHz single core 64-bit ARM v8 CPU
| 1 GiB free beyond operating system requirements
| 8 GiB

|===

[#note1]
^*^You can reduce the CPU and RAM resources below the Minimum Specifications for development and testing purposes.
Resources can be as low as 1 GB of free RAM beyond operating system requirements, and a single CPU core.
However, you must adhere to the Minimum Specifications for production._

**_The Recommended Specifications don't take into account your intended workload.
You should follow the xref:sizing-general.adoc[sizing guidelines] when determining system specifications for your Couchbase Server deployment._

[#vector_cpu_requirements]
== Vector Search CPU Requirements

On x86 systems, the Vector Search feature in Couchbase Server version 7.7 and later uses Advanced Vector Extensions 2 (AVX2) instructions to improve search performance.
To use the Vector Search feature, your x86 system must support these instructions.
Most Intel processors from 2013 and later and most AMD processors from 2015 and later support these instructions.
See https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#CPUs_with_AVX2[CPUs with AVX2^] for more detail about the processors that support this instruction set.

Using Vector Search on an unsupported x86 platform can result in search and indexer processes exiting with errors.

ARM-based systems do not have this requirement.

NOTE: The Rosetta feature of MacOS lets you run x86 binaries on Apple Silicon.
Rosetta in versions of MacOS earlier than Sequoia (version 15, released in September of 2024) does not implement the AVX2 instructions.
Therefore, if you run the x86 version of Couchbase Server using Rosetta on earlier MacOS versions, you cannot use the Vector Search feature.
While Rosetta in MacOS Sequoia does support AVX2 instructions, running Vector Search on this platform may result in slower performance because the instructions are emulated instead of being native.
For the best performance on Apple Silicon systems, use the native Apple Silicon build of Couchbase Server instead of the x86 build running in Rosetta.
NOTE: For all storage configuration, network file systems such as CIFS and NFS are not supported.

The recommendations in the table ae a baseline that do not take into account the services you will run on your nodes.
Copy link

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected spelling of 'ae' to 'are' (duplicate of earlier occurrence).

Suggested change
The recommendations in the table ae a baseline that do not take into account the services you will run on your nodes.
The recommendations in the table are a baseline that do not take into account the services you will run on your nodes.

Copilot uses AI. Check for mistakes.

Each service adds its own requirements.
See xref:sizing-general.adoc[] to see the additional requirements for each service.

[#clock-source-linux]
== Clock Source on Linux
The Query service uses the OS monotonic clock for profiling and network timeout purposes.

The Linux kernel uses the _Clock Source_ to obtain the current clock value and this information is stored in `/sys/devices/system/clocksource/clocksource0/current_clocksource`. There are several clock sources (TSC, XEN, and others), which are used depending on the hardware clock capabilities, and the OS installation. The XEN source, which is seen to be the default on AWS setups, can use up to 25% of all available CPU time to obtain the current timestamp. The TSC clock source, on the other hand, incurs very little CPU cost. We recommend changing the clock source to TSC if it is set to anything else.
The Query Service uses the OS monotonic clock for profiling and network timeout purposes.

The Linux kernel uses the Clock Source to obtain the current clock value.
It stores this information in `/sys/devices/system/clocksource/clocksource0/current_clocksource`.
Several clock sources exist (TSC, XEN, and others) which are used depending on the hardware clock capabilities and the OS installation.
The XEN source, which is the default on AWS setups, can use up to 25% of all available CPU time to obtain the current timestamp.
The TSC clock source, on the other hand, has a low CPU cost.
Therefore, you should change the clock source to TSC if it's set to anything else.

Check the clock source on your Linux OS using the following command:

Expand Down
6 changes: 0 additions & 6 deletions modules/release-notes/pages/relnotes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,6 @@
:description: Couchbase Server 8.0.0 introduces multiple new features and fixes, as well as some deprecations and removals.
:page-toclevels: 2

[#deprecated-80]
== Deprecated Platforms

The use of x86 processors that do not support Advanced Vector Extensions 2 (AVX2) is deprecated in version 8.0.
Future versions of Vector Search will rely on these instructions to improve performance.
These instructions are available in most Intel processors produced since 2013 and AMD processors produced since 2015.

include::partial$docs-server-8.0.0-release-note.adoc[]
include::partial$morpheus-breaking-changes-release-note.adoc[]
Expand Down