Scale Resources#

How to adjust CPU and memory resources for Mailu components.

Problem#

You need to increase or decrease resource requests and limits for Mailu components based on your workload, user count, or cluster capacity.

Solution#

The MailuChart accepts a resources configuration object that allows you to customize CPU and memory for each component. If not specified, components use sensible defaults from the component specifications.

Understanding Resource Configuration#

Resource Requests: Guaranteed resources allocated to the pod. Used for scheduling decisions.

Resource Limits: Maximum resources the pod can use. Prevents runaway resource consumption.

Best Practice: Set requests to typical usage and limits to 2-3x requests to allow bursting.

Scale a Single Component#

Adjust resources for a specific component (e.g., Dovecot for high IMAP load):

import { App } from 'cdk8s';
import { MailuChart } from 'cdk8s-mailu';

const app = new App();

new MailuChart(app, 'mailu', {
  namespace: 'mailu',
  domain: 'example.com',
  hostnames: ['mail.example.com'],
  subnet: '10.42.0.0/16',

  // ... other config ...

  resources: {
    dovecot: {
      requests: {
        cpu: '500m',      // Increased from default 200m
        memory: '2Gi',    // Increased from default 1Gi
      },
      limits: {
        cpu: '2000m',     // 4x request
        memory: '4Gi',    // 2x request
      },
    },
  },
});

app.synth();

Scale Multiple Components#

Adjust resources for all heavy components in a high-load deployment:

resources: {
  // Front (Nginx) - handles all incoming connections
  front: {
    requests: { cpu: '200m', memory: '512Mi' },
    limits: { cpu: '1000m', memory: '1Gi' },
  },

  // Dovecot - memory-intensive for IMAP
  dovecot: {
    requests: { cpu: '500m', memory: '2Gi' },
    limits: { cpu: '2000m', memory: '4Gi' },
  },

  // Postfix - CPU-intensive for SMTP
  postfix: {
    requests: { cpu: '300m', memory: '1Gi' },
    limits: { cpu: '1000m', memory: '2Gi' },
  },

  // Rspamd - spam filtering
  rspamd: {
    requests: { cpu: '200m', memory: '1Gi' },
    limits: { cpu: '1000m', memory: '2Gi' },
  },

  // Admin - lightweight
  admin: {
    requests: { cpu: '100m', memory: '256Mi' },
    limits: { cpu: '500m', memory: '512Mi' },
  },
},

Component-Specific Scaling Guidelines#

Dovecot (IMAP/POP3)#

Memory-intensive - scales with concurrent user connections and mailbox operations.

Small deployment (< 50 users):

dovecot: {
  requests: { cpu: '200m', memory: '1Gi' },
  limits: { cpu: '1000m', memory: '2Gi' },
}

Medium deployment (50-500 users):

dovecot: {
  requests: { cpu: '500m', memory: '2Gi' },
  limits: { cpu: '2000m', memory: '4Gi' },
}

Large deployment (500+ users):

dovecot: {
  requests: { cpu: '1000m', memory: '4Gi' },
  limits: { cpu: '4000m', memory: '8Gi' },
}

ClamAV (Antivirus)#

Very resource-intensive - requires significant memory for virus signature database.

Only if needed (add to resources config):

clamav: {
  requests: { cpu: '1000m', memory: '2Gi' },
  limits: { cpu: '4000m', memory: '4Gi' },
}

Note: ClamAV startup takes 5-10 minutes to download virus signatures. Consider if antivirus scanning is truly required for your use case.

Postfix (SMTP)#

CPU-intensive - scales with email throughput.

High-volume mail server:

postfix: {
  requests: { cpu: '500m', memory: '1Gi' },
  limits: { cpu: '2000m', memory: '2Gi' },
}

Rspamd (Spam Filter)#

Balanced workload - CPU for filtering, memory for Bayes database.

High spam volume:

rspamd: {
  requests: { cpu: '300m', memory: '1Gi' },
  limits: { cpu: '1500m', memory: '2Gi' },
}

Apply Changes#

After modifying resource configuration:

# Regenerate manifests
npm run synth

# Apply updated configuration
kubectl apply -f dist/mailu.k8s.yaml

# Watch pod restarts
kubectl get pods -n mailu -w

Note: Changing resource requests may cause pods to be rescheduled to different nodes with sufficient capacity.

Verify Resource Usage#

Check actual resource consumption to inform scaling decisions:

# Current resource usage
kubectl top pods -n mailu

# Per-component usage (sorted by memory)
kubectl top pods -n mailu --sort-by=memory

# Per-component usage (sorted by CPU)
kubectl top pods -n mailu --sort-by=cpu

Recommended monitoring period: Monitor for 24-48 hours covering peak usage times before adjusting resources.

Troubleshooting#

Pod stuck in Pending state#

Symptom: Pod shows Pending status with event “Insufficient memory” or “Insufficient cpu”.

Solution: Either reduce resource requests or add more node capacity to the cluster.

# Check pod events
kubectl describe pod -n mailu <pod-name> | grep -A 10 Events

OOMKilled pods#

Symptom: Pod restarts with exit code 137, events show “OOMKilled”.

Solution: Increase memory limits for the affected component.

# Check recent pod restarts
kubectl get pods -n mailu
kubectl describe pod -n mailu <pod-name> | grep -A 5 "Last State"

CPU Throttling#

Symptom: Application performance degraded, kubectl top shows CPU at limit.

Solution: Increase CPU limits to allow more bursting.

# Check if pod is hitting CPU limits
kubectl top pods -n mailu | grep <component-name>