1Open Policy Agent(1)                                      Open Policy Agent(1)
2
3
4

NAME

6       opa-build - Build an OPA bundle
7
8
9

SYNOPSIS

11       opa build  [ [...]] [flags]
12
13
14

DESCRIPTION

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

Common Flags

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
73
74       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
81
82       The 'build' command supports targets (specified by -t):
83
84
85              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
90              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
94
95
96       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
101

Signing

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
107
108       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
113
114       For  more  information  on  the   bundle   verification   process   see
115       https://www.openpolicyagent.org/docs/latest/management/#signature-veri‐
116       fication.
117
118
119       Example:
120
121
122              $ opa build --verification-key /path/to/public_key.pem --signing-key /path/to/private_key.pem --bundle foo
123
124
125
126       Where foo has the following structure:
127
128
129              foo/
130                |
131                +-- bar/
132                |     |
133                |     +-- data.json
134                |
135                +-- policy.rego
136                |
137                +-- .manifest
138                |
139                +-- .signatures.json
140
141
142
143       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
150
151       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
156
157       To include additional claims in the payload use the --claims-file  flag
158       to provide a JSON file containing optional claims.
159
160
161       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
165

Capabilities

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
173
174              {
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
197
198
199       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
204
205              opa build ./policies --capabilities $OPA_SRC/capabilities/v0.22.0.json
206
207
208
209

OPTIONS

211       -b, --bundle[=false]      load paths as bundle files or  root  directo‐
212       ries
213
214
215       --capabilities=""      set capabilities.json file path
216
217
218       --claims-file=""       set path of JSON file containing optional claims
219       (see:    https://openpolicyagent.org/docs/latest/management/#signature-
220       format)
221
222
223       --debug[=false]      enable debug output
224
225
226       -e, --entrypoint=""      set slash separated entrypoint path
227
228
229       --exclude-files-verify=[]       set file names to exclude during bundle
230       verification
231
232
233       -h, --help[=false]      help for build
234
235
236       --ignore=[]      set file and directory names to ignore during  loading
237       (e.g., '.*' excludes hidden files)
238
239
240       -O, --optimize=0      set optimization level
241
242
243       -o, --output="bundle.tar.gz"      set the output filename
244
245
246       -r, --revision=""      set output bundle revision
247
248
249       --scope=""      scope to use for bundle signature verification
250
251
252       --signing-alg="RS256"      name of the signing algorithm
253
254
255       --signing-key=""       set  the  secret  (HMAC) or path of the PEM file
256       containing the private key (RSA and ECDSA)
257
258
259       --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
263
264       -t, --target=rego      set the output bundle target type
265
266
267       --verification-key=""      set the secret (HMAC) or  path  of  the  PEM
268       file containing the public key (RSA and ECDSA)
269
270
271       --verification-key-id="default"       name assigned to the verification
272       key used for bundle verification
273
274
275

SEE ALSO

277       opa(1)
278
279
280
281                                   Jan 2023               Open Policy Agent(1)
Impressum