Contents

Status

Current state: under discussion

Discussion thread: TBD

JIRA: TBD

Motivation

As part of the KIP-117 work to create an AdminClient for Kafka, we would like to have a way of adding, deleting, and listing the access control lists (ACLs) which are used to control access on Kafka topics and brokers.

New or Changed Public Interfaces

ACL Components

Each ACL consists of a 4-tuple of (principal, host, operation, permission_type).

The "principal" may be either a specific string that matches a single principal, or a "wildcard" represented by the string "*".  In the wire protocol, we represent principal as a NULLABLE_STRING.

The "host" is the IP address which the ACL applies to, or "*" if the ACL applies to all IP addresses.  In the wire protocol, we represent host as a NULLABLE_STRING.

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

• -1: none

• 0: read

• 1: write

• 2: create

• 3: alter

• 4: describe

• 5: clusterAction

• 6: all

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:

• -1: none

• 0:deny

• 1: allow

Resource Components

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:

• -1: none

• 0: topic

• 1: group

• 2: cluster

The "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.

ListAcls

ListAclsRequest handles listing the ACLs in the cluster.  Principals must possess Cluster:Describe permissions to call ListAclsRequest, or be superuser.  Unauthorized requests will receive a ClusterAuthorizationException.

ListAclsRequest (Version: 0) => principal host operation permission_type resource_type resource_name
  principal => NULLABLE_STRING
  host => NULLABLE_STRING
  operation => INT8
  permission_type => INT8
  resource_type => INT8
  resource_name => NULLABLE_STRING

Each of the arguments to ListAclsRequest acts as a filter.  For example, if a principal is supplied, we will return only ACLs that match that principal.  If an operation is supplied, we will return only ACLs that include that operation.  And so forth.  This capability can be used to easily list all the ACLs that apply to a particular topic, or a particular principal.

Note that an argument of "none" is different than a wildcard argument.  That is, ListAclsRequest(principal=none) will return all ACLs, but ListAclsRequest(principal=*) will return only ACLs that have their principal set to wildcard.

ListAclsResponse (Version: 0) => error_code [resource]
  error_code => INT16
  resource => resource_type resource_name [acl]
  resource_type => INT8
  resource_name => STRING
  acl => principal host operation permission_type
  principal => STRING 
  host => STRING
  operation => INT8
  permission_type => INT8

The error_code field will be set if there was an error processing the request.

Each resource_info object describes the a specific resource, and the ACLs bound to that resource.  Note that if filters were specified in the ListAclsRequest, this may not be a complete list of all the ACLs bound to the resource, but only the ones which matched the supplied filters.

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.

AddAcls

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

AddAclsRequest (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 receives a list of resource requests.  Each resource request specifies a list of requests to add particular ACLs.

AddAclsRequest 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.

AddAclsResponse (Version: 0) => error_code [addition_response]
  error_code => INT16
  addition_response => error_code error_string
  error_code => INT16
  error_string => 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 AddAclsRequest.  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_string will be null.  If there was an error, the error_code will be non-zero and the error_string will give a detailed error message.

RemoveAcls

RemoveAclsRequest handles removing ACLs from the cluster. Principals must possess Cluster:All permissions to call AddAclsRequest, or be superuser.  Unauthorized requests will receive a ClusterAuthorizationException.

AddAclsRequest (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 receives a list of resource requests.  Each resource request specifies a list of requests to add particular ACLs.

AddAclsRequest 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.

AddAclsResponse (Version: 0) => error_code [addition_response]
  error_code => INT16
  addition_response => error_code error_string
  error_code => INT16
  error_string => 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 AddAclsRequest.  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_string will be null.  If there was an error, the error_code will be non-zero and the error_string will give a detailed error message.

Proposed Changes

Compatibility, Deprecation, and Migration Plan

Once AdminClient supports ACL operations, we can transition the command-line utilities to using it, instead of contacting ZooKeeper directly.

Rejected Alternatives