pihole

Configures Pi-hole as the Kubernetes DNS layer for cluster.home hostnames and LAN-wide resolution.

1|Updated Apr 3, 2026

Search Tags:#kubernetes #dns #homelab #pihole #cilium #loadbalancer #split-dns

Ready to run

npx skills add https://github.com/villadalmine/infra --skill pihole-villadalmine

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: pihole
Source: https://github.com/villadalmine/infra/tree/main/.agents/skills/pihole
Command: npx skills add https://github.com/villadalmine/infra --skill pihole-villadalmine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill removes the guesswork from running Pi-hole as the DNS entrypoint for a Kubernetes homelab, so cluster hostnames resolve reliably and workstation DNS setup stays consistent.

Core Features & Use Cases

Cluster DNS Routing: Maps cluster.home names to the shared gateway IP while forwarding all other queries upstream.
Kubernetes Exposure: Uses Cilium LoadBalancer IP allocation, shared TCP and UDP services, and persistent storage for a stable Pi-hole deployment.
Workstation Split-DNS: Guides Fedora Silverblue and macOS clients to use Pi-hole only for cluster domains without changing their general internet DNS.
Operational Reliability: Captures Pi-hole 6.x startup timing, listening mode, probe tuning, and troubleshooting patterns for slow boot or neighbor-cache issues.

Quick Start

Configure Pi-hole in the cluster and point your workstation to its DNS IP so cluster.home hostnames resolve through the homelab gateway.

Frequently Asked Questions about pihole

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I configure Pi-hole for split-DNS on a Kubernetes homelab cluster?▼

Configure Pi-hole as the Kubernetes DNS layer to map cluster.home hostnames to a shared gateway IP while forwarding other queries upstream, ensuring reliable LAN-wide name resolution. It applies Helm values and persistent storage for stable deployment.

How does Cilium LoadBalancer expose Pi-hole DNS ports in K3s?▼

Cilium LoadBalancer allocates stable IPs for shared TCP and UDP port 53 services, exposing Pi-hole DNS reliably across the homelab K3s cluster. This setup requires persistent storage and startup probe adjustments to keep web access healthy.

Can I use Pi-hole only for cluster domains without changing my workstation's general internet DNS?▼

Yes, workstation split-DNS guides Fedora Silverblue and macOS clients to use Pi-hole specifically for cluster.home domains. This keeps your general internet DNS intact while resolving homelab hostnames through the Pi-hole gateway.

Why does Pi-hole 6.x fail startup probes in Kubernetes and how do I fix it?▼

Pi-hole 6.x startup timing and listening mode often cause probe failures in Kubernetes. Adjusting startup probe thresholds and tuning the listening mode resolves slow boot issues and keeps DNS and web access healthy.

What is the best way to resolve cluster.home hostnames across a homelab K3s environment?▼

Running Pi-hole as the DNS entrypoint maps cluster.home names to the shared gateway IP, providing predictable resolution for homelab K3s clusters. Cilium LoadBalancer services ensure reliable UDP and TCP port 53 exposure.