# pihole Installs pihole in kubernetes ![Version: 2.26.2](https://img.shields.io/badge/Version-2.26.2-informational?style=flat-square) ![AppVersion: 2024.07.0](https://img.shields.io/badge/AppVersion-2024.07.0-informational?style=flat-square) [![All Contributors](https://img.shields.io/badge/all_contributors-27-blue.svg?style=flat-square)](#contributors-) ## Source Code * * * * ## Installation Jeff Geerling on YouTube made a video about the installation of this chart: [![Jeff Geerling on YouTube](https://img.youtube.com/vi/IafVCHkJbtI/0.jpg)](https://youtu.be/IafVCHkJbtI?t=2655) ### Add Helm repository ```shell 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 ```console 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: ```yaml 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: ```yaml 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): ```bash 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](docs/Values.md#admin.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 ...`) 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 | | | ## 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®](https://pi-hole.net/) ## Contributing Feel free to contribute by making a [pull request](https://github.com/MoJo2600/pihole-kubernetes/pull/new/master). Please read [Contribution Guide](../../CONTRIBUTING.md) 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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2)