OPA auth API docs update (#10227)

Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com>

changelog/v1.18.0-beta29/docs-opaAuthServer.yaml

@@ -0,0 +1,6 @@
+changelog:
+  - type: NON_USER_FACING
+    issueLink: https://github.com/solo-io/docs/issues/631
+    resolvesIssue: false
+    description: Update API docs for OpaAuthServer availability in Gloo Gateway.
+      skipCI-kube-tests:true

projects/gloo/api/v1/enterprise/options/extauth/v1/extauth.proto

@@ -1292,8 +1292,12 @@ message ApiKeySecret {
     map<string, string> metadata = 4;
 }
 
-// Enforce Open Policy Agent (OPA) policies in Gloo Edge environments.
-// For Gloo Platform environments, use OpaServerAuth instead.
+// Enforce Open Policy Agent (OPA) policies through an OPA engine
+// that is built into the Gloo external auth server.
+// 
+// For larger scale operations and more capabilities like bundling or caching,
+// you might run the OPA engine as a sidecar or bring your own server
+// by using the OpaServerAuth setting instead.
 message OpaAuth {
     // An optional resource reference to config maps containing modules to assist in the resolution of `query`.
     repeated core.solo.io.ResourceRef modules = 1;
@@ -1333,8 +1337,11 @@ message OpaAuthOptions {
     bool return_decision_reason = 2;
 }
 
-// Enforce Open Policy Agent (OPA) policies through an OPA sidecar as part of the external
-// auth server in Gloo Platform environments. For Gloo Edge environments, use OpaAuth instead.
+// Enforce Open Policy Agent (OPA) policies through an OPA sidecar 
+// to the the Gloo external auth server, or by bringing your own OPA server.
+// This way, you can use OPA at scale and with additional capabilities, such as bundling or caching.
+//
+// For smaller operations or quick tests, you might use the OpaAuth setting instead.
 message OpaServerAuth {
     // The package from your Rego policy bundle used to query the OPA data API.
     //
@@ -1347,11 +1354,11 @@ message OpaServerAuth {
 
     // The address of the OPA server to query, in the format `ADDRESS:PORT`.
     // For OPA servers within the cluster, the address is the pod's service address,
-    // such as `default.svc.cluster.local:8181`. For OPA servers outside the cluster,
+    // such as `opa-svc.default.svc.cluster.local:8181`. For OPA servers outside the cluster,
     // the server must be accessible to the cluster, such as through an ExternalService.
     // If you do not have your own OPA server instance, omit this field.
     // When the external auth service has the OPA server sidecar enabled, the OPA server
-    // sidecar will be used instead.
+    // sidecar will be used instead, with an address such as `http://localhost:8181`.
     string server_addr = 3;
 
     // Additional options for OPA Auth configuration.
@@ -2143,14 +2150,28 @@ message ExtAuthConfig {
         OpaAuthOptions options = 3;
     }
 
-    // Enforce Open Policy Agent (OPA) policies through an OPA sidecar as part of the external auth server in Gloo Platform environments. For Gloo Edge environments, use OpaAuth instead.
+    // Configure the Gloo external auth server to use your own Open Policy Agent (OPA) server.
+    // This way, you can use extra capabilities such as bundling or caching.
     message OpaServerAuthConfig {
+
+        // The package from your Rego policy bundle used to query the OPA data API.
         string package = 1;
 
+        // The rule in your Rego policy bundle used to query the OPA data API. Supports querying subfields with a `/`.
+        // For more information, see the [OPA docs for the Data API](https://www.openpolicyagent.org/docs/latest/rest-api/#data-api).
         string rule_name = 2;
 
+        // The address of the OPA server to query, in the format `ADDRESS:PORT`.
+        // For OPA servers within the cluster, the address is the pod’s service address,
+        // such as `opa-svc.default.svc.cluster.local:8181`. 
+        // For OPA servers outside the cluster, the server must be accessible to the cluster,
+        // such as through an ExternalService. 
+        // If you do not have your own OPA server instance, omit this field. 
+        // When the external auth service has the OPA server sidecar enabled, 
+        // the OPA server sidecar will be used instead, with an address such as `http://localhost:8181`.
         string server_addr = 3;
 
+        // Additional options for OPA Auth configuration.
         OpaAuthOptions options = 4;
     }