Skip to content

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

Closed

Description

@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.

Activity

  1. christianhuth commented on Jun 16, 2026

    @christianhuth
    Author

    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.

  2. linear-code commented on Jun 16, 2026

    @linear-code
  3. locked and limited conversation to collaborators on Jun 19, 2026
  4. converted this issue into a discussion #331 on Jun 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions