Working Behind a Corporate HTTP Proxy

Many enterprise networks do not allow workloads to reach the internet directly. Instead, all outbound traffic must go through a corporate HTTP proxy (for example Squid, Zscaler, or a Blue Coat/Symantec gateway). The LinearB On-Premise Agent supports this topology so that its traffic to the LinearB cloud can be routed through your proxy.

This guide explains what the proxy feature does, how to enable it, and — just as important — what it does not cover, so you can plan the rest of your network allowlisting accordingly.

Overview

The agent runs a small internal reverse proxy called forward-proxy (an NGINX pod). Most LinearB services and job pods do not talk to the LinearB cloud directly — they send their outbound requests to forward-proxy, which applies routing rules and forwards the request to LinearB's cloud API at on-prem-api.linearb.io.

forward-proxy is itself a proxy, and NGINX cannot be told to send its own upstream traffic through another (corporate) HTTP proxy. To bridge that gap, enabling the proxy feature deploys a second component — socat-tunneller — which is proxy-aware. When the feature is on, forward-proxy sends its upstream traffic to socat-tunneller, which relays it through your corporate proxy.

The effective traffic chain becomes:

internal LinearB pods
        │  (in-cluster HTTP, ports 3128–3136)
        ▼
   forward-proxy  (NGINX reverse proxy)
        │  (EXTERNAL_PROXY=true → upstream repointed at socat)
        ▼
  socat-tunneller  (proxy-aware relay, port 8443)
        │  (HTTP CONNECT or raw TCP)
        ▼
  corporate HTTP proxy  (EXTERNAL_PROXY_HOST:EXTERNAL_PROXY_PORT)
        │
        ▼
   on-prem-api.linearb.io:443

When the feature is off (the default), forward-proxy connects to on-prem-api.linearb.io directly and socat-tunneller is not deployed.

Configuration

The feature is controlled by four values under global in your local-values.yaml:

When EXTERNAL_PROXY is true, EXTERNAL_PROXY_HOST, EXTERNAL_PROXY_PORT and EXTERNAL_PROXY_TYPE are all required.

connect vs transparent

• connect (default, recommended for a standard forward proxy): socat-tunneller opens an HTTP CONNECT tunnel to your proxy, asking it to establish a connection to on-prem-api.linearb.io:443. The TLS session then flows end-to-end from the agent to LinearB through that tunnel. Use this for a normal explicit corporate proxy.

• transparent: socat-tunneller forwards a raw TCP stream to EXTERNAL_PROXY_HOST:EXTERNAL_PROXY_PORT with no CONNECT verb. Your proxy must be pre-configured to forward that connection on to on-prem-api.linearb.io (typically by inspecting the TLS SNI). Only use this if you operate a transparent/intercepting gateway that is explicitly set up to route this traffic.

Enabling the proxy

1. In your local-values.yaml, set the four values under global:

global:
  EXTERNAL_PROXY: true
  EXTERNAL_PROXY_HOST: "proxy.corp.example.com"
  EXTERNAL_PROXY_PORT: "3128"
  EXTERNAL_PROXY_TYPE: "connect"

1. Make sure your corporate proxy allows outbound HTTPS to on-prem-api.linearb.io:443 (see Firewall / allowlisting).

2. Deploy or upgrade the agent as usual (helm upgrade --install …). Enabling the feature deploys the additional socat-tunneller workload.

Verifying

After deploying with the proxy enabled:

# The socat-tunneller pod should be running (it only exists when EXTERNAL_PROXY=true)
kubectl get pods -n linearb | grep socat

# Confirm forward-proxy is pointed at socat rather than directly at the internet
kubectl get configmap common-chart-values -n linearb \
  -o jsonpath='{.data.PROXY_PASS_API_DESTINATION}{"\n"}'
# Expected (proxy on):  on-prem-agent-socat-tunneller.linearb.svc.cluster.local:8443
# Expected (proxy off): on-prem-api.linearb.io

# Inspect socat-tunneller logs for connection activity/errors
kubectl logs -n linearb deploy/on-prem-agent-socat-tunneller

If the agent cannot report to the LinearB cloud after enabling the proxy, check, in order: the socat-tunneller pod is running, EXTERNAL_PROXY_HOST/PORT point at the real proxy (not localhost), and the proxy itself is allowed to reach on-prem-api.linearb.io:443.

Scope and limitations

The proxy feature deliberately covers only the LinearB-cloud API egress. Everything below is not routed through EXTERNAL_PROXY and must be planned separately.

What is not routed through the corporate proxy

The following flows egress directly from the agent pods/nodes even when EXTERNAL_PROXY is on. In a locked-down network, allowlist these on your firewall (or arrange another egress path):

See the Prerequisites guide for the full egress FQDN list.

Datadog does not use the proxy automatically

If the Datadog subchart is enabled (datadog-agent.enabled: true), the Datadog agent egresses directly to api.datadoghq.com — the EXTERNAL_PROXY setting does not apply to it. In a network where only the corporate proxy has internet access, this means metrics and logs will silently fail to reach Datadog.

You have three options:

1. Allowlist api.datadoghq.com (and *.datadoghq.com) directly on your firewall — it is already listed as a direct egress FQDN in the Prerequisites guide.
2. Point the Datadog agent at your corporate proxy by adding proxy environment variables to the Datadog subchart (no chart change required). Add them under envDict — see the warning below for why env is the wrong key:

datadog-agent:
  datadog:
    envDict:
      DD_PROXY_HTTPS: "http://proxy.corp.example.com:3128"
      DD_PROXY_HTTP: "http://proxy.corp.example.com:3128"
      # Match the entries below as suffixes and CIDRs, not as exact hostnames
      DD_NO_PROXY_NONEXACT_MATCH: "true"
      # Space-separated — that is the format Datadog defines for DD_PROXY_NO_PROXY
      DD_PROXY_NO_PROXY: "on-prem-agent-rabbitmq-headless kubernetes.default.svc localhost 127.0.0.1 169.254.169.254 .svc .svc.cluster.local .cluster.local 10.0.0.0/8"
  # The Cluster Agent does not inherit datadog.envDict — repeat the variables here.
  clusterAgent:
    envDict:
      DD_PROXY_HTTPS: "http://proxy.corp.example.com:3128"
      DD_PROXY_HTTP: "http://proxy.corp.example.com:3128"
      DD_NO_PROXY_NONEXACT_MATCH: "true"
      # Space-separated, as above
      DD_PROXY_NO_PROXY: "on-prem-agent-rabbitmq-headless kubernetes.default.svc localhost 127.0.0.1 169.254.169.254 .svc .svc.cluster.local .cluster.local 10.0.0.0/8"

The proxy value points at your corporate proxy directly — not at forward-proxy/socat, which only know how to reach the LinearB API. 3. Disable Datadog (datadog-agent.enabled: false) if you do not need it.

datadog-agent:
  datadog:
    env:
      - name: RABBITMQ_USER
        valueFrom:
          secretKeyRef:
            name: rabbitmq-secret
            key: rabbitmq-user
      - name: RABBITMQ_PASSWORD
        valueFrom:
          secretKeyRef:
            name: rabbitmq-secret
            key: rabbitmq-password
      - name: DD_PROXY_HTTPS
        value: "http://proxy.corp.example.com:3128"
      # ...and the remaining proxy variables
  # If you also override clusterAgent.env, repeat the same two credential entries there.

# substitute your Helm release name if it is not `on-prem-agent`
kubectl -n linearb set env daemonset/on-prem-agent-datadog-agent \
  --containers=agent --list | grep -E 'RABBITMQ_|DD_PROXY_|DD_NO_PROXY_'

kubectl -n linearb set env deployment/on-prem-agent-datadog-agent-cluster-agent \
  --containers=cluster-agent --list | grep -E 'RABBITMQ_|DD_PROXY_|DD_NO_PROXY_'

Container image pulls are not proxied

Kubernetes pulls the agent's container images using the node's container runtime (containerd/Docker), which is outside the forward-proxy/socat-tunneller path. If your cluster nodes have no direct internet access, image pulls will fail unless you either:

• configure the container runtime on each node with proxy settings (for containerd, a systemd drop-in that sets HTTP_PROXY/HTTPS_PROXY/NO_PROXY for the containerd service), or
• mirror the images into a registry your nodes can reach and point the chart at it (see Customizing Container Registry).

This is node/OS-level configuration and is not managed by the agent's Helm chart.

Proxy authentication is not supported

The tunnel connects to your corporate proxy without credentials. Proxies that require authentication (Basic/NTLM/Kerberos) are not currently supported by this feature. If your proxy enforces authentication, you will need an unauthenticated allowlist entry (or a dedicated egress path) for the agent to reach on-prem-api.linearb.io.

Custom CA vs. the proxy

The corporate-proxy feature and the custom-CA feature (global.CUSTOM_ROOT_CERTIFICATES) are independent:

• You do not need a custom CA to make EXTERNAL_PROXY work — TLS is tunneled end-to-end to LinearB, so your proxy's certificate is never validated by the agent for that path.
• You may still need CUSTOM_ROOT_CERTIFICATES: true (with your CA bundle) if your proxy performs TLS interception (MITM) on the other, non-proxied flows above — for example git clones or Jira API calls. Those are direct HTTPS calls from the agent and will fail certificate validation against an intercepting proxy unless the proxy's CA is trusted.

Single point of egress

When the proxy is enabled, all LinearB-cloud traffic for every service and job flows through the single forward-proxy → socat-tunneller path. If your corporate proxy is unreachable, all cloud reporting and ingestion stops until it recovers. Treat proxy availability as a dependency of the agent, and monitor socat-tunneller/forward-proxy pod health.

OpenShift: DNS resolver

Because forward-proxy resolves its upstream at runtime, on OpenShift you must point NGINX at the OpenShift DNS service or the proxied requests will fail DNS resolution:

forward-proxy:
  resolver: "dns-default.openshift-dns.svc.cluster.local"

See the v5 upgrade guide for details.

Firewall / allowlisting

When EXTERNAL_PROXY is enabled, plan connectivity as follows:

• The agent nodes/pods must be able to reach your corporate proxy at EXTERNAL_PROXY_HOST:EXTERNAL_PROXY_PORT.
• Your corporate proxy must be allowed to reach on-prem-api.linearb.io:443.
• All other egress destinations listed in What is not routed through the corporate proxy must be reachable directly from the agent (they do not traverse the proxy).

Reference