Skip to main content

Troubleshooting On-Prem Connections

When an integration makes a request to an on-prem resource, it takes several steps to get there:

  1. The integration sends a request to the cloud-based on-prem service.
  2. The on-prem service forwards that request to an on-prem agent on your customer's network.
  3. The on-prem agent forwards the request to your customer's private resource (database, file server, etc).
   ╔══════════════════╗       ╔═════════════════════╗
   ║    Prismatic     ║       ║  Customer Network   ║
   ║------------------║       ║---------------------║
   ║   Integration    ║       ║  Customer Resource  ║
   ║       ↑          ║       ║         ↑           ║
   ║       ↓          ║       ║         ↓           ║
   ║ On-Prem Service <-----------> On-Prem Agent    ║
   ║                  ║       ║                     ║
   ╚══════════════════╝       ╚═════════════════════╝

When a step that relies on an on-prem connection throws an error, it's important to be able to determine where in the chain the connection failed. This article offers basic troubleshooting tips you can use to verify connectivity.

Verifying integration connectivity to the on-prem service​

There's not a lot to debug when it comes to this initial network hop.

When an instance configured with an on-prem connection runs, the connection contains two system-generated inputs: host and port. These values refer to a host and port of Prismatic's on-prem service running alongside your integration.

If you're using a built-in connector that supports on-prem, they will use these host and port values automatically. If you want to build a custom connector that supports on-prem connections, see Supporting on-prem connections in a custom connector. Verify that you are not hard-coding host or port values, or caching these values. Some database libraries persist database connections behind the scenes and can cause issues if the port value changes between executions. Ensure that you close connections when a custom action finishes.

Verifying the on-prem agent is connected​

Next, you should verify that the on-prem agent on your customer's network is connected to Prismatic's on-prem service. Running prism on-prem-resources:list will show you a list of on-prem resources, and their statuses:

$ prism on-prem-resources:list

 Name                  Status      Customer
 ───────────────────── ─────────── ─────────────
 Test MSSQL Server     AVAILABLE
 Acme MSSQL Server     UNAVAILABLE Acme Corp
 IBM DB2 Test Server   AVAILABLE
 Hooli IBM DB2 Server  AVAILABLE   Hooli

Resources without a Customer listed are those that you've marked --orgOnly and are used for testing on-prem connections in the integration designer.

Verify that your customer's on-prem resource appears on this list, and is marked AVAILABLE.

Additionally, check the on-prem agent container's logs. You should see lines that look like this:

2024-12-18 11:48:38 Name: IBM DB2 Test Server
2024-12-18 11:48:39 Registered successfully.

If the Registered successfully log line is missing, your customer may not allow network egress from the Docker network, and will need to open outbound connections to Prismatic on ports 22 and 443.

Verifying connectivity to the customer's resource​

The easiest way to verify that the on-prem agent can access the customer's resource is to attempt to telnet from the on-prem container to the resource. That can be done by opening bash in the on-prem agent, installing telnet, and checking for connectivity:

# Identify the ID of your on-prem container (something like 0ff1cec0ffee)
$ docker container ls

# Open a bash shell using the container's ID within your on-prem container
$ docker exec -it 0ff1cec0ffee bash

# Make sure APP_HOST and APP_PORT environment variables look correct in the on-prem container
root@0ff1cec0ffee:/home/envoy$ printenv

# Install telnet in the on-prem container
root@0ff1cec0ffee:/home/envoy$ apt update && apt install telnet

# Verify connectivity from on-prem container to private resource
root@0ff1cec0ffee:/home/envoy$ telnet ${APP_HOST} ${APP_PORT}

If the telnet command throws an error, the on-prem agent container is unable to access the private resource. The private resource may have a firewall in place, or the customer's network might prevent connectivity between the Docker network and the private resource's network. Ask your customer to enable network traffic between the Docker container and private resource.

Additionally, check the on-prem container's logs. If it has received requests from your integration but cannot forward to those requests to the customer's private resource, you'll see a log that looks like this:

Received data but failed to forward it to the final destination service (172.21.0.2:4000)