Skip to content

USAGE.md

Latest commit

 

History

History
103 lines (75 loc) · 3.07 KB

USAGE.md

File metadata and controls

103 lines (75 loc) · 3.07 KB

Usage

1. Overview

The update plugin manages OS and package updates on headless Debian-based nodes. It exposes endpoints to list pending updates, trigger security-only or full upgrades, view run logs, and retrieve configuration. All endpoints are available under /api/v1/plugins/update.

2. Integration

The plugin is integrated into Config Manager by importing it and registering it with the core's plugin registry:

import update "github.com/msutara/cm-plugin-update"

plugin.Register(update.NewUpdatePlugin())

Note: The plugin implements the plugin.Plugin interface from config-manager-core directly.

3. API Endpoints

Check pending updates

curl http://localhost:7788/api/v1/plugins/update/status

Run security-only updates

curl -X POST http://localhost:7788/api/v1/plugins/update/run \
  -H "Content-Type: application/json" \
  -d '{"type": "security"}'

Run full upgrade

curl -X POST http://localhost:7788/api/v1/plugins/update/run \
  -H "Content-Type: application/json" \
  -d '{"type": "full"}'

Note: Only one update can run at a time. A second request while an update is in progress returns 409 Conflict.

View last run logs

curl http://localhost:7788/api/v1/plugins/update/logs

View plugin configuration

curl http://localhost:7788/api/v1/plugins/update/config

4. Scheduled Jobs

Job ID Default Schedule Description
update.full (none) Run full system upgrade
update.security 0 3 * * * Run security updates

update.full is always available for manual triggering via the jobs API.

update.security is registered when the security source is available (see security_source config). The cron schedule is attached only when auto_security is enabled.

5. Configuration

The plugin exposes a read-only configuration view via GET /config:

{
  "schedule": "0 3 * * *",
  "auto_security": true,
  "security_source": "detected",
  "security_available": true
}
Field Type Description
schedule string Cron expression for automatic security updates
auto_security bool Whether automatic security updates are enabled
security_source string "detected" or "always" — controls gating
security_available bool Read-only; computed once at startup, not persisted in config

security_available is determined once during service initialization by probing the system's apt sources. The cached value is returned in every /config response for informational purposes but is not a configurable setting.

When security_source is "detected" and the system lacks a separate security apt source, the scheduled job is omitted. When set to "always", the job runs regardless of source availability.