Creating and Configuring the On-Premises Connector

This document provides step-by-step instructions for creating and configuring the SGNL On-Premises Connector using the SGNL Console.

Step 1: Create On-Premises Connector

  • Log in to the SGNL Console.
  • Navigate to the Admin Page and select “On-Premises Connector”.
  • Click on “+Add” to add a new On-Premises Connector.
  • Enter the “Display Name” and “Description” for the Connector.
  • Click “Add Connector” to complete the creation process.

Add a Connector

Specify a Name

Step 2: Generate Auth Token for a Connector

  • Navigate to the Admin > On-Premises Connector Page and select the specific On-Premises Connector you want to configure.
  • Click on “Generate Token”, provide a descriptive name for the token, and confirm the action.
  • Copy the generated token and store it securely, as it will not be shown again.

Generate a Token

Deploying the On-Premises Connector as a Deployment in Kubernetes

This section provides step-by-step instructions for deploying the On-Premises Connector as a Kubernetes Deployment. The connector can run in any Kubernetes environment, regardless of where it is hosted.

Prerequisites

  • Access to a running Kubernetes cluster (e.g., EKS or self-managed)
  • kubectl CLI configured for your cluster
  • Access to the Azure Container Registry (ACR) containing the Connector’s image (Request credentials from your SGNL support representative)

Optional: Create a custom image

Create a custom image of the Connector by using a docker multi-stage build. This is optional and not required for the default deployment, but it allows you to customize the Connector image if needed.

For example, you can create a Dockerfile with the following content:

FROM sgnlai.azurecr.io/connector:1.1.0 AS sgnl-image
FROM example.company.com/company/custom-base-image:latest
COPY --from=sgnl-image /sgnl/connector /sgnl/connector

Note that if using a custom image, modify the following steps accordingly to use your custom image instead of the default one.

  • Step 1: Update the docker-registry secret contents to use your custom image registry, username, and password.
  • Step 3: Update spec.template.spec.containers.image to your custom image, and spec.template.spec.imagePullSecrets to your custom image registry secret.

Step 1: Authenticate Kubernetes to Azure Container Registry

Create a Kubernetes pull secret using your ACR credentials for SGNL’s sgnlai-azurecr.io container registry.

kubectl create secret -n sgnl docker-registry sgnl-acr-secret \
    --docker-server=sgnlai.azurecr.io \
    --docker-username="<ACR_USERNAME>" \
    --docker-password="<ACR_TOKEN>"

Step 2: Create ConfigMap and Secret for Connector Configuration

  • Configure the following environment variables for SGNL On-Premises Connector.
    • SGNL_CONNECTOR_SERVER_URL: Set this to your assigned sub-domain with .sgnlapis.cloud as the suffix.
    • SGNL_CONNECTOR_CLIENT_ID: Navigate to Admin > Environment page in the SGNL Console to get the Client ID.
    • SGNL_CONNECTOR_CONNECTOR_IDS: Use the Connector ID created on the Admin > On-Premise Connector page in the SGNL Console.
    • SGNL_CONNECTOR_AUTH_TOKENS: Use the authentication token generated from the Connector’s page in the SGNL Console.
  • Create a Kubernetes ConfigMap for no-sensitive configuration values (such as SGNL_CONNECTOR_SERVER_URL, SGNL_CONNECTOR_CLIENT_ID, and SGNL_CONNECTOR_CONNECTOR_IDS) and a Kubernetes Secret for sensitive values (such as SGNL_CONNECTOR_AUTH_TOKENS ).
apiVersion: v1
kind: ConfigMap
metadata:
  name: connector-config
  namespace: sgnl
data:
  SGNL_CONNECTOR_SERVER_URL: "<subdomain-prefix>.sgnlapis.cloud"
  SGNL_CONNECTOR_CLIENT_ID: "your-client-id"
  SGNL_CONNECTOR_CONNECTOR_IDS: "your-connector-id1,your-connector-id2,your-connector-id3"
apiVersion: v1
kind: Secret
metadata:
  name: connector-secret
  namespace: sgnl
type: Opaque
stringData:
  SGNL_CONNECTOR_AUTH_TOKENS: "your-connector-auth-token1,your-connector-auth-token2,your-connector-auth-token3"

Step 3: Create the Deployment YAML

Create a file named sgnl-connector-deployment.yaml with the following content:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: connector
  namespace: sgnl
  labels:
    app: connector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: connector
  template:
    metadata:
      labels:
        app: connector
    spec:
      containers:
        - name: connector
          image: sgnlai.azurecr.io/connector:1.1.0
          imagePullPolicy: IfNotPresent
          resources:
            limits:
              memory: "256Mi"
              cpu: 200m
            requests:
              memory: "128Mi"
              cpu: 50m
          securityContext:
            allowPrivilegeEscalation: false
            runAsGroup: 65532
            runAsNonRoot: true
            runAsUser: 65532
          envFrom:
            - configMapRef:
                name: connector-config
            - secretRef:
                name: connector-secret
      imagePullSecrets:
        - name: sgnl-acr-secret
      restartPolicy: Always
      nodeSelector:
        kubernetes.io/os: linux

Step 4: Deploy the Deployment

Apply the YAML to your cluster:

kubectl apply -f sgnl-connector-deployment.yaml

This will create a Deployment with 1 pod running the Connector container.

Step 5: Verify the Deployment

Check the status of your Deployment and pods:

kubectl get deployment connector -n sgnl
kubectl get pods -l app=connector -n sgnl

You should see 1 pod running.

After deploying the Connector, it will register itself with the SGNL platform. Once registration is complete and the connector is active, you can configure Systems of Record (SoR) from their respective settings pages to use the OnPremises Connector for data synchronization.

Configuring Disaster Recovery (DR) for On-Premises Connectors

SGNL supports a disaster recovery model for On-Premises Connectors using a primary/secondary relationship. A secondary (DR) connector is deployed to a separate, geographically dispersed Kubernetes cluster and is linked to a primary connector. If the primary connector becomes unavailable, SGNL automatically fails over to the secondary connector with no manual intervention required.

How DR Failover Works

  • When a datasource or integration is configured to use an On-Premises Connector, it references the primary connector.
  • The secondary (DR) connector is not directly selectable in the SGNL Console when configuring datasources or integrations. You always select the primary connector, and SGNL handles failover automatically.
  • If the primary connector disconnects (e.g., its Kubernetes cluster becomes unreachable), SGNL automatically routes requests to the secondary connector.
  • When the primary connector reconnects, it resumes handling requests.
  • A primary connector can have one or more secondary connectors.

Important Constraints

  • Each connector ID represents a single instance. The connector does not support multiple replicas or autoscaling of the same connector ID.
  • A primary connector and a secondary connector are separate connector instances, each with their own unique connector ID and authentication token.
  • Once a connector is created as a secondary (linked to a primary), it cannot be converted to a primary connector. Likewise, a primary connector cannot be converted to a secondary.
  • A primary connector cannot be deleted while it is referenced by any datasource, integration, or secondary connector.
  • A primary connector cannot be disabled while any referencing datasource has sync enabled or any referencing integration has enabled rules.

Step 1: Deploy the Primary Connector

Follow the steps in the previous sections to create, configure, and deploy the primary connector to your first Kubernetes cluster. This connector will serve as the primary instance.

Step 2: Create a Secondary (DR) Connector in the SGNL Console

  • Log in to the SGNL Console.
  • Navigate to the Admin page and select “On-Premises Connector”.
  • Click on “+Add” to add a new On-Premises Connector.
  • Enter the “Display Name” and “Description” for the DR Connector.
  • Select the primary connector that this new connector will serve as a secondary for.
  • Click “Add Connector” to complete the creation process.

Step 3: Generate Auth Token for the Secondary Connector

  • Navigate to the Admin > On-Premises Connector page and select the secondary connector.
  • Click on “Generate Token”, provide a descriptive name, and confirm the action.
  • Copy the generated token and store it securely, as it will not be shown again.

Step 4: Deploy the Secondary Connector to a Separate Kubernetes Cluster

Repeat the Kubernetes deployment steps (Steps 1–5 from Deploying the On-Premises Connector as a Deployment in Kubernetes) on your second, geographically dispersed Kubernetes cluster, using the secondary connector’s unique connector ID and authentication token in the ConfigMap and Secret:

apiVersion: v1
kind: ConfigMap
metadata:
  name: connector-config
  namespace: sgnl
data:
  SGNL_CONNECTOR_SERVER_URL: "<subdomain-prefix>.sgnlapis.cloud"
  SGNL_CONNECTOR_CLIENT_ID: "your-client-id"
  SGNL_CONNECTOR_CONNECTOR_IDS: "your-secondary-connector-id"
apiVersion: v1
kind: Secret
metadata:
  name: connector-secret
  namespace: sgnl
type: Opaque
stringData:
  SGNL_CONNECTOR_AUTH_TOKENS: "your-secondary-connector-auth-token"

The remaining deployment YAML and kubectl commands are identical to the primary connector deployment.

Step 5: Verify Both Connectors

After deploying the secondary connector, verify that both connectors appear as registered and active in the SGNL Console under Admin > On-Premises Connector. The secondary connector will show its association with the primary.

No additional configuration is needed on datasources or integrations — they continue to reference the primary connector, and SGNL will automatically route requests to the secondary if the primary becomes unavailable.

Troubleshooting

  • If pods are stuck in ImagePullBackOff, check your ACR secret and credentials.
  • Use kubectl describe pod <pod-name> -n sgnl for detailed error messages.
  • Use kubectl logs pod <pod-name> -n sgnl for the log messages from the Connector’s pod.

References

Enable On-Premises Connector for a SoR

  • Navigate to a SoR or Add a new SoR from the “Identity Data Fabric” Page.
  • Select a Connector from the drop-down list of registered On-Premises Connectors in “Settings”.

Enable On-Premises Connector for a Protected System for CAEP Hub

  • Navigate to a Protected System or Add a new Protected System.
  • Select a Connector from the drop-down list of registered On-Premises Connectors in “Settings”.

Detach On-Premises Connector for a SoR

  • Navigate to the “Identity Data Fabric” page and select the relevant SoR.
  • In the SoR settings, select “No Connector” from the drop-down list of registered On-Premises Connectors to detach any connector from this SoR.

Detach On-Premises Connector from a Protected System

  • Navigate to the “Protected System” page and select the relevant Protected System.
  • In settings, select “No Connector” from the drop-down list of registered On-Premises Connectors to detach any connector from this Protected System.