Docs
Kubernetes (EKS) overview
Teluul runs application services on Amazon EKS. Kubernetes orchestrates containers (API, workers, and related services), performs health checks, and supports automated rollback when a deployment is unhealthy.
Persistent customer data is not stored inside Kubernetes volumes. Databases run on Amazon RDS outside the cluster. See RDS Database Setup.
- Namespaces such as
teluul-productionandteluul-test - AWS ALB Ingress with HTTPS and
/healthz/health checks - ConfigMaps for shared non-secret configuration; secrets for credentials
- GitLab CI builds images and deploys with Kustomize
Why we use Kubernetes
Our demo ran on one AWS instance with Docker Compose. That works for a demo, but if the instance fails, everything goes down. EKS gives us:
- Stability: if a container crashes, Kubernetes restarts it.
- Safe releases: new versions roll out gradually, and unhealthy ones are stopped.
- Easy scaling: we can add or remove copies (replicas) of a service.
- One standard setup: every future Teluul service is deployed the same way.
Cluster setup
The cluster has a managed node group (EC2 or Fargate) and these add-ons:
Namespaces keep environments separate inside the cluster:
teluul-production: live customer trafficteluul-test: testing before release
Services
| Service | Purpose |
|---|---|
teluul-api |
Main API |
task-worker |
Runs background jobs |
task-scheduler |
Triggers scheduled jobs |
cache-service |
Redis cache |
There is no database service in the cluster. It lives on RDS.
Configuration (Kustomize and ConfigMaps)
Kustomize lets us define a service once in base/ and override only what differs per environment, such as the number of replicas or the domain. That means less duplication and fewer mistakes.
ConfigMap (teluul-config) holds shared settings and is injected into every service. Change it once and every service gets the update.
Examples of what it holds: APP_ENV, APP_DOMAIN, CACHE_URL, TASK_BROKER_URL, TASK_RESULT_URL, CACHE_PREFIX, and FEATURE_* flags.
Secrets hold credentials such as the database password, API secret key and Sentry DSN. Keep these in Kubernetes Secrets or AWS Secrets Manager, never in a ConfigMap.
Ingress and HTTPS
An AWS Application Load Balancer sends traffic into the cluster:
- Internet-facing, in IP mode (the ALB talks directly to pods)
- HTTPS is terminated at the ALB using an ACM certificate
- Domains:
api.teluul.com(production) andstaging.teluul.com(test) - Health checks call
/healthz/
Deployments (GitLab CI)
On every push to the production branch:
- Build Docker images with Kaniko (no Docker daemon needed).
- Publish them to the container registry.
- Deploy by applying the Kustomize manifests to EKS.
- Verify: Kubernetes and the ALB check that the new pods are healthy.
Test deployments work the same way, but go to teluul-test.
Health checks and rollback
When a new version is released:
- Kubernetes starts new pods next to the old ones.
- The ALB and readiness probes check
/healthz/. - If the new pods are unhealthy, they never receive traffic.
- The rollout halts and the previous version keeps serving customers.
To fully revert an unhealthy release, the pipeline should also run kubectl rollout undo, or we can use a tool like Argo Rollouts or Flagger. Rollback only works well if every service has correct readiness and liveness probes.
