1Open Policy Agent(1) Open Policy Agent(1)
2
3
4
6 opa-build - Build an OPA bundle
7
8
9
11 opa build [ [...]] [flags]
12
13
14
16 Build an OPA bundle.
17
18
19 The 'build' command packages OPA policy and data files into bundles.
20 Bundles are gzipped tarballs containing policies and data. Paths refer‐
21 ring to directories are loaded recursively.
22
23
24 $ ls
25 example.rego
26
27 $ opa build -b .
28
29
30
31 You can load bundles into OPA on the command-line:
32
33
34 $ ls
35 bundle.tar.gz example.rego
36
37 $ opa run bundle.tar.gz
38
39
40
41 You can also configure OPA to download bundles from remote HTTP end‐
42 points:
43
44
45 $ opa run --server \
46 --set bundles.example.resource=bundle.tar.gz \
47 --set services.example.url=http://localhost:8080
48
49
50
51 Inside another terminal in the same directory, serve the bundle via
52 HTTP:
53
54
55 $ python3 -m http.server --bind localhost 8080
56
57
58
59 For more information on bundles see https://www.openpolicya‐
60 gent.org/docs/latest/management.
61
62
64 When -b is specified the 'build' command assumes paths refer to exist‐
65 ing bundle files or directories following the bundle structure. If mul‐
66 tiple bundles are provided, their contents are merged. If there are any
67 merge conflicts (e.g., due to conflicting bundle roots), the command
68 fails.
69
70
71 The -O flag controls the optimization level. By default, optimization
72 is disabled (-O=0). When optimization is enabled the 'build' command
73 generates a bundle that is semantically equivalent to the input files
74 however the structure of the files in the bundle may have been changed
75 by rewriting, inlining, pruning, etc. Higher optimization levels may
76 result in longer build times.
77
78
79 The 'build' command supports targets (specified by -t):
80
81
82 rego The default target emits a bundle containing a set of policy and data files
83 that are semantically equivalent to the input files. If optimizations are
84 disabled the output may simply contain a copy of the input policy and data
85 files. If optimization is enabled at least one entrypoint (-e) must be supplied.
86
87 wasm The wasm target emits a bundle containing a WebAssembly module compiled from
88 the input files for each specified entrypoint. The bundle may contain the
89 original policy or data files.
90
91
92
93 The -e flag tells the 'build' command which documents will be queried
94 by the software asking for policy decisions, so that it can focus opti‐
95 mization efforts and ensure that document is not eliminated by the op‐
96 timizer.
97
98
100 The 'build' command can be used to verify the signature of a signed
101 bundle and also to generate a signature for the output bundle the com‐
102 mand creates.
103
104
105 If the directory path(s) provided to the 'build' command contain a
106 ".signatures.json" file, it will attempt to verify the signatures in‐
107 cluded in that file. The bundle files or directory path(s) to verify
108 must be specified using --bundle.
109
110
111 For more information on the bundle verification process see
112 https://www.openpolicyagent.org/docs/latest/management/#signature-veri‐
113 fication.
114
115
116 Example:
117
118
119 $ opa build --verification-key /path/to/public_key.pem --signing-key /path/to/private_key.pem --bundle foo
120
121
122
123 Where foo has the following structure:
124
125
126 foo/
127 |
128 +-- bar/
129 | |
130 | +-- data.json
131 |
132 +-- policy.rego
133 |
134 +-- .manifest
135 |
136 +-- .signatures.json
137
138
139
140 The 'build' command will verify the signatures using the public key
141 provided by the --verification-key flag. The default signing algorithm
142 is RS256 and the --signing-alg flag can be used to specify a different
143 one. The --verification-key-id and --scope flags can be used to specify
144 the name for the key provided using the --verification-key flag and
145 scope to use for bundle signature verification respectively.
146
147
148 If the verification succeeds, the 'build' command will write out an up‐
149 dated ".signatures.json" file to the output bundle. It will use the key
150 specified by the --signing-key flag to sign the token in the ".signa‐
151 tures.json" file.
152
153
154 To include additional claims in the payload use the --claims-file flag
155 to provide a JSON file containing optional claims.
156
157
158 For more information on the format of the ".signatures.json" file see
159 https://www.openpolicyagent.org/docs/latest/management/#signature-for‐
160 mat.
161
162
164 The 'build' command can validate policies against a configurable set of
165 OPA capabilities. The capabilities define the built-in functions and
166 other language features that policies may depend on. For example, the
167 following capabilities file only permits the policy to depend on the
168 "plus" built-in function ('+'):
169
170
171 {
172 "builtins": [
173 {
174 "name": "plus",
175 "infix": "+",
176 "decl": {
177 "type": "function",
178 "args": [
179 {
180 "type": "number"
181 },
182 {
183 "type": "number"
184 }
185 ],
186 "result": {
187 "type": "number"
188 }
189 }
190 }
191 ]
192 }
193
194
195
196 Capablities can be used to validate policies against a specific version
197 of OPA. The OPA repository contains a set of capabilities files for
198 each OPA release. For example, the following command builds a directory
199 of policies ('./policies') and validates them against OPA v0.22.0:
200
201
202 opa build ./policies --capabilities $OPA_SRC/capabilities/v0.22.0.json
203
204
205
206
208 -b, --bundle[=false] load paths as bundle files or root directo‐
209 ries
210
211
212 --capabilities="" set capabilities.json file path
213
214
215 --claims-file="" set path of JSON file containing optional claims
216 (see: https://openpolicyagent.org/docs/latest/management/#signa‐
217 ture-format)
218
219
220 --debug[=false] enable debug output
221
222
223 -e, --entrypoint="" set slash separated entrypoint path
224
225
226 --exclude-files-verify=[] set file names to exclude during bundle
227 verification
228
229
230 -h, --help[=false] help for build
231
232
233 --ignore=[] set file and directory names to ignore during loading
234 (e.g., '.*' excludes hidden files)
235
236
237 -O, --optimize=0 set optimization level
238
239
240 -o, --output="bundle.tar.gz" set the output filename
241
242
243 -r, --revision="" set output bundle revision
244
245
246 --scope="" scope to use for bundle signature verification
247
248
249 --signing-alg="RS256" name of the signing algorithm
250
251
252 --signing-key="" set the secret (HMAC) or path of the PEM file
253 containing the private key (RSA and ECDSA)
254
255
256 --signing-plugin="" name of the plugin to use for signing/verifi‐
257 cation (see https://openpolicyagent.org/docs/latest/management/#signa‐
258 ture-plugin
259
260
261 -t, --target=rego set the output bundle target type
262
263
264 --verification-key="" set the secret (HMAC) or path of the PEM
265 file containing the public key (RSA and ECDSA)
266
267
268 --verification-key-id="default" name assigned to the verification
269 key used for bundle verification
270
271
272
274 opa(1)
275
276
277
278 May 2021 Open Policy Agent(1)