Page History

...

The "operation" is the particular operation which the ACL controls.  In the wire protocol, we represented resource_type as an INT8.  The mappings are:

• -2: unknown

• -1: noneany

• 0: read

• 1: write

• 2: create

• 3: alter

• 4: describe

• 5: clusterAction

• 6: all

"Unknown" represents an operation type that we don't know how to decode.  "Any" can only be used in filters, and matches any operation type.

The "permission_type" is whether the ACL allows access or forbids it.  In the wire protocol, we represented resource_type as an INT8.  The mappings are:

• -2: unknown

• -1: noneany

• 0:deny

• 1: allow

Representing Resource Components on the Wire

"Unknown" represents a permission type that we don't know how to decode.  "Any" can only be used in filters, and matches any permission type.

Representing Resource Components on the Wire

Every ACLs is bound to a specific Every ACLs is bound to a specific resource.

The "resource_type" is the type of resource the ACL applies to.  In the wire protocol, we represented resource_type as an INT8.  The mappings are:

• -2: unknown

• -1: any

• 0: topic

• 1: group

• 2: cluster

The "Unknown" represents a resource type that we don't know how to decode.  "Any" can only be used in filters, and matches any resource type.

The "resource_name" is the name of the particular resource.  resource_name" is the name of the particular resource.  For example, when "resource_type" == "topic", "resource_name" will be the topic name.  In the wire protocol, we represent principal as a NULLABLE_STRING.

...

The AdminClient needs some classes to represent the concepts of resource types, ACL operations, and permission types.

publicenum class ResourceTypeAclResourceType {
  /**
   * Parse the given string as a resource type.
   */
  public static ResourceType fromString(String str);
  public static final ResourceType ANY = new ResourceType((byte)-1);
  public static final ResourceType TOPIC = new ResourceType((byte)0);
  public static final ResourceType GROUP = new ResourceType((byte)1);
  public static final ResourceType CLUSTER = new ResourceType((byte)2);
  private final byte ty;
  ResourceType(byte ty) {
    this.ty = ty;
  }
  public String toString();
}public class AclOperation {
  /**
   * Parse the given string as an ACL operation.
   */
  public static AclOperation fromString(String str);
  public static final AclOperation ANY = new AclOperation((byte)-1);
  public static final AclOperation READ = new AclOperation((byte)0);
  public static final AclOperation WRITE = new AclOperation((byte)1);
  public static final AclOperation CREATE = new AclOperation((byte)2);
  public static final AclOperation DELETE = new AclOperation((byte)3);
  public static final AclOperation ALTER = new AclOperation((byte)4);
  public static final AclOperation DESCRIBE = new AclOperation((byte)5);
  public static final AclOperation CLUSTER_ACTION = new AclOperation((byte)6);
  public static final AclOperation ALL = new AclOperation((byte)7);
  private final byte op;
  AclOperation(byte op) {
    this.op = op;
  }
  public String toString();
}
public class AclPermissionType {
  /**
   * Parse the given string as a permission type.
   */
  public static AclPermissionType fromString(String str);
  public static final AclPermissionType ANY = new AclPermissionType((byte)-1);
  public static final AclPermissionType DENY = new AclPermissionType((byte)0);
  public static final AclPermissionType ALLOW = new AclPermissionType((byte)1);
  private final byte ty;
  AclPermissionType(byte ty) {
    this.ty = ty;
  }
  public String toString();
}

AdminClient#listAcls

The listAcls API surfaces ListAclsRequest.

ListAclsResult AdminClient#listAcls(AclFilter filter, ListAclsOptions options);

public ListAclsOptions 
  ListAclsOptions setTimeout(Integer timeout);
}

AclFilter objects represent the filters applied during listAcls.

Fields which are null match anything.  AclFilter.ANY matches any ACL.

...

... }

enum AclOperation { ... }

enum AclPermissionType { ... }

The enumerators have the values described in the "New Network Requests" section, as well as functions to translate between INT8 and the enum types.

AclResource Class

The AclResource class represents a resource that an ACL can be attached to.

class AclResource {
  String name;
  AclResourceType resourceType;
}

AclData Class

The AclResource class represents data about an ACL itself.

class AclData {
  String principal;
  String host;
  AclOperation operation;
  AclPermissionType permissionType;
}

AclFixture Class

The AclFixture class represents an ACL and the resource it is attached to.

class AclFixture {
  AclResource resource;
  AclData data;
}

AdminClient#listAcls

The listAcls API surfaces ListAclsRequest.

ListAclsResult AdminClient#listAcls(AclFixture filter, ListAclsOptions options);

public ListAclsOptions 
  ListAclsOptions setTimeout(Integer timeout);
}

The "filter" object is a filter which will be used to select which ACLs are reported.  Fields which are null or ANY match anything.  It is an error to specify fields as UNKNOWN.

The ListAclsResult object contains a KafkaFuture with the ACL Descriptions.

public ListAclsResult {
  public KafkaFuture<List<AclFixture>> all

The ListAclsResult object contains a KafkaFuture with the ACL Descriptions.

public ListAclsResult {
  public KafkaFuture<List<AclDescription>> all();
}
public class AclDescription {
  public String principal();
  public String host();
  public AclOperation Operation();
  public AclPermissionType aclPermissionType();
  public AclResourceType aclResourceType();
  public String resourceName();
  public String toString();
}

AdminClient#CreateAcls

The CreateAcls API surfaces CreateAclsRequest.

...

If we later add new resource types, operation types, and so forth, we would like to be able to interact with them with the old AdminClient.  This is why the AclResourceType, AclOperation, and AclPermissionType classes are not enums have UNKNOWN values.  If we get an INT8 which we don't know the name for, we can still create a Java object with that byte.  That Java object will describe itself as UNKNOWN(9) instead of WRITEit gets mapped to an UNKNOWN object.

What if we later add more dimensions to the 4-tuple that describes ACLs, or the 2-tuple that describes resources?  CreateAcls will continue to work, although the entries it creates will always get the default value for the new dimension.  ListAcls and DeleteAcls will also continue to work.  The filters created by older clients will always have an implicit "any" entry for the new dimension.  This allows the old AdminClient to continue to be able to function in the new environment.

...