Pulse/docs/CENTRALIZED_MANAGEMENT.md

Centralized Agent Management (Pro/Pro+/Cloud)

Pro, Pro+, and Cloud support 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 → Unified 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
interval	string	Set reporting interval (e.g., "30s", "1m")
enable_host	boolean	Enable/Disable host monitoring (metrics + command execution)
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, pbs, or auto)
docker_runtime	string	Container runtime preference (auto, docker, podman)
disable_auto_update	boolean	Disable automatic agent updates
disable_docker_update_checks	boolean	Disable Docker image update detection
kube_include_all_pods	boolean	Include all non-succeeded pods in Kubernetes reports
kube_include_all_deployments	boolean	Include all deployments in Kubernetes reports
log_level	string	Set agent log level (debug, info, warn, error)
report_ip	string	Override the reported IP address for the agent
disable_ceph	boolean	Disable local Ceph status polling

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 --enable-docker=false on the host.
• commandsEnabled (AI command execution) is controlled separately per agent in Settings → Unified Agents and is applied live on report. It is not part of profile settings.

API Usage

All endpoints require Admin authentication and a Pro, Pro+, or Cloud license.

1. Create a Profile

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).

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

GET /api/admin/profiles/
Authorization: Bearer <admin-token>

4. List Assignments

GET /api/admin/profiles/assignments
Authorization: Bearer <admin-token>

5. Unassign Profile

DELETE /api/admin/profiles/assignments/{agent_id}
Authorization: Bearer <admin-token>

6. Get Agent Config (Debugging)

To see what configuration an agent receives:

GET /api/agents/agent/{agent_id}/config
Authorization: Bearer <agent-or-admin-token>

Requires agent:config:read (or admin tokens with management scopes).

7. Schema, Validation, and Suggestions

Use the schema endpoint to see supported keys and types, and validate configs before saving:

GET /api/admin/profiles/schema
Authorization: Bearer <admin-token>

POST /api/admin/profiles/validate
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "config": {
    "interval": "60s",
    "enable_docker": true
  }
}

Optional AI suggestions:

POST /api/admin/profiles/suggestions
Authorization: Bearer <admin-token>
Content-Type: application/json

8. Version History and Rollback

Each profile update increments its version and is stored in profile-versions.json.

GET /api/admin/profiles/{id}/versions
Authorization: Bearer <admin-token>

Rollback to a specific version:

POST /api/admin/profiles/{id}/rollback/{version}
Authorization: Bearer <admin-token>

9. Change Log and Deployment Status

Change log entries are stored in profile-changelog.json:

GET /api/admin/profiles/changelog
Authorization: Bearer <admin-token>

Deployment status is stored in profile-deployments.json:

GET /api/admin/profiles/deployments
Authorization: Bearer <admin-token>

Update deployment status via:

POST /api/admin/profiles/deployments
Authorization: Bearer <admin-token>
Content-Type: application/json

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
• profile-versions.json
• profile-changelog.json
• profile-deployments.json

Deleting a profile automatically removes its assignments.