Kubernetes Client Laravel Package

Technical Evaluation

Architecture fit

• The package is a standalone, framework-agnostic PHP client, not a Laravel package. There is no ServiceProvider, no facade, no config stub, and no publishable assets. Any Laravel adoption means we own a thin integration layer (provider + config + facade) ourselves — roughly half a day of work, but it becomes our code to maintain forever.
• Positive signal: src/Collection/ extends Illuminate collections and the README/AGENTS notes describe Illuminate as a dependency. That means the maintainer has already accepted Laravel's support library as a contract, and the ergonomics (collections of Pods, filtering, mapping) line up with how our developers already work.
• The design is conventional and legible: Client as entry point, RepositoryRegistry for $client->pods()-style accessors, Model/Attribute/Explorer for attribute traversal, Repository/Strategy/PatchMergeTrait for CRDs, PSR-18 HTTP client discovery across curl/socket/Guzzle7/Symfony adapters. Nothing exotic; a mid-level Laravel developer can read the source in an afternoon.
• The engineering discipline is unusually strong for a 3-star package: PHPStan at max level, PSR-12, dual PHPUnit + Behat suites, and a fake API server that records method, URI, headers and body so scenarios assert what was actually sent over the wire. That fake-cluster harness is directly reusable as a pattern for our own integration tests, and it is arguably the most valuable artifact in the repository.

Integration feasibility

• Hard gate: PHP 8.4+ required. Our Laravel baseline (11/12) runs happily on 8.2 and 8.3, and most of our fleet is there. This is not a soft constraint — Composer will refuse to install. Adopting this package forces a PHP 8.4 runtime upgrade on every service that touches it, which is a platform-level project, not a package decision.
• Secondary gate: no published version constraints we can inspect from the summary; we must verify the illuminate/collections constraint is compatible with our pinned Laravel major. A loose or over-tight constraint here can deadlock composer update across the monorepo.
• HTTP transport is the easy part. Laravel already ships Guzzle, so adding php-http/guzzle7-adapter satisfies discovery with no new egress or proxy behaviour — provided the package's HttpClientDiscovery respects our existing proxy/CA-bundle conventions rather than constructing its own.
• Authentication surface (kubeconfig loading, inline PEM material written to private temp files, Client::setTmpDir()) is where feasibility actually gets decided. This works on a VM; in our containerised, read-only-root-filesystem deployments it needs an explicit writable emptyDir and a cleanup story. Service-account token projection and short-lived tokens are the common case for us, and the summary does not establish support for kubeconfig exec credential plugins — a likely blocker if we target EKS/GKE/AKS.
• Build-vs-buy is genuinely open. The alternatives are: (a) the official generated kubernetes/php-client (OpenAPI-generated, broader resource coverage, historically stale); (b) shelling out to kubectl from queued jobs (zero code, terrible error handling, no typed responses); (c) running this package. Given 3 stars and 0 dependents, option (c) is the highest-uncertainty path and should be justified by a concrete requirement the other two can't meet — most plausibly CRD interaction via PatchMergeTrait, or a typed, testable object model inside a Laravel service class.

Technical risk

Key questions

1. Does Client support kubeconfig exec credential plugins and projected service-account tokens, or only static tokens and inline PEM? This single answer may decide the evaluation.
2. What is the exact illuminate/collections constraint, and is it satisfiable on our pinned Laravel major without a --with-all-dependencies cascade?
3. How does HttpClientDiscovery interact with HTTPS_PROXY, NO_PROXY and a custom CA bundle? Does it inherit our adapter configuration or override it?
4. What are the temp-file lifecycle and permissions precisely — mode bits, cleanup on fatal error, and behaviour when setTmpDir() is never called?
5. Is there a deprecation/support policy for Kubernetes API versions, and what is the maintainer's release cadence over the last 12 months?
6. Does the streaming parser handle watch connections (long-lived, chunked, reconnect), or only request/response?
7. Is there any concurrency/rate-limit awareness (429 + Retry-After) or retry policy, or is that entirely the caller's problem?
8. What is the realistic resource coverage — core, apps/v1, batch, networking, RBAC — and how are unknown/custom resources handled outside the CRD patch trait?

Integration Approach

Stack fit

• The package is a reasonable technical fit for a Laravel service that needs to read cluster state — dashboards, self-service portals, environment status panels, drift reports — and a weaker fit for writing (deploy, scale, delete), where idempotency, retries, and blast-radius control matter more than model ergonomics.
• Laravel's queue + scheduler model pairs naturally with poll-and-reconcile workloads ($client->pods() on a schedule, results into Eloquent, broadcast to the UI). This is the lowest-risk, highest-value first use case.
• The Illuminate collections dependency is a genuine fit advantage: results slot into existing collect() pipelines and Blade/Livewire views without an adapter layer.
• Poor fit for anything latency-critical or event-driven. This is a synchronous HTTP client; Kubernetes-native eventing belongs in an informer/controller (Go), not in PHP-FPM.

Migration path

1. Spike, isolated. A throwaway Laravel 12 app on PHP 8.4 against a local kind/k3d cluster. Validate the four unknowns: auth mode, proxy/CA behaviour, temp-dir handling under a read-only rootfs, and collection ergonomics.
2. Wrap, don't scatter. Create a single KubernetesServiceProvider binding a configured Client as a singleton, with config/kubernetes.php mapping kubeconfig path, context, tmp dir, timeouts and TLS material from environment/secret store. Expose a narrow ClusterReader interface; every controller and job depends on the interface, never on Teknoo\Kubernetes\Client. This is the single highest-leverage decision — it makes the eventual swap to the official client or kubectl a one-class change.
3. Read-only in production. Ship status/drift features only. No mutate verbs.
4. Write operations, gated. Feature flag, dedicated service account with least-privilege RBAC, dry-run first, and an audit record written to our own database before the API call.

Compatibility

• PHP 8.4 is the gating item and should be sequenced as its own platform workstream, not bundled into a feature. If 8.4 is 2+ quarters out, this evaluation effectively pauses.
• Pin the package exactly ("teknoo/kubernetes-client": "x.y.z"), not with a caret. With zero external dependents there is no ecosystem pressure to keep it stable, and the stated policy is that public API must not break — good, but unverified by third parties.
• Our Laravel HTTP client configuration (retries, timeouts, middleware) does not apply here, because the package resolves its own PSR-18 adapter. Timeouts and TLS must be configured through the package's own options. Expect this to surprise developers; document it.

Sequencing

Platform PHP 8.4 upgrade → vendor review (security policy, auth plugin support, release cadence) → isolated spike in kind → service provider + config + ClusterReader wrapper with contract tests against a fake API server modeled on the package's own Behat approach → read-only production feature → write operations behind flag with least-privilege RBAC.

The go/no-go sits between steps 2 and 3, and hinges entirely on exec-plugin/service-account auth and the PHP 8.4 timeline.

Operational Impact

Maintenance

• We inherit a low-traffic upstream. Realistically we should budget for owning the fork, not consuming the dependency: expect to carry patches for Kubernetes API deprecations and PHP minor releases ourselves. Budget ~1–2 engineer-days per quarter of steady-state attention, plus a spike whenever Kubernetes makes a breaking API removal.
• Our own integration layer (provider, config, ClusterReader) is a permanent line item. Small, but it is code we wrote and must maintain, and it does not exist as a community artifact we can hand off.
• Upside: with PHPStan max and a strict "no modifying existing tests" policy, upstream PRs should be easy to reason about if we ever do contribute back. Contributing a Laravel service provider upstream would be a cheap way to reduce our own surface area and buy goodwill with a single-maintainer project.

Support

• Effectively no support channel. No visible maintainer SLA, no commercial backing, no dependents to lean on for community answers. Escalation path is "read the source" or "read the Kubernetes API spec."
• Our on-call runbook must therefore be written by whoever does the spike, and must document the auth flow, the temp-file locations, and the exact adapter in use.
• Developer ramp-up is modest: the codebase is small and idiomatic. But the Kubernetes ramp-up is the real cost — RBAC, resource versions, patch semantics. Budget for one engineer to become the named owner; a shared-responsibility model here will produce incidents.

Scaling

• Scales as well as HTTP request/response does, which is to say: fine for polling a handful of resources per request, poor for cluster-wide listing at scale. Listing all pods across namespaces pulls the full response into memory via the model layer; on a large cluster this is a multi-megabyte PHP array. Enforce fieldSelector/labelSelector and namespace scoping in the wrapper.
• No watch/informer support means no efficient change detection. Polling intervals become the scaling dial, and aggressive polling against the API server is a real cost and a real 429 source.
• In Laravel, run this on the queue with bounded worker concurrency, never synchronously in a web request that a user is waiting on. Client as a singleton in an Octane worker should be validated for connection reuse and temp-file leakage across requests — this is a specific Octane risk given the temp-file ownership model.

Failure modes

Ramp-up

• Week 1: spike in kind, answer the eight key questions, produce a two-page findings note.
• Week 2: ClusterReader wrapper, service provider, contract tests against a fake API server.
• Week 3: first read-only feature behind a flag; runbook; named owner assigned.
• Write operations only after a full quarter of clean read-only operation and an explicit RBAC review.

Bottom line. Technically respectable, operationally fragile. The package is well-engineered for its size but carries the risk profile of a 3-star, zero-dependent, single-maintainer project — and it imposes a PHP 8.4 floor that likely exceeds our current platform baseline. I would fund a one-week spike only if a concrete requirement (CRD interaction or a typed object model inside Laravel) cannot be met by the official client or a kubectl-from-queue approach. Otherwise the disciplined answer is to defer, revisit when PHP 8.4 is our floor, and treat the fake-API-server test harness as the reusable takeaway in the meantime.