archive
The archive.* family of state modules.
| Module | Summary |
|---|---|
archive.extracted | Extract a tar or zip archive (from a local path or URL) into a target directory. |
All states also accept the full set of requisite parameters and Salt-parity state attributes — see Dependencies & Requisites.
archive.extracted
Extract a tar or zip archive (from a local path or URL) into a target directory.
Source: pkg/state/modules/archive/archive_extracted.go
archive.extracted extracts source (a local file path or an http/https/ftp URL) into name (the target directory, defaulting to the state ID). Idempotency has three independent strengths, weakest to strongest: without if_missing or source_hash, a PRE-EXISTING target directory alone counts as "already extracted" (declare one of them for anything beyond throwaway use); if_missing names a path whose existence is the sole extraction marker (Salt parity), replacing the weak directory check; source_hash records the declared value in a marker file after a successful extraction and re-extracts when the declaration no longer matches — it is an OPAQUE string comparison, never a checksum verified against the archive bytes.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | State ID | target directory the archive is extracted into; defaults to the state ID |
source | string | Yes | (none) | local file path, or an http/https/ftp URL to the archive; required |
archive_format | string | No | auto | archive format: tar, zip, or auto (inferred from the source name); defaults to auto |
if_missing | string | No | (none) | path whose existence means the archive is already extracted; when set, it is the sole idempotency check (besides source_hash) |
source_hash | string | No | (none) | declared hash of the source archive (e.g. sha256=<hex>); recorded after extraction and compared as an opaque string on later runs — NOT verified against the archive bytes |
makedirs | bool | No | (none) | create the target directory (and parents, mode 0755) before extracting; a boolean that also accepts the integers 1 (true) and 0 (false) |
Effects
Check
With if_missing set: reports a change unless that path exists (the target-directory fallback is not consulted). Without it: reports a change unless the target directory exists — and a directory this run's makedirs created ahead of a FAILED extraction attempt does not count (a retried Apply proceeds rather than latching on its own directory). When source_hash is declared, ALSO requires a marker file recording that exact value to exist inside the target — an unset or mismatched marker reports a change even if the directory/if_missing guard passed, so bumping source/source_hash re-extracts.
Apply
Re-evaluates the same guard as Check (a watch-forced apply bypasses Check entirely, and an already-extracted archive must be a clean no-op — never a re-download/re-extract over local modifications). When extraction is needed: creates the target directory (mode 0755) when makedirs is set and it does not already exist; downloads a remote source (http/https/ftp) to a temp file via curl -fSL, falling back to wget when curl is unavailable; extracts with unzip -o <archive> -d <dir> (zip) or tar -xf <archive> -C <dir> (tar), inferring the format from the source name when archive_format is auto (.zip → zip; .tgz/.tbz2/.txz/anything containing .tar → tar; anything else defaults to tar); a non-zero exit fails the state. Only AFTER a successful extraction does it write the source_hash marker (a failed attempt never latches the state as done). Reports the source, target, and resolved format in its details.
Revert
If Apply created the target directory (via makedirs), removes it recursively. Otherwise an explicit no-op (Changed: false) — individual extracted files are not tracked, so there is nothing else safe to remove.
Examples
Extract a release tarball once
if_missing points at a file the archive actually creates, the real extraction marker.
/opt/prometheus:
archive.extracted:
- source: https://github.com/prometheus/prometheus/releases/download/v2.53.0/prometheus-2.53.0.linux-amd64.tar.gz
- if_missing: /opt/prometheus/prometheus-2.53.0.linux-amd64
- makedirs: trueExtract a local zip archive
archive_format overrides auto-detection; if_missing avoids re-extracting.
/srv/webapp:
archive.extracted:
- source: /tmp/webapp-release.zip
- archive_format: zip
- if_missing: /srv/webapp/index.htmlRe-extract on a version bump with source_hash
Changing source_hash (or source) triggers re-extraction on the next run; the value is an opaque declaration, not a verified checksum.
/opt/myapp:
archive.extracted:
- source: /srv/releases/myapp-2.0.0.tar.gz
- source_hash: "sha256=<hex-of-2.0.0>"
- makedirs: trueExtract an archive ad hoc
The bare positional argument is the target directory; source is a key=value.
zester '*' archive.extracted /opt/tool source=/tmp/tool.tar.gz