> 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/core-concepts/gateways.md).

# Gateways

Gateways are groups of collectors that receive telemetry from edge collectors, process it centrally, and forward it to destinations.

A Gateway is a named group of gateway collectors that sits between your edge collectors and your destinations. Edge collectors send telemetry to the Gateway; the Gateway processes it and forwards it to your SIEM, observability backend, or storage. In Bindplane, a Gateway is a resource you create and manage directly, with its own page, setup checklist, configuration, and telemetry view.

{% hint style="info" %}
Gateways are different from the [OpAMP Gateway](/feature-guides/deployment-and-management/opamp-gateway.md) extension. A Gateway carries **telemetry** from edge collectors to destinations. The OpAMP Gateway extension relays **management traffic** (OpAMP) from collectors to the Bindplane server.
{% endhint %}

## Why Use a Gateway

Most large deployments need a gateway tier. A Gateway gives you:

* **Credential isolation**: only gateway collectors hold destination API keys and certificates. Edge collectors never see them.
* **Network control**: outbound traffic leaves your network from a small, known set of hosts instead of from every server.
* **Central processing**: filtering, parsing, enrichment, and sampling run on dedicated, well-sized gateway collectors instead of competing with your workloads at the edge.
* **One place to change routing**: switch or add destinations once on the Gateway instead of rolling out to every edge collector.

For sizing and architecture guidance, see [Edge Collectors v. Gateways](/production-checklist/bindplane-otel-collector/edge-collectors-v.-gateways.md).

## How Gateways Work

A Gateway groups collectors with the **Gateway** role. Every collector in a Gateway carries a `gateway=<name>` label and runs the configuration assigned to the Gateway.

* **One configuration per Gateway.** Assign a configuration with the **Gateway** role. All members run it, and new members pick it up automatically.
* **Gateway takes priority.** If a collector belongs to a Gateway, the Gateway's configuration wins over any Edge Fleet or `configuration` label. See [Core Concepts](/core-concepts.md#how-a-collector-gets-its-configuration).
* **Gateways and Edge Fleets are separate.** Gateway collectors aren't added to Edge Fleets. Edge Fleets are for edge collectors.
* **Status is live.** The Gateway page shows collector counts, connection status, collector versions, the configurations members are running, and throughput.

Edge collectors reach a Gateway with the [Bindplane Gateway destination](/integrations/destinations/bindplane-gateway.md). The gateway configuration receives that traffic with the [Bindplane Gateway source](/integrations/sources/bindplane-gateway.md) over OTLP on port 4317 (gRPC) or 4318 (HTTP).

## Creating a Gateway

Select **Gateways** in the navigation and create a new Gateway. First, choose a deployment method:

| Deployment method     | When to use it                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Kubernetes**        | Run the gateway on a Kubernetes cluster. Gateway collectors run as a scalable workload behind a Kubernetes Service. |
| **Load Balanced VMs** | Run the gateway on one or more VMs behind a load balancer.                                                          |

Then give the Gateway a name, such as `US East`, choose the collector type, and select **Create Gateway**.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-c3d9c3ff33d83a90cc31c7070fb3464e6dbf3c4d%2Ffeature-guides-gateways-create-configure.png?alt=media" alt="Create Gateway drawer with Kubernetes selected, showing the Gateway Name and Collector Type fields"><figcaption></figcaption></figure>

Bindplane opens the Gateway's page with a **Finish setting up this Gateway** checklist. Work through it to finish the deployment, then select **Complete Setup**:

1. **Provision your gateway infrastructure.** Choose a deployment type and set up its components. The checklist links to single-node and multi-node guides, and a sizing guide.
2. **Install Collectors.** Install a gateway collector on each host. Collectors installed from the Gateway page join the Gateway automatically.
3. **Enter Hostname.** Enter the fully qualified hostname or IP address that edge collectors use to reach the Gateway, usually the load balancer's address. You can edit it later from the **Hostname** field in the Gateway's details.
4. **Publish a Configuration.** Assign the configuration the Gateway's collectors will run, add your final destinations and any central processing, then roll it out.

Once setup is complete, the Gateway page shows the Gateway's details, telemetry throughput, collector status and versions, and its member collectors.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-541ee26dda59753cb9a7f1ed81f1ee73db6f6c3e%2Ffeature-guides-gateways-detail-page.png?alt=media" alt="Gateway page after setup, showing Details, Telemetry Overview, Collector Status, Collector Versions, and the Collectors table"><figcaption></figcaption></figure>

Next, point your edge collectors at the Gateway: add a Bindplane Gateway destination to your edge configurations using the Gateway's hostname, then roll them out.

#### CLI

Optionally, you can use the CLI to create a Gateway. Define your Gateway in a YAML file. Below is an explanation of the parameters.

| Parameter                   | Description                                                                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiVersion`                | The API version of the resource. Gateway resources use `bindplane.observiq.com/v1`.                                                                                                   |
| `kind`                      | The kind of resource. In this case, `Gateway`.                                                                                                                                        |
| `metadata.name`             | A unique identifier for the Gateway. Collectors join the Gateway with the label `gateway=<metadata.name>`. Must be a valid Kubernetes label value and can't be changed later.         |
| `metadata.displayName`      | A friendly, readable name for the Gateway.                                                                                                                                            |
| `metadata.description`      | An optional description of the Gateway.                                                                                                                                               |
| `spec.configuration`        | The name of the configuration with the **Gateway** role that member collectors run. Don't include a version; rollouts control which version is live. May be empty and assigned later. |
| `spec.loadBalancerHostname` | Optional. The fully qualified hostname or IP address that edge collectors use to reach the Gateway. This is the **Hostname** shown on the Gateway page.                               |

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Gateway
metadata:
    name: us-east-gateway
    displayName: US East Gateway
    description: Gateway for us-east edge collectors
spec:
    configuration: ""
    loadBalancerHostname: gateway.us-east.example.com
```

Apply the Gateway. For example:

```sh
bindplane apply us-east-gateway.yaml
```

Make sure the API key used to make these requests has permission to create and modify Gateways (requires project admin or project user permission).

### Gateways Managed by the Kubernetes Operator

If you deploy gateway collectors with the Bindplane Kubernetes Operator, the Gateway's lifecycle follows the operator workload:

* Adding a gateway workload to an operator configuration creates the Gateway. Each cluster gets one Gateway per gateway workload.
* Removing the workload deletes the Gateway. You can't delete an operator-managed Gateway from the Gateway page.
* Bindplane names the Gateway after the operator and workload, shown as `<operator> / <workload>`.

{% hint style="info" %}
Operator-managed Gateways may not be enabled for every organization yet. If you don't see the operator option in the install wizard, use the Kubernetes or Load Balanced VMs option.
{% endhint %}

## Adding Collectors to a Gateway

Use **Install Collectors** on the Gateway page, or in the setup checklist, to add capacity. The **Install Collectors for Gateway** drawer shows an install command for the Gateway's platform. Run it on each host you want in the Gateway. The command sets the `gateway=<name>` label, for example `-k 'gateway=dynatrace-gateway'` on Linux, so new collectors join the Gateway and receive its configuration as soon as they connect. New collectors appear in the drawer's table once they start up.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-6023376f0be2b48f67c21c626f5262a24278c1b6%2Ffeature-guides-gateways-install-collectors.png?alt=media" alt="Install Collectors for Gateway drawer with a Linux install command that sets the gateway label, and a table where new collectors appear"><figcaption></figcaption></figure>

The `gateway` label is managed by Bindplane. It's hidden from the label editor, so use the Gateway page or the CLI to add or remove collectors.

If a collector connects with a `gateway` label for a Gateway that doesn't exist yet, Bindplane creates the Gateway automatically.

#### CLI

Optionally, you can add a collector to a Gateway through the CLI by assigning the `gateway` label to the collector.

```sh
bindplane label collector <collector-id> gateway=<gateway-name>
```

To add collectors at install time, include the label in the install command, for example `-k 'gateway=<gateway-name>'` on Linux. The install command generated on the Gateway page already includes it.

## Removing Collectors from a Gateway

In the **Collectors** table on the Gateway page, select the collectors to remove, then select **Remove Collector** and confirm with **Remove**.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-5c7699a12eced4bba2480e975452acc3f9681614%2Ffeature-guides-gateways-remove-collectors.png?alt=media" alt="Remove collector confirmation dialog on a Gateway page, explaining that the gateway label is removed from the selected collector"><figcaption></figcaption></figure>

Removing a collector deletes its `gateway` label. The collector stays connected to Bindplane and isn't deleted, but it no longer belongs to the Gateway or runs the Gateway's configuration. It falls back to its Edge Fleet or `configuration` label, if it has one, or to an empty configuration. See [How a Collector Gets Its Configuration](/core-concepts.md#how-a-collector-gets-its-configuration).

{% hint style="warning" %}
Removing a collector doesn't stop the process on the host or pod. If the collector's deployment still sets the `gateway` label, for example in a Gateway manifest or install command, the collector can rejoin the Gateway when it's reinstalled or restarted. Uninstall it or remove it from your deployment to take it out of service.
{% endhint %}

#### CLI

Optionally, you can remove a collector from a Gateway through the CLI by removing the `gateway` label from the collector.

```sh
bindplane label collector <collector-id> gateway- --overwrite
```

## Changing a Gateway's Configuration

On the Gateway page, select **Change Configuration**, or **Assign Configuration** in the setup checklist. Choose a configuration with the **Gateway** role and select **Assign**. To remove the Gateway's configuration, select **Detach**.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-e427bb628993a0aa4d45a505e8b04fc527d4b300%2Ffeature-guides-gateways-select-configuration.png?alt=media" alt="Select a Configuration dialog on a Gateway page, with gateway configurations listed in the Configurations dropdown and Detach, Cancel, and Assign buttons"><figcaption></figcaption></figure>

Roll out the configuration to push it to every member collector. See [Rollouts](/core-concepts/rollouts.md).

#### CLI

Optionally, you can assign a configuration to a Gateway through the CLI by updating the YAML file with the configuration name.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Gateway
metadata:
    name: us-east-gateway
    displayName: US East Gateway
    description: Gateway for us-east edge collectors
spec:
    configuration: us-east-gateway-config
    loadBalancerHostname: gateway.us-east.example.com
```

```sh
bindplane apply us-east-gateway.yaml
```

{% hint style="warning" %}
A configuration that's assigned to a Gateway can't be deleted. Assign a different configuration to the Gateway first.
{% endhint %}

{% hint style="info" %}
Operator-managed Gateways get their configuration from the operator workload, so you can't assign one directly, and `spec.configuration` must stay empty.
{% endhint %}

## Viewing Gateway Collectors

The **Gateways** page lists every Gateway in the project with its collector count and throughput. To see the individual collectors, open a Gateway or use the **Gateway Instances** tab on the [Collectors](/core-concepts/collectors.md) page. The **Fleet / Gateway** column shows which Gateway each collector belongs to.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-b8f669a92dc471d46ae58bdc5dca6fcbd289bf61%2Ffeature-guides-collectors-gateway-instances-tab.png?alt=media" alt="Collectors page with the Gateway Instances tab selected, listing gateway collectors and their Gateway in the Fleet / Gateway column"><figcaption></figcaption></figure>

#### CLI

Optionally, you can list Gateways through the CLI:

```sh
bindplane get gateways
```

Or get a single Gateway as YAML:

```sh
bindplane get gateway <gateway-name> -o yaml
```

## Deleting a Gateway

On the Gateway page, select **Delete** and confirm. Deleting a Gateway removes it from Bindplane and can't be undone.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-b1a0ed886db7ad2ba6596797b03181754f58dd68%2Ffeature-guides-gateways-delete.png?alt=media" alt="Delete gateway confirmation dialog warning that the action cannot be undone"><figcaption></figcaption></figure>

{% hint style="warning" %}
All collectors must be removed from the Gateway before it can be deleted. See [Removing Collectors from a Gateway](#removing-collectors-from-a-gateway).
{% endhint %}

Gateways managed by the Kubernetes Operator can't be deleted from the Gateway page. Remove the gateway workload from the operator configuration instead. See [Gateways Managed by the Kubernetes Operator](#gateways-managed-by-the-kubernetes-operator).

#### CLI

Optionally, you can delete the Gateway through the CLI.

```sh
bindplane delete gateway <gateway-name>
```

The REST API also supports listing, getting, and deleting Gateways under `/v1/gateways`.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bindplane.com/core-concepts/gateways.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.