diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c067f4fc1..80c1c2801 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,13 +81,13 @@ Our process is currently as follows: 1. When you open a PR a maintainer will automatically be assigned for review 1. Make sure that your PR is passing CI - if you need help with failing checks please feel free to ask! 1. Once it is passing all CI checks, a maintainer will review your PR and you may be asked to make changes. -1. When you have received at least one approval from a maintainer, your PR will be merged automiatcally. +1. When you have received at least one approval from a maintainer, your PR will be merged automatically. In some cases, other changes may conflict with your PR. If this happens, you will get notified by a comment in the issue that your PR requires a rebase, and the `needs-rebase` label will be applied. Once a rebase has been performed, this label will be automatically removed. ## Development Environment Setup -[Instructions](https://bpfman.netlify.app/building-bpfman/#development-environment-setup) +[Instructions](https://bpfman.io/main/governance/contributing/#development-environment-setup) ## Signoff Your Commits @@ -138,8 +138,8 @@ A good commit message should describe what changed and why. Examples: - * bpfman: validate program section names - * bpf: add dispatcher program test slot + * bpfman: validate program section names + * bpf: add dispatcher program test slot 2. Keep the second line blank. 3. Wrap all other lines at 72 columns (except for long URLs). @@ -189,9 +189,9 @@ cargo +nightly clippy --all -- --deny warnings * Verify that Go code has been formatted and linted * Verify that Yaml files have been formatted (see - [Install Yaml Formatter](https://bpfman.io/getting-started/building-bpfman/#install-yaml-formatter)) + [Install Yaml Formatter](https://bpfman.io/main/getting-started/building-bpfman/#install-yaml-formatter)) * Verify that unit tests are passing locally (see - [Unit Testing](https://bpfman.io/developer-guide/testing/#unit-testing)): + [Unit Testing](https://bpfman.io/main/developer-guide/testing/#unit-testing)): ```console cd src/bpfman/ @@ -199,7 +199,7 @@ cargo test ``` * Verify that integration tests are passing locally (see - [Basic Integration Tests](https://bpfman.io/developer-guide/testing/#basic-integration-tests)): + [Basic Integration Tests](https://bpfman.io/main/developer-guide/testing/#basic-integration-tests)): ```console cd src/bpfman/ @@ -216,7 +216,7 @@ make test * If developing the bpfman-operator, verify that bpfman-operator integration tests are passing locally (see - [Kubernetes Integration Tests](https://bpfman.io/developer-guide/testing/#kubernetes-integration-tests)): + [Kubernetes Integration Tests](https://bpfman.io/main/developer-guide/testing/#kubernetes-integration-tests)): ```console cd src/bpfman/bpfman-operator/ diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 775efc2d3..214fa3d31 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -2,7 +2,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for general contribution guidelines. See [GOVERNANCE.md](./GOVERNANCE.md) for governance guidelines and maintainer responsibilities. -See [CODEOWNERS](./CODEOWNERS) for a detailed list of owners for the various source directories. +See [CODEOWNERS](https://github.com/bpfman/bpfman/blob/main/CODEOWNERS) for a detailed list of owners for the various source directories. | Name | Employer | Responsibilities | | ---- | -------- | ---------------- | diff --git a/README.md b/README.md index 5457af949..670e66974 100644 --- a/README.md +++ b/README.md @@ -41,15 +41,15 @@ This allows users to confidently deploy eBPF through custom resource definitions Here are some links to help in your bpfman journey (all links are from the bpfman website ): - [Welcome to bpfman](https://bpfman.io/) for overview of bpfman. -- [Setup and Building bpfman](https://bpfman.io/getting-started/building-bpfman/) for +- [Setup and Building bpfman](https://bpfman.io/main/getting-started/building-bpfman/) for instructions on setting up your development environment and building bpfman. -- [Tutorial](https://bpfman.io/getting-started/tutorial/) for some examples of starting +- [Tutorial](https://bpfman.io/main/getting-started/tutorial/) for some examples of starting `bpfman`, managing logs, and using the CLI. -- [Example eBPF Programs](https://bpfman.io/getting-started/example-bpf/) for some +- [Example eBPF Programs](https://bpfman.io/main/getting-started/example-bpf/) for some examples of eBPF programs written in Go, interacting with `bpfman`. -- [How to Deploy bpfman on Kubernetes](https://bpfman.io/developer-guide/develop-operator/) for details on launching +- [How to Deploy bpfman on Kubernetes](https://bpfman.io/main/developer-guide/develop-operator/) for details on launching bpfman in a Kubernetes cluster. -- [Meet the Community](https://bpfman.io/governance/meetings/) for details on community meeting details. +- [Meet the Community](https://bpfman.io/main/governance/meetings/) for details on community meeting details. ## License @@ -81,3 +81,4 @@ dual licensed as above, without any additional terms or conditions. [GNU General Public License, Version 2]: LICENSE-GPL2 [BSD 2 Clause]: LICENSE-BSD2 [libxdp]: https://github.com/xdp-project/xdp-tools +[TC dispatcher]:https://github.com/bpfman/bpfman/blob/main/bpf/tc_dispatcher.bpf.c diff --git a/REVIEWING.md b/REVIEWING.md index 7a495a644..d296236e7 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -35,7 +35,7 @@ Be trustworthy. During a review, your actions both build and help maintain the t ## Process -* Reviewers are automatically assigned based on the [CODEOWNERS](./CODEOWNERS) file. +* Reviewers are automatically assigned based on the [CODEOWNERS](https://github.com/bpfman/bpfman/blob/main/CODEOWNERS) file. * Reviewers should wait for automated checks to pass before reviewing * At least 1 approved review is required from a maintainer before a pull request can be merged * All CI checks must pass diff --git a/changelogs/CHANGELOG-v0.3.1.md b/changelogs/CHANGELOG-v0.3.1.md index 8ccb003aa..b227d5bf5 100644 --- a/changelogs/CHANGELOG-v0.3.1.md +++ b/changelogs/CHANGELOG-v0.3.1.md @@ -48,28 +48,29 @@ Lastly, the bpfman user and user group was removed which will only effect users that run bpfman via a systemd service and try to use `bpfctl` without root privileges. This helped reduce internal complexity and allows us to focus instead on finetuning the permissions of the bpfman process itself, see the [linux -capabilities guide](https://bpfman.io/developer-guide/linux-capabilities/) for more information. +capabilities guide](https://bpfman.io/main/developer-guide/linux-capabilities/) for more information. ## What's Changed (excluding dependency bumps) -* release: automate release yamls by @astoycos in https://github.com/bpfman/bpfman/pull/775 -* bpf: returns an error when adding a tc program to existence clsact qdisc by @navarrothiago in https://github.com/bpfman/bpfman/pull/761 -* workspace-ified the netlink dependencies by @anfredette in https://github.com/bpfman/bpfman/pull/783 -* Don't try and pin .data maps by @astoycos in https://github.com/bpfman/bpfman/pull/794 -* .github: Add actions to dependabot by @dave-tucker in https://github.com/bpfman/bpfman/pull/803 -* Fix Procceedon bug (Issue #791) by @anfredette in https://github.com/bpfman/bpfman/pull/792 -* Add script to delete bpfman qdiscs on all interfaces by @anfredette in https://github.com/bpfman/bpfman/pull/780 -* Fix BPF Licensing by @dave-tucker in https://github.com/bpfman/bpfman/pull/796 -* Fix example bytecode image builds add test coverage by @astoycos in https://github.com/bpfman/bpfman/pull/810 -* Relicense userspace to Apache 2.0 only by @dave-tucker in https://github.com/bpfman/bpfman/pull/795 -* bpfman: Use tc dispatcher from container image by @dave-tucker in https://github.com/bpfman/bpfman/pull/817 -* bpfman: Unify the "run as root" and "run as bpfman user" codepaths by @Billy99 in https://github.com/bpfman/bpfman/pull/777 -* bpfman, bpfctl, operator: Remove support for TCP/TLS by @dave-tucker in https://github.com/bpfman/bpfman/pull/819 -* bpfman-operator: Make the CSI deployment default for bpfman-operator by @Billy99 in https://github.com/bpfman/bpfman/pull/811 -* ci: Add YAML formatter by @dave-tucker in https://github.com/bpfman/bpfman/pull/802 -* Fix some panics + add testing and fix for map sharing by @astoycos in https://github.com/bpfman/bpfman/pull/820 -* bpfman: mount default bpffs on kind by @astoycos in https://github.com/bpfman/bpfman/pull/823 -* bpfman: Remove unused file by @dave-tucker in https://github.com/bpfman/bpfman/pull/824 -* Document valid kernel versions by @Billy99 in https://github.com/bpfman/bpfman/pull/827 -* Update documentation on new YAML Linter by @Billy99 in https://github.com/bpfman/bpfman/pull/830 -**Full Changelog**: https://github.com/bpfman/bpfman/compare/v0.3.0...v0.3.1 +* release: automate release yamls by @astoycos in +* bpf: returns an error when adding a tc program to existence clsact qdisc by @navarrothiago in +* workspace-ified the netlink dependencies by @anfredette in +* Don't try and pin .data maps by @astoycos in +* .github: Add actions to dependabot by @dave-tucker in +* Fix Procceedon bug (Issue #791) by @anfredette in +* Add script to delete bpfman qdiscs on all interfaces by @anfredette in +* Fix BPF Licensing by @dave-tucker in +* Fix example bytecode image builds add test coverage by @astoycos in +* Relicense userspace to Apache 2.0 only by @dave-tucker in +* bpfman: Use tc dispatcher from container image by @dave-tucker in +* bpfman: Unify the "run as root" and "run as bpfman user" codepaths by @Billy99 in +* bpfman, bpfctl, operator: Remove support for TCP/TLS by @dave-tucker in +* bpfman-operator: Make the CSI deployment default for bpfman-operator by @Billy99 in +* ci: Add YAML formatter by @dave-tucker in +* Fix some panics + add testing and fix for map sharing by @astoycos in +* bpfman: mount default bpffs on kind by @astoycos in +* bpfman: Remove unused file by @dave-tucker in +* Document valid kernel versions by @Billy99 in +* Update documentation on new YAML Linter by @Billy99 in + +**Full Changelog**: diff --git a/docs/blog/posts/introduction-to-bpfman.md b/docs/blog/posts/introduction-to-bpfman.md index 7e7d53403..db2ec3e65 100644 --- a/docs/blog/posts/introduction-to-bpfman.md +++ b/docs/blog/posts/introduction-to-bpfman.md @@ -45,7 +45,7 @@ discuss the problems bpfman can help solve, and how to deploy and use it. While some organizations have had success developing, deploying, and maintaining production software which includes eBPF programs, the barrier to entry is still -very high. +very high. Following the basic eBPF development workflow, which often involves many hours trying to interpret and fix mind-bending [eBPF verifier] errors, the process of @@ -71,7 +71,6 @@ what eBPF does, and how it can help reduce the costs associated with deploying and managing eBPF-powered workloads. [eBPF verifier]:https://docs.kernel.org/bpf/verifier.html -[bpfman]:https://bpfman.io ## bpfman Overview @@ -80,7 +79,7 @@ lifecycle of eBPF programs. In particular, it can load, unload, modify, and monitor eBPF programs on a single host, or across a full Kubernetes cluster. The key components of bpfman include the bpfman daemon itself which can run independently on any Linux box, an accompanying Kubernetes Operator designed -to bring first-class support to clusters via Custom Resource Definitions (CRDs), +to bring first-class support to clusters via Custom Resource Definitions (CRDs), and eBPF program packaging. These components will be covered in more detail in the following sections. @@ -137,7 +136,6 @@ interact. [Aya]:https://aya-rs.dev/ [multi-prog]:https://github.com/xdp-project/xdp-tools/blob/master/lib/libxdp/protocol.org - ### bpfman Kubernetes Support The benefits of bpfman are brought to Kubernetes by the bpfman operator. The bpfman @@ -281,8 +279,9 @@ status: status: "True" type: ReconcileSuccess ``` -More details about this process can be seen -[here](https://bpfman.io/getting-started/example-bpf-k8s/) + +More details about this process can be seen [here] +[here]:../../getting-started/example-bpf-k8s.md #### eBPF program packaging @@ -315,7 +314,7 @@ using bpfman, only the bpfman daemon, which can be tightly controlled, needs the privileges required to load eBPF programs, while access to the API can be controlled via standard RBAC methods on a per-application and per-CRD basis. Additionally, the signing and validating of bytecode images enables supply chain -security. +security. #### Visibility and Debuggability @@ -336,6 +335,7 @@ this for you so you don't have to. eBPF bytecode images help here as well by simplifying the distribution of eBPF bytecode to multiple nodes in a cluster, and also allowing separate fine-grained versioning control for user space and kernel space code. + ### Demonstration This demonstration is adapted from the instructions documented by Andrew Stoycos @@ -344,10 +344,12 @@ This demonstration is adapted from the instructions documented by Andrew Stoycos These instructions use kind and bpfman release v0.2.1. It should also be possible to run this demo on other environments such as minikube or an actual cluster. -Another option is to [build the code -yourself](https://bpfman.io/getting-started/building-bpfman/) and use [`make -run-on-kind`](https://bpfman.io/getting-started/example-bpf-k8s/) to create the -cluster as is described in the given links. Then, start with step 5. +Another option is to [build the code yourself] and use [make run-on-kind] + +[build the code yourself]:../../getting-started/building-bpfman.md#development-environment-setup +[make run-on-kind]:../../getting-started/example-bpf-k8s.md + +to create the cluster as is described in the given links. Then, start with step 5. #### Run the demo @@ -439,7 +441,7 @@ Notes: for the pod's primary node interface, which may not have a lot of traffic. However, running the `kubectl` command below generates traffic on that interface, so run the command a few times and give it a few seconds in between -to confirm whether the counters are incrementing. +to confirm whether the counters are incrementing. - Replace "go-xdp-counter-ds-9lpgp" with the go-xdp-counter pod name for your deployment. @@ -605,4 +607,4 @@ to see you there! [bpfman-disc]:https://github.com/bpfman/bpfman/discussions/new/choose [bpfman-iss]:https://github.com/bpfman/bpfman/issues/new [k8s-slack]:https://kubernetes.slack.com -[sync]:https://bpfman.io/governance/meetings/ +[sync]:../../governance/MEETINGS.md diff --git a/docs/blog/posts/sled-integration.md b/docs/blog/posts/sled-integration.md index 3a1e6856e..2a7a27017 100644 --- a/docs/blog/posts/sled-integration.md +++ b/docs/blog/posts/sled-integration.md @@ -330,9 +330,9 @@ the project will be able to completely transition to becoming a library without having to worry about data and state management. If you are interested in in memory databases, eBPF, Rust, or any of the technologies -discussed today please don't hesitate to reach out on [kubernetes slack at `#bpfman`] -or join one of the [community meetings] to get involved. +discussed today please don't hesitate to reach out at [kubernetes slack] on channel +`#bpfman` or join one of the [community meetings] to get involved. [sled]:https://github.com/spacejam/sled -[kubernetes slack at `#bpfman`]:(https://kubernetes.slack.com/archives/C04UJBW2553) -[community meetings]:[https://bpfman.io/main/governance/meetings/] +[kubernetes slack]:https://kubernetes.slack.com/archives/C04UJBW2553 +[community meetings]:../../governance/MEETINGS.md diff --git a/docs/developer-guide/documentation.md b/docs/developer-guide/documentation.md index 2971e787c..b9c988313 100644 --- a/docs/developer-guide/documentation.md +++ b/docs/developer-guide/documentation.md @@ -50,14 +50,10 @@ The file [docs/developer-guide/api-spec.md](https://github.com/bpfman/bpfman/blob/main/docs/developer-guide/api-spec.md) documents the CRDs used in a Kubernetes deployment. The contents are auto-generated when PRs are pushed to Github. -The script [scripts/make-docs.sh](https://github.com/bpfman/bpfman/blob/main/scripts/make-docs.sh) -manages the generation of this file. -## Generate Documentation +The contents can be generated locally by running the command `make -C bpfman-operator apidocs.html` from the root bpfman directory. -On each PR pushed to https://github.com/bpfman/bpfman the documentation is generated. -To preview of the generated site, click on the `Details` link of the -`netlify/bpfman/deploy-preview` Check from the Github GUI. +## Generate Documentation If you would like to test locally, build and preview the generated documentation, from the bpfman root directory, use `mkdocs` to build: @@ -67,6 +63,9 @@ cd bpfman/ mkdocs build ``` +>**NOTE:** If `mkdocs build` gives you an error, make sure you have the mkdocs +packages listed below installed. + To preview from a build on a local machine, start the mkdocs dev-server with the command below, then open up `http://127.0.0.1:8000/` in your browser, and you'll see the default home page being displayed: @@ -100,3 +99,6 @@ Once installed, ensure the `mkdocs` is in your PATH: mkdocs -V mkdocs, version 1.4.3 from /home/$USER/.local/lib/python3.11/site-packages/mkdocs (Python 3.11) ``` + +>**NOTE:** If you have an older version of mkdocs installed, you may need to use +the `--upgrade` option (e.g., `pip install --upgrade mkdocs`) to get it to work.