Skip to content

Release Process

This document describes how to cut a release for the bpfman project.

Overview

A release for the bpfman project is comprised of the following major components:

  • bpfman (Core library) and bpfman-api (Core GRPC API protobuf definitions) library crates
  • bpfman (CLI), and bpfman-rpc (gRPC server) binary crates
  • bpf-metrics-exporter and bpf-log-exporter binary crates
  • bpfman RPMs stored in the bpfman COPR repository.
  • Kubernetes User Facing Custom Resource Definitions (CRDs)
    • TcProgram
    • XdpProgram
    • TracepointProgram
    • UprobeProgram
    • KprobeProgram
    • FentryProgram
    • FexitProgram
  • Corresponding go pkgs in the form of github.com/bpfman/bpfman which includes the following:
    • github.com/bpfman/bpfman/clients/gobpfman/v1: The go client for the bpfman GRPC API API helpers.
  • Corresponding go pkgs in the form of github.com/bpfman/bpfman-operator which includes the following:
    • github.com/bpfman/bpfman-operator/apis: The go bindings for the bpfman CRD API
    • github.com/bpfman/bpfman-operator/pkg/client: The autogenerated clientset for the bpfman CRD API
    • github.com/bpfman/bpfman-operator/pkg/helpers: The provided bpfman CRD API helpers.
  • The following core component container images with tag :
    • quay.io/bpfman/bpfman
    • quay.io/bpfman/bpfman-operator
    • quay.io/bpfman/bpfman-agent
    • quay.io/bpfman/bpfman-operator-bundle
    • quay.io/bpfman/xdp-dispatcher
    • quay.io/bpfman/tc-dispatcher
  • The relevant example bytecode container images with tag from source code located in the bpfman project:
    • quay.io/bpfman-bytecode/go-xdp-counter
    • quay.io/bpfman-bytecode/go-tc-counter
    • quay.io/bpfman-bytecode/go-tracepoint-counter
    • quay.io/bpfman-bytecode/xdp-pass
    • quay.io/bpfman-bytecode/tc-pass
    • quay.io/bpfman-bytecode/tracepoint
    • quay.io/bpfman-bytecode/xdp-pass-private
    • quay.io/bpfman-bytecode/go-uprobe-counter
    • quay.io/bpfman-bytecode/go-kprobe-counter
    • quay.io/bpfman-bytecode/uprobe
    • quay.io/bpfman-bytecode/kprobe
    • quay.io/bpfman-bytecode/uretprobe
    • quay.io/bpfman-bytecode/kretprobe
    • quay.io/bpfman-bytecode/fentry
    • quay.io/bpfman-bytecode/fexit
    • quay.io/bpfman-bytecode/go-app-counter
  • The relevant example userspace container images with tag from source code located in the bpfman project:
    • quay.io/bpfman-userspace/go-xdp-counter
    • quay.io/bpfman-userspace/go-tc-counter
    • quay.io/bpfman-userspace/go-tracepoint-counter
    • quay.io/bpfman-userspace/go-uprobe-counter
    • quay.io/bpfman-userspace/go-target
    • quay.io/bpfman-userspace/go-kprobe-counter
    • quay.io/bpfman-userspace/go-app-counter
  • The OLM (Operator Lifecycle Manager) for the Kubernetes Operator.
    • This includes a bundle directory on disk as well as the quay.io/bpfman/bpfman-operator-bundle image with the tag .

Versioning strategy

Overview

Each new release of bpfman is defined with a "bundle version" that represents the Git tag of a release, such as v0.4.2. This contains the components described above

Kubernetes API Versions (e.g. v1alpha2, v1beta1)

Within the bpfman-operator, API versions are primarily used to indicate the stability of a resource. For example, if a resource has not yet graduated to beta, it is still possible that it could either be removed from the API or changed in backwards incompatible ways. For more information on API versions, refer to the full Kubernetes API versioning documentation.

Releasing a new version

Writing a Changelog

To simplify release notes generation, we recommend using the Kubernetes release notes generator:

go install k8s.io/release/cmd/release-notes@latest
export GITHUB_TOKEN=your_token_here
release-notes --start-sha EXAMPLE_COMMIT --end-sha EXAMPLE_COMMIT --branch main --repo bpfman --org bpfman

This output will likely need to be reorganized and cleaned up a bit, but it provides a good starting point. Once you're satisfied with the changelog, create a PR. This must go through the regular PR review process and get merged into the main branch. Approval of the PR indicates community consensus for a new release.

Additionally you can navigate to the github release page and draft a release generating release notes there as well.

Release Steps

The following steps must be done by one of the bpfman maintainers, please always try and cut a release candidate before pushing an official major or minor release.

RELEASE CANDIDATE Release

Often times cutting a release candidate is a great way to test any changes to our release infrastructure before cutting an official release. Make sure release candidate versions contain an rc suffix i.e 0.4.0-rc1. This is a lighter weight process meaning many of the versioned manifests do not necessarily need to be created.

  • Open an update PR that:
    • Adds a new changelog for the release
    • Updates the Cargo.toml version for the workspace:
      • version = "x.x.x"
      • bpfman = { version = "x.x.x", path = "./bpfman" }"
      • bpfman-api = { version = "x.x.x", path = "./bpfman-api" }
      • Note: bpfman-csi does not need to be updated.
    • Runs cargo generate-lockfile
    • Updates the bpfman-operator version in it's Makefile:
      • VERSION ?= x.x.x
  • Make sure CI is green and merge the update PR.
  • Create a tag using the HEAD of the main branch. This can be done using the git CLI or Github's release page.
  • Tag the release using the commit on main where the changelog update merged. This can be done using the git CLI or Github's release page.

Once these steps are completed:

  • Make sure a new RPM has been built and pushed to the bpfman COPR repository.
  • Make sure all actions have completed successfully
  • Ensure images are built and updated with the new version tag at:
    • quay.io/bpfman
    • quay.io/bpfman-bytecode
    • quay.io/bpfman-userspace

PATCH Release

  • Create a new branch in your fork named something like <githubuser>/release-x.x.x. Use the new branch in the upcoming steps.
  • Use git to cherry-pick all relevant PRs into your branch.
  • Create a branch from the major-minor tag of interest i.e: git checkout -b release-x.x.x <major.minor.patch>
  • Create a pull request of the <githubuser>/release-x.x.x branch into the release-x.x branch upstream. Add a hold on this PR waiting for at least one maintainer/codeowner to provide a lgtm. This PR:
    • Adds a new changelog for the release
    • Updates the Cargo.toml version for the workspace:
      • version = "x.x.x"
      • bpfman = { version = "x.x.x", path = "./bpfman" }"
      • bpfman-api = { version = "x.x.x", path = "./bpfman-api" }
      • Note: bpfman-csi does not need to be updated.
    • Runs cargo generate-lockfile
    • Updates the bpfman-operator version in it's Makefile:
      • VERSION ?= x.x.x
    • Runs make bundle from the bpfman-operator directory to update the bundle version. This will generate a new /bpfman-operator/bundle directory which will ONLY be tracked in the release-x.x branch not main.
  • Verify the CI tests pass and merge the PR into release-x.x.
  • Create a tag using the HEAD of the release-x.x.x branch. This can be done using the git CLI or Github's release page.
  • The Release will be automatically created, after that is complete do the following:
    • run make build-release-yamls and attach the yamls for the version to the release. These will include:
      • bpfman-crds-install.yaml
      • bpfman-operator-install.yaml
      • go-xdp-counter-install.yaml
      • go-tc-counter-install.yaml
      • go-tracepoint-counter-install.yaml
      • go-uprobe-counter-install.yaml
      • go-uretprobe-counter-install.yaml
      • go-kprobe-counter-install.yaml
      • go-app-counter-install.yaml
      • go-xdp-counter-install-selinux.yaml
      • go-tc-counter-install-selinux.yaml
      • go-tracepoint-counter-install-selinux.yaml
      • go-uprobe-counter-install-selinux.yaml
      • go-uretprobe-counter-install-selinux.yaml
      • go-kprobe-counter-install-selinux.yaml
      • go-app-counter-install-selinux.yaml
  • Update the community-operator and community-operators-prod repositories with the latest bundle manifests. See the following PRs as examples:
    • https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/2696
    • https://github.com/k8s-operatorhub/community-operators/pull/2790

MAJOR or MINOR Release

  • Open an update PR that:
    • Adds a new changelog for the release
    • Updates the Cargo.toml version for the workspace:
      • version = "x.x.x"
      • bpfman = { version = "x.x.x", path = "./bpfman" }"
      • bpfman-api = { version = "x.x.x", path = "./bpfman-api" }
      • Note: bpfman-csi does not need to be updated.
    • Runs cargo generate-lockfile
    • Updates the bpfman-operator version in it's Makefile:
      • VERSION ?= x.x.x
    • Runs make bundle from the bpfman-operator directory to update the bundle version.
    • Adds a new examples config directory for the release version.
    • Modify the tag for XDP_DISPATCHER_IMAGE and TC_DISPATCHER_IMAGE in bpfman/src/lib.rs from latest to the new release tag.
  • Make sure CI is green and merge the update PR.
  • Create a tag using the HEAD of the main branch. This can be done using the git CLI or Github's release page.
  • Tag the release using the commit on main where the changelog update merged. This can be done using the git CLI or Github's release page.
  • The Release will be automatically created, after that is complete do the following:
    • run make build-release-yamls and attach the yamls for the version to the release. These will include:
      • bpfman-crds-install.yaml
      • bpfman-operator-install.yaml
      • go-xdp-counter-install.yaml
      • go-tc-counter-install.yaml
      • go-tracepoint-counter-install.yaml
      • go-uprobe-counter-install.yaml
      • go-uretprobe-counter-install.yaml
      • go-kprobe-counter-install.yaml
      • go-app-counter-install.yaml
      • go-xdp-counter-install-selinux.yaml
      • go-tc-counter-install-selinux.yaml
      • go-tracepoint-counter-install-selinux.yaml
      • go-uprobe-counter-install-selinux.yaml
      • go-uretprobe-counter-install-selinux.yaml
      • go-kprobe-counter-install-selinux.yaml
      • go-app-counter-install-selinux.yaml