---
title: "Named clusters — Kubernetes API for Laravel | Roundly"
description: "Configure clusters in config/kubernetes.php or register them in code, then resolve them anywhere by name — through the facade or dependency injection."
url: https://roundly-consulting.com/open-source/docs/kubernetes-api-for-laravel/named-clusters
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Kubernetes API for Laravel](https://roundly-consulting.com/open-source/docs/kubernetes-api-for-laravel.md)

# 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:

```php
// 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 = every KUBECONFIG file merged, or ~/.kube/config
        'context' => 'staging',        // null = current-context
        'manager' => 'shop-staging',   // no namespace: the context's, else default
    ],
    '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:

```php
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:

```php
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](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## 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](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/kubernetes-api-for-laravel.md)