From 79ef5791c96dfbfedf03d1a5d67562f17aebbaa8 Mon Sep 17 00:00:00 2001
From: Tchoupinax <corentinfiloche@hotmail.fr>
Date: Mon, 25 Mar 2024 08:22:16 +0100
Subject: [PATCH] docs: improvement documentation (#6)

* docs: add the Changelog file

* docs: explanation description + roadmap
---
 CHANGELOG.md | 14 ++++++++++++++
 README.md    | 29 +++++++++++++++++++++++++++--
 2 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..2f435e2
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,14 @@
+## 0.1.1 | 2024-03-24
+
+#### Chores
+
+- Repair the CI
+- Improve documentation
+
+## 0.1.0 | 2024-03-24
+
+🎉 The project is alive. The main feature works well in test, let's push it to production.
+
+#### Features
+
+- Allow to edit a label of a deployment without downtime
diff --git a/README.md b/README.md
index eb70e2d..e3e46ca 100644
--- a/README.md
+++ b/README.md
@@ -29,9 +29,22 @@ Deployment's labels are immutable. That means, if you have to edit, rename or ad
 
 To be able to add labels without any downtime, we have to use a [blue-green strategy](https://www.redhat.com/en/topics/devops/what-is-blue-green-deployment). This projects aims to do this operation automatically and without human manual operation. The production must be safe!
 
-## Explanation
+## Explanations
 
-TODO
+Labels are immutable by design but moreover they can be used as selector for a service. That means if you break a label, you could cut the link between a Kubernetes service and a pod. That definitively not something you want to happen in your production. To prevent from meeting this issue, we make this operation.
+
+We have a deployment called `api` with labels `app=api` and `kubernetes.io/name=Api`. However, this label is bad typed and should be totally in lowercase. So we want to rename it. A service, called `api` too, targets pods with labels `app=api` `kubernetes.io/name=Api`.
+
+1. **Clone deployment**: we will create the same deployment, called the same and suffixed by `changing-label-tmp`. This deployment won't have the label we want to edit or remove (here it's `kubernetes.io/name`).
+2. **Edit the service**: we will update the service to set selectors to match a subset of labels that matches both deployment. It's mandatory to ensure the service will loadbalance traffic between pods accross both deployment.
+3. **Wait all pods are ready**: you might know that Kubernetes waits until a pod is alive (liveness) and ready (readyness) to send traffic to it. That the goal here and we are querying Kubernetes's API to ensure both deployment have all of their pod ready.
+4. **Delete the old deployment**: as we want to rewrite label, we have to delete and create again the deployment. Labels are immutable and it's the **only way** to do it.
+5. **Create the deployment with new label**: this deployment has all final labels but continue to work with the current service. Remember this service targets a subset of selector.
+6. **Wait all pods are ready**: we repeat the operation about the new deployment.
+7. **Remove temporary deployment**: now that the deployment is ready, we can cut the temporary one and leaves in place the new deployment with modified label.
+8. **[Optional] Add the label to service selector**: some labels are recommenced by Kubernetes to be present as default label and thoses labels might be added to the service selector. That means we are making the matching set stronger.
+      - See [documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)
+      - For the moment, only `kubernetes.io/name` is considered to be added to the service
 
 ## Zero downtime testing
 
@@ -70,3 +83,15 @@ echo 'GET YOUR_URL' | \
           latency.p95+latency.p50+latency.p25 \
           bytes_in.sum+bytes_out.sum
 ```
+
+## Roadmap
+
+1.0.0
+- [] Sucessful migration in production with relatively high volume
+- [] Handle the fact the edited label is the only one used for the service
+- [] Documentation about potentials issues from scale (DB)
+- [] Better handling of labels added to the service and well understand of K8S's good pratices
+
+0.1.0
+- [x] Successful test with zero downtime
+- [x] Basic documentation