Skip to content

Commit

Permalink
Merge pull request bpfman#1236 from Billy99/billy99-doc-multiarch
Browse files Browse the repository at this point in the history 
docs: Update docs
  • Loading branch information
@mergify
mergify[bot] authored Oct 2, 2024
2 parents 4f4e826 + 6678e4d commit a5fa0a7
Show file tree
Hide file tree
Showing 20 changed files with 1,148 additions and 426 deletions.
28 changes: 17 additions & 11 deletions bpfman/src/bin/cli/args.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -320,26 +320,34 @@ pub(crate) enum ImageSubCommand {
///
/// To use, the --container-file and --tag must be included, as well as a pointer to
/// at least one bytecode file that can be passed in several ways. Use either:
///
/// * --bytecode: for a single bytecode built for the host architecture.
///
/// * --cilium-ebpf-project: for a cilium/ebpf project directory which contains
/// multiple object files for different architectures.
///
/// * --bc-386-el .. --bc-s390x-eb: to add one or more architecture specific bytecode files.
///
/// Examples:
/// bpfman image build -f Containerfile.bytecode -t quay.io/<USER>/go-xdp-counter:test \
/// -b ./examples/go-xdp-counter/bpf_x86_bpfel.o
#[clap(verbatim_doc_comment)]
Build(BuildBytecodeArgs),
/// Generate the OCI image labels for a given bytecode file.
///
/// To use, the --container-file and --tag must be included, as well as a pointer to
/// at least one bytecode file that can be passed in several ways. Use either:
///
/// * --bytecode: for a single bytecode built for the host architecture.
///
/// * --cilium-ebpf-project: for a cilium/ebpf project directory which contains
/// multiple object files for different architectures.
///
/// * --bc-386-el .. --bc-s390x-eb: to add one or more architecture specific bytecode files.
///
/// Examples:
/// bpfman image generate-build-args --bc-amd64-el ./examples/go-xdp-counter/bpf_x86_bpfel.o
#[clap(verbatim_doc_comment)]
GenerateBuildArgs(GenerateArgs),
}

Expand Down Expand Up @@ -457,11 +465,6 @@ impl GoArch {
#[derive(Args, Debug)]
#[command(disable_version_flag = true)]
pub(crate) struct BuildBytecodeArgs {
/// Optional: bytecode file to use for building the image assuming host architecture.
/// Example: -b ./bpf_x86_bpfel.o
#[clap(flatten)]
pub(crate) bytecode_file: BytecodeFile,

/// Required: Name and optionally a tag in the name:tag format.
/// Example: --tag quay.io/bpfman-bytecode/xdp_pass:latest
#[clap(short, long, verbatim_doc_comment)]
Expand All @@ -476,6 +479,9 @@ pub(crate) struct BuildBytecodeArgs {
/// Example: --runtime podman
#[clap(short, long, verbatim_doc_comment)]
pub(crate) runtime: Option<String>,

#[clap(flatten)]
pub(crate) bytecode_file: BytecodeFile,
}

#[derive(Args, Debug)]
Expand All @@ -498,6 +504,12 @@ pub(crate) struct BytecodeFile {
#[clap(short, long, verbatim_doc_comment)]
pub(crate) bytecode: Option<PathBuf>,

/// Optional: If specified pull multi-arch bytecode files from a cilium/ebpf formatted project
/// where the bytecode files all contain a standard bpf_<GOARCH>_<(el/eb)>.o tag.
/// Example: --cilium-ebpf-project ./examples/go-xdp-counter
#[clap(short, long, verbatim_doc_comment)]
pub(crate) cilium_ebpf_project: Option<PathBuf>,

/// Optional: bytecode file to use for building the image assuming amd64 architecture.
/// Example: --bc-386-el ./examples/go-xdp-counter/bpf_386_bpfel.o
#[clap(long, verbatim_doc_comment, group = "multi-arch")]
Expand Down Expand Up @@ -562,12 +574,6 @@ pub(crate) struct BytecodeFile {
/// Example: --bc-s390x-eb ./examples/go-xdp-counter/bpf_s390x_bpfeb.o
#[clap(long, verbatim_doc_comment, group = "multi-arch")]
pub(crate) bc_s390x_eb: Option<PathBuf>,

/// Optional: If specified pull multi-arch bytecode files from a cilium/ebpf formatted project
/// where the bytecode files all contain a standard bpf_<GOARCH>_<(el/eb)>.o tag.
/// Example: --cilium-ebpf-project ./examples/go-xdp-counter
#[clap(short, long, verbatim_doc_comment)]
pub(crate) cilium_ebpf_project: Option<PathBuf>,
}

#[derive(Args, Debug)]
Expand Down
47 changes: 28 additions & 19 deletions docs/developer-guide/develop-operator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -167,14 +175,15 @@ When editing
follow best practices describe in
[Proto Best Practices](https://protobuf.dev/programming-guides/dos-donts/).

**Note:** `cargo xtask build-proto` also pulls in
[proto/csi.proto](https://github.com/bpfman/bpfman/blob/main/proto/csi.proto) (which is in the
same directory as
[proto/bpfman.proto](https://github.com/bpfman/bpfman/blob/main/proto/bpfman.proto)).
[proto/csi.proto](https://github.com/bpfman/bpfman/blob/main/proto/csi.proto) is taken from
[container-storage-interface/spec/csi.proto](https://github.com/container-storage-interface/spec/blob/master/csi.proto).
See [container-storage-interface/spec/spec.md](https://github.com/container-storage-interface/spec/blob/master/spec.md)
for more details.
!!! Note
`cargo xtask build-proto` also pulls in
[proto/csi.proto](https://github.com/bpfman/bpfman/blob/main/proto/csi.proto) (which is in the
same directory as
[proto/bpfman.proto](https://github.com/bpfman/bpfman/blob/main/proto/bpfman.proto)).
[proto/csi.proto](https://github.com/bpfman/bpfman/blob/main/proto/csi.proto) is taken from
[container-storage-interface/spec/csi.proto](https://github.com/container-storage-interface/spec/blob/master/csi.proto).
See [container-storage-interface/spec/spec.md](https://github.com/container-storage-interface/spec/blob/master/spec.md)
for more details.

### Generated Files

Expand All @@ -186,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
```

Expand All @@ -202,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
```

Expand All @@ -233,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
```

Expand All @@ -242,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
Expand Down
17 changes: 10 additions & 7 deletions docs/developer-guide/documentation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,10 @@ This indicates to `mkdocs` to pull the additional file from the project root dir

For example: [docs/governance/MEETINGS.md](https://github.com/bpfman/bpfman/blob/main/docs/governance/MEETINGS.md)

> **NOTE:** This works for the website generation, but if a Markdown file is viewed through
Github (not the website), the link is broken.
So these files should only be linked from `docs/index.md` and `mkdocs.yml`.
!!! Note
This works for the website generation, but if a Markdown file is viewed through
Github (not the website), the link is broken.
So these files should only be linked from `docs/index.md` and `mkdocs.yml`.

### docs/developer-guide/api-spec.md

Expand All @@ -63,8 +64,9 @@ cd bpfman/
mkdocs build
```

>**NOTE:** If `mkdocs build` gives you an error, make sure you have the mkdocs
packages listed below installed.
!!! 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
Expand Down Expand Up @@ -97,8 +99,9 @@ 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.
!!! 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.

## Document Images

Expand Down
Loading

0 comments on commit a5fa0a7

Please sign in to comment.