Built-in handlers

spec.type selects a handler. spec.params is a string map; its values and spec.services are rendered before host operations. Extra parameter keys are accepted, but the built-in handlers use only the keys listed here. A misspelled optional key can therefore be silently ignored.

File

The file handler maintains one whole file, replacing its content rather than merging it with existing settings.

Keel creates missing parent directories with requested mode 0755 (subject to the process umask). It compares existing bytes and permissions. Identical bytes with no explicit mode produce no change. If only an explicit mode differs, Keel uses chmod. Otherwise it writes a temporary file in the target directory and renames it over the destination, so readers do not see a partial write.

The replacement file gets mode 0644 when mode is omitted, including when replacing an existing file whose contents differ. If contents already match, omitting mode leaves the existing permissions alone. Specify mode whenever permissions matter. Special mode bits (setuid, setgid and sticky) are masked out.

Ownership, ACLs, extended attributes and security labels are not managed or preserved explicitly during replacement. New files are created by the agent (root in the supplied DaemonSet). Parent symlinks are followed by filesystem operations; lexical path containment is not a symlink isolation boundary. A final symlink can be replaced when content differs. Use ordinary host file paths and assess existing filesystem layout before managing sensitive configuration.

The handler does not validate the application-specific file format, keep a backup, remove files, synchronize directories or reload an application itself. List services under spec.services when a change needs a restart. Avoid special files and virtual filesystems that cannot support temporary-file replacement.

Package

The package handler ensures one package is installed on the host.

If installed and no version is requested, the package is left alone. If missing, or its installed version differs from the requested value, Keel runs the backend's install command and reports a change on success. It does not perform a post-install version verification. Package installation may run maintainer scripts and change or restart services independently of spec.services.

Detection uses the exact ID from the host's /etc/os-release, not the container OS, executable discovery or ID_LIKE:

The table describes the commands implemented by Keel, not a guarantee that every repository accepts every pinned target. Version availability, downgrade support and target syntax depend on the host package manager. In particular, the pacman backend does not fetch archived package files to implement arbitrary version pinning. Test pins against the chosen host and repository before rollout.

Installed versions come from dpkg-query, rpm (VERSION-RELEASE), apk or pacman. Use the exact backend version string, including release/revision components. An unrecognized OS ID yields a handler error even if a suitable manager happens to be installed. A failed package query can be treated as not installed and lead to an installation attempt; read command errors when troubleshooting.

Commands run through chroot into the configured host root, or directly when the local CLI targets /. The host needs executable tools, libraries, package metadata, repository access and sufficient disk space. Keel does not configure repositories, credentials, package removal, reboot handling or transaction rollback. Package changes that require a reboot need a separate node-maintenance procedure. See administrator recovery.

Service restart behavior

Both handlers use the same optional spec.services. Keel validates rendered names before applying the handler. After a reported change it runs one systemd daemon reload, then attempts every listed restart, collecting failures. A failed daemon reload prevents the restart loop. A later pending-restart retry can restart units that already succeeded in an earlier attempt.

Keel does not enable units, check application health, orchestrate dependencies between NodeConfigs or support a non-systemd restart backend. See the NodeConfig reference and the local CLI for the difference in restart recovery without status.