1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00

OSDOCS-10856: Add bpfman Operator for ingress firewalls

- https://issues.redhat.com/browse/OSDOCS-10856
This commit is contained in:
Jason Boxman
2024-08-08 09:25:44 -04:00
committed by openshift-cherrypick-robot
parent dbd651feb5
commit 51a1bb3d6d
15 changed files with 443 additions and 1 deletions

View File

@@ -1352,6 +1352,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

View File

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

View File

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

View File

@@ -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:
+
[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
----

View File

@@ -0,0 +1,93 @@
// Module included in the following assemblies:
//
// * 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:
+
[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
----

View File

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

View File

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

View File

@@ -0,0 +1 @@
../../../_attributes

View File

@@ -0,0 +1,49 @@
:_mod-docs-content-type: ASSEMBLY
[id="bpfman-operator-about"]
= About the eBPF Manager Operator
include::_attributes/common-attributes.adoc[]
:context: bpfman-operator-about
toc::[]
:FeatureName: eBPF Manager Operator
include::snippets/technology-preview.adoc[]
[id="about-ebpf_{context}"]
== About Extended Berkeley Packet Filter (eBPF)
eBPF extends the original Berkeley Packet Filter for advanced network traffic filtering. It acts as a virtual machine inside the Linux kernel, allowing you to run sandboxed programs in response to events such as network packets, system calls, or kernel functions.
// Per legal, the approved name for this is exactly: "eBPF Manager"
[id="about-bpfman-operator_{context}"]
== About the eBPF Manager Operator
eBPF Manager simplifies the management and deployment of eBPF programs within Kubernetes, as well as enhancing the security around using eBPF programs. It utilizes Kubernetes custom resource definitions (CRDs) to manage eBPF programs packaged as OCI container images. This approach helps to delineate deployment permissions and enhance security by restricting program types deployable by specific users.
eBPF Manager is a software stack designed to manage eBPF programs within Kubernetes. It facilitates the loading, unloading, modifying, and monitoring of eBPF programs in Kubernetes clusters. It includes a daemon, CRDs, an agent, and an operator:
bpfman:: A system daemon that manages eBPF programs via a gRPC API.
eBPF CRDs:: A set of CRDs like XdpProgram and TcProgram for loading eBPF programs, and a bpfman-generated CRD (BpfProgram) for representing the state of loaded programs.
bpfman-agent:: Runs within a daemonset container, ensuring eBPF programs on each node are in the desired state.
bpfman-operator:: Manages the lifecycle of the bpfman-agent and CRDs in the cluster using the Operator SDK.
The eBPF Manager Operator offers the following features:
- Enhances security by centralizing eBPF program loading through a controlled daemon. eBPF Manager has the elevated privileges so the applications don't need to be. eBPF program control is regulated by standard Kubernetes Role-based access control (RBAC), which can allow or deny an application's access to the different eBPF Manager CRDs that manage eBPF program loading and unloading.
- Provides detailed visibility into active eBPF programs, improving your ability to debug issues across the system.
- Facilitates the coexistence of multiple eBPF programs from different sources using protocols like libxdp for XDP and TC programs, enhancing interoperability.
- Streamlines the deployment and lifecycle management of eBPF programs in Kubernetes. Developers can focus on program interaction rather than lifecycle management, with support for existing eBPF libraries like Cilium, libbpf, and Aya.
[role="_additional-resources"]
[id="additional-resources_{context}"]
== Additional resources
* link:https://ebpf.io/what-is-ebpf/[eBPF Documentation]
* link:https://bpfman.io/latest[bpfman]
* link:https://bpfman.io/latest/developer-guide/api-spec/[eBPF Manager custom resource definition (CRD) API specification]
[id="next-steps_{context}"]
== Next steps
* xref:../../../networking/network_security/ebpf_manager/ebpf-manager-operator-install.adoc#bpfman-operator-install[Installing the eBPF Manager Operator]

View File

@@ -0,0 +1,22 @@
:_mod-docs-content-type: ASSEMBLY
[id="bpfman-operator-deploy"]
= Deploying an eBPF program
include::_attributes/common-attributes.adoc[]
:context: bpfman-operator-deploy
toc::[]
As a cluster administrator, you can deploy containerized eBPF applications with the eBPF Manager Operator.
For the example eBPF program deployed in this procedure, the sample manifest does the following:
First, it creates basic Kubernetes objects like `Namespace`, `ServiceAccount`, and `ClusterRoleBinding`. It also creates a `XdpProgram` object, which is a custom resource definition (CRD) that eBPF Manager provides, that loads the eBPF XDP program. Each program type has it's own CRD, but they are similar in what they do. For more information, see link:https://bpfman.io/main/getting-started/example-bpf-k8s/#loading-ebpf-programs-on-kubernetes[Loading eBPF Programs On Kubernetes].
Second, it creates a daemon set which runs a user space program that reads the eBPF maps that the eBPF program is populating. This eBPF map is volume mounted using a Container Storage Interface (CSI) driver. By volume mounting the eBPF map in the container in lieu of accessing it on the host, the application pod can access the eBPF maps without being privileged. For more information on how the CSI is configured, see See link:https://bpfman.io/main/getting-started/example-bpf-k8s/#deploying-an-ebpf-enabled-application-on-kubernetes[Deploying an eBPF enabled application On Kubernetes].
:FeatureName: eBPF Manager Operator
include::snippets/technology-preview.adoc[]
include::modules/nw-bpfman-operator-deploy.adoc[leveloffset=+1]

View File

@@ -0,0 +1,21 @@
:_mod-docs-content-type: ASSEMBLY
[id="bpfman-operator-install"]
= Installing the eBPF Manager Operator
include::_attributes/common-attributes.adoc[]
:context: bpfman-operator-install
toc::[]
As a cluster administrator, you can install the eBPF Manager Operator by using the {product-title} CLI or the web console.
:FeatureName: eBPF Manager Operator
include::snippets/technology-preview.adoc[]
include::modules/nw-bpfman-operator-installing-cli.adoc[leveloffset=+1]
include::modules/nw-bpfman-operator-installing-console.adoc[leveloffset=+1]
[id="next-steps_{context}"]
== Next steps
* xref:../../../networking/network_security/ebpf_manager/ebpf-manager-operator-deploy.adoc#bpfman-operator-deploy[Deploying a containerized eBPF program]
* xref:../../../networking/network_security/ingress-node-firewall-operator.adoc#bpfman-infw-configure_ingress-node-firewall-operator[Configuring Ingress Node Firewall Operator to use the eBPF Manager Operator]

View File

@@ -0,0 +1 @@
../../../images

View File

@@ -0,0 +1 @@
../../../modules

View File

@@ -0,0 +1 @@
../../../snippets

View File

@@ -20,6 +20,20 @@ include::modules/nw-infw-operator-config-object.adoc[leveloffset=+1]
include::modules/nw-infw-operator-rules-object.adoc[leveloffset=+2]
:FeatureName: eBPF Manager Operator integration
include::snippets/technology-preview.adoc[]
include::modules/nw-bpfman-infw-about.adoc[leveloffset=+1]
include::modules/nw-bpfman-infw-configure.adoc[leveloffset=+1]
include::modules/nw-infw-operator-viewing.adoc[leveloffset=+1]
include::modules/nw-infw-operator-troubleshooting.adoc[leveloffset=+1]
include::modules/nw-infw-operator-troubleshooting.adoc[leveloffset=+1]
ifndef::openshift-rosa[]
[role="_additional-resources"]
[id="additional-resources_{context}"]
== Additional resources
* xref:../../networking/network_security/ebpf_manager/ebpf-manager-operator-about.adoc#bpfman-operator-about[About the eBPF Manager Operator]
endif::openshift-rosa[]