Merge pull request #275 from finos/feat/add-k8s-provider

feat(k8s): native Kubernetes provider with Pod, Deployment, StatefulSet, and Job handlers

Author: fgogolli

.github/workflows/ci-tests.yml

@@ -98,7 +98,7 @@ jobs:
   # Per-provider matrix. One job per provider subtree under
   # tests/providers/. New providers land here as new matrix entries —
   # no separate onmoto job needed (moto-mocked tests live under
-  # tests/providers/aws/moto and run as part of the aws entry).
+  # tests/providers/aws/mocked and run as part of the aws entry).
   providers-tests:
     name: Providers Tests
     needs: [config, setup-cache]

CHANGELOG.md

@@ -35,11 +35,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - New `[aws]` extra (alias for AWS deps currently in core). The canonical install
   command going forward is `pip install orb-py[aws]`. This continues to work
   unchanged when AWS deps move out of core in a future major version.
+- New `[k8s]` extra: modern first-class Kubernetes provider with Pod, Deployment, StatefulSet, and Job handlers, watch-based ingestion, startup reconciliation, and orphan garbage collection. Install with `pip install "orb-py[k8s]"`. See `docs/root/providers/kubernetes/index.md` for the full reference.
 - New `[all-providers]` meta-extra: pulls in all currently implemented providers.
 - New `[monitoring-aws]` extra: AWS-specific OpenTelemetry boto instrumentation (previously bundled inside `[monitoring]`).
 - New `[test-aws]` extra: moto + response-mocking deps for AWS test suites.
 - Architecture test `test_boto3_leak_detection.py`: asserts boto3/botocore are never imported outside `providers/aws/` except by guarded backward-compat shims.
 - Unit tests `test_no_provider_install.py`: verifies ORB core modules boot cleanly when AWS deps are absent.
+- Third-party provider plugin discovery via the `orb.providers` entry-point group. Plugins are loaded by `discover_provider_plugins()` after the built-in providers register; failures are logged and tolerated so a broken plugin cannot prevent ORB from starting. See `docs/root/providers/kubernetes/plugin-authoring.md` for the plugin contract and a worked Kubeflow MPIJob example.
+- `KubernetesProviderStrategy.register_handler` classmethod: plugin extension point for attaching a new `provider_api` handler to the Kubernetes provider without forking the strategy.
+- Kubernetes provider documentation under `docs/root/providers/kubernetes/`: overview, configuration reference, handlers guide, authentication guide, RBAC example, migration guide from `orb.k8s_legacy`, and plugin-authoring walkthrough.
 
 ### Changed
 

Makefile

@@ -6,6 +6,7 @@
 # Include all modular makefiles
 include makefiles/common.mk
 include makefiles/dev.mk
+include makefiles/providers.mk
 include makefiles/quality.mk
 include makefiles/ci.mk
 include makefiles/deploy.mk

README.md

@@ -36,7 +36,8 @@ Built for AWS today (EC2, Auto Scaling Groups, SpotFleet, EC2Fleet), with an ext
 
 **Provider support:**
 - **AWS** — EC2 RunInstances, EC2Fleet, SpotFleet, Auto Scaling Groups
-- **Custom** — extensible via [provider registry](docs/root/developer_guide/architecture.md)
+- **Kubernetes** — Pod, Deployment, StatefulSet, Job (`pip install "orb-py[k8s]"`; see [Kubernetes provider docs](docs/root/providers/k8s/index.md))
+- **Custom** — extensible via [provider registry](docs/root/developer_guide/architecture.md) and the [`orb.providers` entry-point group](docs/root/providers/k8s/plugin-authoring.md)
 
 **Scheduler support:**
 - **HostFactory** — runs as an [IBM Spectrum Symphony provider plugin](#hostfactory-integration)
@@ -96,6 +97,7 @@ will return a clear "no provider configured" error rather than an ImportError.
 
 ```bash
 pip install "orb-py[aws]"          # AWS provider (boto3 + botocore)
+pip install "orb-py[k8s]"   # Kubernetes provider (kubernetes SDK)
 pip install "orb-py[aws,cli]"      # AWS provider + colored CLI output
 pip install "orb-py[aws,api]"      # AWS provider + REST API server
 pip install "orb-py[monitoring-aws]"  # AWS provider + full monitoring stack
@@ -108,6 +110,8 @@ pip install "orb-py[all]"          # All providers + all features
 |----------|----------------|
 | Core only (no provider) | `pip install orb-py` |
 | AWS operator | `pip install "orb-py[aws]"` |
+| Kubernetes operator | `pip install "orb-py[k8s]"` |
+| AWS + Kubernetes | `pip install "orb-py[aws,k8s]"` |
 | AWS + colored CLI | `pip install "orb-py[aws,cli]"` |
 | AWS + REST API | `pip install "orb-py[aws,api]"` |
 | AWS + monitoring | `pip install "orb-py[monitoring-aws]"` |

config/aws_templates.json

@@ -18,7 +18,7 @@
       "name": "EC2 Fleet Instant On-Demand",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944146"
+      "createdAt": "2026-07-06T22:07:11.806716"
     },
     {
       "templateId": "EC2Fleet-Instant-Spot",
@@ -38,7 +38,7 @@
       "name": "EC2 Fleet Instant Spot",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944377"
+      "createdAt": "2026-07-06T22:07:11.806807"
     },
     {
       "templateId": "EC2Fleet-Instant-Mixed",
@@ -58,7 +58,7 @@
       "name": "EC2 Fleet Instant Mixed",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944400",
+      "createdAt": "2026-07-06T22:07:11.806823",
       "percentOnDemand": 30
     },
     {
@@ -78,7 +78,7 @@
       "name": "EC2 Fleet Request On-Demand",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944411"
+      "createdAt": "2026-07-06T22:07:11.806831"
     },
     {
       "templateId": "EC2Fleet-Request-Spot",
@@ -98,7 +98,7 @@
       "name": "EC2 Fleet Request Spot",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944421"
+      "createdAt": "2026-07-06T22:07:11.806839"
     },
     {
       "templateId": "EC2Fleet-Request-Mixed",
@@ -119,7 +119,7 @@
       "name": "EC2 Fleet Request Mixed",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944431",
+      "createdAt": "2026-07-06T22:07:11.806849",
       "percentOnDemand": 40,
       "allocationStrategyOnDemand": "lowestPrice"
     },
@@ -140,7 +140,7 @@
       "name": "EC2 Fleet Maintain On-Demand",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944439"
+      "createdAt": "2026-07-06T22:07:11.806857"
     },
     {
       "templateId": "EC2Fleet-Maintain-Spot",
@@ -160,7 +160,7 @@
       "name": "EC2 Fleet Maintain Spot",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944454"
+      "createdAt": "2026-07-06T22:07:11.806864"
     },
     {
       "templateId": "EC2Fleet-Maintain-Mixed",
@@ -181,7 +181,7 @@
       "name": "EC2 Fleet Maintain Mixed",
       "providerApi": "EC2Fleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944463",
+      "createdAt": "2026-07-06T22:07:11.806870",
       "percentOnDemand": 50,
       "allocationStrategyOnDemand": "prioritized"
     },
@@ -204,7 +204,7 @@
       "name": "Spot Fleet Request - Lowest Price",
       "providerApi": "SpotFleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944477"
+      "createdAt": "2026-07-06T22:07:11.806881"
     },
     {
       "templateId": "SpotFleet-Request-Diversified",
@@ -225,7 +225,7 @@
       "name": "Spot Fleet Request - Diversified",
       "providerApi": "SpotFleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944484"
+      "createdAt": "2026-07-06T22:07:11.806887"
     },
     {
       "templateId": "SpotFleet-Request-CapacityOptimized",
@@ -246,7 +246,7 @@
       "name": "Spot Fleet Request - Capacity Optimized",
       "providerApi": "SpotFleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944490"
+      "createdAt": "2026-07-06T22:07:11.806894"
     },
     {
       "templateId": "SpotFleet-Maintain-LowestPrice",
@@ -267,7 +267,7 @@
       "name": "Spot Fleet Maintain - Lowest Price",
       "providerApi": "SpotFleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944496"
+      "createdAt": "2026-07-06T22:07:11.806899"
     },
     {
       "templateId": "SpotFleet-Maintain-Diversified",
@@ -288,7 +288,7 @@
       "name": "Spot Fleet Maintain - Diversified",
       "providerApi": "SpotFleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944502"
+      "createdAt": "2026-07-06T22:07:11.806905"
     },
     {
       "templateId": "SpotFleet-Maintain-CapacityOptimized",
@@ -309,7 +309,7 @@
       "name": "Spot Fleet Maintain - Capacity Optimized",
       "providerApi": "SpotFleet",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944508"
+      "createdAt": "2026-07-06T22:07:11.806910"
     },
     {
       "templateId": "ASG-OnDemand",
@@ -327,7 +327,7 @@
       "name": "Auto Scaling Group On-Demand",
       "providerApi": "ASG",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944518"
+      "createdAt": "2026-07-06T22:07:11.806920"
     },
     {
       "templateId": "ASG-Spot",
@@ -346,7 +346,7 @@
       "name": "Auto Scaling Group Spot",
       "providerApi": "ASG",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944532"
+      "createdAt": "2026-07-06T22:07:11.806929"
     },
     {
       "templateId": "ASG-Mixed",
@@ -365,7 +365,7 @@
       "name": "Auto Scaling Group Mixed",
       "providerApi": "ASG",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944541",
+      "createdAt": "2026-07-06T22:07:11.806937",
       "percentOnDemand": 30
     },
     {
@@ -383,7 +383,7 @@
       "name": "Run Instances On-Demand",
       "providerApi": "RunInstances",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944549"
+      "createdAt": "2026-07-06T22:07:11.806944"
     },
     {
       "templateId": "RunInstances-Spot",
@@ -401,7 +401,7 @@
       "name": "Run Instances Spot",
       "providerApi": "RunInstances",
       "providerType": "aws",
-      "createdAt": "2026-06-24T12:58:15.944556"
+      "createdAt": "2026-07-06T22:07:11.806955"
     }
   ]
 }

config/k8s_templates.json

@@ -0,0 +1,49 @@
+{
+  "scheduler_type": "hostfactory",
+  "templates": [
+    {
+      "templateId": "k8s-pod-example",
+      "maxNumber": 1,
+      "imageId": "busybox:latest",
+      "priceType": "ondemand",
+      "allocationStrategy": "lowestPrice",
+      "name": "Kubernetes Pod example",
+      "providerApi": "Pod",
+      "providerType": "k8s",
+      "createdAt": "2026-07-06T22:07:11.808371"
+    },
+    {
+      "templateId": "k8s-deployment-example",
+      "maxNumber": 3,
+      "imageId": "busybox:latest",
+      "priceType": "ondemand",
+      "allocationStrategy": "lowestPrice",
+      "name": "Kubernetes Deployment example",
+      "providerApi": "Deployment",
+      "providerType": "k8s",
+      "createdAt": "2026-07-06T22:07:11.808407"
+    },
+    {
+      "templateId": "k8s-statefulset-example",
+      "maxNumber": 3,
+      "imageId": "busybox:latest",
+      "priceType": "ondemand",
+      "allocationStrategy": "lowestPrice",
+      "name": "Kubernetes StatefulSet example",
+      "providerApi": "StatefulSet",
+      "providerType": "k8s",
+      "createdAt": "2026-07-06T22:07:11.808466"
+    },
+    {
+      "templateId": "k8s-job-example",
+      "maxNumber": 3,
+      "imageId": "busybox:latest",
+      "priceType": "ondemand",
+      "allocationStrategy": "lowestPrice",
+      "name": "Kubernetes Job example",
+      "providerApi": "Job",
+      "providerType": "k8s",
+      "createdAt": "2026-07-06T22:07:11.808487"
+    }
+  ]
+}

docs/mkdocs.yml

@@ -164,6 +164,15 @@ nav:
       - Feature Mapping: hostfactory/feature_mapping.md
       - Deployment Scenarios: hostfactory/deployment_scenarios.md
       - Supported APIs: hostfactory/supported-apis.md
+  - Providers:
+    - Kubernetes:
+      - Overview: providers/k8s/index.md
+      - Infrastructure Discovery: providers/k8s/discovery.md
+      - Configuration: providers/k8s/configuration.md
+      - Handlers: providers/k8s/handlers.md
+      - Authentication: providers/k8s/auth.md
+      - Migrating from k8s-legacy: providers/k8s/migrating-from-k8s-legacy.md
+      - Plugin Authoring: providers/k8s/plugin-authoring.md
   - CLI Reference:
     - Overview: cli/README.md
     - Full CLI Reference: cli/cli-reference.md

docs/root/developer_guide/adding_a_provider.md

@@ -570,7 +570,7 @@ def pytest_collection_modifyitems(config, items):
 The AWS provider tests are the reference layout:
 
 - Unit tests: `tests/providers/aws/unit/`
-- Mocked integration tests: `tests/providers/aws/moto/`
+- Mocked integration tests: `tests/providers/aws/mocked/`
 - Real-AWS tests: `tests/providers/aws/live/`
 - Contract tests: `tests/providers/aws/contract/`