Class: Karafka::Admin::Acl

Inherits:
Karafka::Admin show all
Defined in:
lib/karafka/admin/acl.rb

Overview

Struct and set of operations for ACLs management that simplifies their usage. It allows to use Ruby symbol based definitions instead of usage of librdkafka types (it allows to use rdkafka numerical types as well out of the box)

We map the numerical values because they are less descriptive and harder to follow.

This API works based on ability to create a ‘Karafka:Admin::Acl` object that can be then used using `#create`, `#delete` and `#describe` class API.

Constant Summary

Constants inherited from Karafka::Admin

Recovery

Instance Attribute Summary collapse

Attributes inherited from Karafka::Admin

#custom_kafka

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Karafka::Admin

cluster_info, #cluster_info, copy_consumer_group, #copy_consumer_group, create_partitions, #create_partitions, create_topic, #create_topic, delete_consumer_group, #delete_consumer_group, delete_topic, #delete_topic, plan_topic_replication, #plan_topic_replication, read_lags_with_offsets, #read_lags_with_offsets, read_topic, #read_topic, read_watermark_offsets, #read_watermark_offsets, rename_consumer_group, #rename_consumer_group, seek_consumer_group, #seek_consumer_group, topic_info, #topic_info, trigger_rebalance, #trigger_rebalance, with_admin, #with_admin, with_consumer, #with_consumer

Constructor Details

#initialize(kafka: nil, resource_type: nil, resource_name: nil, resource_pattern_type: nil, principal: nil, host: "*", operation: nil, permission_type: nil) ⇒ Acl

Initializes a new Acl instance with specified attributes.

This class serves dual purposes:

  1. As an ACL rule definition when called with resource_type and other ACL parameters

  2. As an admin operations instance when called with only kafka: parameter

Each parameter is mapped to its corresponding value in the respective *_MAP constant, allowing usage of more descriptive Ruby symbols instead of numerical types.

Examples:

Create an ACL rule

acl = Karafka::Admin::Acl.new(
  resource_type: :topic,
  resource_name: 'my-topic',
  resource_pattern_type: :literal,
  principal: 'User:my-user',
  operation: :read,
  permission_type: :allow
)

Create an admin instance for a different cluster

admin = Karafka::Admin::Acl.new(kafka: { 'bootstrap.servers': 'other:9092' })
admin.do_create(acl)

Parameters:

  • kafka (Hash) (defaults to: nil) —

    custom kafka configuration for admin operations (optional)

  • resource_type (Symbol, Integer) (defaults to: nil) —

    Specifies the type of Kafka resource (like :topic, :consumer_group). Accepts either a symbol from RESOURCE_TYPES_MAP or a direct rdkafka numerical type.

  • resource_name (String, nil) (defaults to: nil) —

    The name of the Kafka resource (like a specific topic name). Can be nil for certain types of resource pattern types.

  • resource_pattern_type (Symbol, Integer) (defaults to: nil) —

    Determines how the ACL is applied to the resource. Uses a symbol from RESOURCE_PATTERNS_TYPE_MAP or a direct rdkafka numerical type.

  • principal (String, nil) (defaults to: nil) —

    Specifies the principal (user or client) for which the ACL is being defined. Can be nil if not applicable.

  • host (String) (defaults to: "*") —

    (default: ‘*’) Defines the host from which the principal can access the resource. Defaults to ‘*’ for all hosts.

  • operation (Symbol, Integer) (defaults to: nil) —

    Indicates the operation type allowed or denied by the ACL. Uses a symbol from OPERATIONS_MAP or a direct rdkafka numerical type.

  • permission_type (Symbol, Integer) (defaults to: nil) —

    Specifies whether to allow or deny the specified operation. Uses a symbol from PERMISSION_TYPES_MAP or a direct rdkafka numerical type.



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/karafka/admin/acl.rb', line 232

def initialize(
  kafka: nil,
  resource_type: nil,
  resource_name: nil,
  resource_pattern_type: nil,
  principal: nil,
  host: "*",
  operation: nil,
  permission_type: nil
)
  # If resource_type is provided, this is an ACL rule definition
  if resource_type
    @resource_type = map(resource_type, RESOURCE_TYPES_MAP)
    @resource_name = resource_name
    @resource_pattern_type = map(resource_pattern_type, RESOURCE_PATTERNS_TYPE_MAP)
    @principal = principal
    @host = host
    @operation = map(operation, OPERATIONS_MAP)
    @permission_type = map(permission_type, PERMISSION_TYPES_MAP)
    super(kafka: kafka || {})
    freeze
  else
    # This is an admin operations instance
    super(kafka: kafka || {})
  end
end

Instance Attribute Details

#host ⇒ Object (readonly)

Returns the value of attribute host.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def host
  @host
end

#operation ⇒ Object (readonly)

Returns the value of attribute operation.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def operation
  @operation
end

#permission_type ⇒ Object (readonly)

Returns the value of attribute permission_type.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def permission_type
  @permission_type
end

#principal ⇒ Object (readonly)

Returns the value of attribute principal.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def principal
  @principal
end

#resource_name ⇒ Object (readonly)

Returns the value of attribute resource_name.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def resource_name
  @resource_name
end

#resource_pattern_type ⇒ Object (readonly)

Returns the value of attribute resource_pattern_type.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def resource_pattern_type
  @resource_pattern_type
end

#resource_type ⇒ Object (readonly)

Returns the value of attribute resource_type.



187
188
189
 
# File 'lib/karafka/admin/acl.rb', line 187

def resource_type
  @resource_type
end

Class Method Details

.all ⇒ Object

See Also:



128
129
130
 
# File 'lib/karafka/admin/acl.rb', line 128

def all
  new.all
end

.create(acl) ⇒ Object

Parameters:

  • acl (Acl) —

    ACL rule to create

See Also:



111
112
113
 
# File 'lib/karafka/admin/acl.rb', line 111

def create(acl)
  new.create(acl)
end

.delete(acl) ⇒ Object

Parameters:

  • acl (Acl) —

    ACL pattern to match for deletion

See Also:



117
118
119
 
# File 'lib/karafka/admin/acl.rb', line 117

def delete(acl)
  new.delete(acl)
end

.describe(acl) ⇒ Object

Parameters:

  • acl (Acl) —

    ACL pattern to describe

See Also:



123
124
125
 
# File 'lib/karafka/admin/acl.rb', line 123

def describe(acl)
  new.describe(acl)
end

Instance Method Details

#all ⇒ Array<Acl>

Returns all acls on a cluster level

Returns:

  • (Array<Acl>) —

    all acls



173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/karafka/admin/acl.rb', line 173

def all
  describe(
    self.class.new(
      resource_type: :any,
      resource_name: nil,
      resource_pattern_type: :any,
      principal: nil,
      operation: :any,
      permission_type: :any,
      host: "*"
    )
  )
end

#create(acl) ⇒ Array<Acl>

Creates (unless already present) a given ACL rule in Kafka

Parameters:

Returns:

  • (Array<Acl>) —

    created acls



136
137
138
139
140
141
142
 
# File 'lib/karafka/admin/acl.rb', line 136

def create(acl)
  with_admin_wait do |admin|
    admin.create_acl(**acl.to_native_hash)
  end

  [acl]
end

#delete(acl) ⇒ Array<Acl>

Note:

More than one Acl may be removed if rules match that way

Removes acls matching provide acl pattern.

Parameters:

Returns:

  • (Array<Acl>) —

    deleted acls



148
149
150
151
152
153
154
155
156
 
# File 'lib/karafka/admin/acl.rb', line 148

def delete(acl)
  result = with_admin_wait do |admin|
    admin.delete_acl(**acl.to_native_hash)
  end

  result.deleted_acls.map do |result_acl|
    from_rdkafka(result_acl)
  end
end

#describe(acl) ⇒ Array<Acl>

Takes an Acl definition and describes all existing Acls matching its criteria

Parameters:

Returns:

  • (Array<Acl>) —

    described acls



161
162
163
164
165
166
167
168
169
 
# File 'lib/karafka/admin/acl.rb', line 161

def describe(acl)
  result = with_admin_wait do |admin|
    admin.describe_acl(**acl.to_native_hash)
  end

  result.acls.map do |result_acl|
    from_rdkafka(result_acl)
  end
end

#to_native_hash ⇒ Hash

Converts the Acl into a hash with native rdkafka types

Returns:

  • (Hash) —

    hash with attributes matching rdkafka numerical types



261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/karafka/admin/acl.rb', line 261

def to_native_hash
  {
    resource_type: remap(resource_type, RESOURCE_TYPES_MAP),
    resource_name: resource_name,
    resource_pattern_type: remap(resource_pattern_type, RESOURCE_PATTERNS_TYPE_MAP),
    principal: principal,
    host: host,
    operation: remap(operation, OPERATIONS_MAP),
    permission_type: remap(permission_type, PERMISSION_TYPES_MAP)
  }.freeze
end