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.
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

Signing

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

Capabilities

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

OPTIONS

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

SEE ALSO

274       opa(1)
275
276
277
278                                   May 2021               Open Policy Agent(1)
Impressum