Update Readme, add some comments

Author: sajadbahar

.github/workflows/deploy.yaml

@@ -21,7 +21,7 @@ jobs:
         with:
           context: .
           push: true
-          tags: narsic/scaling_kubernetes_hpa_vpa:latest
+          tags: sajadbahar/scaling_kubernetes_hpa_vpa:latest
 
   deploy-to-k8s:
     runs-on: ubuntu-latest

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sajad Baharvandi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,105 @@
+# Kubernetes Scaling with HPA and VPA
+
+This repository demonstrates the setup and configuration of Kubernetes Horizontal Pod Autoscaler (HPA) and Vertical Pod Autoscaler (VPA) to achieve efficient scaling in a microservice environment. It includes manifests and configurations for deploying a sample application on Kubernetes with scaling capabilities.
+
+## Overview
+
+This project provides:
+- **Horizontal Pod Autoscaling (HPA)** to scale pods based on CPU usage.
+- **Vertical Pod Autoscaling (VPA)** to adjust pod resource requests automatically.
+- Examples of CI/CD integration using GitHub Actions and Docker images.
+
+## Project Structure
+
+```plaintext
+├── k8s-manifests          # Kubernetes deployment and service manifests
+├── examples               # Contain Exanple for VPA, HPA and combined one
+├── .github/workflows      # GitHub Actions workflows for CI/CD pipeline
+└── README.md              # Project documentation
+```
+
+### Key Files
+- **k8s-manifests/deployment.yaml** - Configures deployment with autoscaling.
+- **k8s-manifests/hpa.yaml** - Sets up Horizontal Pod Autoscaling (HPA).
+- **k8s-manifests/vpa.yaml** - Sets up Vertical Pod Autoscaling (VPA).
+- **.github/workflows** - CI/CD pipeline to build and push Docker images.
+
+## Features
+- Horizontal Pod Autoscaling (HPA): Automatically scales the number of pod replicas based on CPU utilization.
+- Vertical Pod Autoscaling (VPA): Dynamically adjusts CPU and memory resource requests and limits for containers.
+- Example manifests for deploying and scaling a sample application.
+
+## Requirements
+
+- **Kubernetes Cluster** - Minimum version 1.18.
+- **kubectl** - To apply manifests and manage the cluster.
+- **Docker** - For building images.
+- **GitHub CLI** - Recommended for managing GitHub Actions locally.
+
+## Setup Instructions
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/sajadbahar/scaling_kubernetes_hpa_vpa.git
+cd scaling_kubernetes_hpa_vpa
+```
+
+### 2. Configure Docker Registry and CI/CD
+
+Make sure to update the Docker image reference in `.github/workflows` with your Docker registry credentials.
+
+### 3. Deploy the Application
+
+Use `kubectl` to apply the manifests:
+
+```bash
+kubectl apply -f k8s-manifests/
+```
+
+### 4. Verify Deployment and Scaling
+
+Check the status of your deployments and autoscaling:
+
+```bash
+kubectl get pods
+kubectl describe hpa
+kubectl describe vpa
+```
+
+## Environment Variables
+
+To facilitate flexible configuration, use environment variables for sensitive data and deployment-specific values.
+
+## Metrics Collection
+
+To enable metrics collection for autoscaling, you will need a metrics server in your Kubernetes cluster.
+You can deploy Prometheus as a Helm chart for collecting metrics or use any other preferred setup.
+
+## CI/CD Pipeline
+
+The repository is set up with GitHub Actions CI/CD, which automates the process of building and pushing the Docker image.
+Make sure to review and configure the `.github/workflows` file to set up your specific repository, image, and credentials.
+
+## Environment Variables
+
+To make image configuration dynamic, specify the Docker image repository as an environment variable:
+
+```yaml
+containers:
+  - name: worker
+    image: ${DOCKER_REPO:-your-default-image}
+```
+Update the deployment YAML files with environment variables as required by your CI/CD setup.
+
+## Contributing
+
+Contributions are welcome! Please submit a pull request or open an issue for discussion.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE.md) file for details.
+
+---
+
+This repository is a demonstration of Kubernetes autoscaling features and is intended for learning purposes.

k8s-manifests/deployment.yaml

@@ -1,9 +1,11 @@
+# Kubernetes Deployment for worker service
+# Defines a Deployment for autoscaling tests, running a worker service with specified resource requests and limits.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: worker
 spec:
-  replicas: 1
+  replicas: 1  # Initial number of replicas, set by Horizontal Pod Autoscaler (HPA)
   selector:
     matchLabels:
       app: worker
@@ -14,14 +16,14 @@ spec:
     spec:
       containers:
       - name: worker
-        image: narsic/scaling_kubernetes_hpa_vpa:latest
+        image: ${WORKER_IMAGE:-sajadbahar/scaling_kubernetes_hpa_vpa:latest} # Default if env variable is not set
         resources:
           requests:
-            cpu: "10m"       # Define CPU requests
-            memory: "12Mi"   # Define memory requests (optional)
+            cpu: "10m"       # Minimum CPU requested for Pod scheduling
+            memory: "12Mi"   # Minimum memory requested for Pod scheduling
           limits:
-            cpu: "50m"       # Define CPU limits
-            memory: "25Mi"   # Define memory limits (optional)
+            cpu: "50m"       # Maximum CPU allowed per Pod
+            memory: "25Mi"   # Maximum memory allowed per Pod
         env:
           - name: REDIS_HOST
             value: $(REDIS_SERVICE_HOST)  # Adjust based on your service name

k8s-manifests/hpa.yaml

@@ -1,3 +1,5 @@
+# Horizontal Pod Autoscaler (HPA) for the worker Deployment
+# Adjusts the number of replicas based on CPU utilization thresholds.
 apiVersion: autoscaling/v2
 kind: HorizontalPodAutoscaler
 metadata:
@@ -6,13 +8,13 @@ spec:
   scaleTargetRef:
     apiVersion: apps/v1
     kind: Deployment
-    name: worker
-  minReplicas: 1
-  maxReplicas: 5
+    name: worker  # Name of the deployment to scale
+  minReplicas: 1  # Minimum number of Pods
+  maxReplicas: 5  # Maximum number of Pods
   metrics:
   - type: Resource
     resource:
       name: cpu
       target:
         type: Utilization
-        averageUtilization: 70
+        averageUtilization: 70  # Target average CPU utilization per Pod

k8s-manifests/vpa.yaml

@@ -1,3 +1,5 @@
+# Vertical Pod Autoscaler (VPA) for the worker Deployment
+# Adjusts CPU and memory requests for Pods based on observed usage patterns.
 apiVersion: autoscaling.k8s.io/v1
 kind: VerticalPodAutoscaler
 metadata:
@@ -6,6 +8,6 @@ spec:
   targetRef:
     apiVersion: "apps/v1"
     kind: Deployment
-    name: worker
+    name: worker  # Deployment to which the VPA applies
   updatePolicy:
-    updateMode: "Auto"
+    updateMode: "Auto"  # Mode of VPA; Auto allows automatic resource adjustments