nextdns-operator

README

NextDNS Kubernetes Operator

A Kubernetes operator for managing NextDNS profiles declaratively using Custom Resources.

Features

• Declarative DNS management as Kubernetes resources
• Multi-CRD architecture (shared allowlists, denylists, TLD lists)
• Full NextDNS API coverage
• Profile lifecycle management (create, adopt, delete)
• Automatic drift detection
• ConfigMap export for app integration
• Observe mode for safe profile adoption
• Gateway API support (TCPRoute/UDPRoute) for DNS traffic exposure

Custom Resources

CRD	Description
NextDNSProfile	Main profile configuration with security, privacy, and parental control settings
NextDNSAllowlist	Reusable list of allowed domains
NextDNSDenylist	Reusable list of blocked domains
NextDNSTLDList	Reusable list of blocked TLDs
NextDNSCoreDNS	Deploy CoreDNS instances forwarding to NextDNS upstream

Installation

Helm (Recommended)

# Install from OCI registry
helm install nextdns-operator oci://ghcr.io/jacaudi/charts/nextdns-operator \
  --version 0.1.0 \
  --namespace nextdns-operator-system \
  --create-namespace

Kubectl

# Install CRDs
kubectl apply -f https://github.com/jacaudi/nextdns-operator/releases/latest/download/install.yaml

# Deploy operator
kubectl apply -f https://github.com/jacaudi/nextdns-operator/releases/latest/download/operator.yaml

Local Development

# Install CRDs
task install

# Run locally
task run

Quick Start

Once the operator is installed:

1. Create a Secret with your NextDNS API key:

apiVersion: v1
kind: Secret
metadata:
  name: nextdns-credentials
  namespace: default
type: Opaque
stringData:
  api-key: "your-nextdns-api-key"

1. Create a NextDNSProfile:

apiVersion: nextdns.io/v1alpha1
kind: NextDNSProfile
metadata:
  name: my-profile
  namespace: default
spec:
  name: "My DNS Profile"
  credentialsRef:
    name: nextdns-credentials
  security:
    aiThreatDetection: true
    googleSafeBrowsing: true

1. Apply the resources:

kubectl apply -f secret.yaml
kubectl apply -f profile.yaml

1. Check the status:

kubectl get nextdnsprofile my-profile -o yaml

Examples

See the config/samples directory for complete examples:

• NextDNSProfile - Full profile with security, privacy, and settings
• NextDNSAllowlist - Shared allowlist for business services
• NextDNSDenylist - Shared denylist for malicious domains
• NextDNSTLDList - Shared list of high-risk TLDs
• NextDNSCoreDNS - CoreDNS deployment with NextDNS upstream
• NextDNSCoreDNS with Gateway - CoreDNS with Gateway API exposure

Documentation

For detailed configuration guides, CRD reference, troubleshooting, and architecture documentation, see the full documentation.

Covers: ConfigMap export, observe mode, CoreDNS deployment (upstream protocols, Multus CNI, domain overrides), drift detection, complete CRD field reference, status conditions, and troubleshooting.

Development

# Run tests
task test

# Build
task build

Acknowledgements

This project stands on the shoulders of giants:

• bjw-s - For the excellent helm-charts library and app-template that powers the Helm chart for this operator. The common library pattern has been invaluable.

• amalucelli - For creating the original nextdns-go client library that this operator's fork is based on. The solid foundation made building this operator possible.

License

Apache 2.0