feat: Add centralized agent configuration management (Pro)

Allows administrators to create configuration profiles and assign them
to agents for centralized fleet management.

- Configuration profiles with customizable settings (Docker, K8s,
  Proxmox monitoring, log level, reporting interval)
- Profile assignment to agents by ID
- Agent-side remote config client to fetch settings on startup
- Full CRUD API at /api/admin/profiles
- Settings UI panel in Settings → Agents → Agent Profiles
- Automatic cleanup of assignments when profiles are deleted
This commit is contained in:
rcourtman 2026-01-08 12:03:55 +00:00
parent 7db6b3e47d
commit 22e01e2244
10 changed files with 1771 additions and 7 deletions

View file

@ -0,0 +1,112 @@
# Centralized Agent Management (Pulse Pro)
Pulse Pro supports centralized management of agent configurations, allowing administrators to define "Configuration Profiles" and assign them to specific agents. This enables bulk updates and consistent configuration across your fleet without manually editing configuration files on each host.
Profiles are managed in the UI: **Settings → Agents → Agent Profiles**.
## Concepts
- **Agent Profile**: A named collection of configuration settings (e.g., "Production Servers", "Debug Mode").
- **Assignment**: A link between a specific Agent ID and an Agent Profile.
- **Precedence**: Server-side profile settings override local agent flags/environment for supported keys.
## Supported Configuration Keys
The following settings can be controlled remotely via profiles:
| Key | Type | Description |
| :--- | :--- | :--- |
| `enable_docker` | boolean | Enable/Disable Docker monitoring |
| `enable_kubernetes` | boolean | Enable/Disable Kubernetes monitoring |
| `enable_proxmox` | boolean | Enable/Disable Proxmox monitoring |
| `proxmox_type` | string | Set Proxmox type (`pve` or `pbs`) |
| `log_level` | string | Set agent log level (`debug`, `info`, `warn`, `error`) |
| `interval` | string | Set reporting interval (e.g., "30s", "1m") |
Notes:
- `interval` accepts a duration string. If you send a JSON number, it is interpreted as seconds.
- Docker auto-detection can still enable Docker monitoring if the agent is not explicitly configured. To force-disable Docker, set `PULSE_ENABLE_DOCKER=false` or install with `--disable-docker` on the host.
- `commandsEnabled` (AI command execution) is controlled separately per agent in **Settings → Agents → Unified Agents** and is applied live on report. It is not part of profile settings.
## API Usage
All endpoints require **Admin** authentication and a **Pulse Pro** license.
### 1. Create a Profile
```http
POST /api/admin/profiles/
Authorization: Bearer <admin-token>
Content-Type: application/json
{
"name": "Production Servers",
"config": {
"enable_docker": true,
"log_level": "info",
"interval": "60s"
}
}
```
### 2. Assign Profile to Agent
You need the Agent ID (typically the machine ID, visible in the Pulse UI or agent logs).
```http
POST /api/admin/profiles/assignments
Authorization: Bearer <admin-token>
Content-Type: application/json
{
"agent_id": "01234567-89ab-cdef-0123-456789abcdef",
"profile_id": "prod-servers"
}
```
### 3. List Profiles
```http
GET /api/admin/profiles/
Authorization: Bearer <admin-token>
```
### 4. List Assignments
```http
GET /api/admin/profiles/assignments
Authorization: Bearer <admin-token>
```
### 5. Unassign Profile
```http
DELETE /api/admin/profiles/assignments/{agent_id}
Authorization: Bearer <admin-token>
```
### 6. Get Agent Config (Debugging)
To see what configuration an agent receives:
```http
GET /api/agents/host/{agent_id}/config
Authorization: Bearer <agent-or-admin-token>
```
## Agent Behavior
1. On startup, the agent computes its Agent ID.
2. It contacts the Pulse server to fetch its configuration profile.
3. If successful, it applies the remote settings, overriding local flags/env for supported keys.
4. If the server is unreachable or returns an error, the agent proceeds with its local configuration.
5. Profile changes take effect on the next agent restart. Command execution toggles are applied dynamically.
## Storage
Profiles and assignments are stored in the Pulse config directory:
- `agent_profiles.json`
- `agent_profile_assignments.json`
Deleting a profile automatically removes its assignments.