1Open Policy Agent(1) Open Policy Agent(1)
2
6 opa-build - Build an OPA bundle
7
11 opa build [ [...]] [flags]
12
16 Build an OPA bundle.
17 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 $ ls
25 example.rego
26 $ opa build -b .
28 You can load bundles into OPA on the command-line:
32 $ ls
35 bundle.tar.gz example.rego
36 $ opa run bundle.tar.gz
38 You can also configure OPA to download bundles from remote HTTP end‐
42 points:
43 $ opa run --server \
46 --set bundles.example.resource=bundle.tar.gz \
47 --set services.example.url=http://localhost:8080
48 Inside another terminal in the same directory, serve the bundle via
52 HTTP:
53 $ python3 -m http.server --bind localhost 8080
56 For more information on bundles see https://www.openpolicya‐
60 gent.org/docs/latest/management.
61
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. When loading an existing bundle file, the .manifest from the in‐
69 put bundle will be included in the output bundle. Flags that set .mani‐
70 fest fields (such as --revision) override input bundle .manifest
71 fields.
72 The -O flag controls the optimization level. By default, optimization
75 is disabled (-O=0). When optimization is enabled the 'build' command
76 generates a bundle that is semantically equivalent to the input files
77 however the structure of the files in the bundle may have been changed
78 by rewriting, inlining, pruning, etc. Higher optimization levels may
79 result in longer build times.
80 The 'build' command supports targets (specified by -t):
83 rego The default target emits a bundle containing a set of policy and data files
86 that are semantically equivalent to the input files. If optimizations are
87 disabled the output may simply contain a copy of the input policy and data
88 files. If optimization is enabled at least one entrypoint (-e) must be supplied.
89 wasm The wasm target emits a bundle containing a WebAssembly module compiled from
91 the input files for each specified entrypoint. The bundle may contain the
92 original policy or data files.
93 The -e flag tells the 'build' command which documents will be queried
97 by the software asking for policy decisions, so that it can focus opti‐
98 mization efforts and ensure that document is not eliminated by the op‐
99 timizer.
100
103 The 'build' command can be used to verify the signature of a signed
104 bundle and also to generate a signature for the output bundle the com‐
105 mand creates.
106 If the directory path(s) provided to the 'build' command contain a
109 ".signatures.json" file, it will attempt to verify the signatures in‐
110 cluded in that file. The bundle files or directory path(s) to verify
111 must be specified using --bundle.
112 For more information on the bundle verification process see
115 https://www.openpolicyagent.org/docs/latest/management/#signature-veri‐
116 fication.
117 Example:
120 $ opa build --verification-key /path/to/public_key.pem --signing-key /path/to/private_key.pem --bundle foo
123 Where foo has the following structure:
127 foo/
130 |
131 +-- bar/
132 | |
133 | +-- data.json
134 |
135 +-- policy.rego
136 |
137 +-- .manifest
138 |
139 +-- .signatures.json
140 The 'build' command will verify the signatures using the public key
144 provided by the --verification-key flag. The default signing algorithm
145 is RS256 and the --signing-alg flag can be used to specify a different
146 one. The --verification-key-id and --scope flags can be used to specify
147 the name for the key provided using the --verification-key flag and
148 scope to use for bundle signature verification respectively.
149 If the verification succeeds, the 'build' command will write out an up‐
152 dated ".signatures.json" file to the output bundle. It will use the key
153 specified by the --signing-key flag to sign the token in the ".signa‐
154 tures.json" file.
155 To include additional claims in the payload use the --claims-file flag
158 to provide a JSON file containing optional claims.
159 For more information on the format of the ".signatures.json" file see
162 https://www.openpolicyagent.org/docs/latest/management/#signature-for‐
163 mat.
164
167 The 'build' command can validate policies against a configurable set of
168 OPA capabilities. The capabilities define the built-in functions and
169 other language features that policies may depend on. For example, the
170 following capabilities file only permits the policy to depend on the
171 "plus" built-in function ('+'):
172 {
175 "builtins": [
176 {
177 "name": "plus",
178 "infix": "+",
179 "decl": {
180 "type": "function",
181 "args": [
182 {
183 "type": "number"
184 },
185 {
186 "type": "number"
187 }
188 ],
189 "result": {
190 "type": "number"
191 }
192 }
193 }
194 ]
195 }
196 Capablities can be used to validate policies against a specific version
200 of OPA. The OPA repository contains a set of capabilities files for
201 each OPA release. For example, the following command builds a directory
202 of policies ('./policies') and validates them against OPA v0.22.0:
203 opa build ./policies --capabilities $OPA_SRC/capabilities/v0.22.0.json
206
211 -b, --bundle[=false] load paths as bundle files or root directo‐
212 ries
213 --capabilities="" set capabilities.json file path
216 --claims-file="" set path of JSON file containing optional claims
219 (see: https://openpolicyagent.org/docs/latest/management/#signature-
220 format)
221 --debug[=false] enable debug output
224 -e, --entrypoint="" set slash separated entrypoint path
227 --exclude-files-verify=[] set file names to exclude during bundle
230 verification
231 -h, --help[=false] help for build
234 --ignore=[] set file and directory names to ignore during loading
237 (e.g., '.*' excludes hidden files)
238 -O, --optimize=0 set optimization level
241 -o, --output="bundle.tar.gz" set the output filename
244 -r, --revision="" set output bundle revision
247 --scope="" scope to use for bundle signature verification
250 --signing-alg="RS256" name of the signing algorithm
253 --signing-key="" set the secret (HMAC) or path of the PEM file
256 containing the private key (RSA and ECDSA)
257 --signing-plugin="" name of the plugin to use for signing/verifi‐
260 cation (see https://openpolicyagent.org/docs/latest/management/#signa‐
261 ture-plugin
262 -t, --target=rego set the output bundle target type
265 --verification-key="" set the secret (HMAC) or path of the PEM
268 file containing the public key (RSA and ECDSA)
269 --verification-key-id="default" name assigned to the verification
272 key used for bundle verification
273
277 opa(1)
278 Jan 2023 Open Policy Agent(1)