Kubernetes

Hyperterse is a standalone binary, so you can run it in a Kubernetes cluster. It requires no external dependencies, it can also be easily scaled up and down.

These instructions are a work in progress. Please report any issues or suggestions to the GitHub repository.

Quick start

1. Build and push image

   # Export bundle
   hyperterse export -f my-query-gateway.terse -o dist
   
   # Build image
   docker build -t your-registry/my-query-gateway:latest .
   
   # Push to registry
   docker push your-registry/my-query-gateway:latest

2. Create secrets

   kubectl create secret generic my-query-gateway-secrets \
     --from-literal=DATABASE_URL="postgresql://user:pass@db:5432/app"

Kubernetes manifests

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-query-gateway
  labels:
    app: my-query-gateway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-query-gateway
  template:
    metadata:
      labels:
        app: my-query-gateway
    spec:
      containers:
        - name: my-query-gateway
          image: your-registry/hyperterse:latest
          ports:
            - containerPort: 8080
          envFrom:
            - secretRef:
                name: my-query-gateway-secrets
          resources:
            requests:
              memory: '128Mi'
              cpu: '100m'
            limits:
              memory: '512Mi'
              cpu: '500m'
          livenessProbe:
            httpGet:
              path: /heartbeat
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /heartbeat
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: my-query-gateway
spec:
  selector:
    app: my-query-gateway
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP

ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-query-gateway
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
    - hosts:
        - api.example.com
      secretName: my-query-gateway-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-query-gateway
                port:
                  number: 80

Apply manifests

1. Apply all manifests

   kubectl apply -f deployment.yaml
   kubectl apply -f service.yaml
   kubectl apply -f ingress.yaml

2. Verify deployment

   kubectl get pods -l app=my-query-gateway
   kubectl get svc my-query-gateway
   kubectl get ingress my-query-gateway

Secrets management

1. Create secrets

   secrets.yaml

   apiVersion: v1
   kind: Secret
   metadata:
     name: my-query-gateway-secrets
   type: Opaque
   stringData:
     DATABASE_URL: 'postgresql://user:pass@db:5432/app'

2. Apply secrets

   kubectl apply -f secrets.yaml

External secrets operator

For production, use External Secrets with AWS Secrets Manager, HashiCorp Vault, etc.:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: my-query-gateway-secrets
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: aws-secrets
  target:
    name: my-query-gateway-secrets
  data:
    - secretKey: DATABASE_URL
      remoteRef:
        key: prod/my-query-gateway/database-url

Scaling

Horizontal pod autoscaler

hpa.yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-query-gateway
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-query-gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Health checks

The deployment includes probes:

• Liveness: Restarts unhealthy pods
• Readiness: Removes from load balancing during startup

Both use the /heartbeat endpoint which returns a simple success response.

Rolling updates

1. Configure rolling update strategy

   Add to your deployment:

   spec:
     strategy:
       type: RollingUpdate
       rollingUpdate:
         maxUnavailable: 1
         maxSurge: 1

2. Update image

   kubectl set image deployment/my-query-gateway \
     my-query-gateway=your-registry/my-query-gateway:v1.2.0

3. Monitor rollout

   kubectl rollout status deployment/my-query-gateway

Monitoring

Prometheus metrics

Add annotations for Prometheus scraping:

template:
  metadata:
    annotations:
      prometheus.io/scrape: 'true'
      prometheus.io/port: '8080'

Network policies

Restrict traffic:

network-policy.yaml

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: my-query-gateway-policy
spec:
  podSelector:
    matchLabels:
      app: my-query-gateway
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: ingress-nginx
      ports:
        - port: 8080
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              name: database
      ports:
        - port: 5432