Skip to content

Latest commit

 

History

History
80 lines (67 loc) · 4.37 KB

README.md

File metadata and controls

80 lines (67 loc) · 4.37 KB
Raw

GitHub release Helm release Artifact Hub main PkgGoDev Go Report Card GitHub go.mod Go version

dkim-manager

dkim-manager is a Kubernetes controller for creating DKIM keys.

Motivation

When sending mail from inside a Kubernetes cluster, you might want to sign outgoing emails with a DKIM signature. Setting up DKIM involves placing a private key for the DKIM signer to consume, and registering a DNS record containing the public key. Doing so manually can be a chore, and in some environments it is not acceptable to create private keys locally. dkim-manager aims to facilitate this process.

Features

dkim-manager is used in combination with external-dns. When a DKIM key is requested via the DKIMKey custom resource, dkim-manager creates a key pair, and creates two resources:

  • a Secret containing the private key, that the mailer pod can mount and consume
  • a DNSEndpoint containing the public key and other necessary information for external-dns to create the DNS record
  • RSA (1024-bit, 2048-bit, 4096-bit) and ed25519 keys are supported
    • 2048-bit RSA is selected as a sensible default

It is recommended to create a delegated subdomain for the sole purpose of storing DKIM records (eg: dkim.example.com) and grant external-dns only permission on that subdomain. See this blog for more details why.

Installation

dkim-manager requires cert-manager and external-dns to be installed first. The helm installation instructions are a good place to get started. If installing external-dns separately, not that the following arguments should be set for dkim-manager to be able to register TXT records:

- --source=crd
- --crd-source-apiversion=externaldns.k8s.io/v1alpha1
- --crd-source-kind=DNSEndpoint
- --managed-record-types=TXT
- --txtPrefix= #some non-empty string

Additionally, it is recommended to set --domainFilter to restrict the scope of operation of external-dns to the domain for which you want to create DKIM keys, and to set --namespace=YOUR_NAMESPACE so that external-dns only looks at resources inside your namespace. Doing so allows you to use external-dns for the sole purpose of registering DKIM TXT records.

Usage

DKIM keys can be requested by creating a DKIMKey resource.

apiVersion: dkim-manager.atelierhsn.com/v1
kind: DKIMKey
metadata:
    name: selector1-example-com
    namespace: example
spec:
    secretName: selector1-example-com
    selector: selector1
    domain: dkim.example.com

This will create the following resources:

# Secret
apiVersion: v1
kind: Secret
metadata:
    name: selector1-example-com
data:
    dkim.example.com.selector1.key: |
        "..."
---
### DNSEndpoint
apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
    name: selector1-example-com
spec:
    endpoints:
    - dnsName: selector1._domainkey.dkim.example.com
      recordTTL: 86400
      recordType: TXT
      targets:
      - "v=DKIM1; h=sha256; k=rsa; p=...."

Future Considerations

Currently, DKIM private keys are stored as a Secret resource. While ubiquitous, this makes the keys visible to any priviledged users inside the cluster. In a future release support for writing private keys to HashiCorp Vault may be considered.