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 responsesUse this mode when your policy requires all external traffic to pass through your API gateway. Otherwise, the outbound (tunnel) setup is simpler.
Before you start
Section titled “Before you start”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.
1. Create the namespace and Secrets
Section titled “1. Create the namespace and Secrets”export CTX=<kube-context> NS=neubirdkubectl --context "$CTX" create namespace "$NS"
# proxy token (at least 32 characters) and the HMAC masking keykubectl --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 TLSkubectl --context "$CTX" -n "$NS" create secret tls neubird-proxy-tls \ --cert=tls.crt --key=tls.key-
The chart doesn’t create the
neubird-proxy-envSecret, 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
2. Write the values file
Section titled “2. Write the values file”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: inboundinbound: 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_KEYmethods: ["*"]allows every method exceptCONNECTandTRACE, for every host. If your systems are only read, use[GET, HEAD]instead.request_deny_patternsare RE2 regular expressions, matched against the query string and the body. The proxy refuses dangerous Splunk searches with403 request_denied.mask: hmackeeps masked values linkable: the same value always gets the same code. See HMAC masking for the trade-offs. To use plain labels instead, remove theredactionblock and theREDACTION_HMAC_KEYkey.
3. Install
Section titled “3. Install”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 systemkubectl --context "$CTX" -n "$NS" exec deploy/neubird-proxy -- \ /neubird-proxy test -config /etc/neubird-proxy/config.yaml https://splunk.corp.example.comLeave 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.
4. Point your gateway at the proxy
Section titled “4. Point your gateway at the proxy”Set the gateway’s backend to the proxy’s ClusterIP Service:
https://neubird-proxy.<namespace>.svc:8443The 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:
| Header | Value |
|---|---|
Authorization | Bearer <proxy token> |
X-Neubird-Destination | The 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.
5. Verify
Section titled “5. Verify”kubectl --context "$CTX" -n "$NS" get pods -l app.kubernetes.io/instance=neubird-proxykubectl --context "$CTX" -n "$NS" logs deploy/neubird-proxy | head -20 # startup, warningsSend a request through the proxy (Splunk example) from a host or pod that can reach the Service:
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:
kubectl --context "$CTX" -n "$NS" logs deploy/neubird-proxy | grep '"msg":"request"'Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause / fix |
|---|---|
ImagePullBackOff | The 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. |
401 | The proxy token from the gateway is missing or wrong. |
403 destination_not_allowed | X-Neubird-Destination is missing or isn’t https://host[:port], or its host isn’t in neubird_destinations.hosts. |
403 request_denied | The query or body matched request_deny_patterns. The reason includes the index of the pattern that matched. |
404 unknown_connection | The path isn’t under /_neubird/dest/. |
502 upstream_unavailable + x509: unknown authority | The system uses an internal CA. Pass it with --set-file upstreamCA.cert=.... |
502 upstream_unavailable + no such host / timeout | DNS or a firewall between the proxy and the system. |