mailcow-operator

Kubernetes operator for managing mailcow resources with Custom Resource Definitions (CRDs). It reconciles Mailcow, Domain, Mailbox, Alias, and DomainAdmin resources.

Features

• Declarative management of mailcow domains, mailboxes, aliases, and domain admins
• Finalizers to ensure clean deletion

Prerequisites

• Kubernetes cluster
• mailcow deployment reachable from the operator
• helm (for installation via Helm)

Install via Helm

The Helm chart lives in helm/chart.

Install CRDs and controller:

helm install mailcow-operator ./helm/chart \
	--namespace mailcow-operator \
	--create-namespace

or using the released version:

helm repo add mailcow-operator https://tarteo.github.io/mailcow-operator
helm install mailcow-operator mailcow-operator/mailcow-operator \
    --namespace mailcow-operator \
    --create-namespace

and to uninstall:

helm uninstall mailcow-operator --namespace mailcow-operator

Using the CRDs

The operator manages these CRDs:

• Mailcow — stores API endpoint and credentials reference
• Domain — manages mail domains
• Mailbox — manages mailboxes for domains
• Alias — manages aliases
• DomainAdmin — manages domain administrators

Create a Mailcow resource

apiVersion: mailcow.onestein.nl/v1
kind: Mailcow
metadata:
  name: example-mailcow
spec:
  endpoint: "https://mail.example.com"
  secret:
    name: mailcow-credentials
    key: apiToken

Create a Domain

apiVersion: mailcow.onestein.nl/v1
kind: Domain
metadata:
  name: example-domain
spec:
  mailcow: example-mailcow
  domain: "example.com"
  description: "Example Domain"
  quota: 1000
  defQuota: 500
  maxQuota: 500
  active: true
  maxMailboxes: 60

Create a Mailbox

apiVersion: mailcow.onestein.nl/v1
kind: Mailbox
metadata:
  name: example-mailbox
spec:
  mailcow: example-mailcow
  domain: example.com
  localPart: "user"
  name: "mr. example"
  passwordSecret:
    name: mailbox-password-secret
    key: password
  quota: 500
  active: true

Create an Alias

apiVersion: mailcow.onestein.nl/v1
kind: Alias
metadata:
  name: example-alias
spec:
  mailcow: example-mailcow
  address: "@example.com" # Catch-all alias
  goTo: "user@example.com"
  active: true

Create a DomainAdmin

apiVersion: mailcow.onestein.nl/v1
kind: DomainAdmin
metadata:
  name: example-domainadmin
spec:
  mailcow: example-mailcow
  username: "test-example"
  passwordSecret:
    name: domainadmin-password-secret
    key: password
  domains:
    - example.com
    - example2.com
  active: true

Development

Generate CRDs and deepcopy

make manifests generate

Build and run locally

make build
make run

Regenerate mailcow API client

The mailcow API is generated from the mailcow OpenAPI specification using oapi-codegen. The openapi.yaml is pulled from a mailcow version 2024-01d release. And then edited due to the specification not being fully correct and missing schemas for some endpoints.

oapi-codegen --config=mailcow/oapi-codegen.yaml mailcow/openapi.yaml

Roadmap

• Add more controllers for other mailcow resources
• Add e2e tests
• Allow multiple goto addresses in aliases
• Make the created DKIM ConfigMap name configurable
• Add an option to force the password of mailbox resources to be updated on each reconciliation according to the secret
• Add an option to force the password and name of mailboxes to be updated on each reconciliation according to the secret and spec
• Add support for multiple mailcow versions
• Update status of mailboxes (quota used, etc.)
• Update status of domains (number of mailboxes, etc.)