diff --git a/public/docs-static/img/how-to-guides/kubernetes/kubernetes-api-policy.png b/public/docs-static/img/how-to-guides/kubernetes/kubernetes-api-policy.png new file mode 100644 index 00000000..c7064567 Binary files /dev/null and b/public/docs-static/img/how-to-guides/kubernetes/kubernetes-api-policy.png differ diff --git a/public/docs-static/img/how-to-guides/kubernetes/kubernetes-api.png b/public/docs-static/img/how-to-guides/kubernetes/kubernetes-api.png new file mode 100644 index 00000000..bc733a20 Binary files /dev/null and b/public/docs-static/img/how-to-guides/kubernetes/kubernetes-api.png differ diff --git a/public/docs-static/img/how-to-guides/kubernetes/resources-1.png b/public/docs-static/img/how-to-guides/kubernetes/resources-1.png new file mode 100644 index 00000000..bf39dcee Binary files /dev/null and b/public/docs-static/img/how-to-guides/kubernetes/resources-1.png differ diff --git a/public/docs-static/img/how-to-guides/kubernetes/resources-policy.png b/public/docs-static/img/how-to-guides/kubernetes/resources-policy.png new file mode 100644 index 00000000..57fc6154 Binary files /dev/null and b/public/docs-static/img/how-to-guides/kubernetes/resources-policy.png differ diff --git a/public/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key-with-extra-labels.png b/public/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key-with-extra-labels.png new file mode 100644 index 00000000..3292d233 Binary files /dev/null and b/public/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key-with-extra-labels.png differ diff --git a/public/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key.png b/public/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key.png new file mode 100644 index 00000000..a72d61dd Binary files /dev/null and b/public/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 1777e72c..fb72b45d 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -188,10 +188,21 @@ export const docsNavigation = [ isOpen: false, links: [ {title: 'Enable post quantum cryptography', href: '/how-to/enable-post-quantum-cryptography' }, - {title: 'Deploying with Jamf Pro', href: '/how-to/jamf-pro-netbird-integration' }, - {title: 'Deploying with Kandji', href: '/how-to/kandji-netbird-integration' }, - - + { + title: 'MDM', + isOpen: true, + links: [ + {title: 'Deploying with Jamf Pro', href: '/how-to/jamf-pro-netbird-integration' }, + {title: 'Deploying with Kandji', href: '/how-to/kandji-netbird-integration' }, + ] + }, + { + title: 'Kubernetes', + isOpen: true, + links: [ + {title: 'Operator', href: '/how-to/kubernetes-operator' }, + ] + }, ] }, diff --git a/src/pages/how-to/kubernetes-operator.mdx b/src/pages/how-to/kubernetes-operator.mdx new file mode 100644 index 00000000..549ca83f --- /dev/null +++ b/src/pages/how-to/kubernetes-operator.mdx @@ -0,0 +1,331 @@ +# Access Private Kubernetes Clusters with NetBird Kubernetes Operator + +Accessing private Kubernetes clusters can be challenging, especially when connecting from remote locations or +having multiple clusters to manage. NetBird Kubernetes operator simplifies this process by enabling secure access +to your Kubernetes clusters using custom resource configurations and annotations to expose your cluster and services in your NetBird network. + +The NetBird Kubernetes operator automatically creates [Networks and Resources](/how-to/networks) in your NetBird account, allowing you to +seamlessly access your Kubernetes services and control plane from your NetBird network. + +## Deployment + +### Prerequisites + +- (Recommended) helm version 3+ +- kubectl version v1.11.3+. +- Access to a Kubernetes v1.11.3+ cluster. +- (Recommended) Cert Manager. + +### Installation +You have two methods of installing the NetBird Kubernetes operator: using Helm or the install.yaml file. + +#### Using Helm +1. Add helm repository. +```shell +helm repo add netbirdio https://netbirdio.github.io/kubernetes-operator +``` +2. (Recommended) Install [cert-manager](https://cert-manager.io/docs/installation/#default-static-install) for k8s API to communicate with the NetBird operator. +```shell +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml +``` +3. Add NetBird API token. You can create a PAT by following the steps [here](/how-to/access-netbird-public-api#creating-a-service-user). +```shell +kubectl create namespace netbird +kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret) +``` + + Replace `~/nb-pat.secret` with your NetBird API key. + + +4. (Recommended) Create a [`values.yaml`](https://github.com/netbirdio/kubernetes-operator/blob/main/examples/ingress/values.yaml) file, check `helm show values netbirdio/kubernetes-operator` for more info. +```yaml +ingress: + enabled: true + router: + enabled: true + +netbirdAPI: + keyFromSecret: "netbird-mgmt-api-key" + +# by default the managementURL points to the NetBird cloud service: https://api.netbird.io:443 +# managementURL: "https://netbird.example.io:443" +``` +5. Install using helm install: +```shell +helm install --create-namespace -f values.yaml -n netbird netbird-operator netbirdio/kubernetes-operator +``` +6. Check installation +```shell +kubectl -n netbird get pods +``` +Output should be similar to: +``` +NAME READY STATUS RESTARTS AGE +netbird-operator-kubernetes-operator-67769f77db-tmnfn 1/1 Running 0 42m +``` +```shell +kubectl -n netbird get services +``` +Output should be similar to: +```shell +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +netbird-operator-kubernetes-operator-metrics ClusterIP 192.168.194.165 8080/TCP 47m +netbird-operator-kubernetes-operator-webhook-service ClusterIP 192.168.194.222 443/TCP 47m +``` +### Updating or Modifying the Operator Configuration +The configuration or version update of the operator can be done with `helm upgrade`: +```shell +helm upgrade --create-namespace -f values.yaml -n netbird netbird-operator ./helm/kubernetes-operator + ``` + +#### Using install.yaml + +install.yaml only includes a very basic template for deploying a stripped-down version of Kubernetes-operator. +This option does not include any configurations for ingress capabilities and requires the cert-manager to be installed. + + +```shell +kubectl create namespace netbird +kubectl apply -n netbird -f https://raw.githubusercontent.com/netbirdio/kubernetes-operator/refs/heads/main/manifests/install.yaml +``` +## Expose Kubernetes Control Plane to your NetBird Network +To access your Kubernetes control plane from a NetBird network, you can expose your Kubernetes control plane as a +[NetBird resource](/how-to/networks#resources) by enabling the following option in the operator values: + +```yaml +ingres: + enabled: true + kubernetesAPI: + enabled: true +``` +The operator will create a NetBird network resource similar to the example below: + +

+ API +

+ +## Expose Kubernetes Services to NetBird Network + +Kubernetes services is a common way to route traffic to your application pods. With the NetBird operator `ingress` you can expose services to your +NetBird network as resources by using annotations in your services. The operator will create networks, resources, +and add routing peers to your NetBird configuration. + +By default, the ingress configuration is disabled. You can enable it with the following values using the helm chart: +```yaml +ingress: + enabled: true + router: + enabled: true +``` + +You can expose services using the annotations `netbird.io/expose: "true"` and `netbird.io/groups: "resource-group"`; see the example below: +```yaml +apiVersion: v1 +kind: Service +metadata: + name: app + annotations: + netbird.io/expose: "true" + netbird.io/groups: "app-access" +spec: + selector: + app: app + ports: + - protocol: TCP + port: 8080 + targetPort: 80 + type: ClusterIP +``` + +This will create a Network and a resource similar to the example below: +

+ resources +

+ + + Ingress DNS Resolution requires enabled `DNS Wildcard Routing` and at least one DNS Nameserver configured for clients. + Learn more about Networks settings [here](/how-to/networks#enable-dns-wildcard-routing). + + +Other annotations can be used to further configure the resources created by the operator: + +|Annotation|Description|Default|Valid Values| +|:---:|:---:|:---:|:---:| +|`netbird.io/expose`| Expose service using NetBird Network Resource ||(`null`, `true`)| +|`netbird.io/groups`| Comma-separated list of group names to assign to Network Resource. If non-existing, the operator will create them for you. |`{ClusterName}-{Namespace}-{Service}`|Any comma-separated list of strings.| +|`netbird.io/resource-name`| Network Resource name |`{Namespace}-{Service}`|Any valid network resource name, make sure they're unique!| +|`netbird.io/policy`| Name(s) of NBPolicy to propagate service ports as destination. ||Comma-separated list of names of any NBPolicy resource| +|`netbird.io/policy-ports`| Narrow down exposed ports in a policy. Leave empty for all ports. ||Comma-separated integer list, integers must be between 0-65535| +|`netbird.io/policy-protocol`| Narrow down protocol for use in a policy. Leave empty for all protocols. ||(`tcp`,`udp`)| + +## Control Access to Your Kubernetes Resources with Access Control Policies +By default, resources created by the operator will not have any access control policies assigned to them. +To allow the operator to manage your access control policies, configure policy bases in your `values.yaml` file. +In this file, you can define source groups, name suffixes, and other settings related to access control policies. +Afterward, you can tag the policies in your service annotations using the annotation `netbird.io/policy: "policy-base"`. +See the examples `values.yaml` below: + +```yaml +ingress: + enabled: true + router: + enabled: true + policies: + app-users: + name: App users # Required, name of policy in NetBird console + description: Policy for app users access # Optional + sourceGroups: # Required, name of groups to assign as source in Policy. + - app-users + protocols: # Optional, restricts protocols allowed to resources, defaults to ['tcp', 'udp']. + - tcp + bidirectional: false + k8s-admins: + name: App admins + sourceGroups: + - app-admins +``` +After adding the policy base and [applying the configuration](#updating-or-modifying-the-operator-configuration), +you can use the `app-users` and `k8s-admins` bases for your services and Kubernetes API configurations. + +### Linking Policy Bases to the Kubernetes API Service +To link a policy base to the Kubernetes API, we need to update the operator configuration by adding the policy and groups to the `kubernetesAPI` key as follows: +```yaml + kubernetesAPI: + enabled: false + groups: + - k8s-access + policies: + - k8s-admins +``` +After updating and [applying the configuration](#updating-or-modifying-the-operator-configuration), you should see a policy similar to the one below: +

+ resources policy +

+ +### Linking Policy Bases to Kubernetes Services +You can link policy bases with the annotation `netbird.io/policy:` where you can simply add one or more bases to the service, +see the example below where we link the base `"app-users"` to our app service: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: app + annotations: + netbird.io/expose: "true" + netbird.io/groups: "app-access" + netbird.io/policy: "app-users" +spec: + selector: + app: app + ports: + - protocol: TCP + port: 8080 + targetPort: 80 + type: ClusterIP +``` + +The operator will create a policy in your management account similar to the one below: +

+ resources policy +

+ +You can reference multiple policy bases using a comma separated list of policy bases: `netbird.io/policy: "app-users,app-admins"` + +## Accessing Remote Services Using Sidecars +To access services running in different locations from your Kubernetes clusters, you can deploy NetBird sidecars—additional +containers that run alongside your Kubernetes service containers within the same pod. + +A NetBird sidecar joins your network as a regular peer and becomes a subject to access control, routing, +and DNS configurations as any other peer in your NetBird network. This allows your Kubernetes application traffic to be securely routed +through the NetBird network, enabling egress-like access to remote services from your Kubernetes services across various locations or cloud providers. + +To enable sidecar functionality in your deployments, you first need to generate a setup key, either via the UI (see image below) +or by following [this guide](/how-to/register-machines-using-setup-keys) for more details. + +

+ Setup Keys +

+ +Next, you'll create a secret in Kubernetes and add a new resource called `NBSetupKey`. The `NBSetupKey` name can then be +referenced in your deployments or daemon sets to specify which setup key should be used when injecting a sidecar into +your application pods. Below is an example of a secret and an `NBSetupKey` resource: + +```yaml +apiVersion: v1 +stringData: + setupkey: EEEEEEEE-EEEE-EEEE-EEEE-EEEEEEEEEEEE +kind: Secret +metadata: + name: app-setup-key +``` +NBSetupKey: +```yaml +apiVersion: netbird.io/v1 +kind: NBSetupKey +metadata: + name: app-setup-key +spec: + # Optional, overrides management URL for this setupkey only + # defaults to https://api.netbird.io + # managementURL: https://netbird.example.com + secretKeyRef: + name: app-setup-key # Required + key: setupkey # Required +``` + +After adding the resource, you can reference the `NBSetupKey` in your deployments or daemon-sets as shown below: + +```yaml +kind: Deployment +... +spec: +... + template: + metadata: + annotations: + netbird.io/setup-key: app-setup-key # Must match the name of an NBSetupKey object in the same namespace +... + spec: + containers: +... +``` + +### Using Extra Labels to Access Multiple Pods Using the Same Name +Starting with `v0.27.0`, NetBird supports extra DNS labels, allowing you to define extended DNS names for peers. This enables grouping peers under a shared DNS name and distributing traffic using DNS round-robin load balancing. + +To use this feature, create a setup key with the “Allow Extra DNS Labels” option enabled. See the example below for reference: + +

+ Setup keys with extra labels +

+ +And add the annotation `netbird.io/extra-dns-labels` to your pod; see the example below: + +```yaml +kind: Deployment +... +spec: +... + template: + metadata: + annotations: + netbird.io/setup-key: app-setup-key # Must match the name of an NBSetupKey object in the same namespace + netbird.io/extra-dns-labels: "app" +... + spec: + containers: +... +``` +With this setup, other peers in your NetBird network can reach these pods using the domain `app.` +(e.g., for NetBird cloud, app.netbird.cloud). The access will be made using a DNS round-robin fashion for multiple pods. + +## Get started +

+ +

+ +- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) +- Follow us [on Twitter](https://twitter.com/netbird) +- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-31rofwmxc-27akKd0Le0vyRpBcwXkP0g) +- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub diff --git a/src/pages/how-to/networks.mdx b/src/pages/how-to/networks.mdx index 4d33f135..2725b9c4 100644 --- a/src/pages/how-to/networks.mdx +++ b/src/pages/how-to/networks.mdx @@ -103,6 +103,11 @@ You can enable DNS resolution on the routing peer by accessing your account `Set | **Support for site-2-site IP ranges routing?** | No, but support is planned | Yes, when you create a network route without access control groups | +## Use cases +- [Routing traffic to multiple IP resources](/how-to/routing-traffic-to-multiple-resources) +- [Accessing restricted website domain resources](/how-to/accessing-restricted-domain-resources) +- [Accessing entire domains within networks](/how-to/accessing-entire-domains-within-networks) + ## Get started

diff --git a/src/pages/how-to/register-machines-using-setup-keys.mdx b/src/pages/how-to/register-machines-using-setup-keys.mdx index 294e8c44..5fa4f9a0 100644 --- a/src/pages/how-to/register-machines-using-setup-keys.mdx +++ b/src/pages/how-to/register-machines-using-setup-keys.mdx @@ -23,9 +23,14 @@ There are 2 types of setup keys: ## Ephemeral peers -You can create a setup key with the ephemeral peers option enabled. -Peers that are offline for over 10 minutes will be removed automatically. +Ephemeral peers allows you to add temporary peers to your network and having them automatically removed once they become offline for over 10 minutes. +This is particular useful when you want to run NetBird with Kubernetes pods or autoscaling groups. +## Allow Extra DNS Labels +This flag allows peers added with the setup key to add additional extra DNS labels to their peers. +This is useful when you want to add more context to your peers and access these peers using a single domain name. + +```bash {{ title: 'Starting NetBird Client' }} ## Using setup keys Setup keys are available in the NetBird Management Dashboard under the `Setup Keys` tab [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).