core.pkg

soul-sidesoulstack.systemsystemroot required

Manage OS packages via the native package manager.

core.pkg brings OS packages to the required state via the host's native package manager. The backend is chosen automatically from host facts, and the states are idempotent: if a package is already at the required version, the step does nothing and reports changed=false. Install and remove run with the soul agent process's privileges and require root.

Requirements

Rootrequired
Sidesoul-side
Collectionsoulstack.system
Categorysystem

Capabilitiesrun_as_rootexec_subprocess

Backend detection

Auto from host facts (os.pkg_mgr); when absent, runtime detection: apt (Debian/Ubuntu), dnf (RHEL ≥ 8), yum (RHEL ≤ 7), apk (Alpine). If none is found, the step fails.

States

core.pkg.installed — The package is installed (optionally an exact version).

Changes when

The package was missing or the installed version ≠ the requested one.

Stays unchanged when

The required version is already installed.

Parameters

Param	Type	Required / default	Description
`name`	`string`	required	Package name.
`version`	`string`	optional	Exact package version (if omitted — any).

Example — Installing redis-server with a pinned version and retry

- name: Install redis-server
  module: core.pkg.installed
  retry: { count: 3, delay: 10s }
  params:
    name: redis-server
    version: "7.0.15"

Output

Field	Type	Description
`name`	`string`
`installed`	`true`
`version`	`string`

core.pkg.latest — The package is upgraded to the newest repository version.

Changes when

The package was missing or the version changed after the operation.

Stays unchanged when

The package is already at the latest available version.

Parameters

Param	Type	Required / default	Description
`name`	`string`	required	Package name.

Example — Keep curl at the latest available version

- name: Keep curl at the latest available version
  module: core.pkg.latest
  params:
    name: curl

Output

Field	Type	Description
`name`	`string`
`installed`	`true`
`version`	`string`

core.pkg.absent — The package is removed.

Changes when

The package was present and was removed.

Stays unchanged when

The package is not present.

Parameters

Param	Type	Required / default	Description
`name`	`string`	required	Package name.

Example — Remove an unneeded package

- name: Remove telnet
  module: core.pkg.absent
  params:
    name: telnet

Output

Field	Type	Description
`name`	`string`
`installed`	`false`

Reference

Supported backends

Manager	Distributions	How it is chosen
apt	Debian, Ubuntu	from the os.pkg_mgr fact, otherwise runtime detection
dnf	RHEL ≥ 8, Fedora	same
yum	RHEL ≤ 7	same
apk	Alpine	same

Notes

On apt/apk the repository index is refreshed once per process lifetime before installed/latest — important for fresh VMs and containers. dnf/yum pull metadata on their own.
Requires root: install and remove go through the package manager.

Security & defaults

The package manager verifies package signatures, not the module: the trust source is the apt/dnf/yum/apk repository keys on the host.
The module does not add repository keys and does not set --allow-unauthenticated / --nogpgcheck.
name and version must come from the Destiny author, not from untrusted input: installation runs the package's maintainer scripts (postinst and so on) with the soul agent's privileges.

core.pkg

Requirements

States

Reference

Notes

Security & defaults

See also