> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/bindplane-gateway.md). # Bindplane Gateway The Bindplane Gateway source receives OTLP metrics, logs, and traces sent by other Bindplane agents that use a [Bindplane Gateway destination](https://docs.bindplane.com/integrations/destinations/bindplane-gateway). It is the receiving half of Bindplane's gateway pattern, where a small set of central collectors aggregate telemetry from a fleet of edge agents before forwarding it to your destinations. The source listens for OTLP over gRPC (default port `4317`) and HTTP (default port `4318`). When paired with a Bindplane Gateway destination, telemetry passing through this source is not double-counted in the Summary view, and connections between gateway sources and destinations can be rendered on the overview page through gateway topology. ### Supported Telemetry | Platform | Metrics | Logs | Traces | | --------------------------- | ------- | ---- | ------ | | Linux | ✓ | ✓ | ✓ | | macOS | ✓ | ✓ | ✓ | | Windows | ✓ | ✓ | ✓ | | Kubernetes Node (DaemonSet) | ✓ | ✓ | ✓ | | Kubernetes Deployment | ✓ | ✓ | ✓ | | Kubernetes Gateway | ✓ | ✓ | ✓ | | OpenShift Node (DaemonSet) | ✓ | ✓ | ✓ | | OpenShift Deployment | ✓ | ✓ | ✓ | | OpenShift Gateway | ✓ | ✓ | ✓ | ### Prerequisites This is an internal Bindplane source, so there is no third-party vendor to configure. You need: * One or more Bindplane agents acting as gateway nodes, running a configuration that includes this source. * Other Bindplane agents (or configurations) that send telemetry using a [Bindplane Gateway destination](https://docs.bindplane.com/integrations/destinations/bindplane-gateway) pointed at this gateway's address. * Network reachability from the sending agents to the gateway on the configured gRPC and HTTP ports (defaults `4317` and `4318`). For background on when to deploy gateways versus agents, see [Agents v. Gateways](https://docs.bindplane.com/production-checklist/bindplane-otel-collector/agents-v.-gateways). ### Configuration
Bindplane docs - Bindplane Gateway - image 1
**General** | Parameter | Type | Required | Default | Description | | --------------------- | ------------------ | -------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Choose Telemetry Type | telemetry selector | No | `["Logs", "Metrics", "Traces"]` | Select which types of telemetry to accept. | | Listen Address | string | No | `0.0.0.0` | The IP address to listen on. | | GRPC Port | int | No | `4317` | TCP port to receive OTLP telemetry using the gRPC protocol. The port used must not be the same as the HTTP port. Set to `0` to disable. | | HTTP Port | int | No | `4318` | TCP port to receive OTLP telemetry using the HTTP protocol. The port used must not be the same as the gRPC port. Set to `0` to disable. | **Advanced** | Parameter | Type | Required | Default | Description | | ----------------------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum Message Size | int | No | `20` | Sets the maximum size (in MiB) of messages accepted by the server. Applies when GRPC Port is not `0`. | | Enable Gateway Topology | bool | No | `true` | Enables tracking connections between Bindplane Gateway sources and destinations to render gateway connections on the overview page. | | Topology Interval | duration | No | `1m` | The rate at which topology updates are sent to Bindplane. Applies when Enable Gateway Topology is `true`. Applicable only for topology processor version v1.75.0 and earlier; for v1.76.0 and later, use the Advanced Configuration Options. | | Include Metadata | bool | No | `false` | Propagates the incoming connection's metadata to downstream consumers. Applies when Enable Gateway Topology is `false`. | **TLS (Advanced)** | Parameter | Type | Required | Default | Description | | ------------------------------ | ------ | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Enable TLS | bool | No | `false` | Whether or not to use TLS. | | Server Certificate File | string | Yes (when Enable TLS) | *(empty)* | A path to the server certificate to be used for TLS. Required when Enable TLS is `true`. | | Server Private Key | string | Yes (when Enable TLS) | *(empty)* | A path to the server private key to be used for TLS. Required when Enable TLS is `true`. | | Mutual TLS | bool | No | `false` | Whether or not to require client TLS authentication (mTLS). Applies when Enable TLS is `true`. | | TLS Certificate Authority File | string | Yes (when Mutual TLS) | *(empty)* | A path to the certificate authority to use for authenticating client certificates. Required when Enable TLS and Mutual TLS are both `true`. | **GRPC Timeout (Advanced)** Applies when GRPC Port is not `0`. | Parameter | Type | Required | Default | Description | | ------------------------ | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable GRPC Timeout | bool | No | `true` | Enable to configure advanced gRPC timeout behavior. | | Max Idle Time | int | No | `60` | Maximum amount of time (seconds) after which an idle connection would be closed by sending a GoAway. Applies when Enable GRPC Timeout is `true`. | | Max Connection Age | int | No | `60` | Maximum amount of time (seconds) a connection may exist before it will be closed by sending a GoAway. Applies when Enable GRPC Timeout is `true`. | | Max Connection Age Grace | int | No | `300` | Additive period after Max Connection Age after which the connection will be forcibly closed. Applies when Enable GRPC Timeout is `true`. | **HTTP Timeout (Advanced)** Applies when HTTP Port is not `0`. | Parameter | Type | Required | Default | Description | | ------------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable HTTP Timeout | bool | No | `true` | Enable to configure advanced HTTP timeout behavior. | | Read Timeout | int | No | `0` | Maximum duration (seconds) for reading the entire request, including the body. Set to `0` to disable. Applies when Enable HTTP Timeout is `true`. | | Read Header Timeout | int | No | `60` | Maximum duration (seconds) allowed to read request headers. The connection deadline resets after headers are read. Set to `0` to disable. Applies when Enable HTTP Timeout is `true`. | | Write Timeout | int | No | `30` | Maximum duration (seconds) before timing out writes of the response. Resets on each new request header. Set to `0` to disable. Applies when Enable HTTP Timeout is `true`. | | Idle Timeout | int | No | `60` | Maximum time (seconds) to wait for the next request when keep-alives are enabled. Set to `0` to disable. Applies when Enable HTTP Timeout is `true`. | **CORS (Advanced)** Applies when HTTP Port is not `0`. | Parameter | Type | Required | Default | Description | | -------------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | Configure CORS | bool | No | `false` | Enable Cross-Origin Resource Sharing support for HTTP requests. | | CORS Allowed Origins | strings | No | *(empty)* | A list of origins a cross-domain request can be executed from. Applies when Configure CORS is `true`. | | CORS Allowed Headers | strings | No | *(empty)* | The allowed headers sets what headers will be allowed in CORS requests. Applies when Configure CORS is `true`. | | CORS Max Age | int | No | `0` | Indicates how long (in seconds) the results of a preflight request can be cached. Applies when Configure CORS is `true`. | ### Examples #### Receive all signals on the default ports A gateway node that accepts logs, metrics, and traces over OTLP gRPC and HTTP on every interface, using the defaults. This is the minimal configuration. There are no required fields unless you enable TLS. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: bindplane-gateway spec: type: bindplane_gateway parameters: - name: telemetry_types value: - Logs - Metrics - Traces - name: listen_address value: "0.0.0.0" - name: grpc_port value: 4317 - name: http_port value: 4318 ``` #### Terminate TLS at the gateway Enable server-side TLS so sending agents connect over an encrypted channel. The certificate and key files must exist on the gateway host. The sending agents' Bindplane Gateway destination must be configured to use TLS against the same hostname the certificate is issued for. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: bindplane-gateway-tls spec: type: bindplane_gateway parameters: - name: telemetry_types value: - Logs - Metrics - Traces - name: enable_tls value: true - name: cert_file value: /opt/observiq-otel-collector/tls/gateway.crt - name: key_file value: /opt/observiq-otel-collector/tls/gateway.key ``` #### Require client certificates with mutual TLS For environments where the gateway must authenticate the sending agents, enable Mutual TLS and supply a certificate authority file. Only clients presenting a certificate signed by that CA are accepted. Each sending agent must present a client certificate trusted by the configured CA. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: bindplane-gateway-mtls spec: type: bindplane_gateway parameters: - name: telemetry_types value: - Logs - Metrics - Traces - name: enable_tls value: true - name: cert_file value: /opt/observiq-otel-collector/tls/gateway.crt - name: key_file value: /opt/observiq-otel-collector/tls/gateway.key - name: mutual_tls value: true - name: ca_file value: /opt/observiq-otel-collector/tls/ca.crt ``` #### Kubernetes service endpoints The source can be attached to any Kubernetes or OpenShift Node (DaemonSet), Deployment, or Gateway configuration without extra parameters. Applications and agents inside the cluster forward telemetry to the managed collectors through the cluster's services. The following endpoints reach the managed Node (DaemonSet) collectors: | Protocol | Service | Endpoint | | -------- | ------------------ | ---------------------------------------------------------------------- | | gRPC | clusterIP | `bindplane-node-agent.bindplane-agent.svc.cluster.local:4317` | | gRPC | headless clusterIP | `bindplane-node-agent-headless.bindplane-agent.svc.cluster.local:4317` | | HTTP | clusterIP | `http://bindplane-node-agent.bindplane-agent.svc.cluster.local:4318` | The following endpoints reach the managed Gateway collectors: | Protocol | Service | Endpoint | | -------- | ------------------ | ------------------------------------------------------------------------- | | gRPC | clusterIP | `bindplane-gateway-agent.bindplane-agent.svc.cluster.local:4317` | | gRPC | headless clusterIP | `bindplane-gateway-agent-headless.bindplane-agent.svc.cluster.local:4317` | | HTTP | clusterIP | `http://bindplane-gateway-agent.bindplane-agent.svc.cluster.local:4318` | Forwarding to either the DaemonSet or the Gateway collectors is a matter of preference. The Gateway collector is recommended when DaemonSet resource consumption is a concern, because it scales independently of cluster size. ### Configuration Tips * The gRPC and HTTP ports must differ. Set either port to `0` to disable that protocol, but do not set both to `0` or the source will accept no traffic. * Leave Enable Gateway Topology on so connections between this source and downstream Bindplane Gateway destinations render on the overview page. Disable it only if you instead need raw connection metadata propagated downstream through Include Metadata. * When this source is paired with a Bindplane Gateway destination, telemetry passing through the gateway is excluded from double-counting in the Summary view. ### Troubleshooting **Symptom:** Sending agents fail to connect and the gateway logs a TLS handshake error. **Solution:** Confirm Enable TLS is on and that the Server Certificate File and Server Private Key paths exist and are readable by the collector on the gateway host. The certificate's subject or SAN must match the hostname the sending agents' Bindplane Gateway destination is pointed at. **Symptom:** With Mutual TLS enabled, clients are rejected even though server TLS works. **Solution:** Ensure the TLS Certificate Authority File on the gateway is the CA that signed the sending agents' client certificates, and that each sending agent presents a client certificate. Mutual TLS requires both Enable TLS and Mutual TLS to be `true`. **Symptom:** No telemetry arrives and connections are refused or time out. **Solution:** Verify the gRPC and HTTP ports are not blocked by a firewall or, in Kubernetes, that the correct clusterIP service and port are used. Confirm the disabled port is not set to `0` for the protocol the sending agents use, and that the gRPC and HTTP ports are distinct. ### Standalone Source ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: bindplane-gateway spec: type: bindplane_gateway parameters: - name: telemetry_types value: - Logs - Metrics - Traces - name: listen_address value: "0.0.0.0" - name: grpc_port value: 4317 - name: http_port value: 4318 - name: enable_tls value: false - name: enable_topology value: true - name: topology_interval value: "1m" ``` ### Related Resources * [Bindplane Gateway destination](https://docs.bindplane.com/integrations/destinations/bindplane-gateway) — the sending half of the gateway pattern. * [Agents v. Gateways](https://docs.bindplane.com/production-checklist/bindplane-otel-collector/agents-v.-gateways) — guidance on when to use gateways. * [OpenTelemetry OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver) — the upstream receiver this source configures. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/sources/bindplane-gateway.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.