Skip to content

OSDOCS-10856: Add bpfman Operator #80208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 30, 2024
Merged

OSDOCS-10856: Add bpfman Operator #80208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1330,6 +1330,16 @@ Topics:
File: logging-network-security
- Name: Understanding the Ingress Node Firewall Operator
File: ingress-node-firewall-operator
- Name: eBPF manager Operator
Dir: ebpf_manager
Distros: openshift-enterprise,openshift-origin
Topics:
- Name: About the eBPF Manager Operator
File: ebpf-manager-operator-about
- Name: Installing the eBPF Manager Operator
File: ebpf-manager-operator-install
- Name: Deploying an eBPF program
File: ebpf-manager-operator-deploy
- Name: Egress Firewall
Dir: egress_firewall
Distros: openshift-enterprise,openshift-origin
Expand Down
15 changes: 15 additions & 0 deletions modules/nw-bpfman-infw-about.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
// Module included in the following assemblies:
//
// * networking/network_security/ingress-node-firewall-operator.adoc

:_mod-docs-content-type: PROCEDURE
[id="ingress-node-firewall-operator_{context}"]
= Ingress Node Firewall Operator integration

The Ingress Node Firewall uses link:https://www.kernel.org/doc/html/latest/bpf/index.html[eBPF] programs to implement some of its key firewall functionality. By default these eBPF programs are loaded into the kernel using a mechanism specific to the Ingress Node Firewall. You can configure the Ingress Node Firewall Operator to use the eBPF Manager Operator for loading and managing these programs instead.

When this integration is enabled, the following limitations apply:

- The Ingress Node Firewall Operator uses TCX if XDP is not available and TCX is incompatible with bpfman.
- The Ingress Node Firewall Operator daemon set pods remain in the `ContainerCreating` state until the firewall rules are applied.
- The Ingress Node Firewall Operator daemon set pods run as privileged.
51 changes: 51 additions & 0 deletions modules/nw-bpfman-infw-configure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
// Module included in the following assemblies:
//
// * networking/network_security/ebpf_manager/ebpf-manager-operator-about.adoc

:_mod-docs-content-type: PROCEDURE
[id="bpfman-infw-configure_{context}"]
= Configuring Ingress Node Firewall Operator to use the eBPF Manager Operator

The Ingress Node Firewall uses link:https://www.kernel.org/doc/html/latest/bpf/index.html[eBPF] programs to implement some of its key firewall functionality. By default these eBPF programs are loaded into the kernel using a mechanism specific to the Ingress Node Firewall.

As a cluster administrator, you can configure the Ingress Node Firewall Operator to use the eBPF Manager Operator for loading and managing these programs instead, adding additional security and observability functionality.

.Prerequisites

* You have installed the OpenShift CLI (`oc`).
* You have an account with administrator privileges.
* You installed the Ingress Node Firewall Operator.
* You have installed the eBPF Manager Operator.

.Procedure

. Apply the following labels to the `ingress-node-firewall-system` namespace:
+
[source,terminal]
----
$ oc label namespace openshift-ingress-node-firewall \
pod-security.kubernetes.io/enforce=privileged \
pod-security.kubernetes.io/warn=privileged --overwrite
----

. Edit the `IngressNodeFirewallConfig` object named `ingressnodefirewallconfig` and set the `ebpfProgramManagerMode` field:
+
.Ingress Node Firewall Operator configuration object
[source,yaml]
----
apiVersion: ingressnodefirewall.openshift.io/v1alpha1
kind: IngressNodeFirewallConfig
metadata:
name: ingressnodefirewallconfig
namespace: openshift-ingress-node-firewall
spec:
nodeSelector:
node-role.kubernetes.io/worker: ""
ebpfProgramManagerMode: <ebpf_mode>
----
+
--
where:

`<ebpf_mode>`: Specifies whether or not the Ingress Node Firewall Operator uses the eBPF Manager Operator to manage eBPF programs. Must be either `true` or `false`. If unset, eBPF Manager is not used.
--
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to add a list of the limitations of using bpfman with INFW somewhere. Maybe here or over in the bpfman Operator docs? Indicate that with bpfman still in Tech Preview, there are some nuances to using it. @msherif1234 has a better list, but here are a few that come to mind:

  • TCX is currently not supported in bpfman, which INFW uses as a backup if XDP is not supported. So INFW won't work in this release (will be available next release) with bpfman on systems that don't support XDP (i.e. ROSA).
  • When deployed with bpfman operator, the INFW daemonset will remain in the "container creating" state until the rules are applied. Everything is working fine, the INFW daemonset pods are just waiting for the eBPF maps to be created and volume mounted into the pods. It can't do anything until the maps are created anyway. This is a security feature which avoids mounting the eBPF maps on the host, which in turn avoids having to grant INFW pods access to the host filesystem.
  • Ideally when INFW is deployed with bpfman operator, the deamonset pods would run as unprivileged. There is an issue with perf event arrays (still being investigated) that is preventing access without privileged mode.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is more less the complete list not sure if need to consider enforce privileged to infw as limitation probably more of new requirements

107 changes: 107 additions & 0 deletions modules/nw-bpfman-operator-deploy.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
// Module included in the following assemblies:
//
// * networking/network_security/ebpf_manager/ebpf-manager-operator-deploy.adoc

:_mod-docs-content-type: PROCEDURE
[id="nw-bpfman-operator-deploy_{context}"]
= Deploying a containerized eBPF program

As a cluster administrator, you can deploy an eBPF program to nodes on your cluster. In this procedure, a sample containerized eBPF program is installed in the `go-xdp-counter` namespace.

.Prerequisites

* You have installed the OpenShift CLI (`oc`).
* You have an account with administrator privileges.
* You have installed the eBPF Manager Operator.

.Procedure

. To download the manifest, enter the following command:
+
[source,terminal]
----
$ curl -L https://github.com/bpfman/bpfman/releases/download/v0.5.1/go-xdp-counter-install-selinux.yaml -o go-xdp-counter-install-selinux.yaml
----

. To deploy the sample eBPF application, enter the following command:
+
[source,terminal]
----
$ oc create -f go-xdp-counter-install-selinux.yaml
----
+
.Example output
[source,text]
----
namespace/go-xdp-counter created
serviceaccount/bpfman-app-go-xdp-counter created
clusterrolebinding.rbac.authorization.k8s.io/xdp-binding created
daemonset.apps/go-xdp-counter-ds created
xdpprogram.bpfman.io/go-xdp-counter-example created
selinuxprofile.security-profiles-operator.x-k8s.io/bpfman-secure created
----

. To confirm that the eBPF sample application deployed successfully, enter the following command:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it might be nice to group all these confirmation steps into a single step (with substeps) or a separated verification section

+
[source,terminal]
----
$ oc get all -o wide -n go-xdp-counter
----
+
.Example output
[source,text]
----
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
pod/go-xdp-counter-ds-4m9cw 1/1 Running 0 44s 10.129.0.92 ci-ln-dcbq7d2-72292-ztrkp-master-1 <none> <none>
pod/go-xdp-counter-ds-7hzww 1/1 Running 0 44s 10.130.0.86 ci-ln-dcbq7d2-72292-ztrkp-master-2 <none> <none>
pod/go-xdp-counter-ds-qm9zx 1/1 Running 0 44s 10.128.0.101 ci-ln-dcbq7d2-72292-ztrkp-master-0 <none> <none>

NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE CONTAINERS IMAGES SELECTOR
daemonset.apps/go-xdp-counter-ds 3 3 3 3 3 <none> 44s go-xdp-counter quay.io/bpfman-userspace/go-xdp-counter:v0.5.0 name=go-xdp-counter
----

. To confirm that the example XDP program is running, enter the following command:
+
[source,terminal]
----
$ oc get xdpprogram go-xdp-counter-example
----
+
.Example output
[source,text]
----

NAME BPFFUNCTIONNAME NODESELECTOR STATUS
go-xdp-counter-example xdp_stats {} ReconcileSuccess
----

. To confirm that the XDP program is collecting data, enter the following command:
+
[source,terminal]
----
$ oc logs <pod_name> -n go-xdp-counter
----
+
Replace `<pod_name>` with the name of a XDP program pod, such as `go-xdp-counter-ds-4m9cw`.
+
.Example output
[source,text]
----
2024/08/13 15:20:06 15016 packets received
2024/08/13 15:20:06 93581579 bytes received

2024/08/13 15:20:09 19284 packets received
2024/08/13 15:20:09 99638680 bytes received

2024/08/13 15:20:12 23522 packets received
2024/08/13 15:20:12 105666062 bytes received

2024/08/13 15:20:15 27276 packets received
2024/08/13 15:20:15 112028608 bytes received

2024/08/13 15:20:18 29470 packets received
2024/08/13 15:20:18 112732299 bytes received

2024/08/13 15:20:21 32588 packets received
2024/08/13 15:20:21 113813781 bytes received
----
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need to list all bpfman operator objects that are customer facing we have a lot
-bpfapplications
-fentryPrograms
-fexitPrograms
-tcPrograms
-xdpPrograms
-tracePointPrograms
-kprobePrograms
-uprobePrograms

93 changes: 93 additions & 0 deletions modules/nw-bpfman-operator-installing-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
// Module included in the following assemblies:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we have this issue with other operators -- but why are we including the documentation here to install bpfman rather than link to the bpfman documentation itself?

//
// * networking/network_security/ebpf_manager/ebpf-manager-operator-install.adoc

:_mod-docs-content-type: PROCEDURE
[id="nw-bpfman-operator-installing-cli_{context}"]
= Installing the eBPF Manager Operator using the CLI

As a cluster administrator, you can install the Operator using the CLI.

.Prerequisites

* You have installed the OpenShift CLI (`oc`).
* You have an account with administrator privileges.

.Procedure

. To create the `bpfman` namespace, enter the following command:
+
[source,terminal]
----
$ cat << EOF| oc create -f -
apiVersion: v1
kind: Namespace
metadata:
labels:
pod-security.kubernetes.io/enforce: privileged
pod-security.kubernetes.io/enforce-version: v1.24
name: bpfman
EOF
----

. To create an `OperatorGroup` CR, enter the following command:
+
[source,terminal]
----
$ cat << EOF| oc create -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
name: bpfman-operators
namespace: bpfman
EOF
----

. Subscribe to the eBPF Manager Operator.

.. To create a `Subscription` CR for the eBPF Manager Operator, enter the following command:
+
[source,terminal]
----
$ cat << EOF| oc create -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: bpfman-operator
namespace: bpfman
spec:
name: bpfman-operator
channel: alpha
source: community-operators
sourceNamespace: openshift-marketplace
EOF
----

. To verify that the Operator is installed, enter the following command:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

similar comment to the above re: verification section or grouping under a single verification step

+
[source,terminal]
----
$ oc get ip -n bpfman
----
+
.Example output
[source,terminal,subs="attributes+"]
----
NAME CSV APPROVAL APPROVED
install-ppjxl security-profiles-operator.v0.8.5 Automatic true
----

. To verify the version of the Operator, enter the following command:

+
[source,terminal]
----
$ oc get csv -n bpfman
----
+
.Example output
[source,terminal,subs="attributes+"]
----
NAME DISPLAY VERSION REPLACES PHASE
bpfman-operator.v0.5.0 eBPF Manager Operator 0.5.0 bpfman-operator.v0.4.2 Succeeded
----
49 changes: 49 additions & 0 deletions modules/nw-bpfman-operator-installing-console.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
// Module included in the following assemblies:
//
// * networking/network_security/ebpf_manager/ebpf-manager-operator-install.adoc

////
Operator Hub capitalizes all Operator names; officially, it is eBPF Manager though.
////

:_mod-docs-content-type: PROCEDURE
[id="nw-bpfman-operator-installing-console_{context}"]
= Installing the eBPF Manager Operator using the web console

As a cluster administrator, you can install the eBPF Manager Operator using the web console.

.Prerequisites

* You have installed the OpenShift CLI (`oc`).
* You have an account with administrator privileges.

.Procedure

. Install the eBPF Manager Operator:

.. In the {product-title} web console, click *Operators* -> *OperatorHub*.

.. Select *eBPF Manager Operator* from the list of available Operators, and if prompted to *Show community Operator*, click *Continue*.

.. Click *Install*.

.. On the *Install Operator* page, under *Installed Namespace*, select *Operator recommended Namespace*.

.. Click *Install*.

. Verify that the eBPF Manager Operator is installed successfully:

.. Navigate to the *Operators* -> *Installed Operators* page.

.. Ensure that *eBPF Manager Operator* is listed in the *openshift-ingress-node-firewall* project with a *Status* of *InstallSucceeded*.
+
[NOTE]
====
During installation an Operator might display a *Failed* status.
If the installation later succeeds with an *InstallSucceeded* message, you can ignore the *Failed* message.
====
+
If the Operator does not have a *Status* of *InstallSucceeded*, troubleshoot using the following steps:
+
* Inspect the *Operator Subscriptions* and *Install Plans* tabs for any failures or errors under *Status*.
* Navigate to the *Workloads* -> *Pods* page and check the logs for pods in the `bpfman` project.
7 changes: 7 additions & 0 deletions modules/nw-infw-operator-config-object.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,13 @@ spec:
One label used in `nodeSelector` must match a label on the nodes in order for the daemon set to start. For example, if the node labels `node-role.kubernetes.io/worker` and `node-type.kubernetes.io/vm` are applied to a node, then at least one label must be set using `nodeSelector` for the daemon set to start.
====

|`spec.ebpfProgramManagerMode`
|`boolean`
|
Specifies if the Node Ingress Firewall Operator uses the eBPF Manager Operator or not to manage eBPF programs. This capability is a Technology Preview feature.

For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].

|====

[NOTE]
Expand Down
1 change: 1 addition & 0 deletions networking/network_security/ebpf_manager/_attributes
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../../../_attributes
Loading