Connecting Sync Gateway to a Couchbase Cluster

Connect the Couchbase Sync Gateway to a Couchbase cluster

Tutorials are accurate at the time of writing but rely heavily on third party software. Tutorials are provided to demonstrate how a particular problem may be solved. Use of third party software is not supported by Couchbase. For further help in the event of a problem, contact the relevant software maintainer.

Sync Gateway is a synchronization server that is responsible for secure data synchronization and routing between Couchbase Lite enabled clients and Couchbase Server. It is an integral component of Couchbase Mobile platform.

This tutorial defines best practices for deploying Sync Gateway on Kubernetes. It covers basic connectivity between Sync Gateway and a Couchbase Cluster deployed by the Operator.

Prerequisites

A Couchbase Server cluster deployed and running. While it is recommended, note that it is not required that Couchbase Server be deployed with Kubernetes. It is possible to deploy Sync Gateway on Kubernetes and connect it to Couchbase Server cluster that is not on Kubernetes. The instructions herein assume that Couchbase Server is deployed using the operator.
This step is optional and only required if the environment is not setup DNS. If the Couchbase Server cluster is configured to use exposedFeatures then the value of "client" must be included in the exposedFeatures list. This is required for Sync Gateway to be able to connect to the server. Alternatively, remove the exposedFeatures section altogether in the server configuration if it is not needed.

Configuring a Sync Gateway

Sync Gateway is configured with a configuration file within its container. The configuration contains sensitive data such as usernames, passwords and TLS private keys. We therefore should define the configuration as a secret. Create a sgw-config.yaml file with the relevant configuration as shown below: Relevant configuration variables are documented below:

apiVersion: v1
kind: Secret
metadata:
  name: sync-gateway
stringData:
  config.json: |-
    {
      "logging": {
        "console": {
          "enabled": true, (1)
          "log_level": "info", (2)
          "log_keys": [
            "*"
          ]
        }
      },
      "databases": {
        "cb-example": { (3)
          "server": "couchbase://cb-example", (4)
          "bucket": "default", (5)
          "username": "Administrator", (6)
          "password": "password", (7)
          "users": {
            "GUEST": {
              "disabled": false,
              "admin_channels": [
                "*"
              ]
            }
          },
          "allow_conflicts": false,
          "revs_limit": 20,
          "enable_shared_bucket_access": true
        }
      }
    }

1	`logging.console.enabled` enables logging to the console. This is especially relevant on Kubernetes where applications are expected to log to standard out.
2	`logging.console.log_level` defines what messages are printed. For most use cases `info` is sufficient, however `debug` may provide additional information that can aid in problem determination.
3	`databases.cb-example` is the names of a database connection. The database name is arbitrary. In this instance we have named it after the `CouchbaseCluster` resource it references.
4	`databases.cb-example.server` defines the Couchbase server instance to connect to. The connection string may be determined the same way as for client SDKs. The connection options are dependent on the chosen network architecture.
5	`databases.cb-example.bucket` defines the bucket name to connect to and use to store mobile data.
6	`databases.cb-example.username` defines the user that will be used to connect to the cluster.
7	`databases.cb-example.password` defines the user password that will be used to connect to the cluster.

Deploy the secret using the following command. If the config file is sgw-config.yaml, the command would be as follows

$ kubectl create -f sgw-config.yaml

Enabling TLS Connectivity to Couchbase Server

TLS is fully supported between Sync Gateway and Couchbase Server. This includes server-side TLS or mutual TLS.

Your Sync Gateway configuration can be modified to allow use of TLS as follows:

apiVersion: v1
kind: Secret
metadata:
  name: sync-gateway
stringData:
  config.json: |-
    {
      "databases": {
        "cb-example": {
            "cacertpath": "/etc/sync_gateway/ca.pem", (1)
            "certpath": "/etc/sync_gateway/cert.pem", (2)
            "keypath": "/etc/sync_gateway/key.pem", (3)
        }
      }
    }
  ca.pem: |- (4)
    -----BEGIN CERTIFICATE-----
    MIIDSzCCAjOgAwIBAgIUDsYnaG+RFwhtoz9hSMwyzfoxOCcwDQYJKoZIhvcNAQEL
    ...
  cert.pem: |- (5)
    -----BEGIN CERTIFICATE-----
    MIIDXDCCAkSgAwIBAgIRAOUsHgVlGyJbvOIYuxD90x4wDQYJKoZIhvcNAQELBQAw
    ...
  key.pem: |- (6)
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDLaRvd8BxDBsPc
    ...

Certificates have been truncated for brevity.

1	`databases.cb-example.cacertpath` defines where the CA certificate will be read from. This path is related to the deployment volume mount as described in Deploying Sync Gateway and the file name as described in this `Secret`.
2	Mutual TLS Only: `databases.cb-example.certpath` defines where the client certificate chain will be read from. This path is related to the deployment volume mount as described in Deploying Sync Gateway and the file name as described in this `Secret`.
3	Mutual TLS Only: `databases.cb-example.keypath` defines where the client key will be read from. This path is related to the deployment volume mount as described in Deploying Sync Gateway and the file name as described in this `Secret`.
4	The `ca.pem` secret is the CA certificate. The name of this secret data item defines the file name as used by `databases.cb-example.cacertpath` in the Sync Gateway configuration.
5	Mutual TLS Only: The `cert.pem` secret is the client certificate chain. The name of this secret data item defines the file name as used by `databases.cb-example.certpath` in the Sync Gateway configuration.
6	Mutual TLS Only: The `key.pem` secret is the client key. The name of this secret data item defines the file name as used by `databases.cb-example.keypath` in the Sync Gateway configuration.

Deploy the secret using the following command. If the config file is sgw-config.yaml, the command would be as follows

$ kubectl create -f sgw-config.yaml

Configuring RBAC User for Sync Gateway

If not using client certificate authentication, secure the system further by using a limited role to access Couchbase Server. In doing so, the scope of operations that can be performed in the event the Sync Gateway configuration is compromised is limited. The RBAC user corresponding to Sync Gateway can be manually configured as specified in Getting Started Guide.

Alternatively, you can take advantage of the Couchbase user RBAC management capability introduced with Autonomous Operator 2.0. With this method, the Autonomous Operator takes care of creating the relevant Sync Gateway user and binding it to a specified role.

Enabling RBAC Management

RBAC security management on the Couchbase Server cluster defaults to false. This is the relevant snippet that would need to be added or modified in your CouchbaseCluster configuration:

security:
  adminSecret: cb-example-auth
  rbac:
    managed: true

Enabling RBAC management by the Autonomous Operator will remove any RBAC users that were manually created on the cluster. Therefore, you will need to specify the relevant users and role bindings for those RBAC users if you want to continue using those identities after enabling RBAC management.

Creating a Sync Gateway RBAC User

First define a secret for the sync-gateway user that contains a password:

apiVersion: v1
kind: Secret
metadata:
  name: sync-gateway
data:
  password: cGFzc3dvcmQ= (1)

1	This password is the literal `password`. The correctly encoded form can be generated on a "UNIX-like" command line terminal with `echo -n 'password' \| base64`.

Deploy the secret using the following command. This creates a sync gateway user with specified password. If the config file is sync-gateway-rbac-user.yaml, the command would be as follows

$ kubectl create -f sync-gateway-rbac-user.yaml

Role Binding of Sync Gateway User

Next define the sync-gateway user and bind it to a group that allows it the "application access" role as defined by Couchbase Server. The Operator will create the required user and group on any Couchbase cluster that selects that user:

apiVersion: couchbase.com/v2
kind: CouchbaseUser
metadata:
  name: sync-gateway
  labels:
    cluster: my-cluster (1)
spec:
  authDomain: local (2)
  authSecret: sync-gateway (3)
---
apiVersion: couchbase.com/v2
kind: CouchbaseGroup
metadata:
  name: sync-gateway
spec:
  roles:
  - name: bucket_full_access (4)
    bucket: default (5)
---
apiVersion: couchbase.com/v2
kind: CouchbaseRoleBinding
metadata:
  name: sync-gateway
spec:
  subjects:
  - kind: CouchbaseUser
    name: sync-gateway
  roleRef:
    kind: CouchbaseGroup
    name: sync-gateway

1	The `CouchbaseUser` is labeled so it can be explicitly selected by a specific cluster. This is the recommended method of deployment as defined in the label selection concepts.
2	The `CouchbaseUser` uses the `local` authentication domain, meaning that a password will be locally installed on the Couchbase cluster for authentication.
3	The `CouchbaseUser` references the secret we previously created so that the Operator can associate the `sync-gateway` user with its password.
4	The `CouchbaseGroup` that the `sync-gateway` user will be a member of needs the `bucket_full_access` role.
5	The `CouchbaseGroup` that the `sync-gateway` user will be a member of only requires access to a single bucket. We therefore further limit scope to only enable modification of the `default` bucket. By default this would be set to `*` granting access to all buckets.

Deploy the Sync Gateway RBAC user using the following command. If the config file is sync-gateway-user-rolebinding.yaml, the command would be as follows

$ kubectl create -f sync-gateway-user-rolebinding.yaml

Configure Sync Gateway with the RBAC User

Finally, to enable Sync Gateway to use the sync-gateway user, modify the configuration defined in Configuring a Sync Gateway:

apiVersion: v1
kind: Secret
metadata:
  name: sync-gateway
stringData:
  config.json: |-
    {
      "databases": {
        "cb-example": {
          "bucket": "default", (1)
          "username": "sync-gateway", (2)
          "password": "password" (3)
        }
      }
    }

1	The `databases.cb-example.bucket` attribute must match the bucket granted access to in the `CouchbaseGroup`.
2	The `databases.cb-example.username` attribute must match the `CouchbaseUser` resource’s name.
3	The `databases.cb-example.password` attribute must match the plain-text password associated with the `CouchbaseUser`.

Deploy the secret using the following command. If the config file is sgw-config.yaml, the command would be as follows

$ kubectl create -f sgw-config.yaml

Deploying Sync Gateway

Sync Gateway is a simple state-less application so does not require any application specific controller like the Operator. An typical configuration is as described below:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sync-gateway
spec:
  replicas: 1 (1)
  selector:
    matchLabels:
      app: sync-gateway
  template:
    metadata:
      labels:
        app: sync-gateway
    spec:
      containers:
      - name: sync-gateway
        image: couchbase/sync-gateway:2.7.0-enterprise (2)
        volumeMounts:
        - name: config
          mountPath: /etc/sync_gateway (3)
          readOnly: true
        env:
        - name: GOMAXPROCS
          value: "1"
      volumes:
      - name: config
        secret:
          secretName: sync-gateway (4)

1	`spec.replicas` defines how many Sync Gateway pods to create. As Sync Gateway is stateless. This attribute can be modified to horizontally scale the deployment as needs require.
2	`spec.template.spec.containers[0].image` defines the container image to deploy. Version 2.7.0 or higher is recommended in order to support connecting to a cluster using public networking with external-DNS or generic networking.
3	`spec.template.spec.containers[0].volumeMounts[0].mountPath` mounts the configuration secret in the correct location. By default the Sync Gateway container will try to load configuration from `/etc/sync_gateway/config.json`, and this is how the `Secret` and `Deployment` are configured.
4	`spec.template.spec.volumes[0].secret.secretName` references the Sync Gateway configuration `Secret` that is mounted in the Sync Gateway container.

Deploy the Sync Gateway cluster from the specified deployment controller file. If the above configuration is in a file named sync-gateway.yaml, the command would be as follows

$ kubectl create -f sync-gateway.yaml

If successful, the equivalent of the following will be returned. In sample output below, the deployment with name sync-gateway was created

deployment.extensions "sync-gateway" created

You can check the status of the deployment with the following command

$ kubectl get deployments sync-gateway

If successful, a listing of the Sync Gateway pods that were deployed is returned. In the sample output below, 2 out of 2 requested Sync Gateway pods up and running

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
sync-gateway   2/2     2            2           24d

At this stage, the Sync Gateway node is configured to communicate with Couchbase Server.

Now, let’s look at the connectivity to Couchbase Lite clients.

Templates

Template files are provided in the Operator binary distribution :

sync-gateway.yaml : Sample Deployment Controller for Sync Gateway using RBAC for server connectivity This template creates a sync gateway RBAC user per procedures outlined in Configuring RBAC User for Sync Gateway section. However, the couchbase-custer.yaml template that is packaged has RBAC management set to false by default. So before you deploy the sync gateway cluster using the sync-gateway.yaml template, you must enable RBAC management on the server cluster as specified in the Enabling RBAC Management section.

These files are provided as evaluation examples — they should be modified to suit production deployments.

Red Hat OCP users will need to modify the provided template to reference an image pull secret. This must grant permission to pull container images from the Red Hat Container Registry.

Connecting Sync Gateway to a Couchbase Cluster

Prerequisites

Configuring a Sync Gateway

Enabling TLS Connectivity to Couchbase Server

Configuring RBAC User for Sync Gateway

Enabling RBAC Management

Creating a Sync Gateway RBAC User

Role Binding of Sync Gateway User

Configure Sync Gateway with the RBAC User

Deploying Sync Gateway

Templates

Further Reading