iskm/maabara
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
maabara/manifests/pihole/README.md

34 KiB
Raw Permalink Blame History

pihole

Installs pihole in kubernetes

Version: 2.26.2 AppVersion: 2024.07.0 All Contributors

Source Code

Installation

Jeff Geerling on YouTube made a video about the installation of this chart:

Jeff Geerling on YouTube

Add Helm repository

helm repo add mojo2600 https://mojo2600.github.io/pihole-kubernetes/
helm repo update

Configure the chart

The following items can be set via --set flag during installation or configured by editing the values.yaml directly.

Configure the way how to expose pihole service:

  • Ingress: The ingress controller must be installed in the Kubernetes cluster.
  • ClusterIP: Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster.
  • LoadBalancer: Exposes the service externally using a cloud provider’s load balancer.

My settings in values.yaml

dnsmasq:
  customDnsEntries:
    - address=/nas/192.168.178.10
 
  customCnameEntries:
    - cname=foo.nas,nas

persistentVolumeClaim:
  enabled: true

serviceWeb:
  loadBalancerIP: 192.168.178.252
  annotations:
    metallb.universe.tf/allow-shared-ip: pihole-svc
  type: LoadBalancer

serviceDns:
  loadBalancerIP: 192.168.178.252
  annotations:
    metallb.universe.tf/allow-shared-ip: pihole-svc
  type: LoadBalancer

Configuring Upstream DNS Resolvers

By default, pihole-kubernetes will configure pod DNS automatically to use Google's 8.8.8.8 nameserver for upstream DNS resolution. You can configure this, or opt-out of pod DNS configuration completely.

Changing The Upstream DNS Resolver

For example, to use Cloudflare's resolver:

podDnsConfig:
  enabled: true
  policy: "None"
  nameservers:
  - 127.0.0.1
  - 1.1.1.1

Disabling Pod DNS Configuration

If you have other DNS policy at play (for example, when running a service mesh), you may not want to have pihole-kubernetes control this behavior. In that case, you can disable DNS configuration on pihole pods:

podDnsConfig:
  enabled: false

Upgrading

To 2.0.0

This version splits the DHCP service into its own resource and puts the configuration to serviceDhcp.

If you have not changed any configuration for serviceDns, you don’t need to do anything.

If you have changed your serviceDns configuration, copy your serviceDns section into a new serviceDhcp section.

To 1.8.22

To enhance compatibility for Traefik, we split the TCP and UDP service into Web and DNS. This means, if you have a dedicated configuration for the service, you have to update your values.yaml and add a new configuration for this new service.

Before (In my case, with metallb):

serviceTCP:
  loadBalancerIP: 192.168.178.252
  annotations:
    metallb.universe.tf/allow-shared-ip: pihole-svc

serviceUDP:
  loadBalancerIP: 192.168.178.252
  annotations:
    metallb.universe.tf/allow-shared-ip: pihole-svc

After:

serviceWeb:
  loadBalancerIP: 192.168.178.252
  annotations:
    metallb.universe.tf/allow-shared-ip: pihole-svc

serviceDns:
  loadBalancerIP: 192.168.178.252
  annotations:
    metallb.universe.tf/allow-shared-ip: pihole-svc

Version 1.8.22 has switched from the deprecated ingress api extensions/v1beta1 to the go forward version networking.k8s.io/v1. This means that your cluster must be running 1.19.x as this api is not available on older versions. If necessary to run on an older Kubernetes Version, it can be done by modifying the ingress.yaml and changing the api definition back. The backend definition would also change from:

            backend:
              service:
                name: \{\{ $serviceName \}\}
                port:
                  name: http

to:

            backend:
              serviceName: \{\{ $serviceName \}\}
              servicePort: http

Uninstallation

To uninstall/delete the my-release deployment (NOTE: --purge is default behaviour in Helm 3+ and will error):

helm delete --purge my-release

Configuration

The following table lists the configurable parameters of the pihole chart and the default values.

Values

Key Type Default Description
DNS1 string "8.8.8.8" default upstream DNS 1 server to use
DNS2 string "8.8.4.4" default upstream DNS 2 server to use
adlists object {} list of adlists to import during initial start of the container
admin object {"annotations":null,"enabled":true,"existingSecret":"","passwordKey":"password"} Use an existing secret for the admin password.
admin.annotations string nil Specify annotations to be added to the secret
admin.enabled bool true If set to false admin password will be disabled, adminPassword specified above and the pre-existing secret (if specified) will be ignored.
admin.existingSecret string "" Specify an existing secret to use as admin password
admin.passwordKey string "password" Specify the key inside the secret to use
adminPassword string "admin" Administrator password when not using an existing secret (see below)
affinity object {}
antiaff.avoidRelease string "pihole1" Here you can set the pihole release (you set in helm install <releasename> ...) you want to avoid
antiaff.enabled bool false set to true to enable antiaffinity (example: 2 pihole DNS in the same cluster)
antiaff.namespaces list [] Here you can pass namespaces to be part of those inclueded in anti-affinity
antiaff.strict bool true Here you can choose between preferred or required
blacklist object {} list of blacklisted domains to import during initial start of the container
capabilities object {}
customVolumes.config object {} any volume type can be used here
customVolumes.enabled bool false set this to true to enable custom volumes
dnsHostPort.enabled bool false set this to true to enable dnsHostPort
dnsHostPort.port int 53 default port for this pod
dnsmasq object {"additionalHostsEntries":[],"customCnameEntries":[],"customDnsEntries":[],"customSettings":null,"staticDhcpEntries":[],"upstreamServers":[]} DNS MASQ settings
dnsmasq.additionalHostsEntries list [] Dnsmasq reads the /etc/hosts file to resolve ips. You can add additional entries if you like
dnsmasq.customCnameEntries list [] Here we specify custom cname entries that should point to A records or elements in customDnsEntries array. The format should be: - cname=cname.foo.bar,foo.bar - cname=cname.bar.foo,bar.foo - cname=cname record,dns record
dnsmasq.customDnsEntries list [] Add custom dns entries to override the dns resolution. All lines will be added to the pihole dnsmasq configuration.
dnsmasq.customSettings string nil Other options
dnsmasq.staticDhcpEntries list [] Static DHCP config
dnsmasq.upstreamServers list [] Add upstream dns servers. All lines will be added to the pihole dnsmasq configuration
doh.enabled bool false set to true to enabled DNS over HTTPs via cloudflared
doh.envVars object {} Here you can pass environment variables to the DoH container, for example:
doh.name string "cloudflared" name
doh.probes object {"liveness":{"enabled":true,"failureThreshold":10,"initialDelaySeconds":60,"probe":{"exec":{"command":["nslookup","-po=5053","cloudflare.com","127.0.0.1"]}},"timeoutSeconds":5}} Probes configuration
doh.probes.liveness object {"enabled":true,"failureThreshold":10,"initialDelaySeconds":60,"probe":{"exec":{"command":["nslookup","-po=5053","cloudflare.com","127.0.0.1"]}},"timeoutSeconds":5} Configure the healthcheck for the doh container
doh.probes.liveness.enabled bool true set to true to enable liveness probe
doh.probes.liveness.failureThreshold int 10 defines the failure threshold for the liveness probe
doh.probes.liveness.initialDelaySeconds int 60 defines the initial delay for the liveness probe
doh.probes.liveness.probe object {"exec":{"command":["nslookup","-po=5053","cloudflare.com","127.0.0.1"]}} customize the liveness probe
doh.probes.liveness.timeoutSeconds int 5 defines the timeout in secondes for the liveness probe
doh.pullPolicy string "IfNotPresent" Pull policy
doh.repository string "crazymax/cloudflared" repository
doh.tag string "latest"
dualStack.enabled bool false set this to true to enable creation of DualStack services or creation of separate IPv6 services if serviceDns.type is set to "LoadBalancer"
extraContainers list []
extraEnvVars object {} extraEnvironmentVars is a list of extra enviroment variables to set for pihole to use
extraEnvVarsSecret object {} extraEnvVarsSecret is a list of secrets to load in as environment variables.
extraInitContainers list [] any initContainers you might want to run before starting pihole
extraObjects list [] any extra kubernetes manifests you might want
extraVolumeMounts object {} any extra volume mounts you might want
extraVolumes object {} any extra volumes you might want
ftl object {} values that should be added to pihole-FTL.conf
hostNetwork string "false" should the container use host network
hostname string "" hostname of pod
image.pullPolicy string "IfNotPresent" the pull policy
image.repository string "pihole/pihole" the repostory to pull the image from
image.tag string "" the docker tag, if left empty it will get it from the chart's appVersion
ingress object {"annotations":{},"enabled":false,"hosts":["chart-example.local"],"path":"/","tls":[]} Configuration for the Ingress
ingress.annotations object {} Annotations for the ingress
ingress.enabled bool false Generate a Ingress resource
maxSurge int 1 The maximum number of Pods that can be created over the desired number of ReplicaSet during updating.
maxUnavailable int 1 The maximum number of Pods that can be unavailable during updating
monitoring.podMonitor object {"enabled":false} Preferably adding prometheus scrape annotations rather than enabling podMonitor.
monitoring.podMonitor.enabled bool false set this to true to enable podMonitor
monitoring.sidecar object {"enabled":false,"image":{"pullPolicy":"IfNotPresent","repository":"ekofr/pihole-exporter","tag":"v0.3.0"},"port":9617,"resources":{"limits":{"memory":"128Mi"}}} Sidecar configuration
monitoring.sidecar.enabled bool false set this to true to enable podMonitor as sidecar
monitoring.sidecar.image.repository string "ekofr/pihole-exporter" the repository to use
nodeSelector object {} Node selector values
persistentVolumeClaim object {"accessModes":["ReadWriteOnce"],"annotations":{},"enabled":false,"size":"500Mi"} spec.PersitentVolumeClaim configuration
persistentVolumeClaim.annotations object {} Annotations for the PersitentVolumeClaim
persistentVolumeClaim.enabled bool false set to true to use pvc
persistentVolumeClaim.size string "500Mi" volume claim size
podAnnotations object {} Additional annotations for pods
podDisruptionBudget object {"enabled":false,"minAvailable":1} configure a Pod Disruption Budget
podDisruptionBudget.enabled bool false set to true to enable creating the PDB
podDisruptionBudget.minAvailable int 1 minimum number of pods Kubernetes should try to have running at all times
podDnsConfig.enabled bool true
podDnsConfig.nameservers[0] string "127.0.0.1"
podDnsConfig.nameservers[1] string "8.8.8.8"
podDnsConfig.policy string "None"
privileged string "false" should container run in privileged mode
probes object {"liveness":{"enabled":true,"failureThreshold":10,"initialDelaySeconds":60,"port":"http","scheme":"HTTP","timeoutSeconds":5,"type":"httpGet"},"readiness":{"enabled":true,"failureThreshold":3,"initialDelaySeconds":60,"port":"http","scheme":"HTTP","timeoutSeconds":5}} Probes configuration
probes.liveness.failureThreshold int 10 threshold until the probe is considered failing
probes.liveness.initialDelaySeconds int 60 wait time before trying the liveness probe
probes.liveness.timeoutSeconds int 5 timeout in seconds
probes.liveness.type string "httpGet" Generate a liveness probe 'type' defaults to httpGet, can be set to 'command' to use a command type liveness probe.
probes.readiness.enabled bool true Generate a readiness probe
probes.readiness.failureThreshold int 3 The failure threshold
probes.readiness.initialDelaySeconds int 60 Initial delay to wait for readiness check
probes.readiness.port string "http" The port
probes.readiness.timeoutSeconds int 5 The timeout in seconds
regex object {} list of blacklisted regex expressions to import during initial start of the container
replicaCount int 1 The number of replicas
resources object {} lines, adjust them as necessary, and remove the curly braces after 'resources:'.
serviceDhcp object {"annotations":{},"enabled":true,"externalTrafficPolicy":"Local","extraLabels":{},"loadBalancerIP":"","loadBalancerIPv6":"","nodePort":"","port":67,"type":"NodePort"} Configuration for the DHCP service on port 67
serviceDhcp.annotations object {} Annotations for the DHCP service
serviceDhcp.enabled bool true Generate a Service resource for DHCP traffic
serviceDhcp.externalTrafficPolicy string "Local" spec.externalTrafficPolicy for the DHCP Service
serviceDhcp.extraLabels object {} Labels for the DHCP service
serviceDhcp.loadBalancerIP string "" A fixed spec.loadBalancerIP for the DHCP Service
serviceDhcp.loadBalancerIPv6 string "" A fixed spec.loadBalancerIP for the IPv6 DHCP Service
serviceDhcp.nodePort string "" Optional node port for the DHCP service
serviceDhcp.port int 67 The port of the DHCP service
serviceDhcp.type string "NodePort" spec.type for the DHCP Service
serviceDns object {"annotations":{},"externalTrafficPolicy":"Local","extraLabels":{},"loadBalancerIP":"","loadBalancerIPv6":"","mixedService":false,"nodePort":"","port":53,"type":"NodePort"} Configuration for the DNS service on port 53
serviceDns.annotations object {} Annotations for the DNS service
serviceDns.externalTrafficPolicy string "Local" spec.externalTrafficPolicy for the DHCP Service
serviceDns.extraLabels object {} Labels for the DNS service
serviceDns.loadBalancerIP string "" A fixed spec.loadBalancerIP for the DNS Service
serviceDns.loadBalancerIPv6 string "" A fixed spec.loadBalancerIP for the IPv6 DNS Service
serviceDns.mixedService bool false deploys a mixed (TCP + UDP) Service instead of separate ones
serviceDns.nodePort string "" Optional node port for the DNS service
serviceDns.port int 53 The port of the DNS service
serviceDns.type string "NodePort" spec.type for the DNS Service
serviceWeb object {"annotations":{},"externalTrafficPolicy":"Local","extraLabels":{},"http":{"enabled":true,"nodePort":"","port":80},"https":{"enabled":true,"nodePort":"","port":443},"loadBalancerIP":"","loadBalancerIPv6":"","type":"ClusterIP"} Configuration for the web interface service
serviceWeb.annotations object {} Annotations for the DHCP service
serviceWeb.externalTrafficPolicy string "Local" spec.externalTrafficPolicy for the web interface Service
serviceWeb.extraLabels object {} Labels for the web interface service
serviceWeb.http object {"enabled":true,"nodePort":"","port":80} Configuration for the HTTP web interface listener
serviceWeb.http.enabled bool true Generate a service for HTTP traffic
serviceWeb.http.nodePort string "" Optional node port for the web HTTP service
serviceWeb.http.port int 80 The port of the web HTTP service
serviceWeb.https object {"enabled":true,"nodePort":"","port":443} Configuration for the HTTPS web interface listener
serviceWeb.https.enabled bool true Generate a service for HTTPS traffic
serviceWeb.https.nodePort string "" Optional node port for the web HTTPS service
serviceWeb.https.port int 443 The port of the web HTTPS service
serviceWeb.loadBalancerIP string "" A fixed spec.loadBalancerIP for the web interface Service
serviceWeb.loadBalancerIPv6 string "" A fixed spec.loadBalancerIP for the IPv6 web interface Service
serviceWeb.type string "ClusterIP" spec.type for the web interface Service
strategyType string "RollingUpdate" The spec.strategyTpye for updates
tolerations list [] Toleration
topologySpreadConstraints list [] Specify a priorityClassName priorityClassName: "" Reference: https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/
virtualHost string "pi.hole"
webHttp string "80" port the container should use to expose HTTP traffic
webHttps string "443" port the container should use to expose HTTPS traffic
whitelist object {} list of whitelisted domains to import during initial start of the container

Maintainers

Name Email Url
MoJo2600 christian.erhardt@mojo2k.de

Remarks

MetalLB 0.8.1+

pihole seems to work without issue in MetalLB 0.8.1+

MetalLB 0.7.3

MetalLB 0.7.3 has a bug, where the service is not announced anymore, when the pod changes (e.g. update of a deployment). My workaround is to restart the metallb-speaker-* pods.

Credits

Pi-hole®

Contributing

Feel free to contribute by making a pull request.

Please read Contribution Guide for more information on how you can contribute to this Chart.

Contributors ✨

Thanks goes to these wonderful people:


Christian Erhardt
Jeff Billimek
Steven Imle
Joseph Petersen
Simon Garcia
Andy Gilbreath
James Wilson

Krishnaswamy Subramanian
Lucas Romero
konturn
tdorsey
Ales Zelenik
Damien TOURDE
Jason Sievert

joshua-nord
Maximilian Bode
raackley
Sam Kleiner
Arpan Kapoor
Christian Rodriguez
Dave Cahill

golgoth31
Greg Jeanmart
Joseph Ball
Karlos
dza89
mikewhitley
Vashiru

sam-kleiner
Alex Gorbatchev
Alexander Rabenstein
David Fisher
Utku Özdemir
Morre Meyer
Donald Johnson

Winston R. Milling
Christopher Larivière
Justin Sievenpiper
beastob
Daniel Mühlbachler-Pietrzykowski
Erik Sundell
Kjeld Schouten-Lebbing

Brandon Wulf
DerRockWolf
brnl
Rafael Gaspar
Chadi El Masri
Dan Foulkes
George Rodrigues

Pascal Iske
Theo REY
Watteel Pascal
simon
Eric
Vincent
Clint

Philipp B.
ebCrypto
Ken Lasko
Mark Bundschuh
Max Rosin
Yang
dwarf-king-hreidmar

s94santos
Adam David
Ben Konicek
Gabisonfire
Giorgi Lekveishvili

This project follows the all-contributors specification. Contributions of any kind welcome!

Autogenerated from chart metadata using helm-docs v1.14.2