How to deploy pihole and wireguard on kubernetes using a recursive dns


  • A computer running any linux distribution (in this tutorial I’m using debian buster)
  • This computer needs to have at least 1 Gb of ram and 2 cores.
  • This computer needs to have an static ip address (in my case, LAN:
  • Configure the firewall to accept inbound connections in the following ports:
  • In order to connect from internet, you need to open the following ports in your ISP’s Router:
  • In order to connect to pihole via web UI from internet you need to have a FQDN that points to your Network (in this tutorial I'm using google domains, you can use duckdns if you don't have a domain)
  • A functional K3S cluster (See Installation guide). This tutorial should work with K8S, but you need to deploy some extra features like Traefik Ingress, Klipper Service Load Balancer
  • You need to have kubectl to perform operations in the K3S cluster





$ kubectl apply -f k8s/01-namespaces.yaml

Dynamic DNS

$ kubectl apply -f k8s/02-dynamic-dns-google.yaml


  • unbound StatefulSet configured as recursive DNS resolver
  • Cluster IP service to 53/tcp and 53/udp
$ kubectl apply -f k8s/03-unbound.yaml

Test Unbound installation

Create directories

$ sudo mkdir -p /var/lib/{pihole,wireguard}


  • Persistent volume type hostPath (/var/lib/pihole)
  • Persistent Volume claim
  • Config Map (Timezone, admin email and upstream dns)
  • Secret (Web Password)
  • Pihole StatefulSet
  • Cluster IP Services (Pihole UI, Pihole DNS)
  • LoadBalancer Services (Pihole DNS bind to host)
  • Time Zone (pihole-configmap)
  • Admin email (pihole-configmap)
  • Web Password (pihole-secret)
$ kubectl apply -f k8s/04-pihole.yaml

Test Pihole installation


  • Persistent volume type hostPath (/var/lib/wireguard)
  • Persistent Volume claim
  • Config Map (Timezone, server url, number of peers, etc)
  • Wireguard StatefulSet
  • LoadBalancer Service (Wireguard listen port 51820/udp)
  • Timezone (wireguard-configmap)
  • Server URL (wireguard-configmap)
  • Number of peers (wireguard-configmap)
$ kubectl apply -f k8s/05-wireguard.yaml

Wireguard Client config

Extra (Ingress Configuration for Pihole UI)

Deploy cert-manager

$ kubectl apply -f

Deploy Cluster Issuer (Let’s Encrypt)

$ kubectl apply -f k8s/06-cluster-issuer-letsencrypt.yaml


$ kubectl apply -f k8s/07-ingress.yaml

How to use



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Ivan Moreno

Ivan Moreno

Engineer || MSc student || DevOps in progress