Design

April 24, 2026 ยท View on GitHub

The system is implemented as a k8s operator using the operator-sdk but is deployed as a DaemonSet instead of Deployment with filtering only events for the DaemonSet pod node.

NetworkManager compatibility

kubernetes-nmstate is connecting to NetworkManager running on a host. That implies the following dependency requirements:

kubernetes-nmstate versionNetworkManager version
main, > 0.15.0>= 1.22
<= 0.15.0>= 1.20

Development

For detailed information on setting up your development environment, building, testing, and working with local or remote clusters, see the Developer Guide.

Open a Pull Request

kubernetes-nmstate generally follows the standard GitHub pull request process, but there is a layer of additional specific differences:

The first difference you'll see is that a bot will begin applying structured labels to your PR.

The bot may also make some helpful suggestions for commands to run in your PR to facilitate review. These /command options can be entered in comments to trigger auto-labeling and notifications. Refer to its command reference documentation.

Common new contributor PR issues are:

  • Missing DCO sign-off:
    Developer Certificate of Origin (DCO) Sign-off is a requirement for getting patches into the project (see Developers Certificate of Origin). You can "sign" this certificate by including a line in the git commit of "Signed-off-by: Legal Name ". If you forgot to add the sign-off, you can also amend your commit with the sign-off: git commit --amend -s.

Code Review

To make it easier for your PR to receive reviews, consider the reviewers will need you to:

  • Follow the project coding conventions.
  • Write good commit messages.
  • Break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue.

Best Practices

  • Write clear and meaningful git commit messages.
  • If the PR will completely fix a specific issue, include fixes #123 in the PR body (where 123 is the specific issue number the PR will fix. This will automatically close the issue when the PR is merged.
  • Make sure you don't include @mentions or fixes keywords in your git commit messages. These should be included in the PR body instead.
  • Make sure you include a clear and detailed PR description explaining the reasons for the changes, and ensuring there is sufficient information for the reviewer to understand your PR.

Releasing

To cut a release, push images to quay and publish it on GitHub. The command make release does all this automatically; the version is at version/version.go and the description at version/description.

So the steps would be:

  • Prepare a release calling make prepare-(patch|minor|major)
  • Edit version/description to set a description and order commits
  • Create a PR to review it
  • Merge it to main
  • Wait for Prow to do the release.

The environment variable GITHUB_TOKEN is needed to publish at GitHub, and it must point to a token generated by GitHub to access projects.

Profiling

There is a possibility to enable golang pprof profiler.

  • Enable profiler in operator.yaml by changing value of 'ENABLE_PROFILER' to True

  • You can change profiler port by editing 'PROFILER_PORT' - default is 6060

  • Deploy new code to cluster - example: make cluster-sync

  • Find nmstate-handler pod name - kubectl get pods -n nmstate

  • Create port forwarding to pod - example: kubectl port-forward pod/pod_name 6060:6060 -n nmstate

  • Use go tool pprof ... to gather relevant metrics. Examples:

    • open in browser http://localhost:6060/debug/pprof/
    • download memory graph go tool pprof -png http://localhost:6060/debug/pprof/heap > out.png
    • open cli for cpu 30s sample data go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

    More examples can be found here: https://golang.org/pkg/net/http/pprof/

CI infrastructure

FAQ

The NodeNetworkState does not show the state correctly at ubuntu 18.04 nodes.

In Ubuntu 18.04 they introduced netplan for the network configuration. So to enable NetworkManager you need to follow these steps:

# 1. edit /etc/netplan with:
network:
  version: 2
  renderer: NetworkManager

# 2.- apply the changes
netplan generate
netplan apply

References: