198 lines
6.8 KiB
Markdown
198 lines
6.8 KiB
Markdown
# Mailu Migration Guide: From Kustomize to Helm
|
|
|
|
This document outlines the migration process from the Kustomize-based Mailu deployment to the Helm-based deployment.
|
|
|
|
## Overview
|
|
|
|
The Mailu email server has been migrated from a Kustomize-based deployment to a Helm chart-based deployment. This change provides better maintainability, easier upgrades, and standardized configuration management.
|
|
|
|
## Key Changes
|
|
|
|
### 1. Service Names
|
|
- **Old**: `mailu-smtp`, `email-smtp`, `mailu-front`, `mailu-admin`, `mailu-imap`, `mailu-antispam`
|
|
- **New**: `mailu-postfix`, `mailu-front`, `mailu-admin`, `mailu-dovecot`, `mailu-rspamd`
|
|
|
|
### 2. Configuration Method
|
|
- **Old**: Individual YAML manifests with Kustomize overlays
|
|
- **New**: Helm chart with values files for environment-specific configuration
|
|
|
|
### 3. Directory Structure
|
|
- **Old**: `infrastructure/platform/mail/mailu/{base,overlays/{dev,prod}}`
|
|
- **New**: `infrastructure/platform/mail/mailu-helm/{dev,prod}`
|
|
|
|
### 4. Ingress Configuration
|
|
- **Old**: Ingress resources created as part of the Kustomize setup
|
|
- **New**: Built-in ingress disabled in Helm chart to work with existing ingress controller
|
|
|
|
## Updated Service References
|
|
|
|
The following configurations have been updated to use the new Helm service names:
|
|
|
|
## Ingress Configuration
|
|
|
|
The Mailu Helm chart has been configured to work with your existing ingress setup:
|
|
|
|
- **ingress.enabled: false**: Disables the chart's built-in Ingress creation
|
|
- **tlsFlavorOverride: notls**: Tells Mailu's internal NGINX not to enforce TLS, as your Ingress handles TLS termination
|
|
- **realIpHeader: X-Forwarded-For**: Ensures Mailu's NGINX logs and processes the correct client IPs from behind your Ingress
|
|
- **realIpFrom: 0.0.0.0/0**: Trusts all proxies (restrict to your Ingress pod CIDR for security)
|
|
|
|
### Required Ingress Resource
|
|
|
|
You need to create an Ingress resource to route traffic to Mailu. Here's an example:
|
|
|
|
```yaml
|
|
apiVersion: networking.k8s.io/v1
|
|
kind: Ingress
|
|
metadata:
|
|
name: mailu-ingress
|
|
namespace: bakery-ia # Same as Mailu's namespace
|
|
annotations:
|
|
kubernetes.io/ingress.class: nginx # Or your Ingress class
|
|
nginx.ingress.kubernetes.io/proxy-body-size: "100m" # Allow larger email attachments
|
|
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" # For long connections
|
|
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
|
|
nginx.ingress.kubernetes.io/force-ssl-redirect: "true" # Redirect HTTP to HTTPS
|
|
# If using Cert-Manager: cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
|
spec:
|
|
tls:
|
|
- hosts:
|
|
- mail.bakery-ia.dev # or mail.bakewise.ai for prod
|
|
secretName: mail-tls-secret # Your TLS Secret
|
|
rules:
|
|
- host: mail.bakery-ia.dev # or mail.bakewise.ai for prod
|
|
http:
|
|
paths:
|
|
- path: /
|
|
pathType: Prefix
|
|
backend:
|
|
service:
|
|
name: mailu-front-http # Mailu's front service (check with kubectl get svc -n bakery-ia)
|
|
port:
|
|
number: 80
|
|
```
|
|
|
|
Apply it: `kubectl apply -f ingress.yaml`.
|
|
|
|
This routes all traffic from https://mail.[domain]/ to Mailu's internal NGINX, which proxies to webmail (/webmail), admin (/admin), etc.
|
|
|
|
## Updated Service References
|
|
|
|
The following configurations have been updated to use the new Helm service names:
|
|
|
|
### Common ConfigMap
|
|
- `SMTP_HOST` changed from `email-smtp.bakery-ia.svc.cluster.local` to `mailu-postfix.bakery-ia.svc.cluster.local`
|
|
|
|
### SigNoz Configuration
|
|
- `signoz_smtp_host` changed from `email-smtp.bakery-ia.svc.cluster.local` to `mailu-postfix.bakery-ia.svc.cluster.local`
|
|
- `smtp_smarthost` changed from `email-smtp.bakery-ia.svc.cluster.local:587` to `mailu-postfix.bakery-ia.svc.cluster.local:587`
|
|
|
|
## Deployment Process
|
|
|
|
### Prerequisites
|
|
1. Helm 3.x installed
|
|
2. Access to Kubernetes cluster
|
|
3. Namespace `bakery-ia` exists
|
|
|
|
### Deployment Commands
|
|
|
|
#### For Development:
|
|
```bash
|
|
# Add Mailu Helm repository
|
|
helm repo add mailu https://mailu.github.io/helm-charts/
|
|
helm repo update
|
|
|
|
# Install Mailu for development
|
|
helm upgrade --install mailu-dev mailu/mailu \
|
|
--namespace bakery-ia \
|
|
--create-namespace \
|
|
--values infrastructure/platform/mail/mailu-helm/values.yaml \
|
|
--values infrastructure/platform/mail/mailu-helm/dev/values.yaml
|
|
```
|
|
|
|
#### For Production:
|
|
```bash
|
|
# Add Mailu Helm repository
|
|
helm repo add mailu https://mailu.github.io/helm-charts/
|
|
helm repo update
|
|
|
|
# Install Mailu for production
|
|
helm upgrade --install mailu-prod mailu/mailu \
|
|
--namespace bakery-ia \
|
|
--create-namespace \
|
|
--values infrastructure/platform/mail/mailu-helm/values.yaml \
|
|
--values infrastructure/platform/mail/mailu-helm/prod/values.yaml
|
|
```
|
|
|
|
## Critical Configuration Preservation
|
|
|
|
All critical configurations from the original Kustomize setup have been preserved:
|
|
|
|
- Domain and hostname settings
|
|
- External SMTP relay configuration (Mailgun)
|
|
- Redis integration with shared cluster
|
|
- Database connection settings
|
|
- TLS certificate management
|
|
- Resource limits and requests
|
|
- Network policies
|
|
- Storage configuration (10Gi PVC)
|
|
|
|
## Rollback Procedure
|
|
|
|
If rollback to the Kustomize setup is needed:
|
|
|
|
1. Uninstall the Helm release:
|
|
```bash
|
|
helm uninstall mailu-dev -n bakery-ia # or mailu-prod
|
|
```
|
|
|
|
2. Revert the configuration changes in `infrastructure/environments/common/configs/configmap.yaml` and `infrastructure/monitoring/signoz/signoz-values-prod.yaml`
|
|
|
|
3. Deploy the old Kustomize manifests:
|
|
```bash
|
|
kubectl apply -k infrastructure/platform/mail/mailu/overlays/dev
|
|
# or
|
|
kubectl apply -k infrastructure/platform/mail/mailu/overlays/prod
|
|
```
|
|
|
|
## Verification Steps
|
|
|
|
After deployment, verify the following:
|
|
|
|
1. Check that all Mailu pods are running:
|
|
```bash
|
|
kubectl get pods -n bakery-ia | grep mailu
|
|
```
|
|
|
|
2. Verify SMTP connectivity from other services:
|
|
```bash
|
|
# Test from a pod in the same namespace
|
|
kubectl run test-smtp --image=curlimages/curl -n bakery-ia --rm -it -- \
|
|
nc -zv mailu-postfix.bakery-ia.svc.cluster.local 587
|
|
```
|
|
|
|
3. Check that notification service can send emails:
|
|
```bash
|
|
kubectl logs -n bakery-ia deployment/notification-service | grep -i smtp
|
|
```
|
|
|
|
4. Verify web interface accessibility:
|
|
```bash
|
|
kubectl port-forward -n bakery-ia svc/mailu-front 8080:80
|
|
# Then visit http://localhost:8080/admin
|
|
```
|
|
|
|
## Known Issues
|
|
|
|
1. During migration, existing email data should be backed up before uninstalling the old deployment
|
|
2. DNS records may need to be updated to point to the new service endpoints
|
|
3. Some custom configurations may need to be reapplied after Helm installation
|
|
|
|
## Support
|
|
|
|
For issues with the new Helm-based deployment:
|
|
|
|
1. Check the [official Mailu Helm chart documentation](https://github.com/Mailu/helm-charts)
|
|
2. Review Helm release status: `helm status mailu-[dev|prod] -n bakery-ia`
|
|
3. Check pod logs: `kubectl logs -n bakery-ia deployment/[mailu-postfix|mailu-front|etc.]`
|
|
4. Verify network connectivity between services |