cloudnativephp / kubernetes
A Kubernetes client library for PHP.
Requires
- php: >=8.4
- guzzlehttp/guzzle: ^7.9
- symfony/property-access: ^7.3.0
- symfony/property-info: ^7.3.0
- symfony/serializer: ^7.3.0
- symfony/yaml: ^7.3.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.85.0
- pestphp/pest: ^3.8.0
- phpstan/phpstan: ^2.1.0
- symfony/var-dumper: ^7.3.0
- dev-main
- dev-dependabot/composer/friendsofphp/php-cs-fixer-3.87.2
- dev-dependabot/composer/friendsofphp/php-cs-fixer-3.87.1
- dev-dependabot/composer/symfony-9008902cbb
- dev-dependabot/composer/phpunit/php-code-coverage-11.0.11
- dev-dependabot/composer/phpstan/phpdoc-parser-2.3.0
- dev-dependabot/composer/nikic/php-parser-5.6.1
- dev-dependabot/composer/phpdocumentor/reflection-docblock-5.6.3
- dev-dependabot/composer/guzzle-8824a77580
- dev-dependabot/composer/react/promise-3.3.0
- dev-dependabot/composer/fidry/cpu-core-counter-1.3.0
- dev-dependabot/composer/pest-2c1595312e
- dev-dependabot/composer/composer/semver-3.4.4
This package is not auto-updated.
Last update: 2025-09-24 18:35:42 UTC
README
A modern, type-safe PHP client library for the Kubernetes API. Built with PHP 8.4+ and designed to provide an intuitive, object-oriented interface for managing Kubernetes resources - similar to Laravel's Eloquent ORM but specifically tailored for Kubernetes.
๐ Features
- ๐ Modern PHP 8.4+ - Leverages the latest PHP features including strict types
- ๐ Type-safe - Complete type hints and PHPStan Level 8 compliance
- ๐๏ธ Resource-oriented - Each Kubernetes resource is a dedicated PHP class
- ๐ฏ Comprehensive API Coverage - Supports all major Kubernetes API groups
- โก Fluent Interface - Chainable methods for elegant resource configuration
- ๐งช Battle-tested - 308+ tests with comprehensive coverage
- ๐ Fully Documented - Complete PHPDoc coverage with examples
- ๐ง Developer Experience - Includes formatting, linting, and static analysis tools
๐ Requirements
- PHP 8.4 or higher
- Composer for dependency management
- Kubernetes cluster (for actual API operations)
๐ฆ Installation
Install via Composer:
composer require cloudnativephp/kubernetes
๐ Quick Start
Basic Resource Creation
<?php use Kubernetes\API\Core\V1\Pod; use Kubernetes\API\Core\V1\Service; // Create a Pod $pod = new Pod(); $pod->setName('my-app') ->setNamespace('default') ->addLabel('app', 'my-app') ->addContainer([ 'name' => 'app', 'image' => 'nginx:latest', 'ports' => [['containerPort' => 80]] ]) ->setRestartPolicy('Always'); // Create a Service $service = new Service(); $service->setName('my-app-service') ->setNamespace('default') ->setType('ClusterIP') ->setSelectorMatchLabels(['app' => 'my-app']) ->addPort(80, 80, 'TCP');
Working with Deployments
use Kubernetes\API\Apps\V1\Deployment; $deployment = new Deployment(); $deployment->setName('web-app') ->setNamespace('production') ->setReplicas(3) ->setSelectorMatchLabels(['app' => 'web']) ->addContainer('web', 'nginx:1.21', [80]) ->setRollingUpdateStrategy(1, 1); // Convert to array for API submission $deploymentManifest = $deployment->toArray();
Configuration Management
use Kubernetes\API\Core\V1\ConfigMap; use Kubernetes\API\Core\V1\Secret; // Create ConfigMap $configMap = new ConfigMap(); $configMap->setName('app-config') ->setNamespace('default') ->setData([ 'database.host' => 'postgres.example.com', 'app.debug' => 'false' ]); // Create Secret $secret = new Secret(); $secret->setName('app-secrets') ->setNamespace('default') ->setType('Opaque') ->setData([ 'db-password' => base64_encode('super-secret'), 'api-key' => base64_encode('api-key-value') ]);
Persistent Storage
use Kubernetes\API\Apps\V1\StatefulSet; $statefulSet = new StatefulSet(); $statefulSet->setName('database') ->setNamespace('data') ->setReplicas(3) ->setServiceName('database-headless') ->setSelectorMatchLabels(['app' => 'postgres']) ->addPvcTemplate('data', 'ssd-storage', '100Gi', ['ReadWriteOnce']) ->setPodManagementPolicy('OrderedReady') ->setRollingUpdateStrategy(1);
Batch Jobs & Cron Jobs
use Kubernetes\API\Batch\V1\Job; use Kubernetes\API\Batch\V1\CronJob; // One-time Job $job = new Job(); $job->setName('data-migration') ->setNamespace('default') ->setCompletions(1) ->setParallelism(1) ->createPodTemplate('migrator:latest', ['migrate'], ['--all']); // Scheduled CronJob $cronJob = new CronJob(); $cronJob->setName('backup-job') ->setNamespace('backups') ->setDailySchedule(2, 0) // 2:00 AM daily ->forbidConcurrency() ->setHistoryLimits(7, 2) ->createSimpleJobTemplate('backup-tool:latest', ['backup.sh'], ['--full']);
๐ API Reference
Supported Kubernetes API Groups
API Group | Version | Resources | Status |
---|---|---|---|
core | v1 | Pod, Service, Secret, ConfigMap, PV, PVC, Namespace, Node, Event, Endpoints, LimitRange, ResourceQuota, ServiceAccount, ReplicationController | โ Complete |
apps | v1 | Deployment, StatefulSet, DaemonSet, ReplicaSet | โ Complete |
batch | v1 | Job, CronJob | โ Complete |
rbac.authorization.k8s.io | v1 | Role, RoleBinding, ClusterRole, ClusterRoleBinding | โ Complete |
networking.k8s.io | v1 | NetworkPolicy, Ingress, IngressClass | โ Complete |
Resource Categories
Core Workloads (core/v1)
Pod
- Basic compute unitsService
- Service discovery and load balancingReplicationController
- Legacy pod replication
Advanced Workloads (apps/v1)
Deployment
- Stateless application deploymentsStatefulSet
- Stateful applications with persistent storageDaemonSet
- Node-level system servicesReplicaSet
- Pod replication management
Configuration & Storage (core/v1)
ConfigMap
- Non-sensitive configuration dataSecret
- Sensitive information storagePersistentVolume
/PersistentVolumeClaim
- Storage managementLimitRange
/ResourceQuota
- Resource constraints
Batch Processing (batch/v1)
Job
- Run-to-completion workloadsCronJob
- Time-based scheduled jobs
Security & Access (rbac.authorization.k8s.io/v1)
Role
/ClusterRole
- Permission definitionsRoleBinding
/ClusterRoleBinding
- Permission assignments
Networking (networking.k8s.io/v1)
NetworkPolicy
- Network traffic rulesIngress
/IngressClass
- HTTP/HTTPS routing
๐๏ธ Advanced Usage
Method Chaining
All setter methods return self
for fluent interface support:
$deployment = new Deployment(); $result = $deployment ->setName('api-server') ->setNamespace('production') ->setReplicas(5) ->setSelectorMatchLabels(['app' => 'api']) ->addContainer('api', 'api-server:v1.2.3', [8080]) ->setResourceLimits(['memory' => '512Mi', 'cpu' => '500m']) ->setResourceRequests(['memory' => '256Mi', 'cpu' => '250m']); // $result === $deployment (true)
Helper Methods
Resources include convenience methods for common operations:
// DaemonSet node targeting $daemonSet = new DaemonSet(); $daemonSet->runOnAllNodes() // Includes master/control-plane tolerations ->setHostNetwork(true) // Access host networking ->setPrivileged(true); // Run with elevated privileges // StatefulSet scaling and storage $statefulSet = new StatefulSet(); $statefulSet->scale(5) // Set replica count ->addPvcTemplate('data', 'fast-ssd', '50Gi') // Add storage template ->setPodManagementPolicy('Parallel'); // Parallel startup // Service port management $service = new Service(); $service->addPort(80, 8080, 'TCP', 'http') // External:Internal:Protocol:Name ->addPort(443, 8443, 'TCP', 'https') ->setSessionAffinity('ClientIP');
Resource Conversion
Convert resources to/from arrays for API operations:
// To Array (for API submission) $podArray = $pod->toArray(); // From Array (from API response) $pod = Pod::fromArray($apiResponse); // JSON serialization $jsonManifest = json_encode($deployment->toArray(), JSON_PRETTY_PRINT);
๐ง Development Tools
This library includes comprehensive development tools:
# Run tests composer test # Static analysis (PHPStan Level 8) composer analyse # Code formatting (PSR-12) composer format # All quality checks composer test && composer analyse && composer format
๐ Examples
Complete Application Stack
use Kubernetes\API\Core\V1\{Namespace, Secret, ConfigMap, Service}; use Kubernetes\API\Apps\V1\Deployment; // Create namespace $namespace = new Namespace(); $namespace->setName('my-app'); // Application configuration $configMap = new ConfigMap(); $configMap->setName('app-config') ->setNamespace('my-app') ->setData([ 'REDIS_HOST' => 'redis.my-app.svc.cluster.local', 'LOG_LEVEL' => 'info' ]); // Application secrets $secret = new Secret(); $secret->setName('app-secrets') ->setNamespace('my-app') ->setStringData([ 'DB_PASSWORD' => 'secure-password', 'JWT_SECRET' => 'jwt-signing-key' ]); // Application deployment $deployment = new Deployment(); $deployment->setName('web-app') ->setNamespace('my-app') ->setReplicas(3) ->setSelectorMatchLabels(['app' => 'web']) ->addContainer('web', 'my-app:v1.0.0', [8080]) ->addEnvFromConfigMap('app-config') ->addEnvFromSecret('app-secrets'); // Load balancer service $service = new Service(); $service->setName('web-service') ->setNamespace('my-app') ->setType('LoadBalancer') ->setSelectorMatchLabels(['app' => 'web']) ->addPort(80, 8080);
Database with Persistent Storage
use Kubernetes\API\Core\V1\{Secret, Service}; use Kubernetes\API\Apps\V1\StatefulSet; // Database credentials $dbSecret = new Secret(); $dbSecret->setName('postgres-credentials') ->setNamespace('database') ->setStringData([ 'POSTGRES_USER' => 'admin', 'POSTGRES_PASSWORD' => 'secure-db-password', 'POSTGRES_DB' => 'application' ]); // Headless service for StatefulSet $headlessService = new Service(); $headlessService->setName('postgres-headless') ->setNamespace('database') ->setType('ClusterIP') ->setClusterIp('None') // Headless ->setSelectorMatchLabels(['app' => 'postgres']) ->addPort(5432, 5432); // PostgreSQL StatefulSet $postgres = new StatefulSet(); $postgres->setName('postgres') ->setNamespace('database') ->setReplicas(1) ->setServiceName('postgres-headless') ->setSelectorMatchLabels(['app' => 'postgres']) ->addContainer('postgres', 'postgres:15', [5432]) ->addEnvFromSecret('postgres-credentials') ->addPvcTemplate('data', 'ssd-storage', '20Gi') ->setPodManagementPolicy('OrderedReady');
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
- Clone the repository
- Install dependencies:
composer install
- Run tests:
composer test
- Run static analysis:
composer analyse
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Links
๐ Acknowledgments
- Inspired by Laravel's Eloquent ORM patterns
- Built for the Kubernetes community
- Follows Kubernetes API conventions and best practices
Ready to modernize your Kubernetes PHP applications? Start with composer require cloudnativephp/kubernetes
and experience type-safe Kubernetes resource management!