Synqly Embedded
/
Getting Started

Synqly Embedded

Synqly Embedded is a new offering that allows Synqly customers to self-host Synqly services on their own infrastructure.

  1. Supports Synqly's full management and engine APIs.
  2. Supports multiple methods of Ingress TLS termination. Works with either K8s Ingress Controllers such as nginx, or Pod mounted certificates.
  3. Works with an externally running PostgreSQL compatible databasee.
  4. Supports an AEAD, Azure KMS, AWS KMS or Hashicorp Vault Transit for connector credential security.
  5. Optionally supports an externally running SMTP server.
  6. Optionally supports Synqly's bridge agents.
  7. Optionally supports Synqly's connect-ui and management-ui.

The Synqly Embedded Pod creates a default organization on first startup, then prints the organization information to Pod logs. Use the organization and member information to access the synqly API.

Use the Embedded Helm chart to create kubernetes cluster Synqly components and configuration.

Required Infrastructure

Minimal Infrastructure (POC-only):

  • PostgreSQL-compatible Database

Production Synqly Deployments:

  • PostgreSQL Compatible Database
  • Encryption Key Management System (KMS)
  • SMTP Server (required if running management-ui)

PostgreSQL Compatible Database

Synqly Embedded requires a PostgresSQL compatible database in order to store management configuration such as registered integrations, request metadata, and management-ui users. We officially support PostgreSQL and CockroachDB databases. When provisioning the database, best practice is to create a non-administrator user which can then be granted full access to the synqly database.

Example create CockroachDB user and database

cockroach sql --host=localhost:26257
CREATE USER "synqly-user" WITH PASSWORD 'password';
CREATE DATABASE synqly;
GRANT ALL ON DATABASE synqly TO "synqly-user";
\q

Example create PostgreSQL user and database

psql -d postgres
CREATE USER "synqly-user" WITH PASSWORD 'password';
CREATE DATABASE synqly;
GRANT ALL PRIVILEGES ON DATABASE synqly TO "synqly-user";
\c synqly
GRANT ALL ON SCHEMA public TO "synqly-user";
\q

Helm Configuration

To supply database connection parameters to Synqly services, configure the following fields in your values.yaml file:

global:
  ...
  # (Required): Connection settings for a PostgreSQL compatible database.
  dbName: synqly
  dbHost: <DB_HOST>.cockroachlabs.cloud
  dbUsername: <DB_ROOT_USER>
  dbPassword: <DB_PASSWORD>
  dbPort: "26257"

Encryption Key Management Service (KMS)

Synqly Embedded generates an encryption key for each Synqly Organization that gets created, then uses that key to encrypt any sensitive connector credentials before it gets sent to the DB. This architecture guarantees strong encryption of customer credentials; providing encryption-in-transit on top of whatever encryption-at-rest the DB provides.

When configured to use an external KMS, Embedded stores all generated encryption keys in the target KMS. Production workloads should utilize an external KMS. Storing encryption keys in a separate system from the data they are used to encrypt minimizes the possibility of sensitive data compromise.

It is possible to run Synqly Embedded without an external KMS by leaving the fields in the "Helm Configuration" section below empty. Doing so stores encryption keys in the database and should only be used for non-production workloads.

NOTE: Changing the configured KMS will invalidate all existing saved Synqly connector credentials.

Supported KMS Offerings

Synqly Embedded supports the following KMS offerings and authentication methods:

  1. Azure Key Vault (Azure Client Credentials)
  2. Hashicorp Vault (Token, App Role)
  3. AWS KMS (IAM User Credentials, EKSPodIdentity, IRSA)
  4. AEAD database storage for non-production workloads

Helm Configuration

To supply KMS connection parameters to Synqly services, configure the following fields in your values.yaml file:

global:
  ...
  encryptionKey:
    ...
    # Fill in the section corresponding to your preferred KMS offering
    azureKeyVault:
      ...
    awsKMS:
      ...
    hashicorpVault:
      ...

SMTP Server

Synqly Embedded utilizes an SMTP server to send Management UI member invitation and password reset emails. Management UI members are integrator-side employees that are able to log in to Synqly's management-ui service. Management UI users can view data such as which integrations have been registered and how many requests are being made.

Synqly Embedded can run without an SMTP server, but management-ui members and password resets must then be managed through Synqly API calls instead of through the Management UI. We strongly recommend configuring an SMTP server for production deployments with the management-ui service enabled.

Supported SMTP Offerings

Synqly Embedded can send emails using any SMTP server that supports username + password authentication.

For testing purposes, we have found mailhog/mailpit servers easy to work with.

Helm Configuration

To supply SMTP Server connection parameters to Synqly services, configure the following fields in your values.yaml file:

global:
  ...
  # Settings to connect to an SMTP server. Required in order for Synqly to send
  # User invite and password reset emails.
  smtpServer:
  smtpUsername:
  smtpPassword:

Synqly Embedded Helm Chart

In order to easily install Synqly Embedded on Kubernetes, Synqly offers the synqly/embedded Helm chart. The synqly/embedded Helm chart receives regular releases of updated service images as well as chart improvements.

Image Rotation

Please be aware that each version of the embedded container will run for 90 days after it has been released. A newer container images must be deployed before the current image expires. Outdated embedded images will start logging warning messages after 75 days, and will cease functioning after 90 days. This is a server side control meant to ensure embedded stays up-to-date and receives ongoing security updates.

In order to ensure the embedded image stays up to date:

  1. Update your local Helm repository: Add Synqly's Helm Repository
  2. Run helm search repo synqly to retrieve an updated imageTag from the "App Version" column:
    $ helm search repo synqly

# Result (new `imageTag` is in "App Version")
NAME           	CHART VERSION	APP VERSION         	DESCRIPTION
synqly/embedded	0.0.33       	embedded-2025.02.07	Synqly Embedded
  3. Update all imageTag fields in your values.yaml to use the new value (ex. embedded-2025.02.07)
  4. Upgrade your Helm installation with the updated values.yaml: Install Synqly Embedded

Add Synqly's Helm Repository

(Run once) Run the following command to add the Synqly Helm repository to your local environment

# Add synqly's helm repository to the local helm configuration
helm repo add synqly https://helm.synqly.com/stable

Run the following commands to update your local Synqly Helm repository.

# pull the latest version of all charts
helm repo update synqly

# list the latest synqly embedded chart version
helm search repo synqly

Download Default values.yaml

All Helm charts contain a chart specific values.yaml. The values.yaml file contains all the configuration options available within a given chart.

Deploying Synqly Embedded requires you download the default values.yaml and customize it to reflect your organization and infrastructure.

# create a local values.yaml file for customization
helm show values synqly/embedded > values.yaml

Install Synqly Embedded

Once your values.yaml file accurately reflects your infrastructure, deploy the chart to Kubernetes with the following command.

# install the embedded chart to a namespace called "synqly"
helm upgrade --install synqly-embedded synqly/embedded  \
    --namespace synqly \
    --create-namespace \
    -f values.yaml

(Optional) Pull Chart Locally

It is also possible to pull the full chart locally. Doing so allows you to explore the templated manifests and see how values from values.yaml affect the resultant Kubernetes resources.

# Pull a local copy of the chart to the local filesystem
helm pull synqly/embedded
 
Next page