More doc

Signed-off-by: Marco Emilio "sphakka" Poleggi <marcoep@ieee.org>

README.md

 # Project: web SSO service with K8s/KinD
 
-A pseudo web single-sing-on (SSO) service deployed on a Kubernets cluster
+A pseudo web single-sing-on (SSO) service deployed on a Kubernetes cluster
 provisioned with KinD. This is mostly an integration project with some
 application development.
 
@@ -73,7 +73,7 @@ The following files in directory `views/` handle the client-side workflow.
 The file `main.py` handles the REST logic by conveying all requests to the
 back-end.
 
-:bulb: **This part does not requires adaptations.**
+:bulb: **This part requires adaptations only for the [bonuses](bonuses).**
 
 
 ### Back-end
@@ -287,7 +287,8 @@ The infrastructure (computing instance + S3 storage) shall be provisioned via
 **Terraform**.
 
 :bulb: References:
-  * Terraform: https://registry.terraform.io/providers/hashicorp/aws/latest/docs
+
+* Terraform: https://registry.terraform.io/providers/hashicorp/aws/latest/docs
 
 
 ## Service deployment
@@ -336,12 +337,14 @@ map:
 
 :hammer_and_wrench: You shall:
 
-1. Fork this repository.
+1. Fork this repository. **N.B. Your fork must be a new, private GitEdu
+   project. Please, invite the instructors as "reporters". Do not change the
+   files' layout or names!**
 2. Complete the Python back-end file `Application/backend/main.py`. See the
    section [Development](#development) below. Test locally the application as
    explained in section [Local installation](#local-installation).
 3. Rebuild the application's Docker images, then:
-    - test [locally the deployment](#local-docker-deployment), then
+    - test [locally the deployment](#local-docker-deployment),
     - push the images to your public Docker Hub repository. This task shall
        be automated via Ansible -- see below.
 4. Complete your Terraform files from the version you developed in
@@ -350,7 +353,8 @@ map:
    plus an S3 storage bucket -- no KinD/Kubectl package installation. Commit
    your recipe files and in directory `Terraform/` -- Cloud-init files are
    already in sub-folder `conf/`.
-5. Complete your Ansible playbook, starting from the version you developed in
+5. Complete your Ansible playbook `lb-deployment.yaml`, starting from the
+   version you developed in
    [Lab-Ansible](https://gitedu.hesge.ch/lsds/teaching/bachelor/cloud-and-deployment/lab-ansible)
    Task #10, to (commit all related files in directory `Ansible/`):
     - expose the application portal's IP (i.e, the load-balancer's) to the
@@ -359,16 +363,29 @@ map:
       repository. These shall be [`local_action`
       tasks.](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_delegation.html)
 
+Your **deliverables** are the following files:
+
+  * Python: `backend/main.py` (+ any other front-end files for the bonuses)
+  * Terraform: a single `main.tf` recipe (vars and outputs files  are also OK)
+  * Ansible: a single `kind-metallb.yml` playbook. **N.B. Any other playbook
+    will be ignored!**
+  * K8s: the `lb-deployment.yaml` service manifest. The remaining files
+    shouldn't need to be modified.
+
 :bulb: References:
-  * Build and push Docker images: https://docs.docker.com/get-started/introduction/build-and-push-first-image/
-  * Ansible playbook delegation:
+
+  - Build and push Docker images: https://docs.docker.com/get-started/introduction/build-and-push-first-image/
+  - Ansible playbook delegation:
     https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_delegation.html
 
 
 ### Bonuses
 
-You will get bonus points for any of the following improvements.
+:star: You will get bonus points for any of the following improvements.
 
+  * Use [Kubernetes
+    secrets](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data)
+    instead of a plain ConfigMap. +0.1 points.
   * Ask for the password when removing an account (unenroll) -- extra
     safety. +0.2 points.
   * Use password hashing in the back-end -- extra security. +0.1 points.
@@ -413,8 +430,9 @@ Otherwise, plain install -- you might need to install python dependencies
 $ make install
 ```
 
-Put your SwitchEngines EC2 credentials in file
-`<sandbox>/Application/s3_credentials.env`, which should be already there.
+Put your SwitchEngines S3 credentials in file
+`<sandbox>/Application/s3_credentials.env`, which should be already
+there. :warning: **Do not commit this file in your Git repo!**
 
 Finally, run the application in the current console:
 
@@ -427,12 +445,18 @@ Or, run it in its own terminal:
 $ make trun
 ```
 
+:bulb: The two images are quite compact, nevertheless, to reduce disk space
+waste, please, **do frequent cleanups** with the command:
+``` shell
+$ docker system prune
+```
+
 
 #### Local Docker deployment
 
-:hammer_and_wrench: **Install the following Docker packages on your workstation according
-to your distribution's instructions: docker(.io), docker-cli,
-(docker-)buildx**
+:hammer_and_wrench: **Install the following Docker packages on your
+workstation according to your distribution's instructions: docker(.io),
+docker-cli, (docker-)buildx**
 
 :bulb: Please, peruse the `Makefile` to learn the real Docker commands.
 
@@ -466,6 +490,39 @@ You can manage your containers with the other make commands: dstop, dstart,
 drm, etc.
 
 
+#### Kubernetes
+
+The local deployment uses an `.env` file to pass S3 credentials and other
+variables to Docker. This shall be converted into a [Kubernetes
+CofigMap](https://kubernetes.io/docs/concepts/configuration/configmap/). Even
+though it is not safe for production use, it is enough for our purposes.
+
+:hammer_and_wrench: You shall
+
+  1. write a ConfigMap file `s3_credentials.yaml` based on the
+     `s3_credentials.env` used for Docker;
+  2. extend your K8s deployment YAML file with
+     * support for the two app containers -- the front-end shall be
+     load-balanced;
+     * a `configMapRef` for the back-end using the above ConfigMap file.
+
+Of course, once all files are ready, any related operations shall be handled
+by Ansible. Specifically, a change in the ConfigMap shall trigger a back-end
+service redeployment.
+
+:bulb: For better security, you may use K8s secrets. This would be a
+**bonus**.
+
+:bulb: References:
+
+  * K8s ConfigMaps:
+    https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/
+  * K8s Secrets:
+    https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure
+  * ConfigMap/Secretes tutorial:
+    https://www.baeldung.com/ops/kubernetes-equivalent-of-env-file-docker
+
+
 #### Test workflow
 
 The following tests shall be passed by your implementation:
@@ -475,7 +532,10 @@ The following tests shall be passed by your implementation:
       2. Ansible-playbook shall install KinD/Kubectl and deploy your
          load-balanced application
       3. Your application shall be reachable on port 80 (or another of your
-         choice) from any host outside the Cloud network.
+         choice) **from any host outside the Cloud network.**
+      4. Your K8s deployment shall be reachable via an [SSH tunnel started
+         from your
+         workstation.](https://gitedu.hesge.ch/lsds/teaching/bachelor/cloud-and-deployment/lab-k8s#controlling-your-cluster-from-a-remote-console)
   * Once your application is installed, you shall exercise all the branch
     conditions described by the above workflows:
       1. Enroll a new user: shall succeed