Shared EKS App-Team Baseline

owned).

🧭 Shared EKS App-Team Baseline

Purpose

Define the minimum, compliant, repeatable deployment pattern for application teams deploying into a shared EKS cluster where:

• Namespaces are platform-owned

• Storage is platform-controlled

• App teams only deploy namespaced resources

1️⃣ Ownership & Responsibility Model

Platform / Cloud Team (NOT App Team)

Owns:

• EKS cluster

• Namespaces

• RBAC

• StorageClasses / EBS CSI

• Ingress / API Gateway

• Kafka / MSK

• MongoDB (if shared)

Application Team (This Repo)

Owns:

• Deployments / StatefulSets

• Services

• ConfigMaps / Secrets

• Kustomize overlays

• Runtime configuration (DNS, env vars)

🚫 App teams never create namespaces

2️⃣ Required Repository Structure (Minimum)

k8s/

  base/

    deployment.yaml

    service.yaml

    statefulset.yaml   # only if app-owned state

    kustomization.yaml

  overlays/

    shared/

      kustomization.yaml   # ← namespace set here

3️⃣ Namespace Handling (MANDATORY RULE)

❌ What app teams must NOT do

kind: Namespace

No namespace.yaml.

No metadata.namespace in resource files.

✅ Correct Pattern (Kustomize Injection)

# k8s/overlays/shared/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1

kind: Kustomization

namespace: zsp   # provided by Cloud team

resources:

  - ../../base

Kustomize injects the namespace at render time.

Kubernetes will NOT create it.

4️⃣ Service DNS Convention (Critical)

All in-cluster communication must use Kubernetes DNS:

<service-name>.<namespace>.svc.cluster.local

Example (MongoDB)

mongodb-app.zsp.svc.cluster.local

🚫 Never hardcode old or assumed namespaces

🚫 Never use IPs

🚫 Never rely on default namespace

5️⃣ Application Configuration Pattern (RECOMMENDED)

const mongoService = "mongodb-app";

const mongoNamespace = process.env.K8S_NAMESPACE || "zsp";

export const MONGO_URL =

  `mongodb://${mongoService}.${mongoNamespace}.svc.cluster.local:27017/TMF622v401`;

✔ Namespace configurable

✔ Code environment-agnostic

✔ Safe across dev / test / prod

6️⃣ Storage Rules (Stateful Workloads)

If your app uses:

• MongoDB

• PostgreSQL

• Kafka

• Any PVC

Then:

• ✔ StatefulSet + PVC is allowed only if platform enables storage

• ❌ Do not assume EBS / StorageClass exists

• ❌ Do not create StorageClasses

• ❌ Do not create PVs manually unless approved

If pods are Pending due to PVC:

➡ This is a Platform issue, not an App issue

7️⃣ Pre-Deploy Checklist (App Team)

Before applying manifests:

kubectl get ns <namespace>

kubectl auth can-i create pods -n <namespace>

kubectl auth can-i create services -n <namespace>

kubectl auth can-i create pvc -n <namespace>

If any fail → stop and escalate

8️⃣ Safe Deploy Commands

Render first (always)

kubectl kustomize k8s/overlays/shared

Verify:

• All resources show namespace: zsp

• No Namespace object exists

Apply

kubectl apply -k k8s/overlays/shared

9️⃣ Common Failure → Correct Owner

Symptom

Owner

Pods Pending (PVC)

Platform

Namespace not found

Platform

RBAC forbidden

Platform

DNS not resolving

App (wrong namespace)

Service not found

App

CrashLoopBackOff

App

🔟 One Rule to Remember

Platform creates namespaces.

App teams deploy into them.

Kustomize injects them.

DNS must match them.

📌 Optional: Add This to Every Repo README

This service is deployed into a shared EKS cluster.

Namespaces, storage, and ingress are platform-owned.

This repo uses Kustomize namespace injection and must not

create Kubernetes Namespace resources.

✅ Result

• Zero namespace conflicts

• No RBAC fights

• Predictable DNS

• Easy audits

• Repeatable across all TMF services