Named clusters

Configure clusters under clusters in config/kubernetes.php — each entry takes its connection from a url, a kubeconfig context or the pod’s service account — and pick the default one with default:

// config/kubernetes.php
'default' => env('KUBERNETES_CLUSTER', 'default'),

'clusters' => [
    'default' => [
        'source' => 'url',
        'url' => env('KUBERNETES_URL'),
        'token' => env('KUBERNETES_TOKEN'),
        'ca_certificate' => env('KUBERNETES_CA_CERTIFICATE'),
        'namespace' => 'shop',
        'manager' => 'shop-production',
    ],
    'staging' => [
        'source' => 'kubeconfig',
        'kubeconfig' => null,          // null = KUBECONFIG or ~/.kube/config
        'context' => 'staging',        // null = current-context
        'manager' => 'shop-staging',
    ],
    'in-cluster' => [
        'source' => 'in-cluster',      // the pod's service account
    ],
],

Registering in code

Or register clusters in code, for example in a service provider’s boot() method. The closure receives a blank cluster and must return the configured one; it runs lazily, the first time the cluster is used:

use RoundlyConsulting\KubernetesApi\Cluster;
use RoundlyConsulting\KubernetesApi\Facades\Kubernetes;

// In a service provider's boot() — the closure must return the configured cluster
Kubernetes::registerCluster('production', fn (Cluster $cluster): Cluster => $cluster
    ->url('https://api.prod.example.com:6443')
    ->withToken(config('services.kubernetes.prod_token'))
    ->withCaCertificate('/path/to/ca.crt')
    ->withManagerName('shop-production'));

// Resolve it anywhere by name
$cluster = Kubernetes::cluster('production');

Kubernetes::hasCluster('production');   // true
Kubernetes::clusters();                 // ['default', 'production']

A cluster is resolved once and reused — clusters are immutable, so sharing one is safe.
A code registration overrides a configured cluster of the same name.
An unknown name throws ClusterNotFoundException. A closure that returns anything but a Cluster, or a config entry that isn’t an array, has an unknown source or a non-string setting, throws ClusterConfigurationException naming it. A blank setting is not set and takes its default.
Inject RoundlyConsulting\KubernetesApi\KubernetesManager for the same API without the facade: $kubernetes->cluster('production').

Registering from your own config

The closure is plain PHP, so you can drive registrations from your own config:

use RoundlyConsulting\KubernetesApi\Cluster;
use RoundlyConsulting\KubernetesApi\Facades\Kubernetes;

public function boot(): void
{
    // One entry per cluster in your own config/services.php
    foreach (config('services.kubernetes.clusters', []) as $name => $settings) {
        Kubernetes::registerCluster($name, fn (Cluster $cluster): Cluster => $cluster
            ->url($settings['url'])
            ->withToken($settings['token'])
            ->withCaCertificate($settings['ca'])
            ->withManagerName("shop-{$name}"));
    }
}

The client-side rate limiter keys its budget per apiserver — the cluster URL’s host, port and path prefix — so clusters never share a budget, even when they share a manager name (see Client-side rate limiting).

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages