PHPackages travisghansen/kubernetes-pfsense-controller - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. travisghansen/kubernetes-pfsense-controller ActiveProject[API Development](/categories/api) travisghansen/kubernetes-pfsense-controller =========================================== Integrate Kubernetes and pfSense v0.5.14(3y ago)210323[3 issues](https://github.com/travisghansen/kubernetes-pfsense-controller/issues)[1 PRs](https://github.com/travisghansen/kubernetes-pfsense-controller/pulls)Apache-2.0PHPPHP >=7.3.0 Since Sep 17Pushed 3y ago16 watchersCompare [ Source](https://github.com/travisghansen/kubernetes-pfsense-controller)[ Packagist](https://packagist.org/packages/travisghansen/kubernetes-pfsense-controller)[ Docs](https://github.com/travisghansen/kubernetes-pfsense-controller/)[ RSS](/packages/travisghansen-kubernetes-pfsense-controller/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (10)Dependencies (5)Versions (35)Used By (0) [![Image](https://camo.githubusercontent.com/0038c4632088ad1373d7b867b87e8b59001d84549acc20eff55c9b99ce877c78/68747470733a2f2f696d672e736869656c64732e696f2f646f636b65722f70756c6c732f7472617669736768616e73656e2f6b756265726e657465732d706673656e73652d636f6e74726f6c6c65722e737667)](https://camo.githubusercontent.com/0038c4632088ad1373d7b867b87e8b59001d84549acc20eff55c9b99ce877c78/68747470733a2f2f696d672e736869656c64732e696f2f646f636b65722f70756c6c732f7472617669736768616e73656e2f6b756265726e657465732d706673656e73652d636f6e74726f6c6c65722e737667)[![Image](https://camo.githubusercontent.com/f12d9bead20745ba3aae3fa5358be5cf5939015bbc9200d3131293e87352806a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7472617669736768616e73656e2f6b756265726e657465732d706673656e73652d636f6e74726f6c6c65722f6d61696e2e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/f12d9bead20745ba3aae3fa5358be5cf5939015bbc9200d3131293e87352806a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7472617669736768616e73656e2f6b756265726e657465732d706673656e73652d636f6e74726f6c6c65722f6d61696e2e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265) Intro ===== [](#intro) [kubernetes-pfsense-controller (kpc)](https://github.com/travisghansen/kubernetes-pfsense-controller) works hard to keep [pfSense](https://www.pfsense.org/) and [Kubernetes](https://kubernetes.io/) in sync and harmony. The primary focus is to facilitate a first-class Kubernetes cluster by integrating and/or implementing features that generally do not come with bare-metal installation(s). This is generally achieved using the standard Kubernetes API along with the xmlrpc API for pfSense. Speaking broadly the Kubernetes API is `watch`ed and appropriate updates are sent to pfSense (`config.xml`) via xmlrpc calls along with appropriate reload/restart/update/sync actions to apply changes. Please note, this controller is not designed to run multiple instances simultaneously (ie: do NOT crank up the replicas). Disclaimer: this is new software bound to have bugs. Please make a backup before using it as it may eat your configuration. Having said that, all known code paths appear to be solid and working without issue. If you find a bug, please report it! Updated disclaimer: this software is no longer very new, but is still bound to have bugs. Continue to make backups as appropriate :) Having said that, it's been used for multiple years now on several systems and has yet to do anything evil. Installation ============ [](#installation) Various files are available in the `deploy` directory of the project, alter to your needs and `kubectl apply`. Alternatively, a helm repository is provided for convenience: ``` helm repo add kubernetes-pfsense-controller https://travisghansen.github.io/kubernetes-pfsense-controller-chart/ helm repo update # create your own values.yaml file and edit as appropriate # https://github.com/travisghansen/kubernetes-pfsense-controller-chart/blob/master/stable/kubernetes-pfsense-controller/values.yaml helm upgrade \ --install \ --create-namespace \ --namespace kpc \ --values values.yaml \ kpc-primary \ kubernetes-pfsense-controller/kubernetes-pfsense-controller ``` Support Matrix -------------- [](#support-matrix) Generally speaking `kpc` tracks the most recent versions of both kubernetes and pfSense. Having said that reasonable attempts will be made to support older versions of both. `kpc` currently works with any `2.4+` (known working up to `2.5.2`) version of pfSense and probably very old kubernetes versions (known working up to `1.22`). Plugins ======= [](#plugins) The controller is comprised of several plugins that are enabled/disabled/configured via a Kubernetes ConfigMap. Details about each plugin follows below. metallb ------- [](#metallb) [MetalLB](https://metallb.universe.tf/) implements `LoadBalancer` type `Service`s in Kubernetes. This is done via any combination of Layer2 or BGP type configurations. Layer2 requires no integration with pfSense, however, if you want to leverage the BGP implementation you need a BGP server along with neighbor configuration. `kpc` *dynamically* updates bgp neighbors for you in pfSense by continually monitoring cluster `Node`s. While this plugin is *named* `metallb` it does not **require** MetalLB to be installed or in use. It can be used with `kube-vip` or any other service that requires BGP peers/neighbors. The plugin assumes you've already installed openbgp or frr and configured it as well as created a `group` to use with MetalLB. ``` metallb: enabled: true nodeLabelSelector: nodeFieldSelector: # pick 1 implementation # bgp-implementation: openbgp bgp-implementation: frr options: frr: template: peergroup: metallb openbgp: template: md5sigkey: md5sigpass: groupname: metallb row: - parameters: announce all parmvalue: ``` haproxy-declarative ------------------- [](#haproxy-declarative) `haproxy-declarative` plugin allows you to declaratively create HAProxy frontend/backend definitions as `ConfigMap`resources in the cluster. When declaring backends however, the pool of servers can/will be dynamically created/updated based on cluster nodes. See [declarative-example.yaml](examples/declarative-example.yaml) for an example. ``` haproxy-declarative: enabled: true ``` haproxy-ingress-proxy --------------------- [](#haproxy-ingress-proxy) `haproxy-ingress-proxy` plugin allows you to mirror cluster ingress rules handled by an ingress controller to HAProxy running on pfSense. If you run pfSense on the network edge with non-cluster services already running, you now can dynamically inject new rules to route traffic into your cluster while simultaneously running non-cluster services. To achieve this goal, new 'shared' HAProxy frontends are created and attached to an **existing** HAProxy frontend. Each created frontend should also set an existing backend. Note that existing frontend(s)/backend(s) can be created manually or using the `haproxy-declarative` plugin. When creating the parent frontend(s) please note that the selected type should be `http / https(offloading)` to fully support the feature. If type `ssl / https(TCP mode)` is selected (`SSL Offloading` may be selected or not in the `External address` table) `sni` is used for routing logic and **CANNOT** support path-based logic which implies a 1:1 mapping between `host` entries and backing `service`s. Type `tcp` will not work and any `Ingress` resources that would be bound to a frontend of this type are ignored. Combined with `haproxy-declarative` you can create a dynamic backend service (ie: your ingress controller) and subsequently dynamic frontend services based off of cluster ingresses. This is generally helpful when you cannot or do not for whatever reason create wildcard frontend(s) to handle incoming traffic in HAProxy on pfSense. Optionally, on the ingress resources you can set the following annotations: `haproxy-ingress-proxy.pfsense.org/frontend`and `haproxy-ingress-proxy.pfsense.org/backend` to respectively set the frontend and backend to override the defaults. In advanced scenarios it is possible to provide a template definition of the shared frontend using the `haproxy-ingress-proxy.pfsense.org/frontendDefinitionTemplate` annotation (see [\#19 (comment)](https://github.com/travisghansen/kubernetes-pfsense-controller/issues/19#issuecomment-1416576678)). ``` haproxy-ingress-proxy: enabled: true ingressLabelSelector: ingressFieldSelector: # works in conjunction with the ingress annotation 'haproxy-ingress-proxy.pfsense.org/enabled' # if defaultEnabled is empty or true, you can disable specific ingresses by setting the annotation to false # if defaultEnabled is false, you can enable specific ingresses by setting the annotation to true defaultEnabled: true # can optionally be comma-separated list if you want the same ingress to be served by multiple frontends defaultFrontend: http-80 defaultBackend: traefik #allowedHostRegex: "/.*/" ``` DNS Helpers ----------- [](#dns-helpers) `kpc` provides various options to manage DNS entries in pfSense based on cluster state. Note that these options can be used in place of or in conjunction with [external-dns](https://github.com/kubernetes-incubator/external-dns) to support powerful setups/combinations. ### pfsense-dns-services [](#pfsense-dns-services) `pfsense-dns-services` watches for services of type `LoadBalancer` that have the annotation `dns.pfsense.org/hostname`with the value of the desired hostname (optionally you may specifiy a comma-separated list of hostnames). `kpc` will create the DNS entry in unbound/dnsmasq. Note that to actually get an IP on these services you'll likely need `MetalLB` deployed in the cluster (regardless of the `metallb` plugin running or not). ``` pfsense-dns-services: enabled: true serviceLabelSelector: serviceFieldSelector: #allowedHostRegex: "/.*/" dnsBackends: dnsmasq: enabled: true unbound: enabled: true ``` ### pfsense-dns-ingresses [](#pfsense-dns-ingresses) `pfsense-dns-ingresses` watches ingresses and automatically creates DNS entries in unbound/dnsmasq. This requires proper support from the ingress controller to set IPs on the ingress resources. ``` pfsense-dns-ingresses: enabled: true ingressLabelSelector: ingressFieldSelector: # works in conjunction with the ingress annotation 'dns.pfsense.org/enabled' # if defaultEnabled is empty or true, you can disable specific ingresses by setting the annotation to false # if defaultEnabled is false, you can enable specific ingresses by setting the annotation to true defaultEnabled: true #allowedHostRegex: "/.*/" dnsBackends: dnsmasq: enabled: true unbound: enabled: true ``` ### pfsense-dns-haproxy-ingress-proxy [](#pfsense-dns-haproxy-ingress-proxy) `pfsense-dns-haproxy-ingress-proxy` monitors the HAProxy rules created by the `haproxy-ingress-proxy` plugin and creates host aliases for each entry. To do so you create an arbitrary host in unbound/dnsmasq (something like `.k8s`) and bind that host to the frontend through the config option `frontends.`. Any proxy rules created for that frontend will now automatically get added as aliases to the configured `hostname`. Make sure the static `hostname` created in your DNS service of choice points to the/an IP bound to the corresponding `frontend`. ``` pfsense-dns-haproxy-ingress-proxy: enabled: true # NOTE: this regex is in *addition* to the regex applied to the haproxy-ingress-proxy plugin #allowedHostRegex: "/.*/" dnsBackends: dnsmasq: enabled: true unbound: enabled: true frontends: http-80: hostname: http-80.k8s primary_frontend_name2: hostname: primary_frontend_name2.k8s ``` Notes ===== [](#notes) `regex` parameters are passed through php's `preg_match()` method, you can test your syntax using that. Also note that if you want to specify a regex ending (`$`), you must escape it in yaml as 2 `$`(ie: `#allowedHostRegex: "/.example.com$$/"`). `kpc` stores it's stateful data in the cluster as a ConfigMap (kube-system.kubernetes-pfsense-controller-store by default). You can review the data there to gain understanding into what the controller is managing. You may need/want to bump up the `webConfigurator` setting for `Max Processes` to ensure enough simultaneous connections can be established. Each `kpc` instance will only require 1 process (ie: access to the API is serialized by `kpc`). Links ----- [](#links) - - TODO ==== [](#todo) 1. base64 advanced fields (haproxy) 2. taint haproxy config so it shows 'apply' button in interface? 3. \_index and id management 4. ssl certs name/serial 5. build docker images 6. create manifests 7. ensure pfsync items are pushed as appropriate 8. perform config rollbacks when appropriate? 9. validate configuration(s) to ensure proper schema Development =========== [](#development) check store values ------------------ [](#check-store-values) ``` kubectl -n kube-system get configmaps kubernetes-pfsense-controller-store -o json | jq -crM '.data."haproxy-declarative"' | jq . kubectl -n kube-system get configmaps kubernetes-pfsense-controller-store -o json | jq -crM '.data."metallb"' | jq . ... ``` HAProxy ------- [](#haproxy) XML config structure (note that `ha_backends` is actually frontends...it's badly named): ``` haproxy ha_backends item item ... ha_pools item ha_servers item item ... item ... ``` ### Links [](#links-1) - Links ----- [](#links-2) - - - - - - - ### Health Score 32 — LowBetter than 71% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity22 Limited adoption so far Community21 Small or concentrated contributor base Maturity58 Maturing project, gaining track record Bus Factor1 Top contributor holds 95% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~52 days Recently: every ~20 days Total 33 Last Release 1120d ago PHP version history (2 changes)v0.1.0PHP >=7.2.0 v0.1.8PHP >=7.3.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/d74fac235db729c441642ba84858af4404e8e39be614455c7aed9c07339c9340?d=identicon)[travisghansen](/maintainers/travisghansen) --- Top Contributors [![travisghansen](https://avatars.githubusercontent.com/u/225404?v=4)](https://github.com/travisghansen "travisghansen (76 commits)")[![cptaffe](https://avatars.githubusercontent.com/u/5462583?v=4)](https://github.com/cptaffe "cptaffe (1 commits)")[![slamdev](https://avatars.githubusercontent.com/u/341000?v=4)](https://github.com/slamdev "slamdev (1 commits)")[![toxuin](https://avatars.githubusercontent.com/u/868268?v=4)](https://github.com/toxuin "toxuin (1 commits)")[![valtzu](https://avatars.githubusercontent.com/u/652734?v=4)](https://github.com/valtzu "valtzu (1 commits)") --- Tags apiclientclustercontrollerdnsfirewallhaproxyhaproxy-configurationingressingress-controlleringress-dnsk8skubernetesload-balancermetallbpfsensephpphpapiclientdnscontrollerfirewallclusterkubernetesk8shaproxyloadbalancerIngresspfsensemetallbingresses ### Embed Badge ![Health badge](/badges/travisghansen-kubernetes-pfsense-controller/health.svg) ``` [![Health](https://phpackages.com/badges/travisghansen-kubernetes-pfsense-controller/health.svg)](https://phpackages.com/packages/travisghansen-kubernetes-pfsense-controller) ``` ### Alternatives [renoki-co/php-k8s Control your Kubernetes clusters with this PHP-based Kubernetes client. It supports any form of authentication, the exec API, and it has an easy implementation for CRDs. 321669.7k2](/packages/renoki-co-php-k8s)[kunalvarma05/dropbox-php-sdk Dropbox PHP API V2 SDK (Unofficial) 3633.0M18](/packages/kunalvarma05-dropbox-php-sdk)[travisghansen/kubernetes-client-php Kubernetes API client in PHP supporting REST operations and Watches 3726.0k3](/packages/travisghansen-kubernetes-client-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)