How to Contribute to Nuclio#

This guide will guide you through the process of setting up a development environment and contributing to Nuclio.

In This Document#

Prerequisites
Getting the source code
Setting up a GoLand project
Submitting a PR

Prerequisites#

Ensure that your setup includes the following prerequisite components:

Linux or OSX
Git
Docker version 19.03+
The Go toolchain (CI tests with 1.21, best use that)
Kubernetes version 1.24+ (mostly for testing) - minikube recommended; (you can follow the Minikube getting-started guide)

Getting the source code#

Fork the Nuclio GitHub repository and clone it:

git clone https://github.com/<your username>/nuclio.git ~/nuclio

Check out the development branch, because that’s where all the goodness happens:

cd ~/nuclio && git checkout development

Now, use make modules to get Nuclio’s dependencies and modules

Build Nuclio artifacts (nuctl, container images):

make build

You should now have quite a few nuclio/<something> images tagged as latest-amd64, along with nuctl-latest-<os>-amd64 with a nuctl symbolic link under $GOPATH/bin.

Note: to make nuclio container images available for arm64 architecture run NUCLIO_ARCH=arm64 make build

Now, run a few unit tests:

make lint test-unit

This is a short test suite, and requires only Docker.

Note: Writing (Go) Nuclio tests requiring it having build tag annotation at the first line Use the following build tag annotations to match the test purpose:

test_unit - unit testings
test_integration - integration testings
test_functional - functional testings
test_kube - requires kubernetes platform
test_local - requires docker platform
test_iguazio - requires Iguazio system
test_broken - test suite is broken, cannot be executed on CI

To run Kubernetes nuctl suite locally:

NUCTL_REGISTRY=<registry> make test-k8s-nuctl

To run Docker nuctl suite locally:

make test-docker-nuctl

To run Kubernetes platform integration test locally:

# Installing nuclio CRDs
$ sh test/k8s/ci_assets/install_nuclio_crds.sh

# Running local Docker registry
$ docker run --rm -d -p 5000:5000 registry:2

$ make test-k8s

To run integration tests for docker platform, run:

make test

Note: it may take a while ~90 minutes

On Nuclio CI, we run nuctl test suites against both Docker and Kubernetes platforms.

Running more comprehensive end-to-end tests on kubernetes is currently done manually.

When you’re done, create a feature branch from the development branch; (Nuclio follows the GitFlow branching model):

git checkout -b my-feature

Setting up a GoLand project#

The Nuclio team is a fan of GoLand and uses it heavily for Go projects. It was decided not to include the .idea files at this time, but it’s very easy to create run/debug targets and use the debugger

Clone nuclio git clone git@github.com:nuclio/nuclio.git > ~/nuclio
Open GoLand and File > Open and select ~/nuclio
Enable go modules GoLand > Preferences > Go > Go Modules (vgo) and ensure Enable Go Modules box is checked
Run configurations are (currently) available for tests only

For developing in nuclio locally, see Local development.

Versioning note#

All Nuclio artifacts are versioned. They take their versions from variables in v3io/version-go/version.go.

During link time, the linker set the version variables using the -X flag.

Since there is an auto-fallback to “latest”, if you want to use versioned binaries, make sure to pass the following as part of the Go tool arguments in the Run/Debug configuration:

-ldflags="-X github.com/v3io/version-go.label=1.7.2"

Running the processor (Go)#

Under normal circumstances, the function provided by the user is compiled as a Go plugin that’s loaded by the processor. If you need to debug this plugin loading mechanism, you’re advanced enough to find your way around. If all you want to do is test a new feature on the processor, the easiest way to achieve this is to use Go with the built-in handler (nuclio:builtin). When you specify handler: nuclio:builtin in the processor configuration file, the Go runtime doesn’t try to load a plugin and simply uses pkg/processor/runtime/golang/runtime.go:builtInHandler(). Feel free to modify that function, just don’t check in your changes.

The processor configuration file is basically the content of your function.yaml function-configuration file:

spec:
  runtime: golang
  handler: nuclio:builtin
  logger:
    level: debug
  triggers: { }

Another configuration that should be given to the processor is the platform configuration, which looks like this:

logger:
  sinks:
    myStdoutLoggerSink:
      kind: stdout
  system:
    - level: debug
      sink: myStdoutLoggerSink
  functions:
    - level: debug
      sink: myStdoutLoggerSink

Create these two configuration files in your preferred location, and pass --config <path to processor.yaml> --platform-config <path to platform-config.yaml as Program arguments in the Run/Debug configuration.

For more information about the platform configuration, see Configuring a Platform. For information about the function configuration, see the Function-Configuration Reference.

Running the Nuclio CLI (nuctl)#

There’s nothing special required to run nuctl, but you may want to pass --platform local in case you don’t want to work with Kubernetes.

Submitting a PR#

Your PRs will go through Github Action CI and code review. Make sure to follow the coding conventions and run make fmt lint before submitting a PR, that would save you some time failing on CI linting and test validations

How to Contribute to Nuclio

Contents