mirror of
https://github.com/compute-blade-community/compute-blade-agent.git
synced 2026-04-16 15:35:42 +02:00
7ec49ce05c
* feat(OpenTelemetry): Integrate OpenTelemetry into agent - integrate OpenTelemetry logging with zap logger for better observability - add OpenTelemetry gRPC middleware for enhanced tracing capabilities - document new OTLP exporter endpoint for better configuration guidance * docs: document OTEL env var --------- Co-authored-by: Cedric Kienzler <cedric@specht-labs.de>
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# compute-blade-agent
|
|
|
|
> :warning: **Beta Release**: This software is currently in beta, and both configurations and APIs may undergo breaking changes. It is not yet 100% feature complete, but it functions as intended.
|
|
|
|
## Quick Start
|
|
|
|
Install the agent with the one-liner below:
|
|
|
|
```bash
|
|
curl -L -o /tmp/compute-blade-agent-installer.sh https://raw.githubusercontent.com/compute-blade-community/compute-blade-agent/main/hack/autoinstall.sh
|
|
chmod +x /tmp/compute-blade-agent-installer.sh
|
|
/tmp/compute-blade-agent-installer.sh
|
|
```
|
|
|
|
## Components
|
|
|
|
### `compute-blade-agent`: Hardware Interaction & Monitoring
|
|
|
|
The agent runs as a system service and monitors various hardware states and events:
|
|
|
|
- Reacts to button presses and SoC temperature.
|
|
- Automatically enters **critical mode** (fan 100%, red LED) when overheating.
|
|
- Exposes system metrics via a Prometheus endpoint (`/metrics`).
|
|
|
|
The _identify_ function can be triggered via `bladectl` or a physical button press. It makes the edge LED blink to assist locating a blade in a rack.
|
|
|
|
### `bladectl`: User Command-Line Tool
|
|
|
|
`bladectl` is a CLI utility for remote or local interaction with the running agent. Example use cases:
|
|
|
|
```bash
|
|
bladectl set identify --wait # Blink LED until button is pressed
|
|
bladectl set identify --confirm # Cancel identification
|
|
bladectl unset identify # Cancel identification (alternative)
|
|
```
|
|
|
|
### `fanunit.uf2`: Smart Fan Unit Firmware
|
|
|
|
This firmware runs on the fan unit microcontroller and:
|
|
|
|
- Controls fan speed via UART commands from blade agents.
|
|
- Reports RPM and airflow temperature back to the blade.
|
|
- Forwards button events (1x = left blade, 2x = right blade).
|
|
- Uses EMC2101 for optional advanced features like airflow-based fan control.
|
|
|
|
To install it, [download the `fanunit.uf2`](https://github.com/compute-blade-community/compute-blade-agent/releases/latest), and follow the firmware upgrade instructions [here](https://docs.computeblade.com/fan-unit/uart#update-firmware).
|
|
|
|
## Installation
|
|
|
|
Install the agent with the one-liner below:
|
|
|
|
```bash
|
|
curl -L -o /tmp/compute-blade-agent-installer.sh https://raw.githubusercontent.com/compute-blade-community/compute-blade-agent/main/hack/autoinstall.sh
|
|
chmod +x /tmp/compute-blade-agent-installer.sh
|
|
/tmp/compute-blade-agent-installer.sh
|
|
```
|
|
|
|
> Note: `bladectl` requires root privileges when used locally, due to restricted access to the Unix socket (`/tmp/compute-blade-agent.sock`).
|
|
|
|
## Configuration
|
|
|
|
The default configuration file is located at:
|
|
|
|
```bash
|
|
/etc/compute-blade-agent/config.yaml
|
|
```
|
|
|
|
You can also override any config option via environment variables using the `BLADE_` prefix.
|
|
|
|
### Examples
|
|
|
|
#### YAML:
|
|
```yaml
|
|
listen:
|
|
metrics: ":9666"
|
|
```
|
|
|
|
#### Environment variable override:
|
|
|
|
```bash
|
|
BLADE_LISTEN_METRICS=":1234"
|
|
```
|
|
|
|
### Common Overrides
|
|
|
|
| Variable | Description |
|
|
|---------------------------------------------------|------------------------------------------|
|
|
| `BLADE_STEALTH_MODE=false` | Enable/disable stealth mode |
|
|
| `BLADE_FAN_SPEED_PERCENT=80` | Set static fan speed |
|
|
| `BLADE_CRITICAL_TEMPERATURE_THRESHOLD=60` | Set critical temp threshold (°C) |
|
|
| `BLADE_HAL_RPM_REPORTING_STANDARD_FAN_UNIT=false` | Disable RPM monitoring for lower CPU use |
|
|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint for the OTLP exporter |
|
|
|
|
## Exposing the gRPC API for Remote Access
|
|
|
|
To allow secure remote use of `bladectl` over the network:
|
|
|
|
### 1. Update your config (`/etc/compute-blade-agent/config.yaml`):
|
|
|
|
```yaml
|
|
listen:
|
|
metrics: ":9666"
|
|
grpc: ":8081"
|
|
authenticated: true
|
|
mode: tcp
|
|
```
|
|
|
|
### 2. Restart the agent:
|
|
|
|
```bash
|
|
systemctl restart compute-blade-agent
|
|
```
|
|
|
|
This will:
|
|
|
|
- Generate new mTLS server and client certificates in `/etc/compute-blade-agent/*.pem`
|
|
- Write a new bladectl config to: `~/.config/bladectl/config.yaml` with the client certificates in place
|
|
|
|
## Using `bladectl` from your local machine
|
|
|
|
1. Copy the config from the blade:
|
|
|
|
```bash
|
|
scp root@blade-pi1:~/.config/bladectl/config.yaml ~/.config/bladectl/config.yaml
|
|
```
|
|
|
|
2. Fix the server address to point to the blade:
|
|
|
|
```bash
|
|
yq e '.blades[] | select(.name == "blade-pi1") .blade.server = "blade-pi1.local:8081"' -i ~/.config/bladectl/config.yaml
|
|
```
|
|
|
|
Your `bladectl` tool can now securely talk to the remote agent via gRPC over mTLS.
|