brisk-provider-kubernetes 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 882e58cd13f8b798cc6e6beceb16a38a4140d940ddeeb9cc774bacc74e269a13
+  data.tar.gz: 9040dd237daac56141cc8554089135377dee0eb6d308693b0e6fee046266b882
+SHA512:
+  metadata.gz: 8fa771314fc4cda075e6ade74e7b82241acd0c8f3752159ea82f4673db620e18c98bda64c880d50e7e7fe5864d012a69982a57cdb14346d58c9401bcca569037
+  data.tar.gz: c16a8dc635b63c3ba1d661ab01c066d536e42e900c9693b883667c6d0378994f081a7d0aaf300a2cfaa38838d39f22b7e3ab0180cedb96d052d70b911fb335fe

data/README.md

@@ -0,0 +1,435 @@
+# Brisk Provider: Kubernetes
+
+Run Brisk CI workers as Kubernetes pods in your cluster. This provider manages the full lifecycle of worker pods, from creation to cleanup.
+
+## Features
+
+- ✅ **Dynamic Pod Creation** - Automatically creates worker pods on-demand
+- ✅ **Auto-scaling** - Works with Kubernetes Horizontal Pod Autoscaler
+- ✅ **Health Management** - Uses Kubernetes liveness and readiness probes
+- ✅ **Resource Limits** - Configurable CPU and memory requests/limits
+- ✅ **Node Selection** - Support for node selectors and tolerations
+- ✅ **Namespace Isolation** - Run workers in dedicated namespaces
+- ✅ **Orphan Cleanup** - Automatic reconciliation of orphaned pods
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'brisk-provider-kubernetes'
+```
+
+Or install from source:
+
+```ruby
+gem 'brisk-provider-kubernetes', git: 'https://github.com/brisktest/brisk-provider-kubernetes'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+The provider will auto-register when Rails boots.
+
+## Configuration
+
+### Prerequisites
+
+1. **Kubernetes Cluster** - You need a running Kubernetes cluster
+2. **kubectl Access** - Configured kubeconfig or in-cluster service account
+3. **Namespace** - Create a namespace for Brisk workers:
+
+```bash
+kubectl create namespace brisk-workers
+```
+
+### Environment Variables
+
+**For local development (using kubeconfig):**
+```bash
+KUBECONFIG=/path/to/kubeconfig
+K8S_NAMESPACE=brisk-workers  # Optional, defaults to brisk-workers
+BRISK_API_ENDPOINT=api.brisk.dev:443
+```
+
+**For in-cluster deployment (using service account):**
+```bash
+K8S_NAMESPACE=brisk-workers  # Optional
+BRISK_API_ENDPOINT=api.brisk.dev:443
+```
+
+### RBAC Permissions
+
+The Brisk API needs these Kubernetes permissions:
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: brisk-api
+  namespace: brisk-system
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: brisk-worker-manager
+  namespace: brisk-workers
+rules:
+- apiGroups: [""]
+  resources: ["pods"]
+  verbs: ["get", "list", "watch", "create", "delete"]
+- apiGroups: [""]
+  resources: ["pods/log"]
+  verbs: ["get"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind:RoleBinding
+metadata:
+  name: brisk-api-worker-manager
+  namespace: brisk-workers
+subjects:
+- kind: ServiceAccount
+  name: brisk-api
+  namespace: brisk-system
+roleRef:
+  kind: Role
+  name: brisk-worker-manager
+  apiGroup: rbac.authorization.k8s.io
+```
+
+Apply with:
+```bash
+kubectl apply -f rbac.yaml
+```
+
+### Project Configuration
+
+Create a project using the Kubernetes provider:
+
+```ruby
+project = Project.create!(
+  name: "My K8s Project",
+  worker_provider: 'kubernetes',
+  provider_config: {
+    # Required
+    'namespace' => 'brisk-workers',
+
+    # Optional: Custom environment variables
+    'env' => {
+      'CUSTOM_VAR' => 'value',
+      'DEBUG' => 'true'
+    },
+
+    # Optional: Resource defaults
+    'default_memory_mb' => 4096,
+    'default_cpu_count' => 2,
+
+    # Optional: Node selection
+    'node_selector' => {
+      'workload-type' => 'ci'
+    },
+
+    # Optional: Tolerations for tainted nodes
+    'tolerations' => [
+      {
+        'key' => 'ci-workload',
+        'operator' => 'Equal',
+        'value' => 'true',
+        'effect' => 'NoSchedule'
+      }
+    ]
+  }
+)
+```
+
+## Usage
+
+Once configured, the provider works automatically:
+
+```ruby
+# Start a test run
+jobrun = project.jobruns.create!(/* ... */)
+
+# Provider automatically:
+# 1. Finds available worker pods
+# 2. Creates new pods if needed
+# 3. Allocates them to the jobrun
+# 4. Cleans up after tests complete
+
+# Check worker status
+project.workers.in_use.each do |worker|
+  puts "Worker #{worker.id}: #{worker.state}"
+  puts "  Pod: #{worker.machine.uid}"
+  puts "  Node: #{worker.machine.json_data['node_name']}"
+end
+```
+
+## Pod Configuration
+
+Worker pods are created with:
+
+### Container Spec
+- **Image**: From `project.image.url`
+- **Ports**:
+  - 50051 (gRPC for worker communication)
+  - 8081 (HTTP for health checks)
+- **Environment**:
+  - `BRISK_PROJECT_ID`
+  - `BRISK_PROJECT_TOKEN`
+  - `BRISK_API_ENDPOINT`
+  - `WORKER_CONCURRENCY`
+  - Custom vars from `provider_config['env']`
+
+### Resources
+```yaml
+resources:
+  requests:
+    memory: "4096Mi"  # Configurable
+    cpu: "2"          # Configurable
+  limits:
+    memory: "6144Mi"  # 1.5x requests
+    cpu: "3"          # 1.5x requests
+```
+
+### Health Checks
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 8081
+  initialDelaySeconds: 10
+  periodSeconds: 30
+
+readinessProbe:
+  httpGet:
+    path: /ready
+    port: 8081
+  initialDelaySeconds: 5
+  periodSeconds: 10
+```
+
+### Labels
+All pods are labeled with:
+- `brisk-project-id: <project_id>`
+- `brisk-role: worker`
+- `app: brisk-worker`
+
+Use these labels for monitoring, network policies, etc.
+
+## Advanced Configuration
+
+### Custom Resource Limits
+
+```ruby
+project.update!(
+  provider_config: {
+    'namespace' => 'brisk-workers',
+    'default_memory_mb' => 8192,  # 8GB RAM
+    'default_cpu_count' => 4       # 4 CPUs
+  }
+)
+```
+
+### Node Selection
+
+Run workers on specific nodes:
+
+```ruby
+project.update!(
+  provider_config: {
+    'namespace' => 'brisk-workers',
+    'node_selector' => {
+      'workload-type' => 'ci',
+      'disk-type' => 'ssd'
+    }
+  }
+)
+```
+
+### Tolerations
+
+Run on tainted nodes:
+
+```ruby
+project.update!(
+  provider_config: {
+    'namespace' => 'brisk-workers',
+    'tolerations' => [
+      {
+        'key' => 'ci-workload',
+        'operator' => 'Equal',
+        'value' => 'true',
+        'effect' => 'NoSchedule'
+      }
+    ]
+  }
+)
+```
+
+### Multiple Namespaces
+
+Run different projects in different namespaces:
+
+```ruby
+# Project 1 - staging environment
+project1 = Project.create!(
+  name: "Staging Tests",
+  worker_provider: 'kubernetes',
+  provider_config: { 'namespace' => 'brisk-staging' }
+)
+
+# Project 2 - production environment
+project2 = Project.create!(
+  name: "Production Tests",
+  worker_provider: 'kubernetes',
+  provider_config: { 'namespace' => 'brisk-production' }
+)
+```
+
+## Monitoring
+
+### View Pods
+
+```bash
+# List all Brisk worker pods
+kubectl get pods -n brisk-workers -l app=brisk-worker
+
+# Watch pod status
+kubectl get pods -n brisk-workers -l app=brisk-worker -w
+
+# View logs
+kubectl logs -n brisk-workers <pod-name>
+```
+
+### Metrics
+
+Worker pods expose metrics on port 8081:
+- `/health` - Liveness check
+- `/ready` - Readiness check
+- `/metrics` - Prometheus metrics (if enabled)
+
+### Events
+
+```bash
+# View pod events
+kubectl describe pod -n brisk-workers <pod-name>
+
+# Watch events
+kubectl get events -n brisk-workers -w
+```
+
+## Troubleshooting
+
+### Pods Not Starting
+
+Check events:
+```bash
+kubectl describe pod -n brisk-workers <pod-name>
+```
+
+Common issues:
+- **ImagePullBackOff**: Check image URL and registry credentials
+- **Pending**: Check resource requests vs available node capacity
+- **CrashLoopBackOff**: Check pod logs for errors
+
+### Workers Not Connecting
+
+1. Check pod logs:
+```bash
+kubectl logs -n brisk-workers <pod-name>
+```
+
+2. Verify connectivity:
+```bash
+kubectl exec -n brisk-workers <pod-name> -- curl http://api.brisk.dev
+```
+
+3. Check environment variables:
+```bash
+kubectl exec -n brisk-workers <pod-name> -- env | grep BRISK
+```
+
+### Orphaned Pods
+
+The provider automatically cleans up orphaned pods via reconciliation. To manually clean up:
+
+```bash
+# Delete all pods for a project
+kubectl delete pods -n brisk-workers -l brisk-project-id=<project_id>
+
+# Delete all Brisk worker pods
+kubectl delete pods -n brisk-workers -l app=brisk-worker
+```
+
+## Development
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Testing Locally
+
+1. Start minikube or kind cluster
+2. Configure kubeconfig
+3. Add gem to Gemfile with `path:` option
+4. Create test project with `worker_provider: 'kubernetes'`
+
+### Debugging
+
+Enable debug logging:
+
+```ruby
+# config/environments/development.rb
+Rails.logger.level = :debug
+```
+
+View provider logs:
+```ruby
+Rails.logger.tagged("K8s Provider") do
+  # Provider operations will be logged
+end
+```
+
+## Architecture
+
+### Provider → PodService → Kubernetes API
+
+```
+Provider (provider.rb)
+  └─> PodService (pod_service.rb)
+      └─> K8s Client (k8s-ruby gem)
+          └─> Kubernetes API
+```
+
+### Pod Lifecycle
+
+1. **Creation**: Provider creates pod via PodService
+2. **Registration**: Pod starts and registers via gRPC
+3. **Allocation**: Worker is allocated to jobrun
+4. **Execution**: Tests run on worker
+5. **Cleanup**: Pod is deleted after job completes
+
+### Health Management
+
+- Kubernetes manages pod health via probes
+- Brisk disables internal health tracking (sets `last_checked_at` to far future)
+- Dead pods are automatically restarted by Kubernetes
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/brisktest/brisk-provider-kubernetes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+- Documentation: https://docs.brisk.dev/providers/kubernetes
+- Issues: https://github.com/brisktest/brisk-provider-kubernetes/issues
+- Discussions: https://github.com/brisktest/brisk/discussions

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/brisk/providers/kubernetes/engine.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Brisk
+  module Providers
+    module Kubernetes
+      # Rails Engine for Kubernetes provider
+      # Auto-registers provider when gem is loaded
+      class Engine < ::Rails::Engine
+        isolate_namespace Brisk::Providers::Kubernetes
+
+        # Auto-register provider when Rails boots
+        initializer 'brisk_provider_kubernetes.register', before: :load_config_initializers do |app|
+          app.config.to_prepare do
+            if defined?(::Providers::ProviderRegistry)
+              ::Providers::ProviderRegistry.instance.register(
+                'kubernetes',
+                Brisk::Providers::Kubernetes::Provider
+              )
+              Rails.logger.info '✓ Kubernetes Provider registered'
+            else
+              Rails.logger.warn '⚠ Cannot register Kubernetes Provider - ProviderRegistry not found'
+            end
+          end
+        end
+
+        # Add any migrations from this gem to the main app
+        initializer 'brisk_provider_kubernetes.migrations' do |app|
+          unless app.root.to_s.match?(root.to_s)
+            config.paths['db/migrate'].expanded.each do |expanded_path|
+              app.config.paths['db/migrate'] << expanded_path
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brisk/providers/kubernetes/pod_service.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Brisk
+  module Providers
+    module Kubernetes
+      # Service for managing Kubernetes pods as Brisk workers
+      class PodService
+        attr_reader :project, :client
+
+        def initialize(project, client)
+          @project = project
+          @client = client
+        end
+
+        # Get or create worker pods for a job run
+        # @param jobrun [Jobrun] The job run
+        # @param workers_needed [Integer] Number of workers needed
+        # @return [Array<Worker>] Array of workers
+        def get_workers_for_project(_jobrun, workers_needed)
+          namespace = project.provider_config['namespace'] || 'brisk-workers'
+
+          # Find available workers (pods in Ready state)
+          available_workers = find_available_workers(namespace)
+
+          if available_workers.size >= workers_needed
+            # Use existing workers
+            available_workers.first(workers_needed)
+          else
+            # Create additional workers
+            needed = workers_needed - available_workers.size
+            Rails.logger.info "[K8s] Creating #{needed} new worker pods"
+
+            new_workers = needed.times.map do
+              create_worker_pod(default_machine_config)
+            end
+
+            available_workers + new_workers.compact
+          end
+        end
+
+        # Create a worker pod
+        # @param machine_config [Hash] Machine configuration
+        # @return [Machine] The created machine
+        def create_worker_pod(machine_config)
+          namespace = project.provider_config['namespace'] || 'brisk-workers'
+          pod_name = "brisk-worker-#{project.id}-#{SecureRandom.hex(4)}"
+
+          pod_spec = build_pod_spec(pod_name, machine_config)
+
+          Rails.logger.debug "[K8s] Creating pod: #{pod_name}"
+          client.api('v1').resource('pods', namespace: namespace).create_resource(pod_spec)
+
+          # Wait for pod to get IP address (with timeout)
+          pod = wait_for_pod_ip(namespace, pod_name, timeout: 30)
+
+          # Create machine record
+          machine = Machine.create!(
+            uid: pod.metadata.name,
+            provider: 'kubernetes',
+            ip_address: pod.status.podIP,
+            host_ip: pod.status.hostIP,
+            state: 'running',
+            config: machine_config,
+            json_data: {
+              namespace: namespace,
+              pod_name: pod.metadata.name,
+              node_name: pod.spec.nodeName
+            }
+          )
+
+          Rails.logger.info "[K8s] Created pod #{pod_name} on node #{pod.spec.nodeName}"
+          machine
+        rescue K8s::Error::API => e
+          Rails.logger.error "[K8s] Failed to create pod: #{e.message}"
+          raise ::Providers::ProviderError, "Kubernetes API error: #{e.message}"
+        end
+
+        # Restart a pod (delete and recreate)
+        # @param worker [Worker] The worker to restart
+        # @return [Machine] The new machine
+        def restart_pod(worker)
+          namespace = worker.machine.json_data['namespace'] || 'brisk-workers'
+          old_pod_name = worker.machine.uid
+
+          # Delete old pod
+          begin
+            client.api('v1').resource('pods', namespace: namespace).delete(
+              old_pod_name,
+              propagationPolicy: 'Foreground'
+            )
+          rescue K8s::Error::NotFound
+            # Already deleted, continue
+          end
+
+          # Create new pod
+          create_worker_pod(worker.machine.config || default_machine_config)
+        end
+
+        private
+
+        # Find available workers (free and in ready state)
+        # @param namespace [String] Kubernetes namespace
+        # @return [Array<Worker>] Available workers
+        def find_available_workers(namespace)
+          # Find all pods for this project
+          pods = client.api('v1').resource('pods', namespace: namespace).list(
+            labelSelector: "brisk-project-id=#{project.id},brisk-role=worker"
+          )
+
+          # Get workers from database that are free
+          pod_uids = pods.map { |p| p.metadata.name }
+          machines = project.machines.where(provider: 'kubernetes', uid: pod_uids)
+
+          project.workers.free.not_stale.where(machine: machines).to_a
+        end
+
+        # Wait for pod to get an IP address
+        # @param namespace [String] Kubernetes namespace
+        # @param pod_name [String] Pod name
+        # @param timeout [Integer] Timeout in seconds
+        # @return [K8s::Resource] Pod with IP address
+        def wait_for_pod_ip(namespace, pod_name, timeout: 30)
+          deadline = Time.current + timeout
+
+          loop do
+            pod = client.api('v1').resource('pods', namespace: namespace).get(pod_name)
+
+            return pod if pod.status.podIP.present?
+
+            raise ::Providers::ProviderError, "Timeout waiting for pod IP: #{pod_name}" if Time.current > deadline
+
+            sleep 1
+          end
+        rescue K8s::Error::NotFound
+          raise ::Providers::ProviderError, "Pod not found: #{pod_name}"
+        end
+
+        # Build Kubernetes pod specification
+        # @param pod_name [String] Pod name
+        # @param machine_config [Hash] Machine configuration
+        # @return [Hash] Pod specification
+        def build_pod_spec(pod_name, machine_config)
+          namespace = project.provider_config['namespace'] || 'brisk-workers'
+
+          {
+            apiVersion: 'v1',
+            kind: 'Pod',
+            metadata: {
+              name: pod_name,
+              namespace: namespace,
+              labels: {
+                'brisk-project-id' => project.id.to_s,
+                'brisk-role' => 'worker',
+                'app' => 'brisk-worker'
+              },
+              annotations: {
+                'brisk.dev/project-name' => project.name,
+                'brisk.dev/created-at' => Time.current.iso8601
+              }
+            },
+            spec: {
+              restartPolicy: 'Never',
+              containers: [
+                {
+                  name: 'worker',
+                  image: project.image.url,
+                  imagePullPolicy: 'Always',
+                  env: build_env_vars,
+                  resources: build_resources(machine_config),
+                  ports: [
+                    { name: 'grpc', containerPort: 50_051, protocol: 'TCP' },
+                    { name: 'health', containerPort: 8081, protocol: 'TCP' }
+                  ],
+                  livenessProbe: {
+                    httpGet: { path: '/health', port: 8081 },
+                    initialDelaySeconds: 10,
+                    periodSeconds: 30
+                  },
+                  readinessProbe: {
+                    httpGet: { path: '/ready', port: 8081 },
+                    initialDelaySeconds: 5,
+                    periodSeconds: 10
+                  }
+                }
+              ],
+              # Optional: Use node selector for specific node pools
+              nodeSelector: machine_config[:node_selector] || {},
+              # Optional: Add tolerations for tainted nodes
+              tolerations: machine_config[:tolerations] || []
+            }
+          }
+        end
+
+        # Build environment variables for worker container
+        # @return [Array<Hash>] Environment variables
+        def build_env_vars
+          base_env = [
+            { name: 'BRISK_PROJECT_ID', value: project.id.to_s },
+            { name: 'BRISK_PROJECT_TOKEN', value: project.project_token },
+            { name: 'BRISK_API_ENDPOINT', value: ENV['BRISK_API_ENDPOINT'] || 'api.brisk.dev:443' },
+            { name: 'WORKER_CONCURRENCY', value: project.worker_concurrency.to_s }
+          ]
+
+          # Add custom environment variables from provider config
+          custom_env = project.provider_config.fetch('env', {}).map do |key, value|
+            { name: key.to_s, value: value.to_s }
+          end
+
+          base_env + custom_env
+        end
+
+        # Build resource requests and limits
+        # @param machine_config [Hash] Machine configuration
+        # @return [Hash] Resource specification
+        def build_resources(machine_config)
+          memory = machine_config[:memory_mb] || 4096
+          cpu = machine_config[:cpu_count] || 2
+
+          {
+            requests: {
+              memory: "#{memory}Mi",
+              cpu: cpu.to_s
+            },
+            limits: {
+              memory: "#{memory * 1.5}Mi", # Allow 50% burst
+              cpu: (cpu * 1.5).to_s
+            }
+          }
+        end
+
+        # Default machine configuration
+        # @return [Hash] Default configuration
+        def default_machine_config
+          {
+            memory_mb: 4096,
+            cpu_count: 2,
+            node_selector: {},
+            tolerations: []
+          }
+        end
+      end
+    end
+  end
+end

data/lib/brisk/providers/kubernetes/provider.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'k8s-ruby'
+
+module Brisk
+  module Providers
+    module Kubernetes
+      # Kubernetes provider for Brisk
+      # Manages workers as Kubernetes pods in a cluster
+      class Provider < ::Providers::BaseProvider
+        TRACER = defined?(MyAppTracer) ? MyAppTracer : nil
+
+        # Get workers for a project by finding available pods
+        # @param jobrun [Jobrun] The job run requesting workers
+        # @return [Array<Worker>] Array of allocated workers
+        def get_workers_for_project(jobrun)
+          workers_needed = project.worker_concurrency
+          Rails.logger.info "[K8s] Getting #{workers_needed} workers for jobrun #{jobrun.id}"
+
+          service = Brisk::Providers::Kubernetes::PodService.new(project, k8s_client)
+          service.get_workers_for_project(jobrun, workers_needed)
+        end
+
+        # Create a new worker pod
+        # @param machine_config [Hash] Machine configuration
+        # @return [Machine] The created machine record
+        def create_worker(machine_config)
+          validate_config!
+
+          Rails.logger.info "[K8s] Creating worker pod with config: #{machine_config}"
+
+          service = Brisk::Providers::Kubernetes::PodService.new(project, k8s_client)
+          service.create_worker_pod(machine_config)
+        rescue K8s::Error::API => e
+          raise ::Providers::ProviderError, "Failed to create Kubernetes pod: #{e.message}"
+        end
+
+        # Start a worker pod (scale from 0 or unpause)
+        # @param worker [Worker] The worker to start
+        def start_worker(worker)
+          Rails.logger.info "[K8s] Starting worker #{worker.id}"
+
+          pod_name = worker.machine.uid
+          namespace = k8s_namespace
+
+          # If pod is paused, resume it
+          # Otherwise, ensure it's running
+          client = k8s_client
+          pod = client.api('v1').resource('pods', namespace: namespace).get(pod_name)
+
+          unless pod.status.phase == 'Running'
+            # Restart pod by deleting and recreating
+            service = Brisk::Providers::Kubernetes::PodService.new(project, client)
+            service.restart_pod(worker)
+          end
+        rescue K8s::Error::NotFound
+          Rails.logger.warn "[K8s] Pod #{pod_name} not found, recreating"
+          create_worker(worker.machine.config)
+        rescue K8s::Error::API => e
+          raise ::Providers::ProviderError, "Failed to start pod: #{e.message}"
+        end
+
+        # Stop a worker pod (scale to 0 but preserve definition)
+        # @param worker [Worker] The worker to stop
+        def stop_worker(worker)
+          Rails.logger.info "[K8s] Stopping worker #{worker.id}"
+
+          pod_name = worker.machine.uid
+          namespace = k8s_namespace
+
+          # Delete the pod (deployment will handle recreation if needed)
+          client = k8s_client
+          client.api('v1').resource('pods', namespace: namespace).delete(pod_name, propagationPolicy: 'Foreground')
+
+          worker.machine.update(state: 'stopped')
+        rescue K8s::Error::NotFound
+          Rails.logger.warn "[K8s] Pod #{pod_name} already deleted"
+        rescue K8s::Error::API => e
+          raise ::Providers::ProviderError, "Failed to stop pod: #{e.message}"
+        end
+
+        # Suspend a worker pod (not supported, falls back to stop)
+        # @param worker [Worker] The worker to suspend
+        def suspend_worker(worker)
+          Rails.logger.info "[K8s] Suspending worker #{worker.id} (using stop)"
+          stop_worker(worker)
+        end
+
+        # Destroy a worker pod permanently
+        # @param worker [Worker] The worker to destroy
+        def destroy_worker(worker)
+          Rails.logger.info "[K8s] Destroying worker #{worker.id}"
+
+          pod_name = worker.machine.uid
+          namespace = k8s_namespace
+
+          client = k8s_client
+          client.api('v1').resource('pods', namespace: namespace).delete(
+            pod_name,
+            propagationPolicy: 'Foreground',
+            gracePeriodSeconds: 30
+          )
+
+          worker.machine.update(state: 'terminated', finished_at: Time.current)
+        rescue K8s::Error::NotFound
+          Rails.logger.warn "[K8s] Pod #{pod_name} already deleted"
+        rescue K8s::Error::API => e
+          Rails.logger.error "[K8s] Failed to destroy pod: #{e.message}"
+          # Continue even if deletion fails
+        end
+
+        # Reconcile workers - clean up orphaned pods
+        def reconcile_workers
+          Rails.logger.info "[K8s] Reconciling workers for project #{project.id}"
+
+          namespace = k8s_namespace
+          client = k8s_client
+
+          # Find all pods with project label
+          pods = client.api('v1').resource('pods', namespace: namespace).list(
+            labelSelector: "brisk-project-id=#{project.id},brisk-role=worker"
+          )
+
+          # Get all known machines
+          known_uids = project.machines.where(provider: 'kubernetes').pluck(:uid)
+
+          # Delete orphaned pods
+          orphaned = pods.reject { |pod| known_uids.include?(pod.metadata.name) }
+          orphaned.each do |pod|
+            Rails.logger.info "[K8s] Deleting orphaned pod: #{pod.metadata.name}"
+            client.api('v1').resource('pods', namespace: namespace).delete(
+              pod.metadata.name,
+              propagationPolicy: 'Background'
+            )
+          end
+
+          Rails.logger.info "[K8s] Reconciliation complete: #{orphaned.size} orphaned pods deleted"
+        rescue K8s::Error::API => e
+          Rails.logger.error "[K8s] Reconciliation failed: #{e.message}"
+        end
+
+        # Feature support
+        # @param feature [Symbol] Feature name
+        # @return [Boolean] Whether feature is supported
+        def supports?(feature)
+          # Can create pods on-demand and use HPA (Horizontal Pod Autoscaler)
+          %i[dynamic_creation auto_scale].include?(feature)
+        end
+
+        # Called after workers are allocated
+        # @param workers [Array<Worker>] Allocated workers
+        def after_worker_allocated(workers)
+          Rails.logger.debug "[K8s] #{workers.size} workers allocated, no balancing needed"
+          # Kubernetes handles scheduling and balancing
+        end
+
+        # Called after a worker is freed
+        # @param worker [Worker] The freed worker
+        def after_worker_freed(worker)
+          Rails.logger.info "[K8s] Scheduling cleanup for worker #{worker.id}"
+          # Schedule cleanup after a delay to allow for reuse
+          # CleanupKubernetesWorkerJob.set(wait: 5.minutes).perform_later(worker.id)
+
+          # For now, just log - pods will be cleaned up by reconciliation
+        end
+
+        # Should Brisk track health for this worker?
+        # Kubernetes manages pod health via liveness/readiness probes
+        # @param worker [Worker] The worker
+        # @return [Boolean] false - Kubernetes manages health
+        def should_track_health?(_worker)
+          false
+        end
+
+        # Register worker metadata when worker registers via gRPC
+        # @param worker [Worker] The worker
+        # @param params [Hash] Registration parameters
+        # @return [Hash] Metadata to set on worker
+        def register_worker_metadata(_worker, _params)
+          {
+            last_checked_at: 10.years.from_now # Kubernetes manages health
+          }
+        end
+
+        # Does this provider manage this machine?
+        # @param machine [Machine] The machine
+        # @return [Boolean] true if machine is a Kubernetes pod
+        def manages_machine?(machine)
+          machine.provider == 'kubernetes'
+        end
+
+        private
+
+        # Get Kubernetes client
+        # @return [K8s::Client] Kubernetes client
+        def k8s_client
+          @k8s_client ||= begin
+            config = k8s_config
+            K8s::Client.config(config)
+          end
+        end
+
+        # Get Kubernetes configuration
+        # @return [K8s::Config] Kubernetes configuration
+        def k8s_config
+          # Try in-cluster config first (for running inside Kubernetes)
+          if in_cluster?
+            K8s::Config.load_file('/var/run/secrets/kubernetes.io/serviceaccount/token')
+          else
+            # Use kubeconfig for local development
+            kubeconfig_path = ENV['KUBECONFIG'] || File.expand_path('~/.kube/config')
+            K8s::Config.load_file(kubeconfig_path)
+          end
+        rescue StandardError => e
+          raise ::Providers::ConfigurationError, "Failed to load Kubernetes config: #{e.message}"
+        end
+
+        # Check if running inside Kubernetes cluster
+        # @return [Boolean] true if running in-cluster
+        def in_cluster?
+          File.exist?('/var/run/secrets/kubernetes.io/serviceaccount/token')
+        end
+
+        # Get Kubernetes namespace for this project
+        # @return [String] Namespace name
+        def k8s_namespace
+          project.provider_config['namespace'] || ENV['K8S_NAMESPACE'] || 'brisk-workers'
+        end
+
+        # Validate provider configuration
+        # @raise [Providers::ConfigurationError] if configuration is invalid
+        def validate_config!
+          # Ensure namespace exists or can be created
+          namespace = k8s_namespace
+
+          raise ::Providers::ConfigurationError, 'Kubernetes namespace not configured' unless namespace.present?
+
+          # Validate image is configured
+          return if project.image&.url.present?
+
+          raise ::Providers::ConfigurationError, 'Worker image not configured'
+        end
+      end
+    end
+  end
+end

data/lib/brisk/providers/kubernetes/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Brisk
+  module Providers
+    module Kubernetes
+      VERSION = '1.0.0'
+    end
+  end
+end

data/lib/brisk-provider-kubernetes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'brisk/providers/kubernetes/version'
+require_relative 'brisk/providers/kubernetes/engine'
+require_relative 'brisk/providers/kubernetes/pod_service'
+require_relative 'brisk/providers/kubernetes/provider'

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: brisk-provider-kubernetes
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brisk Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: k8s-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Manage Brisk workers as Kubernetes pods in your cluster
+email:
+- support@brisk.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/brisk-provider-kubernetes.rb
+- lib/brisk/providers/kubernetes/engine.rb
+- lib/brisk/providers/kubernetes/pod_service.rb
+- lib/brisk/providers/kubernetes/provider.rb
+- lib/brisk/providers/kubernetes/version.rb
+homepage: https://github.com/brisktest/brisk-provider-kubernetes
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/brisktest/brisk-provider-kubernetes
+  source_code_uri: https://github.com/brisktest/brisk-provider-kubernetes
+  changelog_uri: https://github.com/brisktest/brisk-provider-kubernetes/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.brisk.dev/providers/kubernetes
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Kubernetes provider for Brisk CI
+test_files: []