From d2ed63500bb6319995f7fb9ee37bd19589c1f33a Mon Sep 17 00:00:00 2001
From: "Marco Emilio \"sphakka\" Poleggi" <marcoep@ieee.org>
Date: Mon, 16 Dec 2024 12:08:50 +0100
Subject: [PATCH] More doc
Signed-off-by: Marco Emilio "sphakka" Poleggi <marcoep@ieee.org>
---
README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 75 insertions(+), 15 deletions(-)
diff --git a/README.md b/README.md
index 2c68c2b..712c80d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# 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
--
GitLab