{"id":48648229,"url":"https://github.com/work-systems-ltd/freeradius-k8s-operator","last_synced_at":"2026-04-15T13:00:54.755Z","repository":{"id":350171548,"uuid":"1205355717","full_name":"Work-Systems-Ltd/freeradius-k8s-operator","owner":"Work-Systems-Ltd","description":"Declarative FreeRADIUS in kubernetes for ISPs","archived":false,"fork":false,"pushed_at":"2026-04-10T06:27:02.000Z","size":76115,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-12T10:13:40.065Z","etag":null,"topics":["freeradius","freeradius-kubernetes","freeradius-server","kubernetes","kubernetes-operator","radius","radius-server"],"latest_commit_sha":null,"homepage":"https://work-systems-ltd.github.io/freeradius-k8s-operator/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Work-Systems-Ltd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-08T22:16:50.000Z","updated_at":"2026-04-10T12:09:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Work-Systems-Ltd/freeradius-k8s-operator","commit_stats":null,"previous_names":["work-systems-ltd/freeradius-k8s-operator"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Work-Systems-Ltd/freeradius-k8s-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Work-Systems-Ltd%2Ffreeradius-k8s-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Work-Systems-Ltd%2Ffreeradius-k8s-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Work-Systems-Ltd%2Ffreeradius-k8s-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Work-Systems-Ltd%2Ffreeradius-k8s-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Work-Systems-Ltd","download_url":"https://codeload.github.com/Work-Systems-Ltd/freeradius-k8s-operator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Work-Systems-Ltd%2Ffreeradius-k8s-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31749763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["freeradius","freeradius-kubernetes","freeradius-server","kubernetes","kubernetes-operator","radius","radius-server"],"created_at":"2026-04-10T08:11:02.707Z","updated_at":"2026-04-13T11:01:01.348Z","avatar_url":"https://github.com/Work-Systems-Ltd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"media/logo.png\" alt=\"FreeRADIUS K8s Operator\" width=\"280\"\u003e\n\n# FreeRADIUS, the Kubernetes-native way.\n\nA Kubernetes operator built for ISP BNG and broadband subscriber management at scale. It turns RADIUS clusters, NAS clients, and unlang policies into native custom resources — so the AAA layer behind your BNGs lives in Git, rolls out with `kubectl apply`, and scales like everything else in your cluster.\n\n[![Go](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go\u0026logoColor=white)](https://go.dev)\n[![Kubernetes](https://img.shields.io/badge/Kubernetes-1.28+-326CE5?logo=kubernetes\u0026logoColor=white)](https://kubernetes.io)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-GitHub_Pages-blue?logo=github)](https://Work-Systems-Ltd.github.io/freeradius-k8s-operator/)\n[![Discord](https://img.shields.io/badge/Discord-join_chat-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/gKQz4kpM)\n\n[**Quick Start**](#quick-start) · [**Why?**](#why-this-exists) · [**Examples**](example/) · [**Docs**](https://Work-Systems-Ltd.github.io/freeradius-k8s-operator/)\n\n\u003c/div\u003e\n\n---\n\n\u003e [!WARNING]\n\u003e This project is under active development and is **not yet production-ready**. APIs, CRD schemas, and behaviors may change without notice. Star the repo to follow along — we're close.\n\n## How it works\n\n```mermaid\nflowchart LR\n    subgraph Git[\"GitOps / kubectl apply\"]\n        CR[\"RadiusCluster\u003cbr/\u003eRadiusClient\u003cbr/\u003eRadiusPolicy\"]\n    end\n\n    subgraph K8s[\"Kubernetes Cluster\"]\n        OP[\"FreeRADIUS\u003cbr/\u003eOperator\"]\n        CFG[\"Rendered ConfigMap\u003cbr/\u003eradiusd.conf\u003cbr/\u003eclients.conf\u003cbr/\u003esites / modules\"]\n        SEC[(\"Secrets\u003cbr/\u003eshared keys\u003cbr/\u003eDB creds\u003cbr/\u003eTLS certs\")]\n        subgraph FR[\"FreeRADIUS Pods\"]\n            P1[\"auth\"]\n            P2[\"acct\"]\n            P3[\"CoA\"]\n        end\n        OBS[\"Metrics\u003cbr/\u003eServiceMonitor\u003cbr/\u003eAlerts\"]\n    end\n\n    subgraph Net[\"Network Edge\"]\n        BNG[\"BNGs / OLTs\u003cbr/\u003eNAS devices\u003cbr/\u003eWiFi APs\"]\n        SUB[\"Subscribers\u003cbr/\u003ePPPoE / IPoE / 802.1X\"]\n    end\n\n    CR --\u003e|watches| OP\n    OP --\u003e|renders| CFG\n    OP -.-\u003e|mounts| SEC\n    CFG --\u003e FR\n    SEC -.-\u003e FR\n    OP --\u003e|scrapes| OBS\n    FR \u003c--\u003e|RADIUS\u003cbr/\u003eauth / acct / CoA| BNG\n    SUB \u003c--\u003e BNG\n\n    classDef crd fill:#0c0c0f,stroke:#22c55e,stroke-width:1px,color:#fafafa\n    classDef op fill:#0c0c0f,stroke:#22c55e,stroke-width:2px,color:#fafafa\n    classDef pod fill:#0c0c0f,stroke:#a1a1aa,stroke-width:1px,color:#fafafa\n    classDef edge fill:#0c0c0f,stroke:#71717a,stroke-width:1px,color:#a1a1aa\n    class CR crd\n    class OP op\n    class CFG,SEC,OBS pod\n    class P1,P2,P3 pod\n    class BNG,SUB edge\n```\n\nYou declare what you want in YAML. The operator watches your CRDs, renders a complete FreeRADIUS config (`radiusd.conf`, `clients.conf`, sites and modules), mounts secrets from Kubernetes Secrets, and rolls out pods behind split-mode Services for auth / accounting / CoA — all with HPA, PDBs, and Prometheus metrics wired up. Your BNGs and NAS devices talk to the resulting Service exactly like any other RADIUS server.\n\n## Why this exists\n\nRADIUS is the quiet workhorse behind every ISP on the planet. Every PPPoE session, every IPoE lease, every DHCP hand-off, every CoA bandwidth change — it all flows through RADIUS and into a BNG. And yet in 2026, running AAA for a BNG fleet still means SSH'ing into pet VMs to hand-edit `radiusd.conf`, copy-pasting `clients.conf` across replicas every time a new OLT shows up, and rolling shared secrets by restarting RADIUS servers one at a time. HA is whatever you cobble together with keepalived and cron. CoA for live PPPoE sessions is an afterthought.\n\nKubernetes solved this for web apps a decade ago. This operator brings the same experience to ISP-grade RADIUS: declarative specs, GitOps-friendly rollouts, automatic config rendering, secret mounting, HPA, PDBs, split auth/accounting/CoA services, and Prometheus metrics — all behind three simple CRDs purpose-built for BNG subscriber AAA.\n\n```yaml\napiVersion: radius.operator.io/v1alpha1\nkind: RadiusCluster\nmetadata:\n  name: bng-aaa\nspec:\n  image: freeradius/freeradius-server:3.2.3\n  replicas: 6\n  autoscaling:\n    enabled: true\n    minReplicas: 6\n    maxReplicas: 30\n  modules:\n    - name: sql\n      type: rlm_sql\n      enabled: true\n      sql:\n        dialect: postgresql\n        server: postgres.aaa.svc.cluster.local\n        port: 5432\n        database: radius\n        login: radius\n        passwordRef:\n          name: sql-db-credentials\n          key: password\n  services:\n    auth:       { type: LoadBalancer }\n    accounting: { type: LoadBalancer }\n    coa:        { type: LoadBalancer }   # scale each independently\n```\n\n`kubectl apply -f` and you have a scaled, self-healing, observable RADIUS tier sitting behind your BNGs.\n\n## How it compares\n\n| | Hand-rolled FreeRADIUS | Helm chart | **This operator** |\n|---|:---:|:---:|:---:|\n| Declarative clients \u0026 policies as CRDs | — | — | **Yes** |\n| Automatic config rendering + rollout | — | partial | **Yes** |\n| Structured unlang policy engine | — | — | **Yes** |\n| Secrets from K8s Secrets (not ConfigMaps) | manual | partial | **Yes** |\n| HPA, PDB, split-mode services | manual | partial | **Yes** |\n| Prometheus exporter + ServiceMonitor + alerts | manual | — | **Yes** |\n| GitOps-native | manual | **Yes** | **Yes** |\n\nEvery backend you actually use is supported out of the box: SQL (MySQL, PostgreSQL, SQLite, MSSQL, Oracle, Mongo), LDAP, REST, Redis, Files, and EAP (TLS/TTLS/PEAP) — with shared connection-pool tuning.\n\n## Quick Start\n\n```bash\n# 1. Install the operator (chart ships the CRDs, RBAC, Deployment, and metrics Service)\nhelm install freeradius-operator ./charts/freeradius-operator \\\n  --namespace freeradius-system --create-namespace\n\n# 2. Deploy a FreeRADIUS instance — either with Helm...\nhelm install bng-prod ./charts/freeradius-cluster \\\n  --namespace radius-prod --create-namespace\n\n# ...or straight from a ready-to-apply example\nkubectl apply -f example/basic/\n\n# 3. Watch it come up\nkubectl get radiusclusters,radiusclients,radiuspolicies -A\n```\n\n\u003e CRDs are installed from the operator chart's `crds/` directory and are **not** upgraded by `helm upgrade`. To update CRDs, re-apply `config/crd/` or the chart's `crds/` directory with `kubectl apply -f`.\n\n### Two charts, two jobs\n\n| Chart | Installs | When to use |\n|---|---|---|\n| [`charts/freeradius-operator`](charts/freeradius-operator/) | CRDs, RBAC, operator Deployment, metrics Service | Once per cluster. Owns the controller that watches and reconciles RadiusCluster / RadiusClient / RadiusPolicy resources. |\n| [`charts/freeradius-cluster`](charts/freeradius-cluster/) | A RadiusCluster + any number of RadiusClients, RadiusPolicies, and inline Secrets | Once per FreeRADIUS instance. Thin pass-through around the CRD specs — every field of `RadiusClusterSpec` is available under `cluster.spec` in values. |\n\nThe workload chart is optional. If you prefer plain manifests or GitOps with Kustomize, apply files from [`example/`](example/) directly and skip the second chart entirely.\n\nReady-to-apply examples live in [`example/`](example/), organized by scenario:\n\n| Example | What it shows |\n|---|---|\n| [`basic/`](example/basic/) | Minimal files-backed auth with VLAN assignment policy |\n| [`sql/`](example/sql/) | PostgreSQL-backed auth with a tuned `rlm_sql` connection pool |\n| [`rest-api/`](example/rest-api/) | Authentication via an external REST API |\n| [`ldap/`](example/ldap/) | LDAP / Active Directory authentication |\n| [`ha-redundant/`](example/ha-redundant/) | Redundant SQL failover with autoscaling and PDB |\n| [`split-mode/`](example/split-mode/) | Independent scaling for auth, accounting, and CoA |\n| [`raw-override/`](example/raw-override/) | Escape hatch for custom modules and raw unlang |\n\nFor a full walkthrough — deploying, scaling, managing clients and policies, troubleshooting, and observability — see the **[documentation](https://Work-Systems-Ltd.github.io/freeradius-k8s-operator/)**.\n\n## Who is this for?\n\n- **ISPs running BNGs at scale** — PPPoE, IPoE, DHCP option-82, CoA bandwidth changes, subscriber accounting. The primary use case.\n- **WISPs and altnets** managing hundreds of OLTs, BNGs, and edge NAS devices across regions and POPs.\n- **Network teams** running campus WiFi, 802.1X, or guest portals and tired of hand-editing config files.\n- **Platform engineers** bringing legacy carrier-grade AAA into a GitOps workflow.\n- **Homelabbers** who want real RADIUS without pets.\n\n## Community\n\n- **[Documentation](https://Work-Systems-Ltd.github.io/freeradius-k8s-operator/)** — getting started, concepts, CRD reference, guides, troubleshooting\n- **[Discord](https://discord.gg/gKQz4kpM)** — chat with the maintainers and other operators\n- **[Issues](../../issues)** — bug reports and feature requests\n- **[Discussions](../../discussions)** — questions, ideas, show-and-tell\n\nIf this project saved you an afternoon of `radiusd.conf` wrangling, **give it a star** — it's the single biggest thing you can do to help others find it.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, local kind setup, code standards, and PR guidelines. First-timers: look for issues labeled `good first issue`.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt with care by [Work Systems Ltd](https://github.com/Work-Systems-Ltd) and contributors.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwork-systems-ltd%2Ffreeradius-k8s-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwork-systems-ltd%2Ffreeradius-k8s-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwork-systems-ltd%2Ffreeradius-k8s-operator/lists"}