Install / Kubernetes

Kubernetes Deployment

Production-grade Kubernetes setup with health probes, HPA, secrets management, and Control Plane / Data Plane architecture.

Architecture Overview

Database Mode (Single Node)

Clients

→

LoadBalancer Service
:80/:443

→

Ferrum Edge Pods
:8000/:8443

→

Backend Services

CP/DP Mode (Distributed)

PostgreSQL

↓

Control Plane
:9000 :50051

→ gRPC →

Data Plane 1
:8000/:8443

Data Plane 2
:8000/:8443

Data Plane N
:8000/:8443

→

Backends

1. Namespace & Secrets

yaml

apiVersion: v1
kind: Namespace
metadata:
  name: ferrum
---
apiVersion: v1
kind: Secret
metadata:
  name: ferrum-secrets
  namespace: ferrum
type: Opaque
stringData:
  database-url: "postgres://ferrum:secret@postgres:5432/ferrum"
  admin-jwt-secret: "your-strong-jwt-secret-here"

2. ConfigMap

yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: ferrum-config
  namespace: ferrum
data:
  FERRUM_MODE: "database"
  FERRUM_LOG_LEVEL: "info"
  FERRUM_LOG_FORMAT: "json"
  FERRUM_ADMIN_HTTP_PORT: "9000"

3. Deployment (Database Mode)

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ferrum-edge
  namespace: ferrum
  labels:
    app: ferrum-edge
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ferrum-edge
  template:
    metadata:
      labels:
        app: ferrum-edge
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: ferrum-edge
          image: ghcr.io/ferrum-edge/ferrum-edge:0.9.0
          ports:
            - name: http
              containerPort: 8000
            - name: https
              containerPort: 8443
            - name: admin
              containerPort: 9000
          envFrom:
            - configMapRef:
                name: ferrum-config
          env:
            - name: FERRUM_DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: ferrum-secrets
                  key: database-url
            - name: FERRUM_ADMIN_JWT_SECRET
              valueFrom:
                secretKeyRef:
                  name: ferrum-secrets
                  key: admin-jwt-secret
          resources:
            requests:
              cpu: "250m"
              memory: "128Mi"
            limits:
              cpu: "2000m"
              memory: "512Mi"
          startupProbe:
            httpGet:
              path: /health
              port: 9000
            initialDelaySeconds: 5
            periodSeconds: 5
            failureThreshold: 12
          livenessProbe:
            httpGet:
              path: /health
              port: 9000
            initialDelaySeconds: 0
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /status
              port: 9000
            initialDelaySeconds: 0
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 3
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sleep", "5"]

4. Services

yaml

# ClusterIP for admin
apiVersion: v1
kind: Service
metadata:
  name: ferrum-admin
  namespace: ferrum
spec:
  selector:
    app: ferrum-edge
  ports:
    - name: admin-http
      port: 9000
      targetPort: 9000
  type: ClusterIP
---
# LoadBalancer for proxy traffic
apiVersion: v1
kind: Service
metadata:
  name: ferrum-edge-lb
  namespace: ferrum
  annotations:
    # Cloud-specific load balancer annotations here
    # AWS: service.beta.kubernetes.io/aws-load-balancer-type: nlb
spec:
  selector:
    app: ferrum-edge
  ports:
    - name: http
      port: 80
      targetPort: 8000
    - name: https
      port: 443
      targetPort: 8443
  type: LoadBalancer

5. Ingress (Admin API)

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ferrum-admin-ingress
  namespace: ferrum
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: admin.ferrumedge.internal
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: ferrum-admin
                port:
                  number: 9000

6. Horizontal Pod Autoscaler

yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: ferrum-edge-hpa
  namespace: ferrum
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: ferrum-edge
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 70

7. CP/DP Mode Deployment

yaml — Control Plane

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ferrum-control-plane
  namespace: ferrum
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ferrum-control-plane
  template:
    metadata:
      labels:
        app: ferrum-control-plane
    spec:
      containers:
        - name: ferrum-edge
          image: ghcr.io/ferrum-edge/ferrum-edge:0.9.0
          ports:
            - containerPort: 9000   # Admin
            - containerPort: 50051  # CP gRPC
          env:
            - name: FERRUM_MODE
              value: control_plane
            - name: FERRUM_CP_GRPC_PORT
              value: "50051"
            - name: FERRUM_DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: ferrum-secrets
                  key: database-url
            - name: FERRUM_ADMIN_JWT_SECRET
              valueFrom:
                secretKeyRef:
                  name: ferrum-secrets
                  key: admin-jwt-secret
---
apiVersion: v1
kind: Service
metadata:
  name: ferrum-control-plane
  namespace: ferrum
spec:
  selector:
    app: ferrum-control-plane
  ports:
    - name: admin
      port: 9000
    - name: grpc
      port: 50051
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ferrum-data-plane
  namespace: ferrum
spec:
  replicas: 5
  selector:
    matchLabels:
      app: ferrum-data-plane
  template:
    metadata:
      labels:
        app: ferrum-data-plane
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: ferrum-edge
          image: ghcr.io/ferrum-edge/ferrum-edge:0.9.0
          ports:
            - containerPort: 8000
            - containerPort: 8443
          env:
            - name: FERRUM_MODE
              value: data_plane
            - name: FERRUM_CP_ADDR
              value: "ferrum-control-plane:50051"
          resources:
            requests:
              cpu: "500m"
              memory: "128Mi"
            limits:
              cpu: "4000m"
              memory: "1Gi"
          startupProbe:
            httpGet:
              path: /health
              port: 9000
            initialDelaySeconds: 3
            periodSeconds: 5
            failureThreshold: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 9000
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /status
              port: 9000
            periodSeconds: 5

📤

Port reference: 8000 HTTP proxy • 8443 HTTPS proxy • 9000 Admin HTTP • 9443 Admin HTTPS • 50051 Control Plane gRPC

Admin API Reference → Docker Compose