feat: update configuration docs to add the patches

kube-green · Aug 15, 2024 · 831fcd8 · 831fcd8
1 parent 9159b87
commit 831fcd8
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 53 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -4,42 +4,25 @@ sidebar_position: 4
 
 # Configuration
 
-In the namespace where you want to enable *kube-green*, apply the SleepInfo CRD.
-An example of CRD is accessible [at this link](https://github.com/kube-green/kube-green/blob/main/testdata/working-hours.yml).
-
-<!-- TODO: add link to api reference instead of the following list -->
-
-The SleepInfo spec contains:
-
-* **weekdays**  
-Day of the week. `*` is every day, `1` is monday, `1-5` is from monday to friday
-* **sleepAt**  
-Time in hours and minutes (HH:mm) when namespace will go to sleep. Valid values are, for example, `19:00` or `*:*` for every minute and every hour.  
-Resources sleep will be deployments (setting replicas value to 0) and, if `suspendCronjobs` option is set to true, cron jobs will be suspended.
-* **wakeUpAt** (*optional*)  
-Time in hours and minutes (HH:mm) when namespace should be restored to the initial state (before sleep). Valid values are, for example, `19:00` or `*:*` for every minute and every hour. If wake up value is not set, pod in namespace will not be restored. So, you will need to deploy the initial namespace configuration to restore it.
-* **timeZone** (*optional*, default to *UTC*)  
-Time zone in IANA specification. For example for italian hour, set `Europe/Rome`.
-* **suspendDeployments** (*optional*, default to *true*)  
-If set to false, deployments will not be suspended during sleep mode..
-* **suspendCronJobs** (*optional*, default to *false*)  
-If set to true, cronjobs will be suspended during sleep mode..
-* **excludeRef** (*optional*)  
-An array of object containing the resource to exclude from sleep. It can specify exactly the name of the specified resource or match based from the labels. The possible formats are:
-  * **apiVersion**: Version of the resource. Now it is supported *"apps/v1"*, *"batch/v1beta1"* and *"batch/v1"*
-  * **kind**: The kind of resource. Now it is supported *"Deployment"* and *"CronJob"*
-  * **name**: The name of the resource
-or
-  * **matchLabels**: an object of strings with the labels to identify a resources
-click [here](#exclude-reference) to see an example.
+In the namespace where you want to enable *kube-green*, apply the `SleepInfo` resource.
+An example of `SleepInfo` is accessible [at this link](https://github.com/kube-green/kube-green/blob/main/testdata/working-hours.yml).
+
+By default, the managed resources are `Deployments` and `StatefulSets`, and it is possible to enable the `CronJobs`. You can manage also other resources adding [custom patches](#patches).
+
+Check the [API reference](apireference_v1alpha1.md) for the SleepInfo CRD to understand each field.
 
 ## Patches
 
-<!-- TODO: -->
+Patches are used to define how to change the resources so that the runtime will "sleep". The patches are applied to the resources at the sleep time and are reverted at the wake up time.
+
+In this way, it is possible to support all the Kubernetes resources, also the ones defined through the custom resource definitions.  
+To let *kube-green* support a custom resource, you need to define the specific `patch` for the resource inside the `SleepInfo` (the API reference is available [here](apireference_v1alpha1.md#kube-green.com/v1alpha1.Patch)) and add the permission to the ClusterRole associated to the *kube-green* manager ([here how to configure the RBAC](./installation/rbac.md)), if not already set.
 
 ## Examples
 
-### Simplest SleepInfo resource
+### Simple SleepInfo resource
+
+The follow configuration sets a sleep to 20:00 and wake up to 08:00 from monday to friday (in Rome timezone) for the default managed resources.
 
 ```yaml
 apiVersion: kube-green.com/v1alpha1
@@ -53,15 +36,15 @@ spec:
   timeZone: "Europe/Rome"
 ```
 
-With this CRD, it's configured a sleep to 20:00 and wake up to 08:00 on weekdays only for Deployments.
+### Exclude resources
 
-### Complete SleepInfo resource
+The follow configuration sets a sleep to 20:00 and wake up to 08:00 from monday to friday (in Rome timezone), for the default managed resources and the `CronJobs`, excluding the `Deployment` named `api-gateway`.
 
 ```yaml
 apiVersion: kube-green.com/v1alpha1
 kind: SleepInfo
 metadata:
-  name: working-hours
+  name: exclude-resources
 spec:
   weekdays: "1-5"
   sleepAt: "20:00"
@@ -74,71 +57,107 @@ spec:
       name:       api-gateway
 ```
 
-With this CRD, it's configured a sleep to 20:00 and wake up to 08:00 on weekdays, for Deployments and CronJobs, excluding the Deployment named api-gateway.
+### Sleep without wake up
 
-### Complete SleepInfo without wake up
+The follow configuration sets a sleep to 20:00 from monday to friday (in Rome timezone) for the default managed resources  and the `CronJobs`. The wake up is not set, so the resources will be suspended until them will be manually changed (for example, through a redeployment).
 
 ```yaml
 apiVersion: kube-green.com/v1alpha1
 kind: SleepInfo
 metadata:
-  name: working-hours
+  name: no-wakep-up
 spec:
   weekdays: "1-5"
   sleepAt: "20:00"
   timeZone: "Europe/Rome"
   suspendCronJobs: true
-  excludeRef:
-    - apiVersion: "apps/v1"
-      kind:       Deployment
-      name:       api-gateway
 ```
 
-With this CRD, it's configured a sleep to 20:00 on weekdays, for Deployments and CronJobs, excluding the Deployment named api-gateway. To wake up, you must redeploy all the resources to set to the initial state.
-
 ### Suspend only CronJobs
 
+The follow configuration sets a sleep to 20:00 and wake up to 08:00 on each day of the week (in Rome timezone), only for `CronJobs`, excluding the specific `CronJob` named `do-not-suspend`.
+
 ```yaml
 apiVersion: kube-green.com/v1alpha1
 kind: SleepInfo
 metadata:
-  name: working-hours
+  name: suspend-cronjobs
 spec:
   weekdays: "*"
   sleepAt: "20:00"
   wakeUpAt: "08:00"
+  timeZone: "Europe/Rome"
   suspendCronJobs: true
   suspendDeployments: false
+  suspendStatefulSets: false
   excludeRef:
     - apiVersion: "batch/v1"
       kind:       CronJob
       name:       do-not-suspend
 ```
 
-With this CRD, it's configured a sleep to 20:00 and wake up to 08:00 on weekdays, only for CronJobs (sleep of Deployments are inactive), excluding the CronJob `do-not-suspend`.
+### Exclude with labels
 
-### Exclude reference
+The follow configuration sets a sleep to 20:00 and wake up to 08:00 on each day of the week (in Rome timezone), for the default managed resources, excluding the resources with the label `kube-green.dev/exclude: true`.
 
 ```yaml
 apiVersion: kube-green.com/v1alpha1
 kind: SleepInfo
 metadata:
-  name: working-hours
+  name: exclude-with-labels
 spec:
   weekdays: "*"
   sleepAt: "20:00"
   wakeUpAt: "08:00"
-  suspendCronJobs: true
+  timeZone: "Europe/Rome"
   excludeRef:
-    - apiVersion: "batch/v1"
-      kind:       CronJob
-      name:       do-not-suspend
     - matchLabels: 
         kube-green.dev/exclude: true
 ```
 
-With this CRD, it's configured a sleep to 20:00 and wake up to 08:00 on weekdays, excluding the CronJob `do-not-suspend` and all the supported resources with the label `kube-green.dev/exclude: true`.
+### Include with labels
+
+The follow configuration sets a sleep to 20:00 and wake up to 08:00 on each day of the week (in Rome timezone), for the default and `CronJobs` resources with the label `kube-green.dev/include: true`.
+
+```yaml
+apiVersion: kube-green.com/v1alpha1
+kind: SleepInfo
+metadata:
+  name: include-with-labels
+spec:
+  weekdays: "1-5"
+  sleepAt: "20:00"
+  wakeUpAt: "08:00"
+  timeZone: "Europe/Rome"
+  suspendCronJobs: true
+  excludeRef:
+    - matchLabels: 
+        kube-green.dev/include: true
+```
 
 ### Custom patches
 
-<!-- TODO: -->
+The follow configuration sets a sleep to 20:00 and wake up to 08:00 from monday to friday (in Rome timezone) for the default managed resources, the `CronJobs` and add the support to the not managed resource `ReplicaSets`.
+
+This is only an example on how to add custom patches to the resources. The patch in this example sets the `replicas` field to `0`. In this way, it is possible to support also some custom resources.
+
+```yaml
+apiVersion: kube-green.com/v1alpha1
+kind: SleepInfo
+metadata:
+  name: add-replicasets-support-with-custom-patches
+spec:
+  weekdays: "1-5"
+  sleepAt: "20:00"
+  wakeUpAt: "08:00"
+  timeZone: "Europe/Rome"
+  suspendCronJobs: true
+  patches:
+    - target:
+        group: apps
+        kind: ReplicaSet
+      patch: |-
+        - path: /spec/replicas
+          op: add
+          value: 0
+```
diff --git a/scripts/api-reference/reference-docs-gen-config.sh b/scripts/api-reference/reference-docs-gen-config.sh
@@ -29,7 +29,7 @@ go install github.com/ahmetb/[email protected]
 
 mkdir -p ${GOPATH}/src/github.com/kube-green
 gitdir="${GOPATH}/src/github.com/kube-green/kube-green"
-git clone "https://github.com/kube-green/kube-green.git" "${gitdir}"
+git clone --depth=1 "https://github.com/kube-green/kube-green.git" "${gitdir}"
 cd "${gitdir}"
 
 generate_reference_docs_per_ref(){