Merge pull request #56 from renoki-co/feature/affinity

[feature] Pod & Node Affinity

Author: rennokki

README.md

@@ -73,6 +73,7 @@ This package is Work in Progress and while there is in active development, PRs a
 
 Each existent resource has its own documentation, filled with examples:
 
+- [Nodes](docs/kinds/Node.md)
 - [Namespaces](docs/kinds/Namespace.md)
 - [Config Maps](docs/kinds/ConfigMap.md)
 - [Secrets](docs/kinds/Secret.md)

docs/RESOURCES.md

@@ -10,8 +10,10 @@
 
 Instances are custom classes that makes the build of containers, for example, more object-oriented that passing an array.
 
+- [Affinity](instances/Affinity.md) - used to declare affinities and anti-affinities
 - [Container](instances/Container.md) - used for Pods & Templates
 - [Container Probes](instances/Probes.md) - used for Pods' Probes
+- [Expressions](instances/Expression.md) - used for various match/fields expressions
 - [Resource Metrics](instances/Metrics.md) - used for Horizontal Pod Autoscalers
 - [Rules](instances/Rules.md) - used for Roles & Cluster Roles
 - [Volumes](instances/Volumes.md) - used for mounting volumes in pods and containers
@@ -22,6 +24,7 @@ Each resource inherits a default "base" class that is making the Resource build-
 
 **Check the documentation for [General Resources](kinds/Resource.md) and [K8s API Usage](Usage.md) before diving in to the actual resources documentation.**
 
+- [Nodes](kinds/Node.md)
 - [Namespaces](kinds/Namespace.md)
 - [Config Maps](kinds/ConfigMap.md)
 - [Secrets](kinds/Secret.md)
@@ -60,11 +63,6 @@ The following list of resources are work in progress and they will be available
 - poddisruptionbudgets
 - podsecuritypolicies
 
-The following concepts are work in progress as instances:
-
-- pod affinity
-- node affinity
-
 # Discussable
 
 The following list of resources might not be useful for the basic needs, so they will be gladly accepted via PR in case there is a need of the resources or they might get discussed and implemented after further reasearch on the structure of the resource.

docs/instances/Affinity.md

@@ -0,0 +1,43 @@
+# Affinity
+
+Affinities work with the help of [Expressions](Expression.md) to specify inclusions and exclusions for particular needs.
+
+## preferredDuringSchedulingIgnoredDuringExecution
+
+`preferredDuringSchedulingIgnoredDuringExecution` option is exposed in the affinity instance as `addPreference`:
+
+```php
+use RenokiCo\PhpK8s\K8s;
+
+$az = K8s::expression()->in('azname', ['us-east-1a', 'us-east-1b']);
+$tier = K8s::expression()->in('tier', ['backend']);
+
+$affinity = K8s::affinity()->addPreference([$az], [], 100); // weight: 100
+```
+
+For `nodeSelectorTerms`, you can use `addNodeSelectorPreference()` with the same parameters.
+
+## requiredDuringSchedulingIgnoredDuringExecution
+
+`requiredDuringSchedulingIgnoredDuringExecution` option is exposed in the affinity instance as `addNodeRequirement`:
+
+```php
+use RenokiCo\PhpK8s\K8s;
+
+$az = K8s::expression()->in('azname', ['us-east-1a', 'us-east-1b']);
+$tier = K8s::expression()->in('tier', ['backend']);
+
+$affinity = K8s::affinity()->addNodeRequirement([$az], [$type]); // requires AZ and tier: backend
+```
+
+For Label Selector requirement, use `addLabelSelectorRequirement`:
+
+```php
+use RenokiCo\PhpK8s\K8s;
+
+$az = K8s::expression()->in('azname', ['us-east-1a', 'us-east-1b']);
+$tier = K8s::expression()->in('tier', ['backend']);
+
+// requires AZ and tier: backend with given topology
+$affinity = K8s::affinity()->addLabelSelectorRequirement([$az], [$type], 'aws.amazonaws.io/some-topology');
+```

docs/instances/Expression.md

@@ -0,0 +1,31 @@
+# Expression
+
+## In & Not In
+
+```php
+use RenokiCo\PhpK8s\K8s;
+
+K8s::expression()->in('some-key', ['value1', 'value2']);
+
+K8s::expression()->notIn('some-key', ['value1', 'value2']);
+```
+
+## Exists & Does Not Exist
+
+```php
+use RenokiCo\PhpK8s\K8s;
+
+K8s::expression()->exists('some-key');
+
+K8s::expression()->doesNotexist('some-key');
+```
+
+## Greater & Less Than
+
+```php
+use RenokiCo\PhpK8s\K8s;
+
+K8s::expression()->greaterThan('some-key', '1');
+
+K8s::expression()->lessThan('some-key', '1');
+```

docs/kinds/Node.md

@@ -0,0 +1,19 @@
+# Node
+
+- [Official Documentation](https://kubernetes.io/docs/concepts/architecture/nodes/)
+
+## Example
+
+```php
+$nodes = K8s::node()->all();
+
+foreach ($nodes as $node) {
+    $node->getInfo();
+
+    $node->getImages();
+
+    $node->getCapacity();
+
+    $node->getAllocatableInfo();
+}
+```

docs/kinds/Pod.md

@@ -35,6 +35,17 @@ $pod = $cluster->pod()
 
 Pods can attach volumes so that container can mount them. Please check the [Container documentation](../instances/Container.md) where you can find details on how to attach volumes for different drivers.
 
+## Attaching affinities & anti-affinities
+
+Pods can declare `affinity` to handle pod and node affinities and anti-affinities. Check [Affinity documentation](../instances/Affinity.md) to read more about the pod affinity and anti-affinity declarations.
+
+You can simply attach affinities for both pod and node by calling specialized methods:
+
+```php
+$pod->setPodAffinity($affinity);
+$pod->setNodeAffinity($affinity);
+```
+
 ## Container Retrieval
 
 Retrieving the containers and init containers can be retrieved as an array of `\RenokiCo\PhpK8s\Instances\Container` classes or as an array.
@@ -59,9 +70,7 @@ foreach ($containers as $container) {
 
 ## Pod Logs
 
-Pods can contain logs, and PHP K8s is good at it. Before checking how it works, please see the [Live Tracking](../../README.md#live-tracking) section from README to see how the closures really work at interpreting the real-time data in Kubernetes.
-
-Retrieve a single string with all logs until the point of call:
+Pods can contain logs, and PHP K8s is good at it. You can retrieve a single string with all logs until the point of call:
 
 ```php
 // Simple logging, no watcher

src/Instances/Affinity.php

@@ -8,33 +8,82 @@ class Affinity extends Instance
      * Add a preference affinity.
      *
      * @param  array  $expressions
+     * @param  array  $fieldsExpressions
      * @param  int  $weight
      * @return $this
      */
-    public function addPreference(array $expressions, int $weight = 1)
+    public function addPreference(array $expressions, array $fieldsExpressions, int $weight = 1)
     {
         foreach ($expressions as &$expression) {
             if ($expression instanceof Expression) {
                 $expression = $expression->toArray();
             }
         }
 
+        foreach ($fieldsExpressions as &$expression) {
+            if ($expression instanceof Expression) {
+                $expression = $expression->toArray();
+            }
+        }
+
+        $preference = [
+            'matchExpressions' => $expressions,
+        ];
+
+        if ($fieldsExpressions) {
+            $preference['matchFields'] = $fieldsExpressions;
+        }
+
         return $this->addToAttribute('preferredDuringSchedulingIgnoredDuringExecution', [
             'weight' => $weight,
-            'preference' => [
-                'matchExpressions' => $expressions,
-            ],
+            'preference' => $preference,
+        ]);
+    }
+
+    /**
+     * Add a preference affinity for nodeSelector.
+     *
+     * @param  array  $expressions
+     * @param  array  $fieldsExpressions
+     * @param  int  $weight
+     * @return $this
+     */
+    public function addNodeSelectorPreference(array $expressions, array $fieldsExpressions, int $weight = 1)
+    {
+        foreach ($expressions as &$expression) {
+            if ($expression instanceof Expression) {
+                $expression = $expression->toArray();
+            }
+        }
+
+        foreach ($fieldsExpressions as &$expression) {
+            if ($expression instanceof Expression) {
+                $expression = $expression->toArray();
+            }
+        }
+
+        $preference = [
+            'matchExpressions' => $expressions,
+        ];
+
+        if ($fieldsExpressions) {
+            $preference['matchFields'] = $fieldsExpressions;
+        }
+
+        return $this->addToAttribute('preferredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms', [
+            'weight' => $weight,
+            'preference' => $preference,
         ]);
     }
 
     /**
-     * Add a required affinity.
+     * Add a required affinity for nodeSelector.
      *
      * @param  array  $expressions
      * @param  array  $fieldsExpressions
      * @return $this
      */
-    public function addRequire(array $expressions, array $fieldsExpressions)
+    public function addNodeRequirement(array $expressions, array $fieldsExpressions)
     {
         foreach ($expressions as &$expression) {
             if ($expression instanceof Expression) {
@@ -48,10 +97,50 @@ public function addRequire(array $expressions, array $fieldsExpressions)
             }
         }
 
+        $requirement = [
+            'matchExpressions' => $expressions,
+        ];
+
         if ($fieldsExpressions) {
-            $this->addToAttribute('requiredDuringSchedulingIgnoredDuringExecution.matchFields', $fieldsExpressions);
+            $requirement['matchFields'] = $fieldsExpressions;
         }
 
-        return $this->addToAttribute('requiredDuringSchedulingIgnoredDuringExecution.matchExpressions', $expressions);
+        return $this->addToAttribute('requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms', $requirement);
+    }
+
+    /**
+     * Add a required affinity for nodeSelector.
+     *
+     * @param  array  $expressions
+     * @param  array  $fieldsExpressions
+     * @param  string  $topologyKey
+     * @return $this
+     */
+    public function addLabelSelectorRequirement(array $expressions, array $fieldsExpressions, string $topologyKey)
+    {
+        foreach ($expressions as &$expression) {
+            if ($expression instanceof Expression) {
+                $expression = $expression->toArray();
+            }
+        }
+
+        foreach ($fieldsExpressions as &$expression) {
+            if ($expression instanceof Expression) {
+                $expression = $expression->toArray();
+            }
+        }
+
+        $requirement = [
+            'matchExpressions' => $expressions,
+        ];
+
+        if ($fieldsExpressions) {
+            $requirement['matchFields'] = $fieldsExpressions;
+        }
+
+        return $this->addToAttribute('requiredDuringSchedulingIgnoredDuringExecution', [
+            'labelSelector' => $requirement,
+            'topologyKey' => $topologyKey,
+        ]);
     }
 }

src/K8s.php

@@ -4,6 +4,18 @@
 
 class K8s
 {
+    /**
+     * Create a new Node kind.
+     *
+     * @param  \RenokiCo\PhpK8s\KubernetesCluster|null  $cluster
+     * @param  array  $attributes
+     * @return \RenokiCo\PhpK8s\Kinds\K8sNode
+     */
+    public static function node($cluster = null, array $attributes = [])
+    {
+        return new Kinds\K8sNode($cluster, $attributes);
+    }
+
     /**
      * Create a new Namespace kind.
      *
@@ -321,6 +333,28 @@ public static function volume(array $attributes = [])
         return new Instances\Volume($attributes);
     }
 
+    /**
+     * Create a new affinity instance.
+     *
+     * @param  array  $attributes
+     * @return \RenokiCo\PhpK8s\Instances\Affinity
+     */
+    public static function affinity(array $attributes = [])
+    {
+        return new Instances\Affinity($attributes);
+    }
+
+    /**
+     * Create a new expression instance.
+     *
+     * @param  array  $attributes
+     * @return \RenokiCo\PhpK8s\Instances\Expression
+     */
+    public static function expression(array $attributes = [])
+    {
+        return new Instances\Expression($attributes);
+    }
+
     /**
      * Load Kind configuration from an YAML text.
      *