Address comments

To be squashed after review. Signed-off-by: Billy McFall <[email protected]>
Billy99 · Oct 2, 2024 · 6678e4d · 6678e4d
1 parent e0eec46
commit 6678e4d
Show file tree

Hide file tree

Showing 9 changed files with 110 additions and 85 deletions.
diff --git a/docs/developer-guide/develop-operator.md b/docs/developer-guide/develop-operator.md
@@ -18,7 +18,7 @@ For building and deploying the bpfman-operator simply see the attached `make hel
 output.
 
 ```bash
-make help
+$ make help
 
 Usage:
   make <target>
@@ -44,20 +44,25 @@ Development
   generate-typed-clients  Generate typed client code
   generate-typed-listers  Generate typed listers code
   generate-typed-informers  Generate typed informers code
+  vendors          Refresh vendors directory.
   fmt              Run go fmt against code.
   verify           Verify all the autogenerated code
+  lint             Run linter (golangci-lint).
   test             Run Unit tests.
   test-integration  Run Integration tests.
   bundle           Generate bundle manifests and metadata, then validate generated files.
   build-release-yamls  Generate the crd install bundle for a specific release version.
 
 Build
   build            Build bpfman-operator and bpfman-agent binaries.
-  build-images     Build bpfman, bpfman-agent, and bpfman-operator images.
-  push-images      Push bpfman, bpfman-agent, bpfman-operator images.
-  load-images-kind  Load bpfman, bpfman-agent, and bpfman-operator images into the running local kind devel cluster.
+  build-images     Build bpfman-agent and bpfman-operator images.
+  build-operator-image  Build bpfman-operator image.
+  build-agent-image  Build bpfman-agent image.
+  push-images      Push bpfman-agent and bpfman-operator images.
+  load-images-kind  Load bpfman-agent, and bpfman-operator images into the running local kind devel cluster.
   bundle-build     Build the bundle image.
   bundle-push      Push the bundle image.
+  catalog-update   Generate catalog yaml file.
   catalog-build    Build a catalog image.
   catalog-push     Push a catalog image.
 
@@ -67,6 +72,7 @@ CRD Deployment
 
 Vanilla K8s Deployment
   setup-kind       Setup Kind cluster
+  destroy-kind     Destroy Kind cluster
   deploy           Deploy bpfman-operator to the K8s cluster specified in ~/.kube/config with the csi driver initialized.
   undeploy         Undeploy bpfman-operator from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
   kind-reload-images  Reload locally build images into a kind cluster and restart the ds and deployment so they're picked up.
@@ -75,6 +81,8 @@ Vanilla K8s Deployment
 Openshift Deployment
   deploy-openshift  Deploy bpfman-operator to the Openshift cluster specified in ~/.kube/config.
   undeploy-openshift  Undeploy bpfman-operator from the Openshift cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
+  catalog-deploy   Deploy a catalog image.
+  catalog-undeploy  Undeploy a catalog image.
 ```
 
 ### Project Layout
@@ -187,7 +195,7 @@ If any of the
 files are modified, then regenerate these files using:
 
 ```bash
-cd bpfman/bpfman-operator/
+cd bpfman-operator/
 make generate
 ```
 
@@ -203,14 +211,14 @@ During development, it may be quicker to find and fix build errors by just build
 To build the code:
 
 ```bash
-cd bpfman/bpfman-operator/
+cd bpfman-operator/
 make build
 ```
 
 To build the container images, run the following command:
 
 ```bash
-cd bpfman/bpfman-operator/
+cd bpfman-operator/
 make build-images
 ```
 
@@ -234,7 +242,7 @@ launch bpfman in a Kubernetes cluster.
 To run locally in a Kind cluster with an up to date build simply run:
 
 ```bash
-cd bpfman/bpfman-operator/
+cd bpfman-operator/
 make run-on-kind
 ```
 
@@ -243,14 +251,14 @@ The `make run-on-kind` will run the `make build-images` if the images do not exi
 Then rebuild and load a fresh build run:
 
 ```bash
-cd bpfman/bpfman-operator/
+cd bpfman-operator/
 make build-images
 make kind-reload-images
 ```
 
-Which will rebuild the bpfman-operator, bpfman-agent, and bpfman images and load them into the kind cluster.
+Which will rebuild the bpfman-operator and bpfman-agent images, and load them into the kind cluster.
 
-By default, the `make run-on-kind` uses the `quay.io/bpfman/bpfman*` images described above.
+By default, the `make run-on-kind` uses the local images described above.
 The container images used for `bpfman`, `bpfman-agent`, and `bpfman-operator` can also be manually configured:
 
 ```bash

diff --git a/docs/developer-guide/image-build.md b/docs/developer-guide/image-build.md
@@ -1,8 +1,9 @@
 # bpfman Container Images
 
 Container images for `bpfman` are automatically built and pushed to `quay.io/` under the
-`:latest` tag whenever code is merged into the `main` branch of the `github.com/bpfman/bpfman`
-and `github.com/bpfman/bpfman-operator` repositories.
+`:latest` tag whenever code is merged into the `main` branch of the
+[bpfman](https://github.com/bpfman/bpfman) and [bpfman-operator](https://github.com/bpfman/bpfman-operator)
+repositories.
 
 * [quay.io/bpfman](https://quay.io/organization/bpfman):  This repository contains images needed
   to run bpfman.
@@ -45,7 +46,7 @@ to the bpfman-operator or bpfman-agent container images.
 The local Makefile will build and load both images based on the current changes: 
 
 ```sh
-cd $HOME/src/bpfman-operator/
+cd bpfman-operator/
 
 make build-images
 make run-on-kind
@@ -59,7 +60,7 @@ By default, bpfman-agent uses `quay.io/bpfman/bpfman:latest`.
 To build the bpfman binaries in a container image, run:
 
 ```sh
-cd $HOME/src/bpfman/
+cd bpfman/
 
 docker build -f ./Containerfile.bpfman.local . -t quay.io/$QUAY_USER/bpfman:test
 ```
@@ -69,21 +70,22 @@ Next, build and deploy the bpfman-operator and bpfman-agent with the locally bui
 image.
 
 ```sh
-cd $HOME/src/bpfman-operator/
+cd bpfman-operator/
 
 BPFMAN_IMG=quay.io/$QUAY_USER/bpfman:test make build-images
 BPFMAN_IMG=quay.io/$QUAY_USER/bpfman:test make run-on-kind
 ```
 
 To use, the Kind cluster must have access to the image.
 So either the image needs to be pushed to a registry and made public (make
-public via the repo GUI after the push):
+public via the repo GUI after the push) before executing the `make run-on-kind`
+command shown above:
 
 ```sh
 docker push quay.io/$QUAY_USER/bpfman:test
 ```
 
-OR load into kind cluster:
+OR it can be loaded into the kind cluster after the cluster is running:
 
 ```sh
 kind load docker-image quay.io/$QUAY_USER/bpfman:test --name bpfman-deployment
@@ -142,8 +144,8 @@ bpfman image build -f Containerfile.bytecode.multi.arch -t quay.io/$QUAY_USER/tc
 bpfman image build -f Containerfile.bytecode.multi.arch -t quay.io/$QUAY_USER/xdp-dispatcher:test -c .output/xdp_dispatcher_v2.bpf/
 ```
 
-!!! NOTE
-    To build images for multiple architectures on a local system, docker may need additional configuration
+!!! Note
+    To build images for multiple architectures on a local system, docker (or podman) may need additional configuration
     settings to allow for caching of non-native images. See 
     [https://docs.docker.com/build/building/multi-platform/](https://docs.docker.com/build/building/multi-platform/)
     for more details.
@@ -208,8 +210,8 @@ $ make build-bc-xdp USER_BC=$QUAY_USER TAG_BC=test-bc PLATFORM=linux/amd64,linux
  => pushing quay.io/$QUAY_USER/go-xdp-counter:test-bc with docker
 ```
 
-!!! NOTE
-    To build images for multiple architectures on a local system, docker may need additional configuration
+!!! Note
+    To build images for multiple architectures on a local system, docker (or podman) may need additional configuration
     settings to allow for caching of non-native images. See 
     [https://docs.docker.com/build/building/multi-platform/](https://docs.docker.com/build/building/multi-platform/)
     for more details.
@@ -220,7 +222,7 @@ If an example userspace container image needs to be built locally, use the follo
 build the userspace container images, (optionally passing the `USER_US` and `TAG_US` for the image):
 
 ```sh
-cd ~/src/bpfman/examples/
+cd bpfman/examples/
 
 # Build all images
 $ make build-us-images USER_US=$QUAY_USER TAG_US=test-us
@@ -248,8 +250,8 @@ $ make build-us-xdp USER_US=$QUAY_USER TAG_US=test-us PLATFORM=linux/amd64,linux
  => pushing quay.io/$QUAY_USER/go-xdp-counter:test-us with docker
 ```
 
-!!! NOTE
-    To build images for multiple architectures on a local system, docker may need additional configuration
+!!! Note
+    To build images for multiple architectures on a local system, docker (or podman) may need additional configuration
     settings to allow for caching of non-native images. See 
     [https://docs.docker.com/build/building/multi-platform/](https://docs.docker.com/build/building/multi-platform/)
     for more details.
@@ -270,7 +272,7 @@ integration tests, several steps need to be performed.
 
 ## Signing Container Images
 
-It is encouraged to sign the eBPF container images, which can easily be done using
+Signing eBPF container images is encouraged and can be easily done using
 [cosign](https://docs.sigstore.dev/signing/quickstart/).
 Below is a summary of the steps needed to sign an image.
 
@@ -282,7 +284,7 @@ go install github.com/sigstore/cosign/v2/cmd/cosign@latest
 
 Then sign the image.
 The `cosign` command will generate a URL.
-Follow the URL to a `sigstore` login and login with either GitHub, Google to Microsoft.
+Follow the `sigstore` URL and login with either GitHub, Google to Microsoft.
 That will generate a verification code that will complete the `cosign` command.
 
 ```console

diff --git a/docs/developer-guide/testing.md b/docs/developer-guide/testing.md
@@ -10,7 +10,8 @@ Unit testing is executed as part of the `build` job by running the following
 command in the top-level bpfman directory.
 
 ```
- cargo test
+cd bpfman/
+cargo test
 ```
 
 ## Go Example Tests
@@ -25,6 +26,7 @@ The full set of basic integration tests are executed by running the following
 command in the top-level bpfman directory.
 
 ```bash
+cd bpfman/
 cargo xtask integration-test
 ```
 
@@ -72,17 +74,7 @@ the eBPF test programs can be found in the `tests/integration-test/bpf`
 directory.  These programs are compiled by executing `cargo xtask build-ebpf
 --libbpf-dir <libbpf dir>`
 
-We also load some tests from local files to test the `load-from-file` option.
-
-The `bpf` directory also contains a script called `build_push_images.sh` that
-can be used to build and push new images to quay if the code is changed.
-Images get pushed automatically when code gets merged, however, it's still
-useful to be able to push them manually sometimes. For example, when a new test
-case requires that both the eBPF and integration code be changed together.  It
-is also a useful template for new eBPF test code that needs to be pushed.
-However, as a word of caution, be aware that existing integration tests will
-start using the new programs immediately, so this should only be done if the
-modified program is backward compatible.
+We also load some tests from local files to test the `bpfman load file` option.
 
 ## Kubernetes Operator Tests
 
@@ -91,42 +83,49 @@ modified program is backward compatible.
 To run all of the unit tests defined in the bpfman-operator controller code run
 `make test` in the bpfman-operator directory.
 
+```bash
+cd bpfman-operator/
+make test
+```
+
 ### Kubernetes Operator Integration Tests
 
 To run the Kubernetes Operator integration tests locally:
 
 1. Build the example test code userspace images locally.
 
-```bash
-    # in bpfman/examples
+    ```bash
+    cd bpfman/examples/
     make build-us-images
-```
+    ```
 
 2. (optional) build the bytecode images
 
-  In order to rebuild all of the bytecode images for a PR, ask a maintainer to do so,
-  they will be built and generate by github actions with the tag
-  `quay.io/bpfman-bytecode/<example>:<branch-name>`
+    In order to rebuild all of the bytecode images for a PR, ask a maintainer to do so,
+    they will be built and generate by github actions with the tag
+    `quay.io/bpfman-bytecode/<example>:<branch-name>`
 
-3. Build the bpfman images locally with the `int-test` tag.
+3. Build the bpfman images locally with a unique tag, for example: `int-test`
 
-```bash
-    # in bpfman/bpfman-operator
-    BPFMAN_AGENT_IMG=quay.io/bpfman/bpfman-agent:int-test BPFMAN_IMG=quay.io/bpfman/bpfman:int-test BPFMAN_OPERATOR_IMG=quay.io/bpfman/bpfman-operator:int-test make build-images
-```
+    ```bash
+    cd bpfman-operator/
+    BPFMAN_AGENT_IMG=quay.io/bpfman/bpfman-agent:int-test BPFMAN_OPERATOR_IMG=quay.io/bpfman/bpfman-operator:int-test make build-images
+    ```
 
-4. Run the integration test suite.
+4. Run the integration test suite with the images from the previous step:
 
-```bash
-    # in bpfman/bpfman-operator
-    BPFMAN_AGENT_IMG=quay.io/bpfman/bpfman-agent:int-test BPFMAN_IMG=quay.io/bpfman/bpfman:int-test BPFMAN_OPERATOR_IMG=quay.io/bpfman/bpfman-operator:int-test make test-integration
-```
+    ```bash
+    cd bpfman-operator/
+    BPFMAN_AGENT_IMG=quay.io/bpfman/bpfman-agent:int-test BPFMAN_OPERATOR_IMG=quay.io/bpfman/bpfman-operator:int-test make test-integration
+    ```
 
-Additionally the integration test can be configured with the following environment variables:
+    If an update `bpfman` image is required, build it separately and pass to `make test-integration` using `BPFMAN_IMG`.
+    See [Locally Build bpfman Container Image](./image-build.md#locally-build-bpfman-container-image).
 
-* **KEEP_TEST_CLUSTER**: If set to `true` the test cluster will not be torn down
-  after the integration test suite completes.
-* **USE_EXISTING_KIND_CLUSTER**: If this is set to the name of the existing kind
-  cluster the integration test suite will use that cluster instead of creating a
-  new one.
+    Additionally the integration test can be configured with the following environment variables:
 
+    * **KEEP_TEST_CLUSTER**: If set to `true` the test cluster will not be torn down
+      after the integration test suite completes.
+    * **USE_EXISTING_KIND_CLUSTER**: If this is set to the name of the existing kind
+      cluster the integration test suite will use that cluster instead of creating a
+      new one.
diff --git a/docs/developer-guide/xdp-overview.md b/docs/developer-guide/xdp-overview.md
@@ -17,7 +17,7 @@ XDP programs on a given interface.
 This tutorial will show you how to use `bpfman` to load multiple XDP programs
 on an interface.
 
-!!! Note:
+!!! Note
     The TC hook point is also associated with an interface.
     Within bpfman, TC is implemented in a similar fashion to XDP in that it uses a dispatcher with
     stub functions.