Skip to content

Inbound (proxy-only) setup

In inbound (proxy-only) mode, the proxy doesn’t open a tunnel. Your own API gateway receives NeuBird’s requests and forwards them to the proxy’s Service on port 8443. The proxy checks the token, the destination and the method, forwards the request to your system, and redacts the response.

NeuBird ──▶ your API gateway ──▶ neubird-proxy (Service :8443) ──▶ your systems
checks token, destination, (Splunk, ...)
methods; redacts responses

Use this mode when your policy requires all external traffic to pass through your API gateway. Otherwise, the outbound (tunnel) setup is simpler.

You need everything listed in Before you start, and also:

  • Listener TLS: a certificate and key that your gateway trusts, issued for neubird-proxy.<namespace>.svc, the name your gateway connects to.
Terminal window
export CTX=<kube-context> NS=neubird
kubectl --context "$CTX" create namespace "$NS"
# proxy token (at least 32 characters) and the HMAC masking key
kubectl --context "$CTX" -n "$NS" create secret generic neubird-proxy-env \
--from-literal=NEUBIRD_PROXY_TOKEN="$(openssl rand -base64 48)" \
--from-literal=REDACTION_HMAC_KEY="$(openssl rand -base64 48)"
# listener TLS
kubectl --context "$CTX" -n "$NS" create secret tls neubird-proxy-tls \
--cert=tls.crt --key=tls.key
  • The chart doesn’t create the neubird-proxy-env Secret, and it must contain both keys.

  • Keep the proxy token: your gateway sends it to the proxy on every request. To read it back:

    Terminal window
    kubectl --context "$CTX" -n "$NS" get secret neubird-proxy-env \
    -o jsonpath='{.data.NEUBIRD_PROXY_TOKEN}' | base64 -d

Create inbound-values.yaml:

image:
repository: <your registry>/neubird-proxy/neubird-proxy
digest: sha256:78197d45a38c2ac25cacc6973a6af56c443345902258e543652ffa51f12a139b # 1.0.0 (cc97e4f)
imagePullSecrets:
- name: <pull-secret> # leave out for a public registry
mode: inbound
inbound:
tls: {existingSecret: neubird-proxy-tls}
env:
existingSecret: neubird-proxy-env
config:
neubird_destinations:
hosts: ["splunk.corp.example.com"] # the systems NeuBird may reach (required)
methods: ["*"] # GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
request_deny_patterns: # block Splunk commands that write, send or run
- '(?i)\|\s*(delete|collect|mcollect|meventcollect|tscollect|map)\b'
- '(?i)\|\s*(sendemail|sendalert|sendresults|outputlookup|outputcsv|outputtext)\b'
- '(?i)\|\s*(script|run|runshellscript|dbxoutput|dbxquery)\b'
redaction:
mask: hmac
hmac_key_env: REDACTION_HMAC_KEY
  • methods: ["*"] allows every method except CONNECT and TRACE, for every host. If your systems are only read, use [GET, HEAD] instead.
  • request_deny_patterns are RE2 regular expressions, matched against the query string and the body. The proxy refuses dangerous Splunk searches with 403 request_denied.
  • mask: hmac keeps masked values linkable: the same value always gets the same code. See HMAC masking for the trade-offs. To use plain labels instead, remove the redaction block and the REDACTION_HMAC_KEY key.
Terminal window
helm install neubird-proxy oci://ghcr.io/neubirdai/charts/neubird-proxy --version 1.0.0 \
--kube-context "$CTX" -n "$NS" \
-f inbound-values.yaml \
--set-file upstreamCA.cert=/path/to/ca-bundle.crt \
--wait
# check DNS, TCP and TLS from the proxy pod to each system
kubectl --context "$CTX" -n "$NS" exec deploy/neubird-proxy -- \
/neubird-proxy test -config /etc/neubird-proxy/config.yaml https://splunk.corp.example.com

Leave out --set-file upstreamCA.cert=... if every system has a publicly trusted certificate. If you use it, pass it on every later upgrade too, because an upgrade without it removes the CA.

Set the gateway’s backend to the proxy’s ClusterIP Service:

https://neubird-proxy.<namespace>.svc:8443

The gateway forwards each request to /_neubird/dest/<path> on the proxy, where <path> is the system’s own API path (for example /_neubird/dest/services/server/info). Each request must carry these headers:

HeaderValue
AuthorizationBearer <proxy token>
X-Neubird-DestinationThe system’s URL as https://host[:port], for example https://splunk.corp.example.com. The host must match neubird_destinations.hosts.
X-Neubird-Upstream-<Header>The system’s credentials. The proxy forwards them as <Header>, so X-Neubird-Upstream-Authorization: Bearer <splunk token> reaches Splunk as Authorization: Bearer <splunk token>.

Send NeuBird the gateway URL and how the gateway authenticates callers, so NeuBird can configure the connection. The proxy token stays between your gateway and the proxy, unless NeuBird calls the proxy directly.

Terminal window
kubectl --context "$CTX" -n "$NS" get pods -l app.kubernetes.io/instance=neubird-proxy
kubectl --context "$CTX" -n "$NS" logs deploy/neubird-proxy | head -20 # startup, warnings

Send a request through the proxy (Splunk example) from a host or pod that can reach the Service:

Terminal window
TOKEN=$(kubectl --context "$CTX" -n "$NS" get secret neubird-proxy-env \
-o jsonpath='{.data.NEUBIRD_PROXY_TOKEN}' | base64 -d)
curl -s --cacert <CA that signed tls.crt> \
"https://neubird-proxy.$NS.svc:8443/_neubird/dest/services/server/info?output_mode=json" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Neubird-Destination: https://splunk.corp.example.com" \
-H "X-Neubird-Upstream-Authorization: Bearer <splunk token>"

The proxy writes an audit line for every request:

Terminal window
kubectl --context "$CTX" -n "$NS" logs deploy/neubird-proxy | grep '"msg":"request"'
SymptomCause / fix
ImagePullBackOffThe digest isn’t in your registry (for example, because you copied the image with docker push instead of az acr import), or the pull secret is wrong.
401The proxy token from the gateway is missing or wrong.
403 destination_not_allowedX-Neubird-Destination is missing or isn’t https://host[:port], or its host isn’t in neubird_destinations.hosts.
403 request_deniedThe query or body matched request_deny_patterns. The reason includes the index of the pattern that matched.
404 unknown_connectionThe path isn’t under /_neubird/dest/.
502 upstream_unavailable + x509: unknown authorityThe system uses an internal CA. Pass it with --set-file upstreamCA.cert=....
502 upstream_unavailable + no such host / timeoutDNS or a firewall between the proxy and the system.