Merge pull request #93 from renoki-co/feature/custom-caller-for-pod-s…

…electors

[2.x] Custom Pods label selector from controllers

docs/kinds/DaemonSet.md

@@ -2,6 +2,7 @@
   - [Example](#example)
   - [Pod Template Retrieval](#pod-template-retrieval)
   - [Getting Pods](#getting-pods)
+    - [Custom Pod Labels](#custom-pod-labels)
   - [Scaling](#scaling)
   - [Daemon Set Status](#daemon-set-status)
 
@@ -55,6 +56,18 @@ $podName = $template['name'];
 
 ## Getting Pods
 
+To get the pods, the Pod template must have the `daemonset-name` label set. This way, the `labelSelector` API parameter is issued and you may retrieve the associated pods:
+
+```yaml
+metadata:
+  name: [here it goes the daemonset name]
+spec:
+  template:
+    metadata:
+      labels:
+        daemonset-name: [here it goes the daemonset name]
+```
+
 You can retrieve the pods as resources controlled by the Daemon Set by issuing `->getPods()`:
 
 ```php
@@ -63,6 +76,23 @@ foreach ($ds->getPods() as $pod) {
 }
 ```
 
+### Custom Pod Labels
+
+If you cannot declare the `daemonset-name` label or simply want to use something else, you may call `selectPods` from the resource:
+
+```php
+use RenokiCo\PhpK8s\Kinds\K8sDaemonSet;
+
+K8sDaemonSet::selectPods(function (K8sDaemonSet $ds) {
+    // $ds is the current DaemonSet
+
+    return [
+        'some-label' => 'some-label-value',
+        'some-other-label' => "{$ds->getName()}-custom-name",
+    ];
+});
+```
+
 ## Scaling
 
 The Scaling API is available via a `K8sScale` resource:

docs/kinds/Deployment.md

@@ -2,6 +2,7 @@
   - [Example](#example)
   - [Pod Template Retrieval](#pod-template-retrieval)
   - [Getting Pods](#getting-pods)
+    - [Custom Pod Labels](#custom-pod-labels)
   - [Scaling](#scaling)
   - [Deployment Status](#deployment-status)
 
@@ -55,6 +56,18 @@ $podName = $template['name'];
 
 ## Getting Pods
 
+To get the pods, the Pod template must have the `deployment-name` label set. This way, the `labelSelector` API parameter is issued and you may retrieve the associated pods:
+
+```yaml
+metadata:
+  name: [here it goes the deployment name]
+spec:
+  template:
+    metadata:
+      labels:
+        deployment-name: [here it goes the deployment name]
+```
+
 You can retrieve the pods as resources controlled by the Deployment by issuing `->getPods()`:
 
 ```php
@@ -63,6 +76,23 @@ foreach ($de->getPods() as $pod) {
 }
 ```
 
+### Custom Pod Labels
+
+If you cannot declare the `deployment-name` label or simply want to use something else, you may call `selectPods` from the resource:
+
+```php
+use RenokiCo\PhpK8s\Kinds\K8sDeployment;
+
+K8sDeployment::selectPods(function (K8sDeployment $dep) {
+    // $dep is the current Deployment
+
+    return [
+        'some-label' => 'some-label-value',
+        'some-other-label' => "{$dep->getName()}-custom-name",
+    ];
+});
+```
+
 ## Scaling
 
 The Scaling API is available via a `K8sScale` resource:

docs/kinds/Job.md

@@ -2,6 +2,7 @@
   - [Example](#example)
   - [Pod Template Retrieval](#pod-template-retrieval)
   - [Getting Pods](#getting-pods)
+    - [Custom Pod Labels](#custom-pod-labels)
   - [Job's Restart Policy](#jobs-restart-policy)
   - [Job Status](#job-status)
 
@@ -53,6 +54,18 @@ $podName = $template['name'];
 
 ## Getting Pods
 
+To get the pods, the Pod template must have the `job-name` label set. This way, the `labelSelector` API parameter is issued and you may retrieve the associated pods:
+
+```yaml
+metadata:
+  name: [here it goes the job name]
+spec:
+  template:
+    metadata:
+      labels:
+        job-name: [here it goes the job name]
+```
+
 You can retrieve the pods as resources controlled by the Job by issuing `->getPods()`:
 
 ```php
@@ -61,6 +74,23 @@ foreach ($job->getPods() as $pod) {
 }
 ```
 
+### Custom Pod Labels
+
+If you cannot declare the `job-name` label or simply want to use something else, you may call `selectPods` from the resource:
+
+```php
+use RenokiCo\PhpK8s\Kinds\K8sJob;
+
+K8sJob::selectPods(function (K8sJob $job) {
+    // $job is the current Job
+
+    return [
+        'some-label' => 'some-label-value',
+        'some-other-label' => "{$job->getName()}-custom-name",
+    ];
+});
+```
+
 ## Job's Restart Policy
 
 You might want to use `OnFailure` or `Never` as restart policies. These can be applied to the pod before passing it

docs/kinds/StatefulSet.md

@@ -2,6 +2,7 @@
   - [Example](#example)
   - [Pod Template Retrieval](#pod-template-retrieval)
   - [Getting Pods](#getting-pods)
+    - [Custom Pod Labels](#custom-pod-labels)
   - [Scaling](#scaling)
   - [StatefulSet Status](#statefulset-status)
 
@@ -68,6 +69,18 @@ $podName = $template['name'];
 
 ## Getting Pods
 
+To get the pods, the Pod template must have the `statefulset-name` label set. This way, the `labelSelector` API parameter is issued and you may retrieve the associated pods:
+
+```yaml
+metadata:
+  name: [here it goes the statefulset name]
+spec:
+  template:
+    metadata:
+      labels:
+        statefulset-name: [here it goes the statefulset name]
+```
+
 You can retrieve the pods as resources controlled by the Stateful Set by issuing `->getPods()`:
 
 ```php
@@ -76,6 +89,23 @@ foreach ($sts->getPods() as $pod) {
 }
 ```
 
+### Custom Pod Labels
+
+If you cannot declare the `statefulset-name` label or simply want to use something else, you may call `selectPods` from the resource:
+
+```php
+use RenokiCo\PhpK8s\Kinds\K8sStatefulSet;
+
+K8sStatefulSet::selectPods(function (K8sStatefulSet $sts) {
+    // $sts is the current StatefulSet
+
+    return [
+        'some-label' => 'some-label-value',
+        'some-other-label' => "{$sts->getName()}-custom-name",
+    ];
+});
+```
+
 ## Scaling
 
 The Scaling API is available via a `K8sScale` resource:

src/Kinds/K8sDaemonSet.php

@@ -16,7 +16,9 @@
 class K8sDaemonSet extends K8sResource implements InteractsWithK8sCluster, Podable, Watchable
 {
     use HasMinimumSurge;
-    use HasPods;
+    use HasPods {
+        podsSelector as protected customPodsSelector;
+    }
     use HasSelector;
     use HasSpec;
     use HasStatus;
@@ -67,6 +69,10 @@ public function setUpdateStrategy(string $strategy, int $maxUnavailable = 1)
      */
     public function podsSelector(): array
     {
+        if ($podsSelector = $this->customPodsSelector()) {
+            return $podsSelector;
+        }
+
         return [
             'daemonset-name' => $this->getName(),
         ];

src/Kinds/K8sDeployment.php

@@ -24,7 +24,9 @@ class K8sDeployment extends K8sResource implements
 {
     use CanScale;
     use HasMinimumSurge;
-    use HasPods;
+    use HasPods {
+        podsSelector as protected customPodsSelector;
+    }
     use HasReplicas;
     use HasSelector;
     use HasSpec;
@@ -78,6 +80,10 @@ public function setUpdateStrategy(string $strategy, $maxUnavailable = '25%', $ma
      */
     public function podsSelector(): array
     {
+        if ($podsSelector = $this->customPodsSelector()) {
+            return $podsSelector;
+        }
+
         return [
             'deployment-name' => $this->getName(),
         ];

src/Kinds/K8sJob.php

@@ -18,7 +18,9 @@ class K8sJob extends K8sResource implements
     Podable,
     Watchable
 {
-    use HasPods;
+    use HasPods {
+        podsSelector as protected customPodsSelector;
+    }
     use HasSelector;
     use HasSpec;
     use HasStatus;
@@ -64,6 +66,10 @@ public function setTTL(int $ttl = 100)
      */
     public function podsSelector(): array
     {
+        if ($podsSelector = $this->customPodsSelector()) {
+            return $podsSelector;
+        }
+
         return [
             'job-name' => $this->getName(),
         ];

src/Kinds/K8sStatefulSet.php

@@ -22,7 +22,9 @@ class K8sStatefulSet extends K8sResource implements
     Watchable
 {
     use CanScale;
-    use HasPods;
+    use HasPods {
+        podsSelector as protected customPodsSelector;
+    }
     use HasReplicas;
     use HasSelector;
     use HasSpec;
@@ -147,6 +149,10 @@ public function getVolumeClaims(bool $asInstance = true)
      */
     public function podsSelector(): array
     {
+        if ($podsSelector = $this->customPodsSelector()) {
+            return $podsSelector;
+        }
+
         return [
             'statefulset-name' => $this->getName(),
         ];

src/Traits/HasPods.php

@@ -2,8 +2,54 @@
 
 namespace RenokiCo\PhpK8s\Traits;
 
+use Closure;
+
 trait HasPods
 {
+    /**
+     * Custom closure to set a dynamic pod selector.
+     *
+     * @var Closure|null
+     */
+    protected static $podSelctorCallback;
+
+    /**
+     * Get the selector for the pods that are owned by this resource.
+     *
+     * @return array
+     */
+    public function podsSelector(): array
+    {
+        if ($callback = static::$podSelctorCallback) {
+            return $callback($this);
+        }
+
+        return [
+            //
+        ];
+    }
+
+    /**
+     * Reset the pods selector callback.
+     *
+     * @return void
+     */
+    public static function resetPodsSelector(): void
+    {
+        static::$podSelctorCallback = null;
+    }
+
+    /**
+     * Dynamically select the pods based on selectors.
+     *
+     * @param  Closure  $callback
+     * @return void
+     */
+    public static function selectPods(Closure $callback): void
+    {
+        static::$podSelctorCallback = $callback;
+    }
+
     /**
      * Get the pods owned by this resource.
      *

tests/DaemonSetTest.php

@@ -120,8 +120,18 @@ public function runCreationTests()
             sleep(1);
         }
 
+        K8sDaemonSet::selectPods(function ($ds) {
+            $this->assertInstanceOf(K8sDaemonSet::class, $ds);
+
+            return ['tier' => 'backend'];
+        });
+
         $pods = $ds->getPods();
+        $this->assertTrue($pods->count() > 0);
+
+        K8sDaemonSet::resetPodsSelector();
 
+        $pods = $ds->getPods();
         $this->assertTrue($pods->count() > 0);
 
         foreach ($pods as $pod) {

tests/DeploymentTest.php

@@ -130,8 +130,18 @@ public function runCreationTests()
             sleep(1);
         }
 
+        K8sDeployment::selectPods(function ($dep) {
+            $this->assertInstanceOf(K8sDeployment::class, $dep);
+
+            return ['tier' => 'backend'];
+        });
+
         $pods = $dep->getPods();
+        $this->assertTrue($pods->count() > 0);
+
+        K8sDeployment::resetPodsSelector();
 
+        $pods = $dep->getPods();
         $this->assertTrue($pods->count() > 0);
 
         foreach ($pods as $pod) {