Networking

This guide provides a deep-dive into the network configuration options for Sombra.

This guide assumes an understanding of:

• Sombra's purpose (Introduction)
• Sombra's high-level network architecture (Architecture)

There are two HTTP APIs on Sombra: the Transcend Ingress, and the Customer Ingress. The Transcend Ingress is used to communicate with the Transcend Cloud, and it works out-of-the-box using a reverse tunnel. The Customer Ingress is used to communicate with your services. It requires that you configure a Kubernetes Ingress, which is generally attached to an application load balancer.

Regardless of deployment option, Sombra always hosts a server that handles all communications coming inbound from your internal servers. Transcend should have no access to this server. For more information on this server, see "Sombra serves an API for your client".

The load balancer that you connect to this server can be restricted to the IP ranges that need to communicate with it. When you launch into production, we recommend locking down this server to the minimal set of IP ranges. For Sombra to make an upstream request to Transcend Cloud, your client will need to supply a Transcend-issued API key.

Your clients must present a bearer authorization token to authenticate to Sombra's Customer Ingress API.

To authenticate an internal service to Sombra, pass the header x-sombra-authorization: Bearer ${INTERNAL_KEY}. The hash of this key is stored in the INTERNAL_KEY_HASH environment variable on Sombra.

To generate these values, refer to the Getting Started guide.

To add mutual TLS authentication, you can set:

• TRUSTED_CLIENT_CA_CERT_ENCODED: (optional) The public certificate authority (CA) certificate of a client who can connect to the internal Sombra API over mutual TLS. If set, Sombra will enforce that all incoming requests to non-health routes have a client cert. Like the SOMBRA_TLS_CERT, this is also a base64-encoded string of the PEM-formatted certificate.

To expose Sombra's Customer Ingress HTTP API to your internal services, you need to configure the customer_service and customer_ingress sections in your values.yaml file to configure a Kubernetes Ingress resource.

customer_service:
  type: NodePort # or LoadBalancer

customer_ingress:
  enabled: true
  # ... Cloud-dependent annotations

How you configure the customer_service and customer_ingress sections depends on your cloud provider. It is best to refer to the cloud provider's documentation for best practices.

In this example, we use the AWS Load Balancer Controller to create a load balancer. If using this method, you also need to install the AWS Load Balancer Controller Helm chart into your cluster.

For all options, refer to AWS's Ingress on Amazon EKS guide.

Prerequisites:

• The AWS Load Balancer Controller Helm chart installed in your cluster.

TLS Termination at the Application Load Balancer on AWS

TLS can be terminated at the load balancer, or at Sombra's server.

customer_service:
  type: NodePort

customer_ingress:
  enabled: true
  className: alb
  annotations:
    alb.ingress.kubernetes.io/certificate-arn: <CERT_ARN>
    alb.ingress.kubernetes.io/healthcheck-path: /health
    alb.ingress.kubernetes.io/healthcheck-port: '5039'
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTP
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 5039}]'
    alb.ingress.kubernetes.io/scheme: internal
    alb.ingress.kubernetes.io/subnets: <VPC_PRIVATE_SUBNET>
    alb.ingress.kubernetes.io/tags: env=dev
    alb.ingress.kubernetes.io/target-type: ip
  hosts:
    - host: <SOMBRA_CUSTOMER_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix

TLS Termination at Sombra's Server on AWS

Or with TLS terminated at Sombra's server:

customer_service:
  type: NodePort

customer_ingress:
  enabled: true
  className: alb
  annotations:
    alb.ingress.kubernetes.io/certificate-arn: <CERT_ARN>
    alb.ingress.kubernetes.io/healthcheck-path: /health
    alb.ingress.kubernetes.io/healthcheck-port: '5040'
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTPS
    alb.ingress.kubernetes.io/backend-protocol: HTTPS
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 5040}]'
    alb.ingress.kubernetes.io/scheme: internal
    alb.ingress.kubernetes.io/subnets: <VPC_PRIVATE_SUBNET>
    alb.ingress.kubernetes.io/tags: env=dev
    alb.ingress.kubernetes.io/target-type: ip
  hosts:
    - host: <SOMBRA_CUSTOMER_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix

envs_as_secret:
  # You must include certificate information for Sombra's server.
  - name: SOMBRA_TLS_CERT
    value: <SOMBRA_TLS_CERT>
  - name: SOMBRA_TLS_KEY
    value: <SOMBRA_TLS_KEY>
  # An optional passphrase associated with your TLS private key. If you set a passphrase when you created your key and certificate, you must provide it here.
  - name: SOMBRA_TLS_KEY_PASSPHRASE
    value: <SOMBRA_TLS_KEY_PASSPHRASE>
  # ... other env vars

In this example, we use the Azure Application Gateway Ingress Controller to configure ingress through a load balancer, with TLS termination at the load balancer.

Prerequisites:

• An Azure Application Gateway
• A TLS secret in your cluster
• The Azure Application Gateway Ingress Controller Helm chart into your cluster.

For more options, refer to Azure's Ingress in Azure Kubernetes Service (AKS) guide.

customer_ingress:
  enabled: true
  className: 'azure-application-gateway'
  annotations:
    appgw.ingress.kubernetes.io/health-probe-hostname: <SOMBRA_CUSTOMER_INGRESS_DOMAIN>
    appgw.ingress.kubernetes.io/health-probe-path: /health
    appgw.ingress.kubernetes.io/health-probe-port: '5039'
  hosts:
    - host: <SOMBRA_CUSTOMER_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: <SOMBRA_CUSTOMER_TLSSECRET_NAME>
      hosts:
        - <SOMBRA_CUSTOMER_INGRESS_DOMAIN>

livenessProbe:
  httpGet:
    path: /health
    port: 5039
    scheme: HTTP
  timeoutSeconds: 100
  periodSeconds: 30
  successThreshold: 1
  failureThreshold: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5039
    scheme: HTTP
  timeoutSeconds: 100
  periodSeconds: 30
  successThreshold: 1
  failureThreshold: 10

In this example, we use the GKE Ingress Controller with Google Cloud Load Balancer to create a load balancer.

Prerequisites:

• A Google Cloud SSL certificate (either Google-managed or self-managed)
• The GKE cluster with Ingress capabilities enabled

For all options, refer to Google's Ingress in Google Kubernetes Engine (GKE) guide.

TLS Termination at the Google Cloud Load Balancer

TLS can be terminated at the load balancer, or at Sombra's server.

customer_service:
  type: NodePort

customer_ingress:
  enabled: true
  className: gce
  annotations:
    kubernetes.io/ingress.class: gce
    kubernetes.io/ingress.global-static-ip-name: <STATIC_IP_NAME>
    ingress.gcp.kubernetes.io/managed-certificates: <MANAGED_CERT_NAME>
    cloud.google.com/load-balancer-type: Internal
    ingress.gcp.kubernetes.io/pre-shared-cert: <SSL_CERT_NAME>
    cloud.google.com/backend-config: '{"default": "<BACKEND_CONFIG_NAME>"}'
  hosts:
    - host: <SOMBRA_CUSTOMER_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix

You'll also need to create a BackendConfig resource for health checks:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: <BACKEND_CONFIG_NAME>
spec:
  healthCheck:
    checkIntervalSec: 30
    timeoutSec: 5
    healthyThreshold: 1
    unhealthyThreshold: 3
    type: HTTP
    requestPath: /health
    port: 5039
  connectionDraining:
    drainingTimeoutSec: 60

TLS Termination at Sombra's Server on GKE

For TLS terminated at Sombra's server:

customer_service:
  type: NodePort

customer_ingress:
  enabled: true
  className: gce
  annotations:
    kubernetes.io/ingress.class: gce
    kubernetes.io/ingress.global-static-ip-name: <STATIC_IP_NAME>
    ingress.gcp.kubernetes.io/managed-certificates: <MANAGED_CERT_NAME>
    cloud.google.com/load-balancer-type: Internal
    ingress.gcp.kubernetes.io/pre-shared-cert: <SSL_CERT_NAME>
    cloud.google.com/backend-config: '{"default": "<BACKEND_CONFIG_NAME>"}'
  hosts:
    - host: <SOMBRA_CUSTOMER_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix

envs_as_secret:
  # You must include certificate information for Sombra's server.
  - name: SOMBRA_TLS_CERT
    value: <SOMBRA_TLS_CERT>
  - name: SOMBRA_TLS_KEY
    value: <SOMBRA_TLS_KEY>
  # An optional passphrase associated with your TLS private key. If you set a passphrase when you created your key and certificate, you must provide it here.
  - name: SOMBRA_TLS_KEY_PASSPHRASE
    value: <SOMBRA_TLS_KEY_PASSPHRASE>
  # ... other env vars

And the corresponding BackendConfig for HTTPS health checks:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: <BACKEND_CONFIG_NAME>
spec:
  healthCheck:
    checkIntervalSec: 30
    timeoutSec: 5
    healthyThreshold: 1
    unhealthyThreshold: 3
    type: HTTPS
    requestPath: /health
    port: 5040
  connectionDraining:
    drainingTimeoutSec: 60

You can disable listeners by setting the following ports to undefined. While you can also override the default port numbers, we recommend keeping the default ports to maintain consistency with our other Sombra guides.

• INTERNAL_PORT_HTTPS: Port for the internal HTTPS server (Customer Ingress; faces inside firewall). Defaults to 5040. Set to undefined if you only want to listen on HTTP. To listen on this HTTPS port, you must also provide SOMBRA_TLS_CERT and SOMBRA_TLS_KEY.
• INTERNAL_PORT_HTTP: Port for the internal HTTP server (Customer Ingress; faces inside firewall). Defaults to 5039. Set to undefined if you only want to listen on HTTPS. At least one of the above environment variables must be set.
• EXTERNAL_PORT_HTTPS: Port for the external HTTPS server (Transcend Ingress; faces outside firewall if using Direct Connection method). Defaults to 5041. Set to undefined if you only want to listen on HTTP. To listen on this HTTPS port, you must also provide SOMBRA_TLS_CERT and SOMBRA_TLS_KEY. You may ignore this option if using the Reverse Tunnel method.
• EXTERNAL_PORT_HTTP: Port for the external HTTP server (Transcend Ingress; faces outside firewall if using Direct Connection method). Defaults to 5042. Set to undefined if you only want to listen on HTTPS. At least one of the above environment variables must be set. You may ignore this option if using the Reverse Tunnel method.

If you want Sombra to listen over HTTPS (on the ports defined in INTERNAL_PORT_HTTPS for the Customer Ingress and/or EXTERNAL_PORT_HTTPS for the Transcend Ingress), you can add TLS certs on Sombra. If you are using the Reverse Tunnel for the Transcend Ingress (the default), this configuration only applies to the Customer Ingress. If you are using Direct Connection for the Transcend Ingress, then this configuration also applies to the external HTTPS server that Transcend will connect to.

• SOMBRA_TLS_CERT: The Sombra TLS Certificate, as a base64 encoded string. This is paired with SOMBRA_TLS_KEY. Either both should be set or neither.
• SOMBRA_TLS_KEY: The TLS private key for this server, base64-encoded in PEM format. Starts with 'LS0tLS1CRUdJT', or in its pre-encoded format, '-----BEGIN'. The pre-encoded string should also include 'PRIVATE KEY-----'. This is paired with SOMBRA_TLS_CERT.
• SOMBRA_TLS_KEY_PASSPHRASE: An optional passphrase associated with your TLS private key. If you set a passphrase when you created your key and certificate, you must provide it here.

Transcend supports two methods of connecting Sombra with Transcend:

1. Reverse Tunnel (recommended): Using the Transcend Sombra Reverse Tunnel, which is a proxy service that allows Transcend to connect to Sombra without allowing inbound connections on your firewall.
2. Direct Connection: Setting up public endpoints for the Transcend ingress to your Sombra, and allow-listing inbound connections from Transcend.

The Reverse Tunnel is our recommended method and is configured by default in all of our deployment guides. The Direct Connection method is a legacy option that we continue to support. We only recommend the Direct Connection method if you have company policies which require it, such as established deployment patterns.

Using the Reverse Tunnel method allows Transcend to connect to Sombra without allowing inbound connections on your firewall.

This is the default—no action is required. Following any of our deployment guides will set up the Reverse Tunnel out of the box!

The Direct Connection requires setting up public endpoints for Transcend to directly connect to Sombra.

If using the Direct Connection deployment method, first decide where you plan to host the gateway. You will need two URLs for both sombra-customer-ingress and sombra-transcend-ingress. For example, this may look something like:

• sombra-transcend-ingress: https://sombra-transcend.acme.com
• sombra-customer-ingress: https://sombra-internal.acme.com:5040

Once you decide on these subdomain names, create a new Sombra gateway in the Sombra settings by clicking the "Create New Self Hosted Sombra" button.

Place a load balancer in front of your Sombra cluster, and point your chosen domain names to the load balancer with TLS certificates that cover those domains.

You can allowlist ingress traffic from Transcend to your Sombra gateway by allowing the following list of IP addresses (Note: all IP addresses need to be allowed):

Follow Configure TLS Certificates to set up your TLS certificate and Configure Ports and Listeners to configure the Sombra's listeners. If your Sombra cluster is deployed behind a load balancer, and you don't want to continue using TLS after the load balancer (thereby using HTTP within your network perimeter), you can omit these environment variables.

If you're using our Helm deployment, you can switch from the Reverse Tunnel to the Direct Connection method by enabling transcend_ingress in values.yaml:

transcend_ingress:
  enabled: true
  className: alb
  annotations:
    alb.ingress.kubernetes.io/certificate-arn: <CERT_ARN>
    alb.ingress.kubernetes.io/healthcheck-path: /health
    alb.ingress.kubernetes.io/healthcheck-port: '5042'
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTP
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 5042}]'
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/subnets: <VPC_PUBLIC_SUBNET>
    alb.ingress.kubernetes.io/tags: env=dev
    alb.ingress.kubernetes.io/target-type: ip
  hosts:
    - host: <SOMBRA_TRANSCEND_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix

Or with TLS:

transcend_ingress:
  enabled: true
  className: alb
  annotations:
    alb.ingress.kubernetes.io/certificate-arn: <CERT_ARN>
    alb.ingress.kubernetes.io/healthcheck-path: /health
    alb.ingress.kubernetes.io/healthcheck-port: '5041'
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTPS
    alb.ingress.kubernetes.io/backend-protocol: HTTPS
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 5041}]'
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/subnets: <VPC_PUBLIC_SUBNET>
    alb.ingress.kubernetes.io/tags: env=dev
    alb.ingress.kubernetes.io/target-type: ip
  hosts:
    - host: <SOMBRA_TRANSCEND_INGRESS_DOMAIN>
      paths:
        - path: /
          pathType: Prefix

envs_as_secret:
  # You must include certificate information for Sombra's server.
  - name: SOMBRA_TLS_CERT
    value: <SOMBRA_TLS_CERT>
  - name: SOMBRA_TLS_KEY
    value: <SOMBRA_TLS_KEY>
  # An optional passphrase associated with your TLS private key. If you set a passphrase when you created your key and certificate, you must provide it here.
  - name: SOMBRA_TLS_KEY_PASSPHRASE
    value: <SOMBRA_TLS_KEY_PASSPHRASE>
  # ...

Note these are examples for setting up a load balancer ingress on AWS, but you can find more examples under Sombra Customer Ingress.

The key difference is in the network configuration. The Direct Connection method requires a load balancer, while the Reverse Tunnel does not require you to configure any ingress network policies, as long as the Sombra containers can communicate with the public internet. The tunnel will handle load-balancing among all your running Sombra containers in a round-robin manner.

The Reverse Tunnel method eliminates the need to set up a load balancer, configure TLS (as there is no inbound connection being made), configure DNS, or open up your firewall.

In this picture, you can see the load balancer setup for a Direct Connection Sombra cluster, where our backend talks directly to a load balancer which talks directly to the Sombra cluster.

In this picture, you can see the Reverse Tunnel method, where the Sombra cluster reach out to our backend to establish a private tunnel that our backend can send messages over.

If you are not self-hosting the security gateway, you may want to add IP-restriction on all incoming webhooks and database connections. All traffic will originate from:

If your servers are receiving webhooks from Transcend, they must still verify the JSON Web Token sent with each webhook. IP restriction should be an additional layer of security, not a replacement of other security measures.

Sombra must be able to make outbound network requests to the web and any services you plan to connect with Transcend. Since Sombra connects to many integrations, and the API URLs Sombra connects to can change at any time, we do not recommend restricting egress from Sombra.