Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/netboxlabs/orb-agent

Orb network observability agent, part of the NetBox ecosystem and developed by NetBox Labs
https://github.com/netboxlabs/orb-agent

diode discovery netbox network network-observability observability orb

Last synced: 1 day ago
JSON representation

Orb network observability agent, part of the NetBox ecosystem and developed by NetBox Labs

Host: GitHub
URL: https://github.com/netboxlabs/orb-agent
Owner: netboxlabs
License: apache-2.0
Created: 2024-10-07T15:46:36.000Z (4 months ago)
Default Branch: develop
Last Pushed: 2025-01-16T21:08:48.000Z (10 days ago)
Last Synced: 2025-01-16T22:22:02.345Z (10 days ago)
Topics: diode, discovery, netbox, network, network-observability, observability, orb
Language: Go
Homepage: https://netboxlabs.com
Size: 240 KB
Stars: 17
Watchers: 1
Forks: 2
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Security: SECURITY.md

Awesome Lists containing this project

README

# Orb Agent - the NetBox Discovery agent
Orb agent is a component of the NetBox Discovery solution. It provides network discovery and observability capabilities and is developed by NetBox Labs.

## Project status
The Orb agent project is currently in the Public Preview stage. For details, please see [NetBox Labs Product and Feature Lifecycle](https://docs.netboxlabs.com/product_feature_lifecycle/). We actively welcome feedback to help us identify and prioritize bugs, features, and improvements.

## Getting Started
To get started with `orb-agent`, first pull the Docker image from [Docker Hub](https://hub.docker.com/r/netboxlabs/orb-agent):

```sh
docker pull netboxlabs/orb-agent:latest
```

## Orb Agent Configuration
The Orb agent requires a configuration file. This file consists of three main sections: `config_manager`, `backends`, and `policies`.

### Config Manager
The `config_manager` section specifies how Orb agent should retrieve it's configuration information. The configuration manager is responsible for processing the configuration to retrieve policies and pass them to the appropriate backend.

```yaml
orb:
config_manager:
active: local
...
```

Currently, only the `local` manager is supported, which retrieves policies from the local configuration file passed to the agent.

### Backends
The `backends` section specifies what Orb agent backends should be enabled. Each Orb agent backend offers specific discovery or observability capabilities and may require specific configuration information.

```yaml
orb:
...
backends:
network_discovery:
...
```
Only the `network_discovery`, `device_discovery` and `worker` backends are currently supported. They do not require any special configuration.
- [Device Discovery](./docs/backends/device_discovery.md)
- [Network Discovery](./docs/backends/network_discovery.md)
- [Worker](./docs/backends/worker.md)

#### Common
A special `common` subsection under `backends` defines configuration settings that are shared with all backends. Currently, it supports passing [diode](https://github.com/netboxlabs/diode) server settings to all backends.

```yaml
backends:
...
common:
diode:
target: grpc://192.168.0.22:8080/diode
api_key: ${DIODE_API_KEY}
agent_name: agent01
```

### Policies
The `policies` section specifies what discovery policies should be passed to each backend. Policies define specific settings for discovery (such as scheduling and default properties) and the scope (targets). Backends can run multiple policies simultaneously, but for each backend all policies must have a unique name. These policies are defined in the `policies` section and are grouped under a subsection for each backend:

```yaml
orb:
...
policies:
device_discovery:
device_policy_1:
# see docs/backends/device_discovery.md
network_discovery:
network_policy_1:
# see docs/backends/network_discovery.md
worker:
worker_policy_1:
# see docs/backends/worker.md
```

## Running the agent

To run `orb-agent`, use the following command from the directory where your created your `agent.yaml` file:

```sh
docker run --net=host -v $(PWD):/opt/orb/ netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml
```
The container needs sufficient permissions, to send `icmp` and `tcp` packets. This can either be achieved by setting the network-mode to `host` or by changing the container user to `root`:

```sh
docker run -u root -v $(PWD):/opt/orb/ netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml
```

### Configuration samples
You can find complete sample configurations [here](./docs/config_samples.md) of how to configure Orb agent to run network and device discoveries, as well as the relevant `docker run` commands.