Configure secure tunnel ingress [Beta]

Beta

Secure tunnel ingress is in the beta phase of development and may not be available on your enrollment. Functionality may change during active development. Contact Palantir Support to request access.

Secure tunnels can carry connections in both directions. Besides routing egress traffic into your network, a secure tunnel cluster can accept TCP connections and UDP traffic from systems in your network. The cluster forwards this traffic to a generic listener in the platform. Systems in your network connect to an initiator as if it were the destination service. The initiator carries the traffic over outbound TLS connections to the platform, so no inbound firewall rules are required between your network and the platform.

This page explains how secure tunnel ingress works, how to restrict which systems can connect to an initiator, and how to troubleshoot connections. To create a generic listener and request an inbound connection policy, review Generic listeners.

How secure tunnel ingress works

Secure tunnel ingress is established by the following components:

ComponentLocationRole
ClientYour networkThe system that opens TCP connections or sends UDP traffic to the initiator.
InitiatorYour networkListens on the gateway port of each approved inbound connection policy, and forwards accepted traffic to the platform over outbound TLS connections.
Inbound connection policyPalantir platformAuthorizes a single generic listener to receive traffic of one transport protocol through one secure tunnel cluster.
Generic listenerPalantir platformReceives the tunneled traffic and delivers it to its backing compute module.

Traffic follows this path:

  1. A client in your network connects to an initiator at <initiator-ip>:<gateway-port>, where <initiator-ip> is the IP address of the initiator and <gateway-port> is the policy's gateway port. For Data Connection agent deployments, a client on the same host as the agent can also connect to localhost:<gateway-port>. Review Connect a client for the address to use in each deployment type.
  2. The initiator checks the client against its ingress allowlist and rejects connections that do not match an entry.
  3. The initiator forwards the traffic to the platform over an outbound TLS connection, authenticating with a token that is scoped to the inbound connection policy.
  4. The platform delivers the traffic to the generic listener's compute module on the policy's upstream port.

The control plane issues each initiator a separate token for every approved policy on its cluster. Tokens are valid for one hour and rotate automatically, so no long-lived credentials are stored in your network.

Gateway ports

Once an inbound connection policy is approved and its listener's compute module is deployed, the cluster's initiators begin listening on the gateway port within a few minutes. Approval alone does not open the gateway port: initiators do not listen for a policy until its compute module is deployed. Gateway ports are allocated from the range 15000 to 16000 and are unique for each protocol within a cluster.

Every initiator in a cluster opens the same gateway ports. How clients reach those ports depends on how the initiator is deployed:

  • Data Connection agent: The initiator binds gateway ports on all network interfaces of the agent host, and clients connect to the agent host's address. Deploy each initiator in a cluster on a separate host to avoid port conflicts, and ensure the gateway port range is free on each host.
  • Apollo: Each initiator runs in its own pod network namespace without host networking, so initiators that share a Kubernetes node do not conflict. Gateway ports are opened inside the initiator pod only. The initiator chart does not expose them through a Kubernetes Service or on the node's IP address, so clients must be able to reach the initiator pod's IP address directly.

Prerequisites

Before you configure secure tunnel ingress, ensure the following:

  • Generic listeners are enabled for your enrollment. Contact Palantir Support to request access.
  • A secure tunnel cluster exists, and at least one of its initiators runs in the network where your clients are located.
  • Clients can reach an initiator over the network on the gateway port assigned to the policy. Review Gateway ports for the address that clients use in each deployment type.

Limitations

Secure tunnel ingress has the following limitations:

  • UDP is one-directional: UDP traffic is forwarded from clients to the compute module only. The compute module cannot send UDP responses back to clients. TCP connections are bidirectional.
  • IPv4 only: Ingress allowlist entries support IPv4 ranges only.

Configure the ingress allowlist

The initiator's ingress allowlist controls which client IP ranges can connect to which gateway ports. The ingress allowlist denies all ingress by default. An empty ingress allowlist blocks all ingress, even if an inbound connection policy is approved.

The ingress allowlist is separate from the egress allowlist. Each entry specifies a client IP range in cidrBlock and a gateway port. Optionally, set endPort to allow an inclusive range from port through endPort.

For example, the following allowlist permits clients in 10.0.0.0/8 to connect to gateway port 15000, and clients in 192.168.10.0/24 to connect to gateway ports 15000 through 15010:

Copied!
1 2 3 4 5 6 allowListedIngressCidrs: - cidrBlock: '10.0.0.0/8' port: 15000 - cidrBlock: '192.168.10.0/24' port: 15000 endPort: 15010

Palantir recommends that you allow only the client ranges and gateway ports that each listener requires.

Data Connection agent configuration

When a Data Connection agent deploys an initiator, the ingress allowlist is empty by default. To edit the ingress allowlist, open the managing agent in Data Connection, navigate to Agent settings > Configuration > Advanced > Envoy, and update the initiator's allowListedIngressCidrs entries.

Apollo configuration

For Apollo-managed deployments, edit the allowListedIngressCidrs entries on the product's configuration page in Apollo.

Connect a client

Once the policy is approved, the compute module is deployed, the initiator is listening, and the ingress allowlist permits the client, configure the client to connect to the following:

  • Host: The address of an initiator in the cluster. For Data Connection agent deployments, use the agent host's address. For Apollo deployments, use the initiator pod's IP address.
  • Port: The policy's gateway port.

Troubleshooting

If a client cannot connect, check the following:

  • Policy status: The inbound connection policy must be approved. Pending and rejected policies do not open a gateway port.
  • Initiator health: At least one initiator in the cluster must be running and connected to the platform. View initiator status on the cluster's page in Control Panel.
  • Gateway port: The initiator must be listening on the policy's gateway port. Initiators only listen for an approved policy once its listener's compute module is deployed, so check the compute module if the port is not open. For Data Connection agent deployments, run lsof -i -P -n | grep <gateway-port> on the agent host to check whether the port is open. For Apollo deployments, the port is open inside the initiator pod, not on the Kubernetes node.
  • Ingress allowlist: The client's IP address and the gateway port must match an entry in the initiator's ingress allowlist.
  • Network path: Firewall rules between the client and the initiator must allow traffic on the gateway port. For Apollo deployments, the client must be able to route to the initiator pod's IP address.
  • Compute module: The compute module must be running, and its server must be bound to 0.0.0.0 on the upstream port.
  • UDP responses: If your client expects UDP responses, note that UDP is one-directional. Use TCP for protocols that require responses.