You are viewing the documentation for a prerelease version.

View Latest

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. The steps discussed below is the preferred option for creatig sync gateway user and binding it to a specified role.

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

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.