added some docs and error handling

Author: adwk67

README.md

@@ -1 +1,68 @@
-# hdfs-group-mapper
+# Stackable Group Mapper for Apache Hadoop
+
+HDFS internally uses user groups for group permissions on folders etc. For this reason it is not enough to just have the groups in OPA during authorization, but they actually need to be available to Hadoop. Hadoop offers a few default group providers, such as:
+
+* LDAP
+* Linux user group (usually provided by SSSD or Centrify or similar tools)
+
+Hadoop exposes an [interface](https://github.com/apache/hadoop/blob/rel/release-3.3.6/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/GroupMappingServiceProvider.java) that users can implement to extend these [group mappings](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/GroupsMapping.html). The Stackable Group Mapper does this to look up user groups from OPA.
+
+## OPA Mappings
+
+OPA mappings are returned from the [User-Info-Fetcher](https://docs.stackable.tech/home/nightly/opa/usage-guide/user-info-fetcher#_example_rego_rule) in this form:
+
+```json
+{
+  "id": "af07f12c-a2db-40a7-93e0-874537bdf3f5",
+  "username": "alice",
+  "groups": [
+    "/superset-admin"
+  ],
+  "customAttributes": {}
+}
+```
+
+The Group Mapper only needs the group listing, which can be requested specifically from the Opa server by providing the current user and filtering out the groups with the `json.filter` function, returning a segment that looks like this:
+
+```json
+{
+  "result": {
+    "groups": {
+      "groups": [
+        "/admin",
+        "/superuser"
+      ]
+    }
+  }
+}
+```
+
+The leading slash is required by Opa/Keycloak to allow the definition of subgroups, but this is removed by the group mapper before returning this list of strings to the internal calling routine.
+
+## Configuration
+
+Group mappings are resolved on the NameNode and the following configuration should be added to the NameNode role:
+
+### envOverrides
+
+#### HADOOP_CLASSPATH
+
+* Fixed value of `"/stackable/hadoop/share/hadoop/tools/lib/*.jar"`
+
+### configOverrides / `core-site.xml`
+
+#### hadoop.security.group.mapping
+
+* Fixed value of `"tech.stackable.hadoop.StackableGroupMapper"`
+
+#### hadoop.security.group.mapping.opa.url
+
+* The Opa Server endpoint e.g. `"http://test-opa.default.svc.cluster.local:8081/v1/data/hdfs"`
+
+#### hadoop.user.group.static.mapping.overrides
+
+* The hdfs-operator will add a default static mapping whenever kerberos is activated. This should be removed so that the mapping implementation can provide this information instead: i.e. with an empty string `""`
+
+## Testing
+
+CRDs for spinning up test infrastructure are provided in `test/stack`. The Tiltfile will deploy these resources, build and copy the mapper to the docker image, and re-deploy the image to the running HdfsCluster.

src/main/java/tech/stackable/hadoop/OpaException.java

@@ -0,0 +1,34 @@
+package tech.stackable.hadoop;
+
+import java.net.URI;
+import java.net.http.HttpResponse;
+
+import static tech.stackable.hadoop.StackableGroupMapper.OPA_MAPPING_URL_PROP;
+
+public abstract class OpaException extends RuntimeException {
+
+    public OpaException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public static final class UriInvalid extends OpaException {
+        public UriInvalid(URI uri, Throwable cause) {
+            super("Open Policy Agent URI is invalid (see configuration property \""
+                    + OPA_MAPPING_URL_PROP + "\"): " + uri, cause);
+        }
+    }
+
+    public static final class EndPointNotFound extends OpaException {
+        public EndPointNotFound(String url) {
+            super("Open Policy Agent URI is unreachable (see configuration property \""
+                    + OPA_MAPPING_URL_PROP + "\"): " + url, null);
+        }
+    }
+
+    public static final class OpaServerError extends OpaException {
+        public <T> OpaServerError(String query, HttpResponse<T> response) {
+            super("OPA server returned status " + response.statusCode() + " when processing query "
+                    + query + ": " + response.body(), null);
+        }
+    }
+}

src/main/java/tech/stackable/hadoop/StackableGroupMapper.java

@@ -14,16 +14,29 @@
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.util.List;
+import java.util.Objects;
 
 public class StackableGroupMapper implements GroupMappingServiceProvider {
-    private static final String OPA_MAPPING_URL_PROP = "hadoop.security.group.mapping.opa.url";
+    public static final String OPA_MAPPING_URL_PROP = "hadoop.security.group.mapping.opa.url";
     private final Logger LOG = LoggerFactory.getLogger(StackableGroupMapper.class);
-    private final Configuration configuration;
     private final HttpClient httpClient = HttpClient.newHttpClient();
     private final ObjectMapper json;
+    private URI opaUri = null;
 
     public StackableGroupMapper() {
-        this.configuration = new Configuration();
+        Configuration configuration = new Configuration();
+
+        String opaMappingUrl = configuration.get(OPA_MAPPING_URL_PROP);
+        if (opaMappingUrl == null) {
+            throw new RuntimeException("Config \"" + OPA_MAPPING_URL_PROP + "\" missing");
+        }
+
+        try {
+            this.opaUri = URI.create(opaMappingUrl);
+        } catch (Exception e) {
+            throw new OpaException.UriInvalid(opaUri, e);
+        }
+
         this.json = new ObjectMapper()
                 // https://github.com/stackabletech/trino-opa-authorizer/issues/24
                 // OPA server can send other fields, such as `decision_id`` when enabling decision logs
@@ -43,15 +56,7 @@ public StackableGroupMapper() {
     public List<String> getGroups(String user) throws IOException {
         LOG.info("Calling StackableGroupMapper.getGroups for user [{}]", user);
 
-        String opaMappingUrl = configuration.get(OPA_MAPPING_URL_PROP);
-
-        if (opaMappingUrl == null) {
-            throw new RuntimeException("Config \"" + OPA_MAPPING_URL_PROP + "\" missing");
-        }
-
-        URI opaUri = URI.create(opaMappingUrl);
         HttpResponse<String> response = null;
-
         OpaQuery query = new OpaQuery(new OpaQuery.OpaQueryInput(user));
         String body = json.writeValueAsString(query);
 
@@ -66,9 +71,15 @@ public List<String> getGroups(String user) throws IOException {
             LOG.error(e.getMessage());
         }
 
-        if (response == null || response.statusCode() != 200) {
-            throw new IOException(opaUri.toString());
+        switch (Objects.requireNonNull(response).statusCode()) {
+            case 200:
+                break;
+            case 404:
+                throw new OpaException.EndPointNotFound(opaUri.toString());
+            default:
+                throw new OpaException.OpaServerError(query.toString(), response);
         }
+
         String responseBody = response.body();
         LOG.debug("Response body [{}]", responseBody);
 

test/stack/05-opa.yaml

@@ -9,6 +9,14 @@ data:
   test.rego: |
     package hdfs
 
+    # this will return the group data in this form:
+    #    "result": {
+    #        "groups":
+    #            "groups": [
+    #                "/admin",
+    #                "/superuser"
+    #            ]
+    #        },...
     groups := json.filter(users_by_name[input.username], ["groups"])
 
     # returning data in the form presented by the UIF

test/stack/10-hdfs.yaml

@@ -41,6 +41,7 @@ spec:
           HADOOP_CLASSPATH: "/stackable/hadoop/share/hadoop/tools/lib/*.jar"
         configOverrides:
           core-site.xml:
+            # the mapper is only handled on the namenode so no need to apply this config to all roles
             hadoop.security.group.mapping: "tech.stackable.hadoop.StackableGroupMapper"
             hadoop.security.group.mapping.opa.url: "http://test-opa.default.svc.cluster.local:8081/v1/data/hdfs"
             # The operator adds a default static mapping when kerberos is activated, see: