...

In contrast to ListAclsRequest, none of the fields in the ACL 4-tuple or the resource 2-tuple are ever set to null or none in the response.

...

CreateAclsRequest and

...

CreateAclsResponse

AddAclsRequest CreateAclsRequest handles adding new ACLs in the cluster. Principals must possess Cluster:All permissions to call AddAclsRequestCreateAclsRequest, or be superuser.  Unauthorized requests will receive a ClusterAuthorizationException.

AddAclsRequestCreateAclsRequest (Version: 0) => [resource_request]
  resource_request => resource_type resource_name [acl_request]
  resource_type => INT8
  resource_name => STRING
  acl_request => principal host operation permission_type
  principal => STRING
  host => STRING
  operation => INT8
  permission_type => INT8 

AddAclsRequest CreateAclsRequest receives a list of resource requests.  Each resource request specifies a list of requests to add particular ACLs.

AddAclsRequest CreateAclsRequest must be sent to the controller broker.  The request is not transactional: if one addition fails, the others may proceed.  Errors are reported independently for each addition.

AddAclsResponseCreateAclsResponse (Version: 0) => error_code [addition_response]
  error_code => INT16
  addition_response => error_code error_message
  error_code => INT16
  error_message => NULLABLE_STRING

The error_code field will be non-zero if the was an error that prevented processing any part of the request.  If the error_code field is non-zero, the addition_response array will be empty.  Otherwise, there will be an addition_response for each addition in the AddAclsRequestCreateAclsRequest.  These responses will be appear in the same order which the requests appeared.  If the request completed successfully, error_code will be 0 and error_message will be null.  If there was an error, the error_code will be non-zero and the error_message will give a detailed error message describing why the addition could not be performed.

...

DeleteAclsRequest receives a list of filters.  It will attempt to remove all the ACLs which match each filter.

Just like AddAclsRequestCreateAclsRequest, DeleteAclsRequest must be sent to the controller broker.  The request is not transactional: if one addition fails, the others may proceed.  Results are reported independently for each removal.

...

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 addAcls CreateAcls API surfaces AddAclsRequestCreateAclsRequest.

AddAclsResultCreateAclsResult AdminClient#addAclsAdminClient#createAcls(Collection<AclDescription> acls, AddAclsOptionsCreateAclsOptions options);

public AddAclsOptionsCreateAclsOptions 
  AddAclsOptionsCreateAclsOptions setTimeout(Integer timeout);
}

public AddAclsResultCreateAclsResult {
  public KafkaFuture<Void> all();
  public Map<AclDescription, KafkaFuture<Void>> results();
}

...

The deleteAcls API surfaces DeleteAclsRequest.

RemoveAclsResultDeleteAclsResult AdminClient#deleteAcls(Collection<AclFilter> filters, DeleteAclsOptions options);

...

What if we later add more dimensions to the 4-tuple that describes ACLs, or the 2-tuple that describes resources?   AddAcls  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.

Rejected Alternatives

Combined

...

CreateAcls and

...

DeleteAcls API (AlterAcls)

We could have combined AddAcls CreateAcls and RemoveAcls DeleteAcls into a single AlterAcls RPC.  However, this would have been a bad idea for a few reasons:

• The name "AlterAcls" suggests that ACLs are being altered.  However, in fact ACLs are only being added or removed, but not altered.
• It's unclear what order the add and remove operations happen in.
• It is unclear whether a remove operation can remove something added in the same AlterAcls request.
• If add and remove operations are reordered, a security hole could be created when brokers are configured with default-allow behavior.  Deleting a restrictive ACL on a secure topic before adding a new restrictive ACL on that topic creates a window of vulnerability.
• AddAcls CreateAcls and RemoveAcls DeleteAcls is similar to the existing AddTopics and RemoveTopics APIs.

...