The Couchbase Autonomous Operator 2.0 release introduces a number of groundbreaking features and enhancements that make it easier than ever to deploy, provision, monitor and manage your Couchbase Server nodes on Kubernetes. In addition to Couchbase server nodes,  Couchbase Mobile deployments include Sync Gateways that provide secure data synchronization between Couchbase Lite enabled clients and the cloud. Couchbase Server is the persistent backing storage for Sync Gateway.

The stateless nature of Sync Gateway lends itself well to Kubernetes. In this post, we provide an overview of how to deploy Sync Gateway on Kubernetes while leveraging the client authentication enhancements introduced in Couchbase Autonomous Operator 2.0.

Couchbase Mobile Deployment

Sync Gateway and Couchbase Autonomous Operator

The Sync Gateway cluster is deployed and managed independently of the Couchbase Server cluster using a Kubernetes deployment controller. While the Couchbase Operator to not used to deploy, provision, and manage the Sync Gateway, the download package includes a sample Deployment template for deploying a Sync Gateway cluster and connecting it a Couchbase Server cluster.

There are two main steps when it comes to deploying a Sync Gateway cluster.

Connecting Sync Gateway to Couchbase Server

First, the Sync Gateway cluster must be bootstrapped with the appropriate Couchbase Server bucket, as specified in the Sync Gateway server config property. A Sync Gateway cluster can connect to a Couchbase Server using any of the following network configurations viz.-

This would require Sync Gateway versions 2.7.1 and later.

This would require Sync Gateway versions 2.7.1 and later.

It is recommended that communication between Sync Gateway and the server be secured over TLS regardless of the network configuration.

As such, while highly recommended, it is not required for the server to be deployed on Kubernetes.

In addition to configuring the network to enable Sync Gateway connect to the server, the Sync Gateway nodes must authenticate with Couchbase Server. You have two options –

Sync Gateway RBAC User

This is probably the most common authentication mechanism used in Couchbase Mobile deployments. Operator 2.0 introduces support for RBAC management. You can use this capability to let the operator automatically manage the creation of Sync Gateway RBAC user. For this, you define a Couchbase User corresponding to the Sync Gateway user and create appropriate User Role Binding that will bind the Sync Gateway user with relevant administrative roles (bucket_full_access)as defined by a Couchbase Group.

In order to leverage this capability, you will need to enable RBAC management.
Kubernetes Operator RBAC Management

You still have a choice to not let the Operator manage the RBAC user, in which case, you would manually create the user on the server per usual procedures.

TLS Client Authentication

Operator 2.0 fully supports mTLS (mutual TLS). This can be leveraged for authenticating the Sync Gateway using client certificates.

Mutual Authentication

Once the Sync Gateway is successfully connected to the server, the next step is to expose it to Couchbase Lite clients

Exposing Sync Gateway to Couchbase Lite Clients

A typical Couchbase Mobile deployment consists of one or more Sync Gateway nodes fronted by a load balancer. Couchbase Lite clients connect to the load balancer. Communication from the clients to the Sync Gateway is secured via TLS. You have a couple of deployment choices –

Load Balancer as Pass-through

In this option, the load balancer operating at Layer 4 of the network stack is a pass-through for traffic between Couchbase Lite clients and Sync Gateway. TLS connections are end-to-end and terminate at the Sync Gateway. This option works for cloud providers supporting external load balancers. You can provision a Load Balancer for Sync Gateway service.
Layer 4 load balancer with Sync Gateway

Load Balancer as TLS Termination

In this option, an application-level load balancer acts as a proxy intercepting communications between Couchbase Lite clients and Sync Gateway, and load balancing decisions are made by inspecting the packet contents. TLS connections are terminated at the load balancer, alleviating the load on the Sync Gateway. This is a very common deployment model for Couchbase Mobile.

TLS Termination Point with App Gateway


We have put together a three-part tutorial that provides step-by-step instructions to

  • Deploy a Sync Gateway cluster and connect it to the server
  • Expose the Sync Gateway deployment to external Couchbase Lite and RESTful clients and
  • Manage the Sync Gateway cluster

It includes a discussion of best practices and sample .yaml config files which can be used as a reference and customized for your deployment.

The instructions in the tutorial apply to any Kubernetes environment. The differences that you will encounter between the managed Kubernetes environments will primarily be in the network configuration and configuration of platform-specific load balancers.

Here are the direct links for setting up Couchbase server cluster on popular managed Kubernetes environments using Autonomous Operator. Once the Couchbase Server is deployed, follow the steps described in the tutorial above to deploy the Sync Gateway cluster.

  • Instructions for setting up Couchbase Server cluster with Amazon Elastic Container Service for Kubernetes (EKS) on Amazon Web Services (AWS) is outlined in this tutorial
  • Instructions for setting up Couchbase Server cluster with Azure Container Service (AKS) on Azure Cloud Platform is outlined in this tutorial
  • Instructions for setting up Couchbase Server cluster with Amazon Elastic Container Service for Kubernetes (EKS) on Amazon Web Services (AWS) is outlined in this tutorial

Deploying using Helm

The operator chart is now extended to support Sync Gateway. So you can deploy the Operator, the Couchbase server and the Sync Gateway clusters in a single step! Of course, the chart can be used to deploy the Sync Gateway cluster exclusively connected to a Couchbase Server that is not deployed using Helm. The Sync Gateway installation is disabled by default.

If you want to deploy the Sync Gateway, create an appropriate override for the values.yaml customizing it to suit your deployment needs and install it.

What Next

From the tutorials, you’d see that it only takes a couple of steps to deploy your Sync Gateway containers using Kubernetes.

If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me.  The Couchbase Forums are another good place to reach out with questions.


I would like to thank Simon Murray for his feedback on the tutorial.



Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

Leave a reply