Skip to main content
Version: Current

Getting started with Helm

This guide installs Nussknacker on Kubernetes and takes you through opening Designer and running your first scenario. The default evaluation setup runs Flink MiniCluster and the Lite Request-Response engine inside Designer. Postgres, Kafka, Schema Registry, Blabber and monitoring are included.

No Docker client or separate Flink installation is needed for the default setup. If you already have a Flink cluster or Ververica Platform, choose its values guide in step 3 instead.

Prerequisites​

  • Kubernetes 1.27 or newer, Helm 3.8 or newer, and kubectl connected to the intended cluster.
  • A default StorageClass, or a StorageClass selected through the chart's persistence settings.
  • Approximately 3 CPU and 9 GB of allocatable memory for the default stack, plus capacity for your scenarios.
  • Permissions to create a namespace, Secrets, workloads and PVCs.
  • curl for the example HTTP call, or use the scenario's Swagger UI.
  • Registry credentials, a Nussknacker license and the exact chart version supplied by Nussknacker. Contact us if you do not have them.

Run the shell examples in Bash on Linux, macOS or Windows through WSL. Check your Kubernetes context first:

kubectl config current-context

An ingress controller and DNS are optional for local evaluation. For browser access through a domain name, prepare them before following the ingress instructions.

1. Chart registry and image access​

The chart is an OCI artifact in registry.nussknacker.io; the application images are in the same private registry. Helm downloads the chart, while Kubernetes pulls the container images. Both need access credentials. OCI installation does not require helm repo add.

Log in with the registry username and password you received:

helm registry login registry.nussknacker.io

Set the exact chart version you received:

export NU_HELM_VERSION='<exact chart version supplied>'
export NU_HELM_CHART=oci://registry.nussknacker.io/nussknacker/charts/nussknacker

The chart version and the application image version are separate identifiers. Do not use an application release line such as 2.3 as Helm's --version value. These guides require a chart with the nussknacker.streaming.deploymentTargets values interface.

For a supplied snapshot chart, use its exact snapshot version and its OCI reference instead:

export NU_HELM_CHART=oci://registry.nussknacker.io/nussknacker-snapshot/charts/nussknacker

2. Configure the namespace and Secrets​

Create the namespace for Designer and its bundled dependencies:

export NU_NAMESPACE=nussknacker
kubectl create namespace "$NU_NAMESPACE"

Install one stack per namespace: the chart uses fixed resource names. You can choose another namespace; keep the same value in all commands.

Helm authentication downloads the chart. Kubernetes needs a separate image-pull Secret to pull the private application images. The examples reference nussknacker-registry and nussknacker-license in values.yaml.

Create the image-pull Secret, replacing the placeholders with your registry credentials:

kubectl -n "$NU_NAMESPACE" create secret docker-registry nussknacker-registry \
--docker-server=registry.nussknacker.io \
--docker-username='REPLACE_WITH_REGISTRY_USERNAME' \
--docker-password='REPLACE_WITH_REGISTRY_PASSWORD'

Create the license Secret with the trial license key you received:

kubectl -n "$NU_NAMESPACE" create secret generic nussknacker-license \
--from-literal=NU_LICENSE_KEY='REPLACE_WITH_LICENSE_KEY'

3. Chart configuration​

For local evaluation, create values.yaml with the following content. It selects the embedded engines and disables ingress; you will open Designer through port-forwarding in step 6. global.publicUrls supplies the local Request-Response and gateway addresses shown in Designer. The gateway WebSocket address is derived automatically from its HTTP address.

# Local evaluation: access Designer and scenario endpoints with kubectl port-forward.
ingress:
enabled: false
global:
publicUrls:
requestResponse: http://localhost:8191
gateway: http://localhost:18147
imagePullSecrets:
- name: nussknacker-registry
license:
existingSecret: nussknacker-license
environment: trial
nussknacker:
streaming:
deploymentTargets:
- name: Flink MiniCluster
useMiniClusterForDeployment: true
requestResponse:
deploymentTargets:
- name: Request-Response embedded

For another execution environment, use the complete values from the matching guide instead:

Deployment targetWhat you needGuide
Flink MiniClusterNo separate Flink clusterEmbedded execution and tuning
Flink session clusterAn existing compatible JobManager and TaskManagersFlink
Ververica PlatformAn existing VVP installation and a Flink 1.20 / Scala 2.12 Designer image; shared RWX storage for perJob or a running session cluster with a sufficient upload limit for sessionVerverica Platform

The Flink and VVP examples use ingress hostnames; replace all REPLACE_WITH_ fields and prepare DNS for them. The VVP variant has steps of its own before the installation: do them in the order of its guide. The chart installs Designer and its dependencies; it does not create an external Flink cluster or install VVP.

Use your own services​

For bundled Postgres and Grafana, keep the defaults. The chart configures their addresses and credentials automatically, including namespace-qualified service addresses for scenarios running in another namespace. Grafana uses /grafana on the Designer ingress host.

Only add the following settings if you use your own Postgres or Grafana. Merge the relevant block into values.yaml; each service can be replaced independently.

For an external Postgres, create a Secret with its password:

kubectl -n "$NU_NAMESPACE" create secret generic nussknacker-db \
--from-literal=password='REPLACE_WITH_DATABASE_PASSWORD'
postgres:
enabled: false
externalDatabase:
host: REPLACE_WITH_DATABASE_HOST
existingSecret: nussknacker-db

The defaults are port 5432, database nussknacker and username nussknacker. Set port, database or username under externalDatabase only when yours differ.

The chart uses this one database definition for Designer, the SQL key-value store and database-backed live data preview. You do not need to repeat JDBC URLs in designer.extraConfig or the model configuration. Both Designer and the Flink runtime must be able to reach it.

For an external Grafana, supply its URL once, including any subpath:

grafana:
enabled: false
externalGrafana:
url: https://grafana.example.com

Designer uses this URL for its dashboard links. Configure authentication, the InfluxDB data source and Nussknacker dashboards in that Grafana installation.

4. Initial installation​

helm upgrade --install nussknacker "$NU_HELM_CHART" \
--version "$NU_HELM_VERSION" --namespace "$NU_NAMESPACE" \
--values values.yaml --wait --timeout 20m

The first start can take several minutes. The dependency charts are included in the package, so no other Helm repositories need to be added. The license is read from the Secret created in step 2.

5. Verify the installation​

kubectl -n "$NU_NAMESPACE" get pods
kubectl -n "$NU_NAMESPACE" get svc
helm test nussknacker --namespace "$NU_NAMESPACE" --timeout 5m

The application workloads should be ready and the Helm test should succeed. Initialization jobs can be Completed. If pods stay Pending, check resources and PVC provisioning. For ImagePullBackOff, check the image-pull Secret and the selected image repositories/tags.

kubectl -n "$NU_NAMESPACE" get pvc
kubectl -n "$NU_NAMESPACE" get events --sort-by=.lastTimestamp
kubectl -n "$NU_NAMESPACE" logs deployment/nussknacker-designer --tail=100

helm test checks the application and dependency endpoints. It does not deploy a scenario through an external Flink cluster or VVP; complete the execution check on the relevant variant page too.

6. Access Designer​

Option 1: Port forwarding​

For the local values above, run this command and leave the terminal open:

kubectl -n "$NU_NAMESPACE" port-forward service/nussknacker-designer 8090:8080 8191:8181

Open http://localhost:8090 and sign in with admin / admin. Reset that password under Administration → Users after the first login; the Designer generates a new one and shows it once. Request-Response scenarios are reachable on port 8191 while the command is running.

To use the HTTP/WebSocket gateway with a streaming scenario, open a second terminal and forward its port too:

kubectl -n nussknacker port-forward service/nussknacker-blabber 18147:8147

For optional access to scenario dashboards through port-forwarding, add this local URL to values.yaml and repeat the Helm command from step 4. This overrides the default ingress address for this access method; Designer takes its dashboard links from the same setting:

grafana:
grafana.ini:
server:
root_url: "http://localhost:3000/grafana/"

Then forward the Grafana authentication proxy in another terminal:

kubectl -n nussknacker port-forward service/nussknacker-grafana 3000:80

Open dashboards from Designer so its sign-in token is passed to Grafana. Port-forwarding Designer alone does not expose Grafana. Use your selected namespace in the additional commands if it differs. If you choose other local ports, update the corresponding public URL settings in values.yaml too; Grafana's URL is set only in server.root_url.

Option 2: Ingress​

To expose the installation through domain names, merge the following settings into your existing values.yaml. Keep your chosen engine configuration and Secret references. When migrating from the local example, remove the global.publicUrls overrides and the optional Grafana server.root_url so the chart derives them from the ingress hosts. Use three distinct DNS names pointing at your ingress controller and set its ingress class. The example assumes an existing TLS Secret covering all three names:

global:
ingress:
hosts:
designer: nussknacker.example.com
requestResponse: request-response.nussknacker.example.com
gateway: gateway.nussknacker.example.com
tls:
enabled: true
secretName: nussknacker-tls
ingress:
enabled: true
className: nginx

Repeat the Helm command from step 4 to apply the settings. Open https://nussknacker.example.com; Grafana is available under /grafana on that host using Designer sign-in. Request-Response endpoints use https://request-response.nussknacker.example.com/scenario/<slug>, and gateway addresses use the gateway host. The names must resolve from the browsers and clients sending requests.

7. Run your first scenario​

The chart does not automatically import or deploy example scenarios. You can import a scenario JSON supplied with your trial, or create a small Request-Response scenario to verify the installation:

  1. In Designer, create a Request-Response scenario named helm-hello-world.
  2. Connect a Request source to a Response sink. Set the request method to POST and the slug to helm-hello-world in the Request node or scenario Properties.
  3. Define a required string field named message in both the input schema and the response schema for HTTP status 200. In the Response node, enable Raw editor, set Value to #input and leave HTTP status code at 200.
  4. Save the scenario and deploy it to Request-Response embedded. Wait until it is RUNNING.
  5. With the port-forward command still running, call the endpoint:
curl --fail http://localhost:8191/scenario/helm-hello-world \
-H 'Content-Type: application/json' \
-d '{"message":"Hello from Nussknacker"}'

The response should contain the same message value. With ingress, use your Request-Response host instead. If the scenario requires authentication, use the invocation shown in its Properties Integration section. See Request-Response authoring for schema editors and endpoint access settings.

This checks the embedded Request-Response engine. To check streaming execution, deploy a streaming scenario to Flink MiniCluster, Flink trial or Ververica Platform trial, according to your chosen values, and verify it processes records. The variant guides describe the additional runtime and metrics checks.

Further configuration​

nussknacker.streaming.deploymentTargets defines the named Flink destinations offered when deploying a scenario. Each entry has its own name and execution settings. streaming.deploymentConfig supplies shared defaults; streaming.modelConfig supplies the shared model and components. With an empty target list, the chart uses its existing single-target deployment configuration.

The first target is the initial default for a scenario that has no previous deployment. Later deployments normally reuse the previous target. An order saved in Designer takes precedence over the YAML order. Use stable, unique names when upgrading an installation with deployed scenarios.

In Helm values the JobManager address is flinkRestUrl. The chart translates it to the application's restUrl. Do not combine a target list with the legacy designer.useMiniCluster and designer.flinkRestUrl aliases. Only one embedded Flink target and one embedded Request-Response target can be defined by this chart.

designer.extraConfig contains HOCON layered after the generated configuration. designer.extraConfigFiles adds mounted files after that, in list order. These overrides remain available for deployment managers such as Ververica Platform, whose configuration is shown in its guide. See scenario deployment configuration for the underlying settings.

Upgrade and cleanup​

To upgrade, update NU_HELM_VERSION and your values, then repeat the Helm command from step 4 and run helm test again. Designer uses Recreate: embedded scenarios restart with its pod, while scenarios on remote Flink continue running there. Rotating an externally managed environment Secret does not necessarily replace the pod; restart Designer after changing such a credential:

kubectl -n "$NU_NAMESPACE" rollout restart deployment/nussknacker-designer

Generated passwords use Helm lookup to reuse existing Secrets during connected upgrades. For Argo CD or other offline rendering, provision credentials outside the chart and configure its existingSecret settings.

To remove the release:

helm uninstall nussknacker --namespace "$NU_NAMESPACE"

Persistent data and retained credential Secrets may remain. Namespace deletion is a separate operation that removes its resources and can delete associated storage; it is not part of this uninstall command.