Update bundle signing docs to clarify key config (#8307)

Following a question about the mixing of these two signature verification
methods.

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

Author: charlieegan3

docs/docs/configuration.md

@@ -795,7 +795,7 @@ Bundles are defined with a key that is the `name` of the bundle. This `name` is
 server provenance, etc.
 
 Each bundle can be configured to verify a bundle signature using the `keyid` and `scope` fields. The `keyid` is the name of
-one of the keys listed under the [keys](#keys) entry.
+one of the keys listed under the [keys](#keys) entry. When using bundle services or discovery, verification keys must be in the configuration file. The `--verification-key` CLI flag only works with the `--bundle` flag for filesystem bundles - see [Bundle Signing](./management-bundles/#signing) for examples.
 
 Signature verification fails if the `bundles[_].signing` field is configured on a bundle but no `.signatures.json` file is
 included in the actual bundle gzipped tarball.

docs/docs/management-bundles/index.md

@@ -90,8 +90,18 @@ bundles:
     signing:
       keyid: my_global_key
       scope: read
+
+keys:
+  my_global_key:
+    algorithm: RS256
+    key: |
+      -----BEGIN PUBLIC KEY-----
+      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+      -----END PUBLIC KEY-----
 ```
 
+See [Configuration - Keys](./configuration/#keys) for details on key configuration.
+
 Using this configuration, OPA will fetch bundles from
 `https://example.com/service/v1/somedir/bundle.tar.gz`.
 
@@ -431,9 +441,7 @@ configured with out-of-band. Only if that verification succeeds does OPA activat
 continues using its existing bundle and reports an activation failure via the status API and error logging.
 
 :::warning
-⚠️ `opa run` performs bundle signature verification only when the `-b`/`--bundle` flag is given
-or when Bundle downloading is enabled. Sub-commands primarily used in development and debug environments
-(such as `opa eval`, `opa test`, etc.) DO NOT verify bundle signatures at this point in time.
+Bundle signature verification works differently depending on how bundles are loaded. Filesystem bundles (`--bundle` flag) use the `--verification-key` CLI flag pointing to a PEM file. Remote bundles define keys in the configuration file under the `keys` section. Sub-commands primarily used in pre-production (such as `opa eval`, `opa test`, etc.) do not verify bundle signatures at this point in time.
 :::
 
 ### Signature Format

docs/docs/management-discovery.md

@@ -284,6 +284,27 @@ signature verification of a discovery bundle **CANNOT** be modified via discover
 > include the keys used to verify the non-discovery bundles. However, OPA does not enforce that recommendation. You may use
 > unsigned discovery bundles that themselves require non-discovery bundles to be signed.
 
+To enable signature verification for discovery bundles, add the `signing` field to your discovery configuration and define the verification key:
+
+```yaml title="Bootstrap Config"
+discovery:
+  service: acmecorp
+  resource: /discovery.tar.gz
+  signing:
+    keyid: discovery_key
+    scope: read
+
+keys:
+  discovery_key: # Cannot come from discovery
+    algorithm: RS256
+    key: |
+      -----BEGIN PUBLIC KEY-----
+      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+      -----END PUBLIC KEY-----
+```
+
+Discovery bundle contents then provides keys for regular bundles - see [Bundle Signing](./management-bundles/#signing) for more details about signing configuration.
+
 ## Discovery Bundle Persistence
 
 OPA can optionally persist the activated discovery bundle to disk for recovery purposes. To enable