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 guide will go into detail on Nomad Pack usage and commands.
3
+
This guide goes more deeply into detail on Nomad Pack usage and commands.
4
4
5
5
For an overview on basic use, see the repository [README](../README.md).
6
6
7
7
For more information on writing custom packs and registries, see the [Writing Packs Guide](./writing-packs.md)
8
-
in the repository or in the [HashiCorp Learn Guides](https://learn.hashicorp.com/nomad).
9
-
10
-
<!-- TODO: Get the link to the writing own packs guide once it is up -->
8
+
in the repository or the [Writing Custom Packs tutorial][writing-packs-tut] at developer.hashicorp.com.
11
9
12
10
## Initialization
13
11
14
-
When first using Nomad Pack, a directory at `./.nomad/packs` will be created to store information about available packs and packs in use.
12
+
The first time you run registry list, Nomad Pack will add a `nomad/packs`
13
+
directory to your desktop user's cache directory—`$XDG_CACHE_DIR` on Linux,
14
+
`~/Library/Caches` on macOS, `%AppData%` on Windows, etc. This folder stores
15
+
information about cloned registries and their available packs.
15
16
16
-
During initializing, Nomad Pack downloads a default registry of packs from [https://github.com/hashicorp/nomad-pack-community- registry](https://github.com/hashicorp/nomad-pack-community-registry).
17
+
During initializing, Nomad Pack downloads a default registry of packs from the
18
+
[Nomad Pack community registry][].
17
19
18
20
The directory structure is as follows:
19
-
20
-
```
21
-
.nomad
21
+
<!-- TODO: this will need to be trued up based on PR -->
22
+
```plaintext
23
+
nomad
22
24
└── packs
23
25
├── <REGISTRY>
24
26
├── <PACK-NAME>
25
27
├── <PACK-REF>
26
28
├── ...files containing pack contents...
27
29
```
28
30
29
-
The contents of the `.nomad/pack` directory are needed for Nomad Pack to work properly,
30
-
but users must not manually manage or change these files. Instead, use the `registry`
31
-
commands.
31
+
The `nomad/packs` directory's contents are managed by Nomad Pack. Users should
32
+
not manually manage or change these files. Instead, use the `registry` commands.
32
33
33
34
## List
34
35
35
36
The `list` command lists the packs available to deploy.
36
37
37
-
```
38
-
nomad-pack list
38
+
```shell
39
+
nomad-pack registry list
39
40
```
40
41
41
-
This command reads from the `.nomad/packs` directory explained above.
42
+
This command reads from the `nomad/packs` directory explained earlier.
42
43
43
-
## Adding new Registries and Packs
44
+
## Add new registries and packs
44
45
45
46
The `registry` command includes several sub-commands for interacting with registries.
46
47
47
48
Custom registries can be added using the `registry add` command. Any `git` based
48
-
registry supported by [`go-getter`](https://github.com/hashicorp/go-getter) should
49
-
work.
49
+
registry supported by [`go-getter`][] should work.
50
50
51
-
For instance, if you wanted to add the entire [Nomad Pack Community Registry](https://github.com/hashicorp/nomad-pack-community-registry),
51
+
For instance, if you wanted to add the entire [Nomad Pack communityregistry][],
52
52
you would run the following command to download the registry.
53
53
54
-
```
54
+
```shell
55
55
nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry
56
56
```
57
57
58
58
To add a single pack from the registry, use the `--target` flag.
59
59
60
-
```
60
+
```shell
61
61
nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry --target=nginx
62
62
```
63
63
64
64
To download single pack or an entire registry at a specific version/SHA, use the `--ref` flag.
65
65
66
-
```
66
+
```shell
67
67
nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry --ref=v0.0.1
68
68
```
69
69
70
70
To remove a registry or pack from your local cache. Use the `registry delete` command.
71
71
This command also supports the `--target` and `--ref` flags.
72
72
73
-
```
73
+
```shell
74
74
nomad-pack registry delete community
75
75
```
76
76
77
-
## Render
77
+
## Render a pack
78
78
79
-
At times, you may wish to use Nomad Pack to render jobspecs, but you will not want to immediately deploy these to Nomad.
79
+
At times, you may wish to use Nomad Pack to render job specifications, but don't
80
+
want to immediately deploy these to Nomad.
80
81
81
-
This can be useful when writing a pack, debugging deployments, integrating Nomad Pack into a CI/CD environment, or if you have another mechanism for handling Nomad deploys.
82
+
This can be useful when writing a pack, debugging deployments, integrating Nomad
83
+
Pack into a CI/CD environment, or if you have another mechanism for handling
84
+
deployments to Nomad.
82
85
83
-
The `render` command takes the `--var` and `--var-file` flags that `run` takes.
86
+
Like the `run` command, the `render` command takes the `--var` and `--var-file`
87
+
flags to provide variable values and overrides.
84
88
85
-
The `--to-dir` flag determines the directory where the rendered templates will be written.
89
+
The `--to-dir` flag determines the directory where the rendered templates will
90
+
be written.
86
91
87
-
The `--render-output-template` can be passed to additionally render the output template. Some output templates rely on a deployment for information. In these cases, the output template may not be rendered with all necessary information.
92
+
Packs can create multiple output files. When running the `render` command
93
+
without the `--to-dir` flag the `render` command outputs all the rendered pack
94
+
templates to the terminal underneath their file names. When rendering a pack's
95
+
output to disk, you should use the `--to-dir` flag.
88
96
89
-
```
97
+
The `--render-output-template` can be passed to additionally render the output
98
+
template. Some output templates rely on a deployment for information. In these
99
+
cases, the output template may not be rendered with all necessary information.
To deploy the resources in a pack to Nomad, use the `run` command.
96
108
97
-
```
109
+
```shell
98
110
nomad-pack run hello-world
99
111
```
100
112
113
+
<!-- TODO: awkward -->
101
114
By passing a `--name` value into `run`, Nomad Pack deploys each resource in the
102
115
pack with a metadata value for "pack name". If no name is given, the pack name
103
116
is used by default.
104
117
105
118
This allows Nomad Pack to manage multiple deployments of the same pack.
106
119
107
-
```
120
+
```shell
108
121
nomad-pack run hello-world --name hola-mundo
109
122
```
110
123
111
-
It is also possible to run a local pack directly from the pack directory by passing in the directory instead of the pack name.
124
+
It's also possible to run a local pack directly from the pack directory by passing in the directory instead of the pack name.
112
125
113
-
```
126
+
```shell
114
127
nomad pack run .
115
128
```
116
129
117
-
### Variables
130
+
### Provide values for pack variables
118
131
119
132
Each pack defines a set of variables that can be provided by the user. Values for variables can be passed into the `run` command using the `--var` flag.
120
133
121
-
```
134
+
```shell
122
135
nomad-pack run hello-world --var greeting=hola
123
136
```
124
137
125
138
Values can also be provided by passing in a variables file.
126
139
127
-
```
140
+
```shell
128
141
nomad-pack run hello-world -f ./my-variables.hcl
129
142
```
130
143
131
144
These files can define overrides to the variables defined in the pack.
132
145
133
-
```
146
+
```hcl
134
147
docker_image = "hashicorp/hello-world"
135
148
136
149
app_count = 3
@@ -148,110 +161,172 @@ app_resources = {
148
161
149
162
To see the type and description of each variable, run the `info` command.
150
163
151
-
```
164
+
```shell
152
165
nomad-pack info hello-world
153
166
```
154
167
155
-
## Plan
168
+
## Plan a pack
156
169
157
170
If you do not want to immediately deploy the pack, but instead want details on how it will be deployed, run the `plan` command.
158
171
159
-
This invokes Nomad in a dry-run mode using the [NomadPlan](https://www.nomadproject.io/api-docs/jobs#create-job-plan) API endpoint.
172
+
This invokes Nomad in a dry-run mode using the Nomad's [Create Job Plan][nomad-plan] API endpoint.
160
173
161
-
```
174
+
```shell
162
175
nomad-pack plan hello-world
163
176
```
164
177
165
178
By passing a `--name` value into plan, Nomad Pack will look for packs deployed with that name. If no name is provided, Nomad Pack uses the pack name by default.
166
179
167
-
```
180
+
```shell
168
181
nomad-pack plan hello-world --name hola-mundo
169
182
```
170
183
171
184
The `plan` command takes the `--var` and `-f` flags like the `run` command.
172
185
173
-
```
186
+
```shell
174
187
nomad-pack plan hello-world --var greeting=hallo
175
188
```
176
189
177
-
```
190
+
```shell
178
191
nomad-pack plan hello-world -f ./my-variables.hcl
179
192
```
180
193
181
-
## Status
194
+
## Get the status of running packs
195
+
182
196
If you want to see a list of the packs currently deployed (this may include packs that are stopped but not yet removed), run the `status` command.
183
197
184
-
```
198
+
```shell
185
199
nomad-pack status
186
200
```
187
201
188
202
To see the status of jobs running in a specific pack, use the `status` command with the pack name.
189
203
190
-
```
204
+
```shell
191
205
nomad-pack status hello-world
192
206
```
193
207
194
-
## Destroy
208
+
## Stop a running pack
195
209
196
-
If you want to remove the resources deployed by a pack, run the `destroy` command with the pack name.
210
+
To stop the jobs without completely removing them from Nomad completely, use the `stop` command:
197
211
212
+
```shell
213
+
nomad-pack stop hola-mundo
198
214
```
215
+
216
+
If you deployed the pack with a `--name` value, you must also provide the name
217
+
you gave the pack. For instance, to stop a `hello-world` pack having the name
218
+
`hola-mundo`, you would run the following command.
219
+
220
+
```shell
221
+
nomad-pack stop hello-world --name hola-mundo
222
+
```
223
+
224
+
When you have deployed a pack with variable overrides that override the job name,
225
+
you must pass in those same overrides when stopping the pack. The `hello-world`
226
+
pack allows you to override the Nomad job name and can be used to demonstrate
227
+
this. If you deploy it with the following command.
228
+
229
+
```shell
230
+
nomad-pack run hello-world --name hola-mundo --var job_name=spanish
231
+
```
232
+
233
+
Running the following command stops the job instance named `spanish`.
0 commit comments