display_name:Archive

description:Create automated and user-invocable scripts that archive and extract selected files/directories with gzip, zstd, or none.

icon:../../../../.icons/tool.svg

verified:false

tags:[backup, archive, tar, helper]

This module installs small, robust scripts in your workspace to create and extract tar archives from a list of files and directories. It supports gzip, zstd, or no compression. The create command prints only the resulting archive path to stdout; operational logs go to stderr. An optional stop hook can also create an archive automatically when the workspace stops, and an optional start hook can wait for an archive and extract it on start.

- Depends on:`tar` (and`gzip` or`zstd` if you select those compression modes)

- Installed scripts:

- Library installed to:

- On start (always): installer decodes and writes the library, then generates the wrappers in`$CODER_SCRIPT_BIN_DIR` with Terraform-provided defaults embedded.

- Optional on stop: when enabled, a separate`run_on_stop` script invokes the create command.

- Create a single`.tar`,`.tar.gz`, or`.tar.zst` containing selected paths.

- Compression algorithms:`gzip`,`zstd`,`none`.

- Defaults for directory, archive path, compression, include/exclude lists come from Terraform and can be overridden at runtime with CLI flags.

- Logs and status messages go to stderr; the create command prints only the final archive path to stdout.

- Strict bash mode and safe invocation of`tar`.

- Optional:

-`run_on_stop` to create an archive automatically when the workspace stops.

-`extract_on_start` to wait for an archive to appear and extract it on start (with timeout).

Basic example:

Customize compression and output:

Enable auto-archive on stop:

Extract on start (optional):

Once the workspace starts, the installer writes:

Create usage:

Extract usage:

Examples:

- Use Terraform defaults:

- Override compression and output file at runtime:

- Add extra paths on the fly (in addition to the Terraform defaults):

- Extract an archive into a directory:

Notes:

- Create prints only the final archive path to stdout. All other output (progress, warnings, errors) goes to stderr.

- Extract prints a short message to stdout indicating the destination.

- Exclude patterns from Terraform are forwarded to`tar` using`--exclude`.

- You can run the wrappers with bash xtrace for more debug information:

-`agent_id` (string, required): The ID of a Coder agent.

-`paths` (list(string), default:`["."]`): Files/directories to include when creating an archive.

-`exclude_patterns` (list(string), default:`[]`): Patterns to exclude (passed to tar via`--exclude`).

-`compression` (string, default:`"gzip"`): One of`gzip`,`zstd`, or`none`.

-`archive_name` (string, default:`"coder-archive"`): Base archive name (extension is inferred from`compression`).

-`output_dir` (string, default:`"/tmp"`): Directory where the archive file will be written/read by default.

-`directory` (string, default:`"~"`): Working directory used for tar with`-C`.

-`create_on_stop` (bool, default:`false`): If true, registers a`run_on_stop` script that invokes the create wrapper on workspace stop.

-`extract_on_start` (bool, default:`false`): If true, the installer waits up to`extract_wait_timeout_seconds` for the archive path to appear and extracts it on start.

-`extract_wait_timeout_seconds` (number, default:`300`): Timeout for`extract_on_start`.

-`archive_path` (string): Full archive path computed as`output_dir/archive_name + extension`, where the extension comes from`compression`:

-`.tar.gz` for`gzip`

-`.tar.zst` for`zstd`

-`.tar` for`none`

-`tar` is required.

-`gzip` is required if`compression = "gzip"`.

-`zstd` is required if`compression = "zstd"`.

- On start, the installer:

- Decodes the embedded library to`$CODER_SCRIPT_DATA_DIR/archive-lib.sh`.

- Generates two wrappers in`$CODER_SCRIPT_BIN_DIR`:`coder-archive-create` and`coder-archive-extract`.

- Embeds Terraform-provided defaults into the wrappers.

- If`extract_on_start` is true, the installer sources the library and calls`archive_wait_and_extract`, waiting up to`extract_wait_timeout_seconds` for the file at`archive_path` to appear.

- If`create_on_stop` is true, a`run_on_stop` script is registered that invokes the create command at stop.

-`umask 077` is applied during operations so archives and extracted files are created with restrictive permissions.

mock_provider"coder" {}

run"apply_defaults" {

command=apply

variables {

paths=["~/project","/etc/hosts"]

}

assert {

condition=output.archive_path=="/tmp/coder-archive.tar.gz"

}

}

run"apply_with_name" {

command=apply

variables {

paths=["/etc/hosts"]

}

assert {

condition=output.archive_path=="/tmp/backups/nightly.tar.zst"

}

}