CRUD operations

Operations use Laravel’s HTTP client and return resource objects hydrated from the apiserver’s response — find() returns the resource, get() a ResourcesCollection (a Laravel Collection):

use RoundlyConsulting\KubernetesApi\Facades\Kubernetes;

$cluster = Kubernetes::cluster('production');

// List — a ResourcesCollection of Deployment resources
$cluster->deployments()->setNamespace('shop')->get();

// Find a single deployment — returns a Deployment resource
$cluster->deployments()->setNamespace('shop')->withName('checkout')->find();

// Check existence — a 404 becomes false, any other error still throws
$cluster->deployments()->setNamespace('shop')->withName('checkout')->existsOnCluster();
$cluster->deployments()->setNamespace('shop')->withName('checkout')->missingOnCluster();

// Create a deployment
$template = [
    'metadata' => ['labels' => ['app' => 'checkout']],
    'spec' => ['containers' => [['name' => 'app', 'image' => 'registry.example.com/checkout:v1.4.0']]],
];

$deployment = $cluster->deployments()
    ->setNamespace('shop')
    ->setName('checkout')
    ->setLabels(['app' => 'checkout'])
    ->setReplicas(3)
    ->setPodsSelectors(['app' => 'checkout'])
    ->setSpec('template', $template)
    ->create();

$deployment->wasRecentlyCreated(); // true
$deployment->exists();             // true

// Update — read, modify, write back
$cluster->deployments()
    ->setNamespace('shop')
    ->withName('checkout')
    ->find()
    ->setReplicas(5)
    ->update();

// Update if it exists, otherwise create it — send the complete desired object
$cluster->deployments()
    ->setNamespace('shop')
    ->setName('checkout')
    ->setReplicas(2)
    ->setPodsSelectors(['app' => 'checkout'])
    ->setSpec('template', $template)
    ->updateOrCreate();

// Delete a deployment
$deleted = $cluster->deployments()->setNamespace('shop')->withName('checkout')->delete();
$deleted->exists(); // false

How writes behave

create() POSTs the object; the returned resource reports wasRecentlyCreated() and exists(). For apps/v1 workloads the apiserver requires a pod selector and a pod template whose labels match it.
update() PUTs the whole object — read it with find() first, so the payload carries the current resourceVersion and every field you didn’t change.
updateOrCreate() finds the resource and creates it on a 404. Otherwise it copies the server’s current resourceVersion into your object and PUTs it, so a concurrent change surfaces as a typed 409 conflict instead of being silently clobbered. The PUT replaces the object — build the complete desired state, and use patch() for partial changes.
delete() sends DeleteOptions with Foreground propagation by default and returns a resource whose exists() is false.
existsOnCluster() and missingOnCluster() turn a 404 into a boolean; any other error still throws.

Query parameters and delete options

Every operation takes an optional query array — ['pretty' => 1] by default — appended to the request, so any apiserver query parameter is one argument away. delete() also accepts a Type carrying the DeleteOptions body:

use RoundlyConsulting\KubernetesApi\Resources\Types\Type;

// Background cascading instead of the default Foreground
$cluster->deployments()->setNamespace('shop')->withName('checkout')
    ->delete(options: Type::make()->setPropagationPolicy('Background'));

// Any apiserver query parameter — here gracePeriodSeconds
$cluster->pods()->setNamespace('shop')->withName('checkout-5f7c9d8b6-x2kqj')
    ->delete(['gracePeriodSeconds' => 0]);

withName() is an alias of setName(): any with…() call is forwarded to the matching set…() method, so both read naturally in a chain.

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