Skip to main content


This quickstart describes how to install Nussknacker configured to use Lite engine in Request-Response Processing mode using helm and Kubernetes and goes through sample scenarios.

If you want really quick look, you can run some parts of this quickstart with embedded engine with:

docker run -it --network host -e DEFAULT_SCENARIO_TYPE=request-response-embedded touk/nussknacker:latest

Note that some things (e.g. metrics) will not work, and this mode is not intended for production use.


  • helm, kubectl (more or less latest version) installed
  • access to Kubernetes cluster
    • for local installation with k3d see below
    • cluster should have ingress configured

Running on local K3d

If you don't have K8s available, we recommend installing k3d. Instructions below assume that the cluster was created with ingress port mapped to 8081 - see guide for the details.


  • Clone Nussknacker-quickstart project from GitHub.
  • Enter k8s-helm directory.
  • If you have configured TLD connected to your ingress (not applicable with e.g. k3d setup), set DOMAIN parameter in .env file.
  • Install additional sample customer service, not included in standard chart with ./additional/ Wait until they're running.
  • Run ./k8s-helm/ and wait until all components start.

In all links below we assume using k3d setup, described above. If you use ingress with TLD configured, please replace http://localhost:8081 with http(s)://nu-quickstart-nussknacker.$DOMAIN/ in all links below.

Now you are ready to check your newly created environment:

Defining a new scenario

  • Go to Nussknacker
  • Click 'Create new scenario' button - name it 'LoanRequest'
  • You'll see an empty workspace
  • Click 'Import' on right panel and upload 'k8s-helm/scenarios/LoanRequest.json'

This scenario determines acceptable amount for loan request. It uses only data available in request in this step.

Input and output schemas are available after clicking properties button:

"properties": {
"customerId": {
"type": "string"
"location": {
"properties": {
"city": {
"type": "string"
"street": {
"type": "string"
"requestType": {
"type": "string"
"requestedAmount": {
"type": "number"
"required": ["customerId", "location", "requestType", "requestedAmount"],
"additionalProperties": false
  • Double-click on nodes to see scenario logic
  • Click 'Save'

You have just created your first scenario!

Test scenario with data

  • Click 'Deploy' on the right panel
  • Wait until deployment status shows running
  • After that your scenario should be exposed as nu-quickstart-loan service inside Kubernetes. First part of service name (nu-quickstart) is taken from helm release name. The second part is defined in "slug" scenario property. You can change it if you want. You can now communicate with deployed k8s service from other POD deployed on the same cluster. For our purpose we expose service port (80) on our machine port (3181) via:
kubectl port-forward service/nu-quickstart-loan 3181:80
  • Now service is available at http://localhost:3181. You can communicate with it using web interface at http://localhost:3181/swagger-ui or you can use curl command for that:
curl -d '{customerId: "anon", requestedAmount: 1555, requestType: "mortgage", location: { city: "Warszawa", street: "Marszałkowska" }}' -HContent-Type:application/json -i http://localhost:3181

or you can run script, that sends similar sample requests:

./k8s-helm/scripts/ <number between 1 and 6>

You should see result similar to below:

$ ./ 1
Sending request:

{customerId: "anon", requestedAmount: 1555, requestType: "mortgage", location: { city: "Warszawa", street: "Marszałkowska" }}

HTTP/1.1 200 OK
Server: akka-http/10.2.9
Date: Fri, 16 Sep 2022 08:17:25 GMT
Content-Type: application/json
Content-Length: 58

{"acceptedAmount":1000,"message":"Large sum for Warszawa"}
  • You can check Metrics tab on Nussknacker. You should see that data were changing a moment after each request.

Test your scenario in a sandbox

For Request-Response scenarios 'generate' feature is currently unavailable, but you can test your scenario with some own prepared file with requests separated by newline. You can use for that ./k8s-helm/scripts/sampleLoanRequests.txt which was used by script described above.

  • Click 'from file' button and upload file with sample requests
  • After a while you will see test results - how many records passed filters, and what where variables values

Add more behaviour to the scenario

After creating and running basic scenario it's time to add more sophisticated behaviour - in this (optional) section you'll see how to use a bit more complex components. After each step you can deploy, test and see modified results.

Integration with external system

In next step we'll see how to enrich data using external system, exposing customer data via OpenAPI. We implemented sample service in python (see customerservice folder), to show you don't have use Java to integrate with Nussknacker.

You can look at k8s-helm/values.yaml file (look for components.openAPI setting) to see how easy it is to configure additional OpenAPI services.

Click 'Import' on right panel and upload k8s-helm/scenarios/LoanRequestWithEnrichers.json

You can see how we use new Enricher getcustomer to retrieve additional customer data to be able to categorize suspicious situations based on customer category

On the video you can see how Nussknacker detect fields from external service and how you can see metrics for OpenAPI intergration.