Running a Postfix Mail Relay on Kubernetes

Sanitized engineering pattern — This page describes the engineering approach at a high level. Company-specific infrastructure, configuration, and operational details are intentionally excluded.

Introduction

I worked on moving an existing Postfix mail relay from a traditional server environment into Kubernetes.

The main challenge was not only running Postfix inside a container. The setup also needed configuration management, persistent logs, controlled SMTP access, workload scheduling, and reliable connectivity to an upstream mail service.

This study explains the engineering approach and troubleshooting process using a simplified architecture. Company-specific infrastructure and configuration details are intentionally excluded.

Project goal

The goal was to run an existing mail-relay workload in Kubernetes while keeping the important operational behaviour clear and manageable.

The work covered SMTP traffic handling, Postfix configuration management, persistent operational logging, controlled workload placement, upstream SMTP connectivity, and useful troubleshooting visibility.

Architecture

The simplified design used a Kubernetes Deployment for the Postfix workload and a Kubernetes Service as the stable path to the workload. Configuration was supplied in a container-friendly form. Persistent storage and syslog-ng kept operational logs available when a Pod was recreated.

The relay handled the connection between client systems and an upstream SMTP service. Keeping those paths visible made it easier to understand where a delivery problem started.

Engineering approach

The existing relay was adapted for a container-based environment rather than copied directly from the previous server setup. Postfix configuration was managed in a Kubernetes-friendly way, and the container environment was checked for the features required by the relay.

Persistent logging was treated as part of the design. syslog-ng and persistent storage kept useful mail logs available beyond an individual Pod lifecycle. Workload scheduling was also considered so the relay ran in the intended place within the Kubernetes environment.

Problems I worked through

Server-specific configuration did not fit Kubernetes

The existing Postfix configuration contained assumptions from a traditional server environment. Some settings did not work correctly inside a container. The configuration had to be adjusted for Kubernetes while preserving the required mail-relay behaviour.

Required Postfix map support was missing

The existing Postfix configuration depended on LMDB lookup maps. The first container environment did not provide the required LMDB support. The required support was added and validated before Postfix could use the configuration correctly.

Logs needed to survive Pod recreation

Container-local logs may disappear when a Pod is replaced or recreated. Persistent storage and syslog-ng were used so operational mail logs remained available for troubleshooting.

SMTP relay access needed to remain controlled

The relay needed to accept mail only from approved sources while keeping normal relay protection enabled. The configuration was corrected without turning the server into an open relay.

Delivery problems had to be isolated

A message could reach Postfix successfully but still fail when the relay tried to connect to the upstream SMTP service. Troubleshooting checked the two paths separately:

This helped determine whether the problem was caused by Postfix, Kubernetes, or network connectivity.

How I validated the setup

Validation included checking:

• the Kubernetes workload state
• that the Service could reach the Postfix workload
• that Postfix started correctly
• that LMDB support was available
• operational logging
• mail queue behaviour
• SMTP connectivity
• end-to-end mail flow
• behaviour during troubleshooting and redeployment

Selected technical checks

These checks are intentionally generic. They show the type of validation used without exposing a production environment.

kubectl get pods -n <namespace>
kubectl get svc -n <namespace>
kubectl get pvc -n <namespace>

postconf -m | grep lmdb
postqueue -p

apiVersion: apps/v1
kind: Deployment
metadata:
  name: postfix-relay
spec:
  template:
    spec:
      nodeSelector:
        workload: mail-relay

Explore the implementation

Sanitized technical evidence

View the sanitized example manifests, Postfix notes, architecture, and troubleshooting guide used to explain this engineering pattern.

View the public engineering evidence ↗

Outcome

The relay was successfully moved into a Kubernetes-based environment and end-to-end mail flow was validated.

The work also provided a clearer way to manage configuration, logging, deployment, and troubleshooting in the container-based environment.

What this work demonstrates

Engineering discussion

Compare approaches, safely.

Questions and technical feedback are welcome. Public discussion is not enabled yet; use the contact flow for an engineering conversation.

Start a conversation →