Kubernetes (K8s) Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• k8s/kustomization.yaml
• k8s/api-deployment.yaml
• k8s/web-deployment.yaml
• k8s/ingress-hpa.yaml
• README.md
• deployment_guide.md

The email-platform project utilizes Kubernetes for deploying its services in a scalable and manageable way. The deployment is orchestrated using Kustomize, which allows for template-free customization of Kubernetes manifests. This document outlines the architecture, components, and configuration of the Kubernetes deployment as defined in the k8s/ directory.

The core components deployed are the tempmail-api (backend and SMTP server), tempmail-web (frontend), and a database. The system is designed to be exposed to the internet via an Ingress controller, with automatic scaling capabilities provided by Horizontal Pod Autoscalers (HPAs).

Kustomization

Sources: k8s/kustomization.yaml

The root of the Kubernetes configuration is the k8s/kustomization.yaml file. It defines all the resources that constitute the application, sets a common namespace, applies common labels, and manages container image versions.

Resources

The Kustomization resource pulls together all the necessary Kubernetes manifests to deploy the application.

This diagram shows the resources managed by the main kustomization.yaml file.

The following resources are included in the deployment:

Resource File	Description
config-secrets.yaml	Defines ConfigMaps and Secrets for the application.
storage.yaml	Defines PersistentVolumeClaims for stateful components.
database-deployment.yaml	Deploys the PostgreSQL database.
api-deployment.yaml	Deploys the backend API and SMTP server.
web-deployment.yaml	Deploys the frontend web application.
ingress-hpa.yaml	Configures Ingress for external traffic and Horizontal Pod Autoscalers.

Sources: k8s/kustomization.yaml:9-14

Configuration

• Namespace: All resources are deployed into the tempmail namespace.
• Common Labels: All resources are labeled with app: tempmail and environment: production.
• Images: The file specifies the container images to be used, allowing for easy updates to image names and tags.

Sources: k8s/kustomization.yaml:6,16-23

Architecture Overview

The Kubernetes deployment follows a standard microservices pattern. External traffic is routed through an Ingress controller to the appropriate backend service (api-service or web-service). These services then route traffic to the pods managed by their respective Deployments. The API deployment utilizes a PersistentVolumeClaim for storage.

This diagram illustrates the flow of traffic from the user to the different components within the Kubernetes cluster.

Sources: k8s/api-deployment.yaml, k8s/web-deployment.yaml, k8s/ingress-hpa.yaml

Components

API Deployment

Sources: k8s/api-deployment.yaml

The api-deployment.yaml manifest defines the backend service for the email platform.

• Deployment: tempmail-api

  • Replicas: Starts with 3 replicas.
  • Image: tempmail-api:latest.
  • Ports: Exposes port 3001 for HTTP and 2525 for SMTP.
  • Storage: Mounts a persistent volume at /app/storage via the api-storage-pvc claim. This is used for storing attachments.
  • Probes:
    • Liveness: httpGet on path /health at port 3001.
    • Readiness: httpGet on path /ready at port 3001.

• Service: api-service

  • A ClusterIP service that exposes the API deployment's ports (3001 and 2525) within the cluster.

Environment Variables

The API container is configured with the following environment variables, primarily sourced from secrets and configmaps.

Variable	Value/Source	Description
DATABASE_URL	Secret tempmail-secrets, key database-url	Connection string for the primary database.
DATABASE_READ_URL	Secret tempmail-secrets, key database-read-url	Connection string for a read-replica database.
JWT_SECRET	Secret tempmail-secrets, key jwt-secret	Secret key for signing JWTs.
REDIS_HOST	redis-service	The internal service name for Redis.
REDIS_PORT	"6379"	The port for the Redis service.
STORAGE_DIR	/app/storage	Path for persistent file storage.
HTTP_PORT	"3001"	The port the HTTP server listens on.
SMTP_PORT	"2525"	The port the SMTP server listens on.
TRUST_PROXY	"true"	Indicates the service is behind a trusted proxy.
WEB_URL	ConfigMap tempmail-config, key web-url	The public URL of the web frontend.

Sources: k8s/api-deployment.yaml:22-50

Web Deployment

Sources: k8s/web-deployment.yaml

The web-deployment.yaml manifest defines the frontend service.

• Deployment: tempmail-web

  • Replicas: Starts with 2 replicas.
  • Image: tempmail-web:latest.
  • Port: Exposes port 80 for HTTP.
  • Probes:
    • Liveness & Readiness: httpGet on path / at port 80.

• Service: web-service

  • A ClusterIP service that exposes the web deployment's port 80 within the cluster.

Environment Variables

Variable	Value/Source	Description
VITE_API_BASE	ConfigMap tempmail-config, key api-url	The base URL for the backend API.

Sources: k8s/web-deployment.yaml:21-25

Ingress and Autoscaling

Sources: k8s/ingress-hpa.yaml

This manifest configures how external traffic reaches the services and how the services scale based on load.

Ingress

The tempmail-ingress resource uses an Nginx Ingress controller to manage external access.

• TLS: It is configured to use cert-manager with a letsencrypt-prod cluster issuer to automatically provision SSL certificates for api.example.com and app.example.com.
• Routing Rules:

Host	Path	Backend Service	Port
api.example.com	/	api-service	3001
app.example.com	/	web-service	80

Sources: k8s/ingress-hpa.yaml:1-33

Horizontal Pod Autoscaler (HPA)

HPAs are defined for both the API and Web deployments to automatically adjust the number of pods.

API HPA (api-hpa)

Parameter	Value
minReplicas	2
maxReplicas	10
cpu.averageUtilization	70%
memory.averageUtilization	80%

Sources: k8s/ingress-hpa.yaml:36-51

Web HPA (web-hpa)

Parameter	Value
minReplicas	2
maxReplicas	5
cpu.averageUtilization	70%

Sources: k8s/ingress-hpa.yaml:54-66

Conclusion

The Kubernetes deployment for the email platform is well-structured, leveraging Kustomize for configuration management. It defines separate deployments for the API and web frontends, exposes them via services, and routes external traffic using an Ingress controller with automated TLS. The use of Horizontal Pod Autoscalers ensures that the application can scale based on CPU and memory load, providing resilience and performance. Persistent storage for the API and configuration management through Secrets and ConfigMaps complete this production-ready setup.