Pod  ->  smallest schedulable unit (one or more containers sharing network/storage)
  |
Deployment  ->  manages ReplicaSets; handles rollouts and rollbacks
  |
Service  ->  stable virtual IP and DNS name that routes to healthy pod IPs
  |
Ingress  ->  HTTP/HTTPS routing rules from outside the cluster into Services

# ---- build stage ----
FROM node:20-alpine AS builder
WORKDIR /app

# Copy manifests first - cached until dependencies change
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts

COPY . .
RUN npm run build

# ---- runtime stage ----
FROM node:20-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app

# Non-root user for security
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./

USER appuser
EXPOSE 3000

# Use exec form to receive signals correctly
CMD ["node", "dist/server.js"]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: production
  labels:
    app: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api-server
          image: registry.example.com/api-server:1.4.2   # pinned tag, never latest
          ports:
            - containerPort: 3000
          envFrom:
            - configMapRef:
                name: api-config
            - secretRef:
                name: api-secrets
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"
          readinessProbe:
            httpGet:
              path: /healthz/ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz/live
              port: 3000
            initialDelaySeconds: 15
            periodSeconds: 20
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: api-server
---
apiVersion: v1
kind: Service
metadata:
  name: api-server
  namespace: production
spec:
  selector:
    app: api-server
  ports:
    - port: 80
      targetPort: 3000
  type: ClusterIP

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.example.com
      secretName: api-tls-cert          # cert-manager populates this
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-server
                port:
                  number: 80

apiVersion: v2
name: api-server
description: API server Helm chart
type: application
version: 0.1.0          # chart version
appVersion: "1.4.2"     # application image version

replicaCount: 3

image:
  repository: registry.example.com/api-server
  tag: ""               # defaults to .Chart.AppVersion
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: true
  host: api.example.com
  tlsSecretName: api-tls-cert

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
replicas: {{ .Values.replicaCount }}

startupProbe:
  httpGet:
    path: /healthz/startup
    port: 3000
  failureThreshold: 30      # allow up to 30 * 10s = 5 min for slow starts
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3       # remove from LB after 3 failures

livenessProbe:
  httpGet:
    path: /healthz/live
    port: 3000
  initialDelaySeconds: 15
  periodSeconds: 20
  failureThreshold: 3       # restart after 3 failures

resources:
  requests:
    cpu: "100m"       # scheduler uses this for placement
    memory: "128Mi"
  limits:
    cpu: "500m"       # throttled at this ceiling
    memory: "256Mi"   # OOMKilled if exceeded
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-server-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-server
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

# 1. Get pod status and events
kubectl get pod <pod-name> -n <namespace>
kubectl describe pod <pod-name> -n <namespace>    # read Events section

# 2. Check current logs
kubectl logs <pod-name> -n <namespace>

# 3. Check previous container logs (the one that crashed)
kubectl logs <pod-name> -n <namespace> --previous

# 4. Check resource pressure on the node
kubectl top pod <pod-name> -n <namespace>
kubectl top node

# 5. If image issue, check image pull events in describe output
# 6. Run interactively with a debug shell
kubectl debug -it <pod-name> -n <namespace> --image=busybox --target=<container-name>