K8S Framework Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dealroadshow/k8s-framework
   

   Add the service provider to config/app.php:

   Dealroadshow\K8sFramework\K8sFrameworkServiceProvider::class,
   

2. First Manifest Define a basic Kubernetes resource in PHP (e.g., app/Kubernetes/Deployment.php):

   <?php
   namespace App\Kubernetes;
   
   use Dealroadshow\K8sFramework\Manifest;
   
   class Deployment extends Manifest
   {
       public function getMetadata(): array
       {
           return [
               'name' => 'my-app',
               'namespace' => 'default',
           ];
       }
   
       public function getSpec(): array
       {
           return [
               'containers' => [
                   [
                       'name' => 'app',
                       'image' => 'nginx:latest',
                   ],
               ],
           ];
       }
   }
   

3. Generate YAML Use the CLI command to render the manifest:

   php artisan k8s:render App\Kubernetes\Deployment
   

   Outputs YAML to storage/app/k8s/.

First Use Case: Deploying a Service

1. Define a Service Manifest

   class Service extends Manifest
   {
       public function getMetadata(): array
       {
           return [
               'name' => 'my-service',
               'namespace' => 'default',
               'labels' => ['app' => 'my-app'],
           ];
       }
   
       public function getSpec(): array
       {
           return [
               'selector' => ['app' => 'my-app'],
               'ports' => [
                   ['port' => 80, 'targetPort' => 8080],
               ],
           ];
       }
   }
   

2. Apply to Cluster Use the k8s:apply command:

   php artisan k8s:apply App\Kubernetes\Service
   

Implementation Patterns

Workflow: CI/CD Integration

1. Dynamic Manifests Use environment variables or config files to parameterize manifests:

   public function getSpec(): array
   {
       return [
           'containers' => [
               [
                   'name' => 'app',
                   'image' => env('APP_IMAGE', 'nginx:latest'),
                   'env' => [
                       ['name' => 'ENVIRONMENT', 'value' => env('APP_ENV')],
                   ],
               ],
           ],
       ];
   }
   

2. Helm-like Templating Combine multiple manifests into a "release":

   class Release
   {
       public function getManifests(): array
       {
           return [
               new Deployment(),
               new Service(),
               new Ingress(),
           ];
       }
   }
   

   Render all manifests at once:

   php artisan k8s:render Release --all
   

Integration Tips

1. Validation Use Laravel’s validation rules to enforce Kubernetes constraints:

   use Illuminate\Support\Facades\Validator;
   
   public function getSpec(): array
   {
       $spec = [
           'containers' => [
               ['name' => 'app', 'image' => 'nginx:latest'],
           ],
       ];
   
       Validator::make($spec, [
           'containers.*.image' => 'required|string',
       ])->validate();
   
       return $spec;
   }
   

2. Namespaces Dynamically set namespaces based on environment:

   public function getMetadata(): array
   {
       return [
           'namespace' => env('K8S_NAMESPACE', 'default'),
       ];
   }
   

3. Secrets and ConfigMaps Load secrets from Laravel’s .env or encrypted storage:

   public function getSpec(): array
   {
       return [
           'envFrom' => [
               ['secretRef' => ['name' => env('SECRET_NAME')]],
           ],
       ];
   }
   

Gotchas and Tips

Pitfalls

1. YAML Formatting

   • The package renders PHP arrays to YAML. Ensure arrays are properly structured to avoid syntax errors:

     // Bad: Missing key for array item
     'ports' => [['port' => 80]], // Missing 'targetPort'
     
     // Good
     'ports' => [['port' => 80, 'targetPort' => 8080]],
     

2. Namespace Conflicts

   • If multiple manifests define the same resource (e.g., Deployment), the last one rendered will overwrite previous ones. Use unique names or labels to avoid clashes.

3. Kubernetes API Limits

   • Large manifests may hit Kubernetes API size limits. Split manifests into smaller chunks or use kubectl’s --dry-run=client for validation.

Debugging

1. Dry Runs Use the --dry-run flag to preview changes without applying:

   php artisan k8s:apply App\Kubernetes\Deployment --dry-run
   

2. Logging Enable debug mode in config/k8s-framework.php:

   'debug' => env('APP_DEBUG', false),
   

   Logs will appear in storage/logs/k8s-framework.log.

3. Manifest Validation Validate manifests against the Kubernetes schema using a tool like kubeval in your CI pipeline.

Extension Points

1. Custom Resource Definitions (CRDs) Extend the Manifest class to support custom resources:

   class CustomResource extends Manifest
   {
       protected $kind = 'MyCustomResource'; // Override default 'Deployment'
       protected $apiVersion = 'mygroup.example/v1';
   
       // ...
   }
   

2. Pre/Post Hooks Add lifecycle hooks for pre-rendering or post-apply actions:

   class Deployment extends Manifest
   {
       public function onBeforeRender()
       {
           // Modify spec before rendering
           $this->spec['replicas'] = env('REPLICAS', 1);
       }
   
       public function onAfterApply()
       {
           // Log or trigger side effects
           \Log::info('Deployment applied: ' . $this->metadata['name']);
       }
   }
   

3. Plugin System Register custom plugins for additional functionality (e.g., Helm chart integration):

   // In a service provider
   $this->app->make('k8s-framework')->extend(function ($framework) {
       $framework->addPlugin(new HelmPlugin());
   });