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 target | What you need | Guide |
|---|---|---|
| Flink MiniCluster | No separate Flink cluster | Embedded execution and tuning |
| Flink session cluster | An existing compatible JobManager and TaskManagers | Flink |
| Ververica Platform | An 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 session | Ververica 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:
- In Designer, create a Request-Response scenario named
helm-hello-world. - Connect a Request source to a Response sink. Set the request method to
POSTand the slug tohelm-hello-worldin the Request node or scenario Properties. - Define a required string field named
messagein both the input schema and the response schema for HTTP status200. In the Response node, enable Raw editor, set Value to#inputand leave HTTP status code at200. - Save the scenario and deploy it to Request-Response embedded. Wait until it is
RUNNING. - 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.