kruby-controller 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +201 -0
  3. data/README.md +117 -0
  4. data/Rakefile +8 -0
  5. data/exe/kruby-controller +32 -0
  6. data/lib/kruby-controller.rb +8 -0
  7. data/lib/kruby_controller/builder/controller_builder.rb +52 -0
  8. data/lib/kruby_controller/cache/cache.rb +100 -0
  9. data/lib/kruby_controller/cache/deep_copy.rb +32 -0
  10. data/lib/kruby_controller/cache/delta.rb +12 -0
  11. data/lib/kruby_controller/cache/informer.rb +453 -0
  12. data/lib/kruby_controller/cache/request_error.rb +55 -0
  13. data/lib/kruby_controller/cache/store.rb +92 -0
  14. data/lib/kruby_controller/cache/watch_stream.rb +144 -0
  15. data/lib/kruby_controller/cli/create_api_command.rb +335 -0
  16. data/lib/kruby_controller/cli/flag_parser.rb +85 -0
  17. data/lib/kruby_controller/cli/init_command.rb +383 -0
  18. data/lib/kruby_controller/controller.rb +200 -0
  19. data/lib/kruby_controller/crd.rb +141 -0
  20. data/lib/kruby_controller/election/leader_elector.rb +212 -0
  21. data/lib/kruby_controller/finalizer/finalizer_manager.rb +31 -0
  22. data/lib/kruby_controller/generator/crd_generator.rb +109 -0
  23. data/lib/kruby_controller/gvk.rb +59 -0
  24. data/lib/kruby_controller/handler/enqueued_object.rb +18 -0
  25. data/lib/kruby_controller/handler/enqueued_owner.rb +51 -0
  26. data/lib/kruby_controller/handler/predicated.rb +21 -0
  27. data/lib/kruby_controller/kubernetes_object_client.rb +77 -0
  28. data/lib/kruby_controller/logger.rb +11 -0
  29. data/lib/kruby_controller/manager.rb +291 -0
  30. data/lib/kruby_controller/owner/owner_reference.rb +23 -0
  31. data/lib/kruby_controller/queue/rate_limiter.rb +51 -0
  32. data/lib/kruby_controller/queue/work_queue.rb +375 -0
  33. data/lib/kruby_controller/reconciler.rb +18 -0
  34. data/lib/kruby_controller/request.rb +59 -0
  35. data/lib/kruby_controller/result.rb +50 -0
  36. data/lib/kruby_controller/status/status_updater.rb +29 -0
  37. data/lib/kruby_controller/version.rb +5 -0
  38. data/lib/kruby_controller.rb +87 -0
  39. metadata +138 -0
@@ -0,0 +1,141 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KrubyController
4
+ # A single attribute of a CRD schema (spec or status field).
5
+ class CRDAttribute
6
+ attr_reader :name, :type, :default, :description, :enum, :properties, :items
7
+
8
+ def initialize(name, type:, required: false, default: nil, description: nil, enum: nil, properties: nil, items: nil)
9
+ @name = name
10
+ @type = type
11
+ @required = required
12
+ @default = default
13
+ @description = description
14
+ @enum = enum
15
+ @properties = normalize_properties(properties)
16
+ @items = items.is_a?(Hash) ? self.class.new(name, **items) : items
17
+ end
18
+
19
+ def required?
20
+ @required
21
+ end
22
+
23
+ def to_h
24
+ {
25
+ type: @type,
26
+ required: @required,
27
+ default: @default,
28
+ description: @description,
29
+ enum: @enum,
30
+ properties: @properties,
31
+ items: @items
32
+ }
33
+ end
34
+
35
+ private
36
+
37
+ def normalize_properties(properties)
38
+ return nil unless properties.is_a?(Hash)
39
+
40
+ properties.transform_values { |opts| self.class.new(nil, **opts) }
41
+ end
42
+ end
43
+
44
+ # DSL for declaring a custom resource definition schema.
45
+ #
46
+ # class CronTask
47
+ # include KrubyController::CRD
48
+ #
49
+ # self.group = "stable.example.com"
50
+ # self.version = "v1"
51
+ # self.kind = "CronTask"
52
+ # self.namespaced = true
53
+ #
54
+ # attribute :schedule, type: :string, required: true, description: "Cron expression"
55
+ # attribute :replicas, type: :integer, default: 1
56
+ # status_attribute :last_schedule, type: :string, description: "Last scheduled time"
57
+ # end
58
+ module CRD
59
+ def self.included(base)
60
+ base.extend(ClassMethods)
61
+ end
62
+
63
+ module ClassMethods
64
+ def group=(value)
65
+ @group = value
66
+ end
67
+
68
+ def group
69
+ raise ArgumentError, "CRD group is not set for #{name}" if @group.nil?
70
+
71
+ @group
72
+ end
73
+
74
+ def version=(value)
75
+ @version = value
76
+ end
77
+
78
+ def version
79
+ @version || "v1"
80
+ end
81
+
82
+ def kind=(value)
83
+ @kind = value
84
+ end
85
+
86
+ def kind
87
+ @kind || name.to_s.split("::").last
88
+ end
89
+
90
+ def namespaced=(value)
91
+ @namespaced = value
92
+ end
93
+
94
+ def namespaced
95
+ return true if @namespaced.nil?
96
+
97
+ @namespaced
98
+ end
99
+
100
+ def plural=(value)
101
+ @plural = value
102
+ end
103
+
104
+ def plural
105
+ @plural
106
+ end
107
+
108
+ def short_names=(value)
109
+ @short_names = value
110
+ end
111
+
112
+ def short_names
113
+ @short_names
114
+ end
115
+
116
+ def attribute(attr_name, **options)
117
+ spec_attributes[attr_name] = CRDAttribute.new(attr_name, **options)
118
+ end
119
+
120
+ def status_attribute(attr_name, **options)
121
+ status_attributes[attr_name] = CRDAttribute.new(attr_name, **options)
122
+ end
123
+
124
+ def spec_attributes
125
+ @spec_attributes ||= inherited_attributes(:spec_attributes)
126
+ end
127
+
128
+ def status_attributes
129
+ @status_attributes ||= inherited_attributes(:status_attributes)
130
+ end
131
+
132
+ private
133
+
134
+ def inherited_attributes(accessor)
135
+ return {} unless superclass.respond_to?(accessor)
136
+
137
+ superclass.public_send(accessor).dup
138
+ end
139
+ end
140
+ end
141
+ end
@@ -0,0 +1,212 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "socket"
4
+ require "time"
5
+
6
+ module KrubyController
7
+ module Election
8
+ # Lease-based leader election using the coordination.k8s.io/v1 Lease API.
9
+ #
10
+ # elector = LeaderElector.new(
11
+ # client: coordination_api,
12
+ # lease_name: "my-controller-lock",
13
+ # lease_namespace: "kube-system"
14
+ # )
15
+ # elector.run { start_controllers }
16
+ #
17
+ # While leading, the lease is renewed every retry_period. When leadership
18
+ # is lost (lease taken over by another identity), the renewal stops and
19
+ # on_stopped_leading is invoked; the elector then keeps retrying.
20
+ class LeaderElector
21
+ attr_reader :leader
22
+
23
+ def initialize(
24
+ client:,
25
+ lease_name:,
26
+ lease_namespace:,
27
+ lease_duration: 15,
28
+ renew_deadline: 10,
29
+ retry_period: 2,
30
+ identity: nil,
31
+ on_stopped_leading: nil
32
+ )
33
+ @client = client
34
+ @lease_name = lease_name
35
+ @lease_namespace = lease_namespace
36
+ @lease_duration = lease_duration
37
+ @renew_deadline = renew_deadline
38
+ @retry_period = retry_period
39
+ @identity = identity || "#{Socket.gethostname}-#{Process.pid}"
40
+ @on_stopped_leading = on_stopped_leading
41
+ @leader = false
42
+ @running = false
43
+ @renewal_running = false
44
+ @thread = nil
45
+ @started_leading_block = nil
46
+ end
47
+
48
+ def run(&block)
49
+ @started_leading_block = block || nil
50
+ @running = true
51
+ @thread = Thread.new { election_loop }
52
+ self
53
+ end
54
+
55
+ def stop
56
+ @running = false
57
+ @renewal_running = false
58
+ @thread&.join
59
+ end
60
+
61
+ private
62
+
63
+ def election_loop
64
+ begin
65
+ while @running
66
+ unless try_acquire
67
+ sleep @retry_period
68
+ next
69
+ end
70
+
71
+ @leader = true
72
+ @renewal_running = true
73
+ renewal_thread = Thread.new { renewal_loop }
74
+ begin
75
+ @started_leading_block&.call
76
+ rescue => e
77
+ KrubyController.logger.error("LeaderElector: on_started_leading failed: #{e.message}")
78
+ end
79
+ renewal_thread.join
80
+ @renewal_running = false
81
+ @leader = false
82
+ @on_stopped_leading&.call
83
+ sleep @retry_period
84
+ end
85
+ ensure
86
+ release
87
+ end
88
+ end
89
+
90
+ def try_acquire
91
+ lease = get_or_create_lease
92
+ return false unless lease_can_be_acquired?(lease)
93
+
94
+ update_lease(lease)
95
+ true
96
+ rescue Kubernetes::ApiError => e
97
+ KrubyController.logger.warn("LeaderElector: acquire failed (HTTP #{e.code}): #{e.message}")
98
+ false
99
+ end
100
+
101
+ def renewal_loop
102
+ @last_successful_renewal = Time.now
103
+ while @running && @renewal_running
104
+ if renew_lease
105
+ @last_successful_renewal = Time.now
106
+ elsif lost_leadership?
107
+ KrubyController.logger.warn("LeaderElector: lost leadership")
108
+ @leader = false
109
+ break
110
+ elsif renewal_deadline_exceeded?
111
+ KrubyController.logger.warn("LeaderElector: renew deadline exceeded, stepping down")
112
+ @leader = false
113
+ break
114
+ end
115
+ sleep @retry_period
116
+ end
117
+ end
118
+
119
+ def renewal_deadline_exceeded?
120
+ (Time.now - @last_successful_renewal) > @renew_deadline
121
+ end
122
+
123
+ def renew_lease
124
+ lease = get_or_create_lease
125
+ return false unless lease_can_be_acquired?(lease)
126
+
127
+ update_lease(lease)
128
+ true
129
+ rescue Kubernetes::ApiError => e
130
+ KrubyController.logger.warn("LeaderElector: renewal failed (HTTP #{e.code}): #{e.message}")
131
+ false
132
+ end
133
+
134
+ def lost_leadership?
135
+ lease = read_lease
136
+ holder = lease&.spec&.holder_identity
137
+ !holder.nil? && !holder.empty? && holder != @identity
138
+ rescue Kubernetes::ApiError
139
+ false
140
+ end
141
+
142
+ def get_or_create_lease
143
+ read_lease
144
+ rescue Kubernetes::ApiError => e
145
+ raise unless e.code == 404
146
+
147
+ create_lease
148
+ end
149
+
150
+ def read_lease
151
+ @client.read_namespaced_lease(@lease_name, @lease_namespace)
152
+ end
153
+
154
+ def create_lease
155
+ body = Kubernetes::V1Lease.build_from_hash(
156
+ metadata: { name: @lease_name, namespace: @lease_namespace },
157
+ spec: { leaseDurationSeconds: @lease_duration }
158
+ )
159
+ @client.create_namespaced_lease(@lease_namespace, body)
160
+ end
161
+
162
+ def lease_can_be_acquired?(lease)
163
+ spec = lease.spec
164
+ return true if spec.nil? || spec.holder_identity.nil? || spec.holder_identity.empty?
165
+ return true if spec.holder_identity == @identity
166
+
167
+ last_seen = to_time(spec.renew_time) || to_time(spec.acquire_time)
168
+ return false if last_seen.nil?
169
+
170
+ (Time.now - last_seen) > (spec.lease_duration_seconds || @lease_duration)
171
+ end
172
+
173
+ def update_lease(lease)
174
+ spec = lease.spec || Kubernetes::V1LeaseSpec.new
175
+ now = Time.now.utc
176
+ spec.acquire_time = now if spec.holder_identity.nil? || spec.holder_identity != @identity
177
+ spec.holder_identity = @identity
178
+ spec.lease_duration_seconds = @lease_duration
179
+ spec.renew_time = now
180
+ lease.spec = spec
181
+ @client.replace_namespaced_lease(@lease_name, @lease_namespace, lease)
182
+ true
183
+ end
184
+
185
+ # Clears the holder using the resourceVersion read above as an atomic
186
+ # precondition, so a takeover between read and release fails with 409
187
+ # instead of destroying the new leader's lease.
188
+ def release
189
+ begin
190
+ lease = read_lease
191
+ if lease&.spec&.holder_identity == @identity
192
+ lease.spec.holder_identity = nil
193
+ @client.replace_namespaced_lease(@lease_name, @lease_namespace, lease)
194
+ KrubyController.logger.info("LeaderElector: released lease #{@lease_name}/#{@lease_namespace}")
195
+ end
196
+ rescue Kubernetes::ApiError => e
197
+ KrubyController.logger.warn("LeaderElector: release failed: #{e.message}")
198
+ end
199
+ @leader = false
200
+ end
201
+
202
+ def to_time(value)
203
+ return nil if value.nil?
204
+ return value if value.is_a?(Time)
205
+
206
+ Time.parse(value.to_s)
207
+ rescue ArgumentError
208
+ nil
209
+ end
210
+ end
211
+ end
212
+ end
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KrubyController
4
+ module Finalizer
5
+ class FinalizerManager
6
+ def initialize(client:, gvk:)
7
+ @client = client
8
+ @gvk = gvk
9
+ end
10
+
11
+ def add_finalizer(obj, finalizer)
12
+ return if has_finalizer?(obj, finalizer)
13
+ (obj["metadata"]["finalizers"] ||= []) << finalizer
14
+ @client.update(obj)
15
+ end
16
+
17
+ def remove_finalizer(obj, finalizer)
18
+ obj["metadata"]["finalizers"]&.delete(finalizer)
19
+ @client.update(obj)
20
+ end
21
+
22
+ def has_finalizer?(obj, finalizer)
23
+ (obj.dig("metadata", "finalizers") || []).include?(finalizer)
24
+ end
25
+
26
+ def deleting?(obj)
27
+ !obj.dig("metadata", "deletionTimestamp").to_s.empty?
28
+ end
29
+ end
30
+ end
31
+ end
@@ -0,0 +1,109 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "yaml"
4
+
5
+ module KrubyController
6
+ module Generator
7
+ class CrdGenerator
8
+ TYPE_MAP = {
9
+ string: "string", integer: "integer", float: "number",
10
+ boolean: "boolean", object: "object", array: "array",
11
+ }.freeze
12
+
13
+ def initialize(klass)
14
+ @klass = klass
15
+ end
16
+
17
+ def generate
18
+ {
19
+ "apiVersion" => "apiextensions.k8s.io/v1",
20
+ "kind" => "CustomResourceDefinition",
21
+ "metadata" => { "name" => "#{plural}.#{group}" },
22
+ "spec" => {
23
+ "group" => group,
24
+ "names" => names_spec,
25
+ "scope" => (@klass.respond_to?(:namespaced) && @klass.namespaced) ? "Namespaced" : "Cluster",
26
+ "versions" => [version_spec],
27
+ },
28
+ }
29
+ end
30
+
31
+ def generate_yaml
32
+ YAML.dump(generate)
33
+ end
34
+
35
+ private
36
+
37
+ def group; @klass.group; end
38
+ def version; @klass.version; end
39
+ def kind; @klass.kind; end
40
+ def plural
41
+ return @klass.plural if @klass.respond_to?(:plural) && @klass.plural
42
+
43
+ default_plural
44
+ end
45
+
46
+ def default_plural
47
+ word = kind.downcase
48
+ if word.end_with?("s", "x", "z", "ch", "sh")
49
+ "#{word}es"
50
+ elsif word.end_with?("y") && !%w[a e i o u].include?(word[-2])
51
+ "#{word[0..-2]}ies"
52
+ else
53
+ "#{word}s"
54
+ end
55
+ end
56
+
57
+ def names_spec
58
+ names = { "plural" => plural, "singular" => kind.downcase, "kind" => kind }
59
+ if @klass.respond_to?(:short_names) && @klass.short_names
60
+ names["shortNames"] = @klass.short_names
61
+ end
62
+ names
63
+ end
64
+
65
+ def version_spec
66
+ {
67
+ "name" => version,
68
+ "served" => true,
69
+ "storage" => true,
70
+ "subresources" => { "status" => {} },
71
+ "schema" => {
72
+ "openAPIV3Schema" => {
73
+ "type" => "object",
74
+ "properties" => { "spec" => spec_schema, "status" => status_schema },
75
+ },
76
+ },
77
+ }
78
+ end
79
+
80
+ def spec_schema; build_schema(@klass.spec_attributes); end
81
+ def status_schema; build_schema(@klass.status_attributes); end
82
+
83
+ def build_schema(attrs)
84
+ return {} unless attrs
85
+ properties = {}
86
+ attrs.each { |name, attr| properties[name.to_s] = attribute_to_schema(attr) }
87
+ schema = { "type" => "object", "properties" => properties }
88
+ required = attrs.select { |_k, v| v.required? }.keys.map(&:to_s)
89
+ schema["required"] = required unless required.empty?
90
+ schema
91
+ end
92
+
93
+ def attribute_to_schema(attr)
94
+ schema = if attr.type == :object && attr.properties
95
+ build_schema(attr.properties)
96
+ else
97
+ { "type" => TYPE_MAP[attr.type] || "string" }.tap do |s|
98
+ s["items"] = attribute_to_schema(attr.items) if attr.respond_to?(:items) && attr.items
99
+ end
100
+ end
101
+
102
+ schema["description"] = attr.description if attr.respond_to?(:description) && attr.description
103
+ schema["default"] = attr.default if attr.respond_to?(:default) && !attr.default.nil?
104
+ schema["enum"] = attr.enum if attr.respond_to?(:enum) && attr.enum
105
+ schema
106
+ end
107
+ end
108
+ end
109
+ end
@@ -0,0 +1,59 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KrubyController
4
+ # Group/Version/Kind identifier for a Kubernetes resource type.
5
+ #
6
+ # GVK.new(group: "stable.example.com", version: "v1", kind: "CronTask")
7
+ # # => resource inferred as "crontasks"
8
+ #
9
+ # Value object: compared by group/version/kind/resource/namespaced.
10
+ class GVK
11
+ attr_reader :group, :version, :kind, :resource
12
+
13
+ def initialize(group:, version:, kind:, resource: nil, namespaced: true)
14
+ @group = group.to_s
15
+ @version = version.to_s
16
+ @kind = kind.to_s
17
+ @resource = (resource || infer_resource).to_s
18
+ @namespaced = namespaced
19
+ end
20
+
21
+ def namespaced?
22
+ @namespaced
23
+ end
24
+
25
+ def to_s
26
+ "#{@group}/#{@version}, Kind=#{@kind}"
27
+ end
28
+
29
+ def ==(other)
30
+ other.is_a?(GVK) &&
31
+ [group, version, kind, resource, namespaced?] ==
32
+ [other.group, other.version, other.kind, other.resource, other.namespaced?]
33
+ end
34
+ alias eql? ==
35
+
36
+ def hash
37
+ [group, version, kind, resource, namespaced?].hash
38
+ end
39
+
40
+ def inspect
41
+ "#<KrubyController::GVK #{self} namespaced=#{@namespaced}>"
42
+ end
43
+
44
+ private
45
+
46
+ def infer_resource
47
+ singular = kind.downcase
48
+ if singular.end_with?("s", "x", "z", "ch", "sh")
49
+ "#{singular}es"
50
+ elsif singular.end_with?("y") && !VOWELS.include?(singular[-2])
51
+ "#{singular[0..-2]}ies"
52
+ else
53
+ "#{singular}s"
54
+ end
55
+ end
56
+
57
+ VOWELS = %w[a e i o u].freeze
58
+ end
59
+ end
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KrubyController
4
+ module Handler
5
+ class EnqueuedObject
6
+ def initialize(queue:)
7
+ @queue = queue
8
+ end
9
+
10
+ def handle(delta_type, obj)
11
+ ns = obj.dig("metadata", "namespace") || ""
12
+ name = obj.dig("metadata", "name")
13
+ return unless name
14
+ @queue.add(KrubyController::Request.new(namespace: ns, name: name))
15
+ end
16
+ end
17
+ end
18
+ end
@@ -0,0 +1,51 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KrubyController
4
+ module Handler
5
+ # Enqueues the parent object when an owned object changes.
6
+ #
7
+ # Only ownerReferences with `controller: true` are considered, and the
8
+ # reference must match the owner GVK by both apiVersion and kind
9
+ # (kind alone would let a same-kind owner from another API group through).
10
+ #
11
+ # The enqueued request carries the OWNER's namespace: for a namespaced
12
+ # owner that is the child's namespace, but a cluster-scoped owner lives
13
+ # under the empty namespace, so the child's namespace must not leak in.
14
+ class EnqueuedOwner
15
+ def initialize(queue:, owner_gvk:, owner_namespaced: true)
16
+ @queue = queue
17
+ @owner_gvk = owner_gvk
18
+ @owner_namespaced = owner_namespaced
19
+ end
20
+
21
+ def handle(delta_type, obj)
22
+ (obj.dig("metadata", "ownerReferences") || []).each do |owner|
23
+ next unless owner["controller"] == true
24
+ next unless owner_matches?(owner)
25
+
26
+ @queue.add(KrubyController::Request.new(
27
+ namespace: owner_namespace(obj),
28
+ name: owner["name"]
29
+ ))
30
+ end
31
+ end
32
+
33
+ private
34
+
35
+ def owner_matches?(owner)
36
+ owner["kind"] == @owner_gvk.kind && owner["apiVersion"] == api_version
37
+ end
38
+
39
+ def owner_namespace(obj)
40
+ return "" unless @owner_namespaced
41
+
42
+ obj.dig("metadata", "namespace") || ""
43
+ end
44
+
45
+ def api_version
46
+ group = @owner_gvk.group.to_s
47
+ group.empty? ? @owner_gvk.version : "#{group}/#{@owner_gvk.version}"
48
+ end
49
+ end
50
+ end
51
+ end
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KrubyController
4
+ module Handler
5
+ # Wraps another handler and only forwards events whose object
6
+ # satisfies the predicate. The predicate is a callable that receives
7
+ # the event object and returns a truthy value to pass it through.
8
+ class Predicated
9
+ def initialize(handler:, predicate:)
10
+ @handler = handler
11
+ @predicate = predicate
12
+ end
13
+
14
+ def handle(delta_type, obj)
15
+ return unless @predicate.call(obj)
16
+
17
+ @handler.handle(delta_type, obj)
18
+ end
19
+ end
20
+ end
21
+ end