# renoki-co/php-k8s architecture

> Architecture diagram of the GitHub repository renoki-co/php-k8s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/renoki-co/php-k8s
- Repository: https://github.com/renoki-co/php-k8s

## Overview

##### Project type and purpose
- This is an open-source PHP library (“php-k8s”) that implements a Kubernetes client.
- Purpose: allow any PHP application (including Laravel via an adapter) to authenticate to a Kube API server, use the exec/logs/watch APIs, and manage core & CRD resources via PHP objects.

##### File structure
- Top level:
- composer.json, PHP configuration (phpunit.xml, psalm.xml), CI/deploy configs (.github, .codecov).
- src/ directory – the heart of the client:
– Contracts/: interface definitions for capabilities (Attachable, Executable, Scalable, Watchable, etc.).
– Exceptions/: typed exceptions for errors coming from kubeconfig parsing, HTTP calls, streaming, etc.
– Instances/: building blocks for JSON payload objects (Container, Volume, Probe, ResourceObject, etc.).
– Kinds/: one-per-resource classes mapping to each K8s kind (Pod, Deployment, Service, CronJob, etc.).
– Traits/: mix-ins that implement common behavior (HasName, HasSpec, CanScale, LoadsFromKubeConfig, MakesHttpCalls).
– K8s.php, KubernetesCluster.php: entry points / façade. PhpK8sServiceProvider for Laravel DI. ResourcesList for discovery.
- tests/: comprehensive unit tests against YAML fixtures and fake kubeconfigs.

##### README for additional insights
- Confirms it’s a generic Kubernetes client (stable, supports v1.24–v1.26).
- Highlights exec API support, CRD extensibility, any authentication mode.
- Mentions optional Laravel package but core is framework-agnostic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
      KubeConfig["kubeconfig file"]:::external
      APIServer["Kubernetes API Server"]:::external
    end

    PHPApp["PHP Application"]:::external

    %% Service Provider & Entrypoints
    subgraph "Service Provider & Entrypoints"
      K8sFacade["K8s.php / Facade"]:::module
      ServiceProvider["PhpK8sServiceProvider"]:::module
      ResourcesList["ResourcesList"]:::module
    end

    %% Configuration & Authentication Module
    subgraph "Configuration & Authentication Module"
      LoadsCfg["LoadsFromKubeConfig"]:::module
      AuthCluster["AuthenticatesCluster"]:::module
      CheckVersion["ChecksClusterVersion"]:::module
      KubernetesCluster["KubernetesCluster"]:::module
    end

    %% HTTP/WebSocket Client Module
    subgraph "HTTP/WebSocket Client Module"
      MakesHTTP["MakesHttpCalls"]:::module
      MakesWS["MakesWebsocketCalls"]:::module
    end

    %% Resource Model Module
    subgraph "Resource Model Module"
      subgraph "Payload Builders (Instances)"
         Instance["Instance"]:::datamodel
         ResourceObject["ResourceObject"]:::datamodel
         Container["Container"]:::datamodel
      end
      subgraph "Typed Resource Classes (Kinds)"
         Pod["K8sPod"]:::datamodel
         Deployment["K8sDeployment"]:::datamodel
         Service["K8sService"]:::datamodel
      end
      subgraph "Resource Traits"
         HasName["HasName"]:::datamodel
         HasSpec["HasSpec"]:::datamodel
         CanScale["CanScale"]:::datamodel
         HasStatus["HasStatus"]:::datamodel
      end
      subgraph "Initialization Traits"
         InitInst["InitializesInstances"]:::datamodel
         InitRes["InitializesResources"]:::datamodel
      end
    end

    %% Error Handling Module
    subgraph "Error Handling Module"
      APIException["KubernetesAPIException"]:::module
      ExecException["KubernetesExecException"]:::module
      KubeCfgException["KubeConfigContextNotFound"]:::module
    end

    %% Connections
    PHPApp -->|"calls facade"| K8sFacade
    PHPApp -->|"via ServiceProvider"| ServiceProvider
    ServiceProvider -->|"binds"| K8sFacade
    K8sFacade -->|"load config"| LoadsCfg
    LoadsCfg -->|"reads"| KubeConfig
    LoadsCfg -->|"auth & check"| AuthCluster
    AuthCluster -->|"check version"| CheckVersion
    LoadsCfg -->|"create cluster"| KubernetesCluster
    KubernetesCluster -->|"uses"| MakesHTTP
    KubernetesCluster -->|"uses"| MakesWS
    MakesHTTP -->|"REST calls"| APIServer
    MakesWS -->|"WebSocket"| APIServer
    APIServer -->|"responses JSON"| ResourceObject
    ResourceObject -->|"builds"| Instance
    Instance -->|"maps to"| Pod
    Instance -->|"maps to"| Deployment
    Instance -->|"maps to"| Service
    Pod -->|"trait mix-in"| HasName
    Pod -->|"trait mix-in"| HasSpec
    Pod -->|"trait mix-in"| HasStatus
    Deployment -->|"trait mix-in"| CanScale
    Service -->|"trait mix-in"| HasName
    InitInst -->|"initialize"| Instance
    InitRes -->|"initialize"| Pod
    MakesHTTP -->|"throws"| APIException
    MakesWS -->|"throws"| ExecException
    LoadsCfg -->|"throws"| KubeCfgException
    APIException -->|"bubbled up"| PHPApp
    ExecException -->|"bubbled up"| PHPApp
    KubeCfgException -->|"bubbled up"| PHPApp

    %% Click Events
    click LoadsCfg "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Cluster/LoadsFromKubeConfig.php"
    click AuthCluster "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Cluster/AuthenticatesCluster.php"
    click CheckVersion "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Cluster/ChecksClusterVersion.php"
    click KubernetesCluster "https://github.com/renoki-co/php-k8s/blob/master/src/KubernetesCluster.php"
    click MakesHTTP "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Cluster/MakesHttpCalls.php"
    click MakesWS "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Cluster/MakesWebsocketCalls.php"
    click Instance "https://github.com/renoki-co/php-k8s/blob/master/src/Instances/Instance.php"
    click ResourceObject "https://github.com/renoki-co/php-k8s/blob/master/src/Instances/ResourceObject.php"
    click Container "https://github.com/renoki-co/php-k8s/blob/master/src/Instances/Container.php"
    click Pod "https://github.com/renoki-co/php-k8s/blob/master/src/Kinds/K8sPod.php"
    click Deployment "https://github.com/renoki-co/php-k8s/blob/master/src/Kinds/K8sDeployment.php"
    click Service "https://github.com/renoki-co/php-k8s/blob/master/src/Kinds/K8sService.php"
    click HasName "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Resource/HasName.php"
    click HasSpec "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Resource/HasSpec.php"
    click CanScale "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Resource/CanScale.php"
    click HasStatus "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/Resource/HasStatus.php"
    click InitInst "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/InitializesInstances.php"
    click InitRes "https://github.com/renoki-co/php-k8s/blob/master/src/Traits/InitializesResources.php"
    click APIException "https://github.com/renoki-co/php-k8s/blob/master/src/Exceptions/KubernetesAPIException.php"
    click ExecException "https://github.com/renoki-co/php-k8s/blob/master/src/Exceptions/KubernetesExecException.php"
    click KubeCfgException "https://github.com/renoki-co/php-k8s/blob/master/src/Exceptions/KubeConfigContextNotFound.php"
    click ServiceProvider "https://github.com/renoki-co/php-k8s/blob/master/src/PhpK8sServiceProvider.php"
    click K8sFacade "https://github.com/renoki-co/php-k8s/blob/master/src/K8s.php"
    click ResourcesList "https://github.com/renoki-co/php-k8s/blob/master/src/ResourcesList.php"

    %% Styles
    classDef module fill:#D6EAF8,stroke:#3498DB,stroke-width:1px
    classDef datamodel fill:#FAD7A0,stroke:#EB984E,stroke-width:1px
    classDef external fill:#A9DFBF,stroke:#27AE60,stroke-width:1px
```
