Skip to content

Commit 1bb0312

Browse files
rennokkirennokki
authored
Merge pull request #67 from renoki-co/revamp/docs
[2.x] Updated docs
2 parents 2cee963 + 6b76fb4 commit 1bb0312

File tree

11 files changed

+223
-56
lines changed

11 files changed

+223
-56
lines changed

‎README.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,9 @@ $svc = $cluster->service()
7070
->create();
7171
```
7272

73-
## 📄 Extensive Documentation
73+
## 📄 Getting Started
7474

75-
This package is Work in Progress and while there is in active development, PRs are also welcomed. Please refer to the [Resources docs](docs/RESOURCES.md) documentation and the [PR List](../../pulls) to know what's up for development.
76-
77-
Each existent resource has its own documentation, filled with examples:
75+
Please refer to the [Resources docs](docs/RESOURCES.md) extensive documentation and the [PR List](../../pulls) to know what's up for development. Below you will find the list of supported resources for a quick and easy access.
7876

7977
| Resource | Default Version
8078
| - | -
@@ -100,8 +98,6 @@ Each existent resource has its own documentation, filled with examples:
10098
| [StatefulSet](docs/kinds/StatefulSet.md) | `apps/v1`
10199
| [StorageClass](docs/kinds/StorageClass.md) | `storage.k8s.io/v1`
102100

103-
For other resources, you can check the [Resources Documentation](docs/RESOURCES.md)
104-
105101
## 🐛 Testing
106102

107103
``` bash

‎docs/CRDS.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Defining CRDs
2+
3+
The ease of using basic Kubernetes resources can be extended into creating CRDs for your custom use case. This needs a lot of context about what you can apply to the resources, based on your needs.
4+
5+
In these examples, we will be looking at the [Traefik CRDs](https://doc.traefik.io/traefik/routing/providers/kubernetes-crd) and [Agones CRDs](https://github.com/googleforgames/agones/tree/main/install/helm/agones/templates/crds). The versions might differ from the actual live Traefik docs, it's just for the example purposes.
6+
7+
# Getting started
8+
9+
Each CRD must extend the `K8sResource` class. This will provide the base PHP API functionalities that you can work with your resource.
10+
11+
Additionally, to be able to interact with the cluster and actually perform operations on it, you should implement the `InteractsWithK8sCluster` interface.
12+
13+
14+
The following example will create an `IngressRoute` CRD-ready class for `traefik.containo.us/v1alpha1`:
15+
16+
```php
17+
use RenokiCo\PhpK8s\Contracts\InteractsWithK8sCluster;
18+
use RenokiCo\PhpK8s\Kinds\K8sResource;
19+
20+
class IngressRoute extends K8sResource implements InteractsWithK8sCluster
21+
{
22+
/**
23+
* The resource Kind parameter.
24+
*
25+
* @var null|string
26+
*/
27+
protected static $kind = 'IngressRoute';
28+
29+
/**
30+
* The default version for the resource.
31+
*
32+
* @var string
33+
*/
34+
protected static $defaultVersion = 'traefik.containo.us/v1alpha1';
35+
36+
/**
37+
* Wether the resource has a namespace.
38+
*
39+
* @var bool
40+
*/
41+
protected static $namespaceable = true;
42+
}
43+
44+
$ir = new IngressRoute([
45+
'spec' => [
46+
'entryPoints' => ...
47+
],
48+
]);
49+
50+
$ir->create();
51+
```
52+
53+
**For non-namespaceable resources, you shall set the `$namespaceable` variable to `false`.**
54+
55+
## Watchable Resources
56+
57+
Watchable Resources are resources that can access the `/watch` endpoint in order to poll the changes over one or more resources. Typically, this can happen on any resource on which you can run `kubectl get some-crd --watch` upon.
58+
59+
For example, on basic CRDs (the default K8s ones), many resources like Service or Secret come with a watchable implementation.
60+
61+
You can read more about [how to watch a resource](Usage.md#watch-resource).
62+
63+
```php
64+
use RenokiCo\PhpK8s\Contracts\InteractsWithK8sCluster;
65+
use RenokiCo\PhpK8s\Contracts\Watchable;
66+
use RenokiCo\PhpK8s\Kinds\K8sResource;
67+
68+
class IngressRoute extends K8sResource implements InteractsWithK8sCluster, Watchable
69+
{
70+
//
71+
}
72+
73+
(new IngressRoute)->whereName('foo')->watch(function ($type, $ir) {
74+
//
75+
});
76+
```
77+
78+
## Scalable Resources
79+
80+
Scalable resources need a custom API on which you can call scale operations on them. Usually, this is done for resources that open a `/scale` endpoint to the API.
81+
82+
On the default CRDs, this is applied to StatefulSets and Deployments.
83+
84+
You can look on [how StatefulSets are scaled](kinds/StatefulSet.md#scaling)
85+
86+
```php
87+
use RenokiCo\PhpK8s\Contracts\InteractsWithK8sCluster;
88+
use RenokiCo\PhpK8s\Contracts\Scalable;
89+
use RenokiCo\PhpK8s\Kinds\K8sResource;
90+
use RenokiCo\PhpK8s\Traits\CanScale;
91+
92+
class GameServerSet extends K8sResource implements InteractsWithK8sCluster, Scalable
93+
{
94+
use CanScale;
95+
}
96+
97+
$scaler = $gameServerSet->scale(3);
98+
```
99+
100+
## Podable Resources
101+
102+
Podable resources are resources that manage pods. You can easily get the pods that are ran under the resource.
103+
104+
For example, Jobs and DaemonSets are one of the kinds that have this behaviour.
105+
106+
In PHP, this implementation is a bit tricky and need some configuration on your side:
107+
108+
```php
109+
use RenokiCo\PhpK8s\Contracts\InteractsWithK8sCluster;
110+
use RenokiCo\PhpK8s\Contracts\Podable;
111+
use RenokiCo\PhpK8s\Kinds\K8sResource;
112+
use RenokiCo\PhpK8s\Traits\HasPods;
113+
114+
class GameServerSet extends K8sResource implements InteractsWithK8sCluster, Podable
115+
{
116+
use HasPods;
117+
118+
/**
119+
* Get the selector for the pods that are owned by this resource.
120+
*
121+
* @return array
122+
*/
123+
public function podsSelector(): array
124+
{
125+
return [
126+
'game-server-name' => $this->getName(),
127+
];
128+
}
129+
}
130+
131+
$gameServerSet = new GameServerSet([
132+
'metadata' => [
133+
'name' => 'some-name',
134+
],
135+
'spec' => [
136+
'template' => [
137+
'metadata' => [
138+
'labels' => [
139+
'game-server-name' => 'some-name', // this must match
140+
],
141+
],
142+
...
143+
],
144+
...
145+
],
146+
...
147+
]);
148+
149+
foreach ($gameServerSet->getPods() as $pod) {
150+
//
151+
}
152+
```
153+
154+
As you can see, there is a `podsSelector()` array where you can define a set of labels that a `Pod` managed by this resource needs to have in order to `->getPods()` to work on it.
155+
156+
The labels for the Pod can be defined in the template spec of the resource. [Read more about the pod template definition in StatefulSets](kinds/StatefulSet.md#example) and [how to retrieve pods in StatefulSets](kinds/StatefulSet.md#getting-pods)
157+
158+
159+
## Loggable Resources
160+
161+
Loggable resources are resources that expose the `/log` endpoint and can easily get logs, both statically and in a polling request manner.
162+
163+
Check the [documentation on how to watch or get logs](kinds/Pod.md#pod-logs) using Pods.
164+
165+
```php
166+
use RenokiCo\PhpK8s\Contracts\Loggable;
167+
use RenokiCo\PhpK8s\Kinds\K8sResource;
168+
169+
class GameServerSet extends K8sResource implements InteractsWithK8sCluster, Loggable
170+
{
171+
//
172+
}
173+
```
174+
175+
# Helper Traits
176+
177+
"Helper Traits" are just traits that make the boring nested variables be easier set with a more friendly way.
178+
179+
You can find some in the [Traits folder](../../tree/master/src/Traits). By default, the `K8sResource` already uses the `HasAttributes` trait.
180+
181+
```php
182+
use RenokiCo\PhpK8s\Kinds\K8sResource;
183+
use RenokiCo\PhpK8s\Traits\HasStatus;
184+
185+
class GameServerSet extends K8sResource implements InteractsWithK8sCluster
186+
{
187+
use HasStatus;
188+
}
189+
190+
$gameServerSet->getStatus('some.path');
191+
```

‎docs/RESOURCES.md‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
## Cluster Interaction
44

5-
- [Methods & Usage](Usage.md)
6-
- [Cluster & Authentication](Cluster.md)
7-
- [General Resources](kinds/Resource.md)
5+
- [Methods & Usage - learn the basics](Usage.md)
6+
- [Cluster & Authentication - authenticate to your cluster](Cluster.md)
7+
- [General API - Methods implemented in all resources](kinds/Resource.md)
88

9-
## Supported Instances
9+
## Instances
1010

11-
Instances are custom classes that makes the build of containers, for example, more object-oriented that passing an array.
11+
Instances are custom PHP classes that makes the nested YAML definitions be easier to define. For example, you can build containers configuration for a pod in a more object-oriented manner by simply passing an Instance object than building the array from scratch.
1212

1313
- [Affinity](instances/Affinity.md) - used to declare affinities and anti-affinities
1414
- [Container](instances/Container.md) - used for Pods & Templates
@@ -18,11 +18,11 @@ Instances are custom classes that makes the build of containers, for example, mo
1818
- [Rules](instances/Rules.md) - used for Roles & Cluster Roles
1919
- [Volumes](instances/Volumes.md) - used for mounting volumes in pods and containers
2020

21-
## Supported Resources
21+
## Resources (CRDs)
2222

2323
Each resource inherits a default "base" class that is making the Resource build-up easier.
2424

25-
**Check the documentation for [General Resources](kinds/Resource.md) and [K8s API Usage](Usage.md) before diving in to the actual resources documentation.**
25+
**Check the documentation for [General API](kinds/Resource.md) and [K8s API Usage](Usage.md) before diving in to the actual resources documentation.**
2626

2727
| Resource | Default Version
2828
| - | -
@@ -48,14 +48,18 @@ Each resource inherits a default "base" class that is making the Resource build-
4848
| [StatefulSet](kinds/StatefulSet.md) | `apps/v1`
4949
| [StorageClass](kinds/StorageClass.md) | `storage.k8s.io/v1`
5050

51-
## Default Versions for Reosurces
51+
## Default Versions for Resources
5252

5353
Since we support multiple K8s Cluster versions, some versions do promote certain resources to GA. Since each resource needs a default version, the package will set **the default versions for the oldest Kubernetes version supported**.
5454

5555
For example, if the package supports `v1.18 +`, then the package will make sure the versions are defaults for `v1.18`. In some cases, like Ingress in `v1.19` that switched from Beta to GA, the `v1beta1` is no longer a default and instead, the `v1` is now a default. If `v1.17` is the oldest supported version, then it will stay to `v1beta`.
5656

5757
The minimum Kubernetes version that is supported by a given package version can be found at the top of [README.md](../README.md).
5858

59+
## Custom CRDs
60+
61+
The `K8sResource` class is extendable and expose a lot of PHP API that you can use to build your custom resources. [Head up to the CRDs docs](CRDS.md) to learn more about implementing your own custom resources.
62+
5963
## Planned
6064

6165
The following list of resources are planned and they will be available soon:

‎docs/Usage.md‎

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,18 @@
1-
# Usage
1+
# Methods & Usage
22

3-
All delivered [Resources](Resources.md) coming with this package do interact with the K8s Cluster you define. For instance, the idea behind this is to be able to import or create resources, with or without YAML, using PHP.
3+
CRDs are by default interacting with the API. For instance, the idea behind this is to be able to import or create resources, with or without YAML, using PHP.
44

55
## Retrieving all resources
66

77
Getting all resources can be done by calling `->all()`:
88

99
```php
1010
$namespaces = $cluster->namespace()->all();
11-
```
12-
13-
Or you can use a specific method to call it at once:
1411

15-
```php
12+
// Or you can use a specific method to call it at once
1613
$namespaces = $cluster->getAllNamespaces();
17-
```
1814

19-
For namespaced resources, you may pass the namespace:
20-
21-
```php
15+
// For namespaced resources, you may pass the namespace
2216
$stagingServices = $cluster->getAllServices('staging');
2317
```
2418

@@ -38,23 +32,15 @@ Getting only one resource is done by calling `->get()`:
3832

3933
```php
4034
$service = $cluster->service()->whereNamespace('staging')->whereName('nginx')->get();
41-
```
4235

43-
You can also shorten it like:
44-
45-
```php
36+
// You can also shorten it like
4637
$service = $cluster->service()->whereNamespace('staging')->getByName('nginx');
47-
```
4838

49-
Or you can use a specific method to call it in at once:
50-
51-
```php
39+
// Or you can use a specific method to call it in at once
5240
$service = $cluster->getServiceByName('nginx', 'staging');
5341
```
5442

55-
Filters can vary, depending if the resources are namespaceable or not.
56-
57-
By default, the namespace is `default` and can be missed from the filters.
43+
Filters can vary, depending if the resources are namespaceable or not. By default, the namespace is `default` and can be missed from the filters.
5844

5945
## Creating resources
6046

@@ -91,7 +77,7 @@ Additionally, you can pass query parameters, grace period and the propagation po
9177
The defaults are:
9278

9379
```php
94-
delete(array $query = ['pretty' => 1], $gracePeriod = null, string $propagationPolicy = 'Foreground'
80+
delete(array $query = ['pretty' => 1], $gracePeriod = null, string $propagationPolicy = 'Foreground')
9581
```
9682

9783
## Creating or updating resources

‎docs/kinds/CronJob.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ $container = K8s::container()
1616

1717
$pod = K8s::pod()
1818
->setName('pi')
19-
->setLabels(['tier' => 'backend'])
19+
->setLabels(['job-name' => 'pi']) // needs job-name: pi so that ->getPods() can work
2020
->setContainers([$container])
2121
->restartOnFailure();
2222

‎docs/kinds/DaemonSet.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ $container = K8s::container()
1717

1818
$pod = K8s::pod()
1919
->setName('mysql')
20-
->setLabels(['tier' => 'backend'])
20+
->setLabels(['daemonset-name' => 'mysql']) // needs daemonset-name: mysql so that ->getPods() can work
2121
->setContainers([$mysql]);
2222

2323
$ds = $this->cluster->daemonSet()

‎docs/kinds/Deployment.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ $container = K8s::container()
1717

1818
$pod = K8s::pod()
1919
->setName('mysql')
20-
->setLabels(['tier' => 'backend'])
20+
->setLabels(['tier' => 'backend']) // needs deployment-name: mysql so that ->getPods() can work
2121
->setContainers([$mysql]);
2222

2323
$dep = $cluster->deployment()

‎docs/kinds/Job.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ $container = K8s::container()
1515

1616
$pod = K8s::pod()
1717
->setName('pi')
18-
->setLabels(['tier' => 'backend'])
18+
->setLabels(['job-name' => 'pi']) // needs job-name: pi so that ->getPods() can work
1919
->setContainers([$container])
2020
->restartOnFailure();
2121

‎docs/kinds/Pod.md‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -118,16 +118,6 @@ if ($pod->isRunning()) {
118118
}
119119
```
120120

121-
For [Job](Job.md) support, you may also check if the pod ran successfully:
122-
123-
```php
124-
foreach ($job->getPods() as $pod) {
125-
if ($pod->isSuccessful()) {
126-
//
127-
}
128-
}
129-
```
130-
131121
## Containers' Statuses
132122

133123
You can check the container statuses:

0 commit comments

Comments
 (0)