You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 on-disk and extract it on start.
11
+
This module installs small, robust scripts in your workspace to create and extract tar archives from a list of files and directories. It supports optional compression (gzip or zstd). 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 on-disk and extract it on start.
12
12
13
-
- Depends on: `tar` (and `gzip` or `zstd` if you select those compression modes)
14
-
- Installed scripts:
15
-
-`$CODER_SCRIPT_BIN_DIR/coder-archive-create`
16
-
-`$CODER_SCRIPT_BIN_DIR/coder-archive-extract`
17
-
- Library installed to:
18
-
-`$CODER_SCRIPT_DATA_DIR/archive-lib.sh`
19
-
- On start (always): installer decodes and writes the library, then generates the wrappers in `$CODER_SCRIPT_BIN_DIR` with Terraform-provided defaults embedded.
20
-
- Optional on stop: when enabled, a separate `run_on_stop` script invokes the create command.
21
13
22
14
## Features
23
15
24
-
-Create a single `.tar`, `.tar.gz`, or `.tar.zst` containing selected paths.
25
-
-Compression algorithms: `gzip`, `zstd`, `none`.
26
-
-Defaults for directory, archive path, compression, include/exclude lists come from Terraform and can be overridden at runtime with CLI flags.
27
-
-Logs and status messages go to stderr; the create command prints only the final archive path to stdout.
28
-
-Strict bash mode and safe invocation of `tar`.
16
+
-Installs two commands into the workspace `$PATH`: `coder-archive-create` and `coder-archive-extract`.
17
+
-Creates a single `.tar`, `.tar.gz`, or `.tar.zst` containing selected paths (depends on `tar`).
18
+
-Optional compression: `gzip`, `zstd` (depends on `gzip` or `zstd`).
19
+
-Stores defaults so commands can be run without arguments (supports overriding via CLI flags).
20
+
-Logs and status messages go to stderr, the create command prints only the final archive path to stdout.
29
21
- Optional:
30
-
-`run_on_stop` to create an archive automatically when the workspace stops.
31
-
-`extract_on_start` to wait for an archive to appear and extract it on start (with timeout).
22
+
-`create_on_stop` to create an archive automatically when the workspace stops.
23
+
-`extract_on_start` to wait for an archive to appear and extract it on start.
32
24
33
25
## Usage
34
26
35
27
Basic example:
36
28
37
-
module "archive" {
38
-
count = data.coder_workspace.me.start_count
39
-
source = "registry.coder.com/coder/archive/coder"
40
-
version = "0.0.1"
41
-
agent_id = coder_agent.example.id
42
-
43
-
# Paths to include in the archive (files or directories).
44
-
directory = "/"
45
-
paths = [
46
-
"/etc/hostname",
47
-
"/etc/hosts",
48
-
]
49
-
}
29
+
```tf
30
+
module "archive" {
31
+
count = data.coder_workspace.me.start_count
32
+
source = "registry.coder.com/coder/archive/coder"
33
+
version = "0.0.1"
34
+
agent_id = coder_agent.example.id
35
+
36
+
# Paths to include in the archive (files or directories).
37
+
directory = "~"
38
+
paths = [
39
+
"./projects",
40
+
"./code",
41
+
]
42
+
}
43
+
```
50
44
51
45
Customize compression and output:
52
46
53
-
module "archive" {
54
-
count = data.coder_workspace.me.start_count
55
-
source = "registry.coder.com/coder/archive/coder"
56
-
version = "0.0.1"
57
-
agent_id = coder_agent.example.id
58
-
59
-
paths = ["/etc/hostname"]
60
-
compression = "zstd" # "gzip" | "zstd" | "none"
61
-
output_dir = "/tmp/backup" # defaults to /tmp
62
-
archive_name = "my-backup" # base name (extension is inferred from compression)
63
-
}
47
+
```tf
48
+
module "archive" {
49
+
count = data.coder_workspace.me.start_count
50
+
source = "registry.coder.com/coder/archive/coder"
51
+
version = "0.0.1"
52
+
agent_id = coder_agent.example.id
53
+
54
+
directory = "/"
55
+
paths = ["/etc", "/home"]
56
+
compression = "zstd" # "gzip" | "zstd" | "none"
57
+
output_dir = "/tmp/backup" # defaults to /tmp
58
+
archive_name = "my-backup" # base name (extension is inferred from compression)
59
+
}
60
+
```
64
61
65
62
Enable auto-archive on stop:
66
63
67
-
module "archive" {
68
-
count = data.coder_workspace.me.start_count
69
-
source = "registry.coder.com/coder/archive/coder"
70
-
version = "0.0.1"
71
-
agent_id = coder_agent.example.id
72
-
73
-
paths = ["/etc/hostname"]
74
-
compression = "gzip"
75
-
create_on_stop = true
76
-
}
64
+
```tf
65
+
module "archive" {
66
+
count = data.coder_workspace.me.start_count
67
+
source = "registry.coder.com/coder/archive/coder"
68
+
version = "0.0.1"
69
+
agent_id = coder_agent.example.id
70
+
71
+
# Creates /tmp/coder-archive.tar.gz of the users home directory (defaults).
72
+
create_on_stop = true
73
+
}
74
+
```
75
+
76
+
Extract on start:
77
+
78
+
```tf
79
+
module "archive" {
80
+
count = data.coder_workspace.me.start_count
81
+
source = "registry.coder.com/coder/archive/coder"
82
+
version = "0.0.1"
83
+
agent_id = coder_agent.example.id
84
+
85
+
# Where to look for the archive file to extract:
86
+
output_dir = "/tmp"
87
+
archive_name = "my-archive"
88
+
compression = "gzip"
89
+
90
+
# Waits up to 5 minutes for /tmp/my-archive.tar.gz to be present.
91
+
extract_on_start = true
92
+
extract_wait_timeout_seconds = 300
93
+
}
94
+
```
77
95
78
-
Extract on start (optional):
96
+
## Inputs
79
97
80
-
module "archive" {
81
-
count = data.coder_workspace.me.start_count
82
-
source = "registry.coder.com/coder/archive/coder"
83
-
version = "0.0.1"
84
-
agent_id = coder_agent.example.id
98
+
-`agent_id` (string, required): The ID of a Coder agent.
99
+
-`paths` (list(string), default: `["."]`): Files/directories to include when creating an archive.
100
+
-`exclude_patterns` (list(string), default: `[]`): Patterns to exclude (passed to tar via `--exclude`).
101
+
-`compression` (string, default: `"gzip"`): One of `gzip`, `zstd`, or `none`.
102
+
-`archive_name` (string, default: `"coder-archive"`): Base archive name (extension is inferred from `compression`).
103
+
-`output_dir` (string, default: `"/tmp"`): Directory where the archive file will be written/read by default.
104
+
-`directory` (string, default: `"~"`): Working directory used for tar with `-C`.
105
+
-`create_on_stop` (bool, default: `false`): If true, registers a `run_on_stop` script that invokes the create wrapper on workspace stop.
106
+
-`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.
107
+
-`extract_wait_timeout_seconds` (number, default: `300`): Timeout for `extract_on_start`.
85
108
86
-
# Where to look for the archive file to extract:
87
-
output_dir = "/tmp"
88
-
archive_name = "coder-archive"
89
-
compression = "gzip"
109
+
## Outputs
90
110
91
-
extract_on_start = true
92
-
extract_wait_timeout_seconds = 300
93
-
}
111
+
-`archive_path` (string): Full archive path computed as `output_dir/archive_name + extension`, where the extension comes from `compression`:
112
+
-`.tar.gz` for `gzip`
113
+
-`.tar.zst` for `zstd`
114
+
-`.tar` for `none`
94
115
95
-
## Running the scripts
116
+
## Command usage
96
117
97
-
Once the workspace starts, the installer writes:
118
+
The installer writes the following files:
98
119
99
120
-`$CODER_SCRIPT_DATA_DIR/archive-lib.sh`
100
121
-`$CODER_SCRIPT_BIN_DIR/coder-archive-create`
101
122
-`$CODER_SCRIPT_BIN_DIR/coder-archive-extract`
102
123
103
124
Create usage:
104
125
105
-
coder-archive-create [OPTIONS] [PATHS...]
106
-
-c, --compression <gzip|zstd|none> Compression algorithm (default from module)
107
-
-C, --directory <DIRECTORY> Change to directory for archiving (default from module)
108
-
-f, --file <ARCHIVE> Output archive file (default from module)
109
-
-h, --help Show help
126
+
```console
127
+
coder-archive-create [OPTIONS] [PATHS...]
128
+
-c, --compression <gzip|zstd|none> Compression algorithm (default from module)
129
+
-C, --directory <DIRECTORY> Change to directory for archiving (default from module)
130
+
-f, --file <ARCHIVE> Output archive file (default from module)
131
+
-h, --help Show help
132
+
```
110
133
111
134
Extract usage:
112
135
113
-
coder-archive-extract [OPTIONS]
114
-
-c, --compression <gzip|zstd|none> Compression algorithm (default from module)
115
-
-C, --directory <DIRECTORY> Extract into directory (default from module)
116
-
-f, --file <ARCHIVE> Archive file to extract (default from module)
117
-
-h, --help Show help
136
+
```console
137
+
coder-archive-extract [OPTIONS]
138
+
-c, --compression <gzip|zstd|none> Compression algorithm (default from module)
139
+
-C, --directory <DIRECTORY> Extract into directory (default from module)
140
+
-f, --file <ARCHIVE> Archive file to extract (default from module)
141
+
-h, --help Show help
142
+
```
118
143
119
144
Examples:
120
145
121
146
- Use Terraform defaults:
122
147
123
-
coder-archive-create
148
+
```
149
+
coder-archive-create
150
+
```
124
151
125
152
- Override compression and output file at runtime:
- Create prints only the final archive path to stdout. All other output (progress, warnings, errors) goes to stderr.
140
-
- Extract prints a short message to stdout indicating the destination.
141
-
- Exclude patterns from Terraform are forwarded to `tar` using `--exclude`.
142
-
- You can run the wrappers with bash xtrace for more debug information:
143
-
-`bash -x "$(which coder-archive-create)" ...`
144
-
145
-
## Inputs
146
-
147
-
-`agent_id` (string, required): The ID of a Coder agent.
148
-
-`paths` (list(string), default: `["."]`): Files/directories to include when creating an archive.
149
-
-`exclude_patterns` (list(string), default: `[]`): Patterns to exclude (passed to tar via `--exclude`).
150
-
-`compression` (string, default: `"gzip"`): One of `gzip`, `zstd`, or `none`.
151
-
-`archive_name` (string, default: `"coder-archive"`): Base archive name (extension is inferred from `compression`).
152
-
-`output_dir` (string, default: `"/tmp"`): Directory where the archive file will be written/read by default.
153
-
-`directory` (string, default: `"~"`): Working directory used for tar with `-C`.
154
-
-`create_on_stop` (bool, default: `false`): If true, registers a `run_on_stop` script that invokes the create wrapper on workspace stop.
155
-
-`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.
156
-
-`extract_wait_timeout_seconds` (number, default: `300`): Timeout for `extract_on_start`.
157
-
158
-
## Outputs
159
-
160
-
-`archive_path` (string): Full archive path computed as `output_dir/archive_name + extension`, where the extension comes from `compression`:
161
-
-`.tar.gz` for `gzip`
162
-
-`.tar.zst` for `zstd`
163
-
-`.tar` for `none`
164
-
165
-
## Requirements
166
-
167
-
-`tar` is required.
168
-
-`gzip` is required if `compression = "gzip"`.
169
-
-`zstd` is required if `compression = "zstd"`.
170
-
171
-
## Behavior
172
-
173
-
- On start, the installer:
174
-
- Decodes the embedded library to `$CODER_SCRIPT_DATA_DIR/archive-lib.sh`.
175
-
- Generates two wrappers in `$CODER_SCRIPT_BIN_DIR`: `coder-archive-create` and `coder-archive-extract`.
176
-
- Embeds Terraform-provided defaults into the wrappers.
177
-
- 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.
178
-
- If `create_on_stop` is true, a `run_on_stop` script is registered that invokes the create command at stop.
179
-
-`umask 077` is applied during operations so archives and extracted files are created with restrictive permissions.
0 commit comments