feat: add NetbirdReverseProxy CRD to deploy account-scoped BYOP clusters on Kubernetes

[christianhuth]

The motivation

Netbird's Bring Your Own Proxy feature lets an account run its own reverse proxy on its own infrastructure, routing traffic exclusively for that account over the Netbird mesh. The official deployment model is Docker-only. Users running Netbird on Kubernetes — especially those already using the operator for NetworkResource and NetworkRouter — have no declarative, operator-managed way to deploy the proxy alongside their workloads.

A NetbirdReverseProxy CRD would bring the proxy lifecycle into Kubernetes: declarative config, secret references, HA via replicas, and certificate persistence via PVCs.

The suggested implementation

Add a NetbirdReverseProxy custom resource. The operator reconciles it into a Deployment (or StatefulSet when a certificate PVC is needed), a Service exposing ports 80 and 443, and the necessary Secret volume mounts.

apiVersion: netbird.io/v1alpha1
kind: NetbirdReverseProxy
metadata:
  name: my-proxy
spec:
  domain: proxy.company.com
  managementURL: https://netbird.example.com:443   # defaults to operator managementURL if omitted
  token:
    secretName: netbird-proxy-token
    secretKey: token                               # NB_PROXY_TOKEN
  privateMode: false                               # NB_PROXY_PRIVATE
  logLevel: info                                   # NB_PROXY_LOG_LEVEL

Operator responsibilities:

• Deploy the netbirdio/reverse-proxy container with the correct environment variables
• Expose ports 80 and 443 via a LoadBalancer Service (type configurable)
• Mount the certificate PVC when specified and set NB_PROXY_CERT_LOCK_METHOD=k8s-lease automatically

Acceptance criteria

• kubectl apply of a NetbirdReverseProxy CR results in a running proxy that registers with the management server and appears in GET /api/reverse-proxies/clusters as type: account
• Deleting the CR tears down the Deployment and Service
• The managementURL field defaults to the operator's own managementURL when omitted

If you think this is a good feature for the Netbird Operator I would like to contribute with a MR.

[christianhuth]

The docs describe two cluster types: account-scoped (BYOP, token is account-scoped) and shared (platform-managed, available to all accounts on the management instance). In self-hosted deployments the management platform operator may also want to run shared proxy clusters.

Does the netbirdio/reverse-proxy binary support both modes, or are shared clusters managed differently at the platform level? If the same binary supports both, the CRD should include a type: shared | account field. If not, shared cluster support would belong in the management platform deployment rather than this operator.

[kgrotel]

this one is a nearly complete CRD -> https://github.com/ccbash/kubernetes-operator/blob/release/v0.11.x/config/crd/bases/netbird.io_reverseproxyservices.yaml

[phillebaba]

The only thing I am debating in regards to this feature is if the operator should take responsibility to manage the actual proxy deployment. While it does make things simpler it also limits the customization options. Things get complicated as everyones specific use cases show up.

[christianhuth]

Which specific use cases do you have in mind or are you worried about?

[christianhuth]

I have created a Helm Chart to deploy the Reverse Proxy, until we have an operator-based solution: https://artifacthub.io/packages/helm/christianhuth/netbird-reverse-proxy