feat!: Major refactor with standardized labels, admin config restructure, doh replacement and security features

CHANGELOG.md

@@ -0,0 +1,113 @@
+# Release Notes
+
+This release brings significant improvements to the Pi-hole Helm chart, including modernized Kubernetes standards and enhanced secure DNS capabilities.
+
+## Breaking Changes
+
+### Standardized Kubernetes Labels
+- **Selector labels have changed** from `app`/`release` to `app.kubernetes.io/name` and `app.kubernetes.io/instance`
+- **Migration required**: Existing deployments must be fully uninstalled and reinstalled due to immutable selector fields
+- All resources now use standardized labels following Helm best practices:
+  - `helm.sh/chart`
+  - `app.kubernetes.io/name`
+  - `app.kubernetes.io/instance`
+  - `app.kubernetes.io/version`
+  - `app.kubernetes.io/managed-by`
+
+### Admin Password Configuration moved
+- **`adminPassword` moved to `admin.password`** - The root-level `adminPassword` value has been moved into the `admin` section
+- Update your values files: change `adminPassword: "xxx"` to `admin.password: "xxx"`
+
+### DNS-over-HTTPS (DoH) Overhaul
+- **Replaced cloudflared with dnscrypt-proxy** for encrypted DNS resolution
+- Cloudflare deprecated the proxy-dns feature in cloudflared
+- More flexible and feature-rich encrypted DNS solution
+
+### Use same terminology as pihole
+- renamed `whitelist` to `allowed` and `blacklist` to `denied` for inclusive terminology
+- Update your values files:
+  - `whitelist: [...]` → `allowed: [...]`
+  - `blacklist: [...]` → `denied: [...]`
+
+## Features
+
+- add commonLabels option to apply labels to all deployed objects ([#347](https://github.com/MoJo2600/pihole-kubernetes/issues/347))
+
+### Enhanced Health Probes
+- **Added startup probes** for both Pi-hole and DoH containers
+- Startup probes allow containers sufficient time to initialize before liveness/readiness probes begin
+- Reduced `initialDelaySeconds` to 0 (startup probe handles the delay)
+- Added DNS resolution check (`dig`) to probe commands for more accurate health detection
+- Leads to faster pod startups (estimated around 80% or higher)
+
+**Why this matters:**
+- **No arbitrary wait times** - Previously, `initialDelaySeconds` had to be set to an estimated value. If the container was ready faster, you waited unnecessarily. If slower, health checks failed.
+- **Adaptive initialization** - Startup probes actively check if the container is ready. Once successful, liveness/readiness probes take over immediately.
+- **Accurate health detection** - The `dig` command verifies actual DNS functionality rather than just open TCP ports. An open port doesn't mean DNS is working.
+- **Faster failure detection** - With `failureThreshold: 3`, unhealthy pods are detected and restarted more quickly.
+
+### ServiceAccount Support
+- Added configurable ServiceAccount with optional token mounting
+- Better security controls for pod identity management
+
+**Why this matters:**
+- **Principle of Least Privilege** - Pods can run with a dedicated ServiceAccount instead of the default account, which often has excessive permissions.
+- **Controllable token mounting** - `automountServiceAccountToken: false` prevents unnecessary API credentials from being mounted into the pod (security risk if compromised).
+- **RBAC integration** - Enables fine-grained permissions if Pi-hole needs Kubernetes API access (e.g., for service discovery).
+- **Audit compliance** - Dedicated ServiceAccounts enable better tracking of API access in audit logs.
+
+### Security Context Support (Experimental)
+- Added `podSecurityContext` and `containerSecurityContext` configuration options
+- Backwards compatible with existing `privileged` and `capabilities` values
+- Documented Pi-hole limitations regarding rootless operation
+
+**Why this matters:**
+- **Explicit security configuration** - Allows setting `privileged: false` to prevent full host access.
+- **Seccomp profiles** - Pod-level `seccompProfile: RuntimeDefault` enables syscall filtering.
+- **Transparency** - Documentation explains why detailed capability management provides limited benefit for Pi-hole (requires 10+ capabilities including NET_ADMIN, NET_RAW, SETUID, etc.).
+
+**Important limitations:**
+- Pi-hole Docker image requires root at startup for gravity database, crontab, and setcap operations
+- `runAsNonRoot`, `runAsUser`, `runAsGroup` are **not supported**
+- `allowPrivilegeEscalation: false` is **not supported** (required for setcap)
+- `readOnlyRootFilesystem: true` is **not supported** (Pi-hole writes to /etc/pihole, /var/log)
+
+### Dynamic NOTES.txt
+- Installation notes now dynamically reflect actual service configuration
+- Context-aware access instructions based on service type (Ingress, LoadBalancer, NodePort, ClusterIP)
+- Conditional DHCP section and improved kubectl commands with namespace flags
+
+### Helm Chart Modernization
+- Upgraded Helm chart to apiVersion v2
+- Optimized `.helmignore` to reduce packaged chart size
+
+## Improvements
+
+### DNS Testing
+- Extended Helm tests with DNS resolution verification
+- New `test-pihole-dns.yaml` validates Pi-hole DNS functionality via nslookup queries
+
+### Documentation
+- Added `loadBalancerIP` deprecation notice for Kubernetes 1.24+
+- Documented recommended migration path using cloud provider annotations (e.g., `metallb.universe.tf/loadBalancerIPs` for MetalLB)
+
+## Migration Guide
+
+Due to the breaking change in selector labels, you must perform a full reinstall:
+
+```bash
+# 1. Backup your Pi-hole configuration (if using persistent storage)
+kubectl cp <namespace>/<pihole-pod>:/etc/pihole ./pihole-backup
+
+# 2. Backup your helm custom values
+helm get values pihole -n <namespace> > pihole-values-backup.yaml
+
+# 3. Uninstall existing release
+helm uninstall pihole -n <namespace>
+
+# 4. Delete the PersistentVolumeClaim if you want a fresh start (optional)
+kubectl delete pvc <release-name>-pihole -n <namespace>
+
+# 5. Install new version
+helm install <release-name> mojo2600/pihole -n <namespace> -f pihole-values-backup.yaml
+```

README.md

@@ -3,9 +3,12 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-27-blue.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-> [!IMPORTANT]  
+> [!IMPORTANT]
 > Additional maintainers wanted! I need help maintaining this chart. Please see [the discussion here](https://github.com/MoJo2600/pihole-kubernetes/discussions/393)
 
+> [!WARNING]
+> **v3 Proposal Repository**: This Repository contains an unfinished rewrite with breaking changes intended as a proposal for v3. Do not use in production. For the stable version, please use the https://github.com/MoJo2600/pihole-kubernetes. For an overview of the changes, take a look at the [CHANGELOG.md](CHANGELOG.md).
+
 [Helm](https://helm.sh) repo for different charts which can be installed on [Kubernetes](https://kubernetes.io)
 
 Further documentation including chart keys, types, and default values is at https://hub.helm.sh/charts/mojo2600/pihole
@@ -28,6 +31,28 @@ helm repo update
   ```
 
 
+## Troubleshooting
+
+### pihole-FTL: no process found (with hostNetwork: true)
+
+When deploying Pi-hole with `hostNetwork: true`, the container may crash with the error `pihole-FTL: no process found`.
+
+**Cause:** A port required by FTL (e.g., UDP port 53, 67, or others) is already in use on the host, preventing the FTL process from binding.
+
+**Solutions:**
+
+1. **DHCP Helper Approach** (recommended for DHCP):
+   - Deploy Pi-hole WITHOUT `hostNetwork: true`
+   - Use a separate [dhcphelper](https://github.com/homeall/dhcphelper) pod with host networking
+   - The helper receives DHCP broadcasts and forwards them as unicast to Pi-hole
+   - See the complete example: [charts/pihole/examples/dhcphelper/](charts/pihole/examples/dhcphelper/)
+
+2. **LoadBalancer with MetalLB**:
+   - Use MetalLB to expose services without host networking
+   - Note: This does NOT work for DHCP (Layer 2 broadcast limitation)
+
+**Why DHCP requires special handling:** DHCP operates at OSI Layer 2 using broadcast messages. Standard Kubernetes networking and LoadBalancers work at Layer 3 (IP) and cannot forward these broadcasts. Either the Pi-hole pod needs direct access to the host network, or a relay/helper must bridge the gap.
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people:

charts/pihole/.helmignore

@@ -18,8 +18,17 @@
 # Various IDEs
 .project
 .idea/
+.vscode/
 *.tmproj
 
+# Backup and temporary files
+*.orig
+
+# CI/CD files
+.github/
+.gitlab-ci.yml
+.travis.yml
+
 # Manually added entries
 ci/
 examples/

charts/pihole/Chart.yaml

@@ -1,8 +1,9 @@
-apiVersion: v1
+apiVersion: v2
+type: application
 description: Installs pihole in kubernetes
 home: https://github.com/MoJo2600/pihole-kubernetes/tree/main/charts/pihole
 name: pihole
-appVersion: "2025.11.1"
+appVersion: "2026.02.0"
 # Do not touch will be updated during release
 version: 2.35.0
 sources: