cleanup & docs

Author: maltesander

CHANGELOG.md

@@ -9,7 +9,8 @@ All notable changes to this project will be documented in this file.
 - Run a `containerdebug` process in the background of each OPA container to collect debugging information ([#666]).
 - Added support for OPA `1.0.x` ([#677]) and ([#687]).
 - Aggregate emitted Kubernetes events on the CustomResources ([#675]).
-- Added role level service and discovery configmap called `<cluster-name>-lb` with `internalTrafficPolicy` set to "Cluster" ([#688]).
+- Added role level services and discovery configmaps called `<cluster-name>-local` with `internalTrafficPolicy` set to `Local`
+  and `<cluster-name>-cluster` with `internalTrafficPolicy` set to `Cluster` ([#688]). 
 
 ### Removed
 

docs/modules/opa/pages/implementation-notes.adoc

@@ -5,7 +5,7 @@ but should not be required reading for regular use.
 
 == OPA replica per node
 
-Since OPA is deployed as a DaemonSet and runs on each Node, two entrypoint Services are defined.
+OPA is deployed as a DaemonSet and runs on each Node. two entrypoint Services are defined.
 
 === Local Traffic Policy
 
@@ -16,15 +16,16 @@ This means that https://kubernetes.io/docs/concepts/workloads/pods/[Pods] access
 
 This should be the default entrypoint and has the same name as the defined OPA cluster.
 
-If the `metadata.name` is `opa`, this service is called `opa`.
+If the `metadata.name` is `opa`, this service is called `opa-local`.
 
-=== Cluster Traffic Policy (load-balanced / round-robin)
+=== Cluster Traffic Policy (round-robin)
 
-This service is called as the OPA cluster suffixed with `-lb`. This entrypoint can be used if latency (e.g. no network requests) is less important.
+This service is called as the OPA cluster suffixed with `-cluster`. This entrypoint can be used if latency (e.g. no network requests) is less important.
 Evaluating complicated rego rules may take some time depending on the provided resources, and can be the limiting factor in e.g. bulk requests.
-Therefore, using this service, every Pod in the cluster is utilized to evaluate policies than instead e.g. just one.
+Therefore, using this service, every Pod in the cluster is utilized to evaluate policies (via round robin). This allows better parallelism when
+evaluating policies, but results in network roundtrips.
 
-If the `metadata.name` is `opa`, this service is called `opa-lb`.
+If the `metadata.name` is `opa`, this service is called `opa-cluster`.
 
 == OPA Bundle Builder
 

docs/modules/opa/pages/reference/discovery.adoc

@@ -26,14 +26,15 @@ metadata:
 spec:
   [...]
 ----
-<1> The name of the OPA cluster, which is also the name of the created discovery ConfigMap.
-<2> The namespace of the discovery ConfigMap.
+<1> The name of the OPA cluster, which is used in the created discovery ConfigMaps.
+<2> The namespace of the discovery ConfigMaps.
 
-The resulting discovery ConfigMap is `{namespace}/{clusterName}`.
+Currently, three discovery ConfigMaps are provided.
 
-== Contents
+=== (DEPRECATED) Internal Traffic Policy `Local` 
 
-The `{namespace}/{clusterName}` discovery ConfigMap contains the following fields where `{clusterName}` represents the name and `{namespace}` the namespace of the cluster:
+The discovery ConfigMap `{namespace}/{clusterName}` contains the following fields where `{clusterName}` represents the name and `{namespace}` the namespace of the cluster.
+This is deprecated and only kept for backwards compatibitliy. Users are adviced to switch to `{namespace}/{clusterName}-local`, which is the identical replacement.
 
 `OPA`::
 ====
@@ -49,3 +50,44 @@ In order to query policies you have to configure your product and its OPA URL as
 [subs="attributes"]
     http://{clusterName}.{namespace}.svc.cluster.local:8081/v1/data/{packageName}/{policyName}
 ====
+
+=== Internal Traffic Policy `Local` 
+
+The discovery ConfigMap `{namespace}/{clusterName}-local` contains the following fields where `{clusterName}-local` represents the name and `{namespace}` the namespace of the cluster.
+Using this discovery service, requests from one Node will always reach the OPA Pod on the same Node. This allows for low latency authorization queriers.
+
+`OPA`::
+====
+A connection string for cluster internal OPA requests.
+Provided the cluster example above, the connection string is created as follows:
+
+[subs="attributes"]
+    http://{clusterName}-local.{namespace}.svc.cluster.local:8081/
+
+This connection string points to the base URL (and web UI) of the OPA cluster.
+In order to query policies you have to configure your product and its OPA URL as follows, given the bundle package name `{packageName}` and the policy name `{policyName}`:
+
+[subs="attributes"]
+    http://{clusterName}-local.{namespace}.svc.cluster.local:8081/v1/data/{packageName}/{policyName}
+====
+
+=== Internal Traffic Policy `Cluster` 
+
+The discovery ConfigMap `{namespace}/{clusterName}-cluster` contains the following fields where `{clusterName}-cluster` represents the name and `{namespace}` the namespace of the cluster.
+Using this discovery service, requests to OPA are distributed over all available OPA Pods, improving parallelism when evaluating policies but slightly increasing the latency of each single query
+to due additional network requests.
+
+`OPA`::
+====
+A connection string for cluster internal OPA requests.
+Provided the cluster example above, the connection string is created as follows:
+
+[subs="attributes"]
+    http://{clusterName}-cluster.{namespace}.svc.cluster.local:8081/
+
+This connection string points to the base URL (and web UI) of the OPA cluster.
+In order to query policies you have to configure your product and its OPA URL as follows, given the bundle package name `{packageName}` and the policy name `{policyName}`:
+
+[subs="attributes"]
+    http://{clusterName}-cluster.{namespace}.svc.cluster.local:8081/v1/data/{packageName}/{policyName}
+====

rust/operator-binary/src/controller.rs

@@ -158,9 +158,6 @@ pub enum Error {
         source: error_boundary::InvalidObject,
     },
 
-    #[snafu(display("object does not define meta name"))]
-    NoName,
-
     #[snafu(display("internal operator failure"))]
     InternalOperatorFailure {
         source: stackable_opa_operator::crd::Error,
@@ -453,7 +450,7 @@ pub async fn reconcile_opa(
 
     let required_services = vec![
         // The server-role service is the primary endpoint that should be used by clients that do
-        // require local access - Deprecated, kept for downwards compatibility
+        // require local access - deprecated, kept for downwards compatibility
         ServiceConfig {
             name: opa
                 .server_role_service_name_itp_local_deprecated()

rust/operator-binary/src/service.rs

@@ -27,14 +27,6 @@ pub enum Error {
     #[snafu(display("object has no name associated"))]
     NoName,
 
-    #[snafu(display("object has no namespace associated"))]
-    NoNamespace,
-
-    #[snafu(display("failed to build ConfigMap"))]
-    BuildConfigMap {
-        source: stackable_operator::builder::configmap::Error,
-    },
-
     #[snafu(display("failed to build object meta data"))]
     ObjectMeta {
         source: stackable_operator::builder::meta::Error,
@@ -58,13 +50,7 @@ pub fn build_discoverable_services(
 
     // discoverable role services
     for sc in service_configs {
-        let service_name = sc.name;
-        services.push(build_server_role_service(
-            opa,
-            resolved_product_image,
-            &service_name,
-            Some(sc.internal_traffic_policy.to_string()),
-        )?);
+        services.push(build_server_role_service(opa, resolved_product_image, sc)?);
     }
 
     Ok(services)
@@ -73,14 +59,13 @@ pub fn build_discoverable_services(
 fn build_server_role_service(
     opa: &v1alpha1::OpaCluster,
     resolved_product_image: &ResolvedProductImage,
-    service_name: &str,
-    internal_traffic_policy: Option<String>,
+    service_config: ServiceConfig,
 ) -> Result<Service> {
     let role_name = v1alpha1::OpaRole::Server.to_string();
 
     let metadata = ObjectMetaBuilder::new()
         .name_and_namespace(opa)
-        .name(service_name)
+        .name(service_config.name)
         .ownerreference_from_resource(opa, None, Some(true))
         .context(ObjectMissingMetadataForOwnerRefSnafu {
             opa: ObjectRef::from_obj(opa),
@@ -106,7 +91,7 @@ fn build_server_role_service(
             ..ServicePort::default()
         }]),
         selector: Some(service_selector_labels.into()),
-        internal_traffic_policy,
+        internal_traffic_policy: Some(service_config.internal_traffic_policy),
         ..ServiceSpec::default()
     };