Skip to content

Commit

Permalink
[NU-1726] new quickstart adaptations (#6370)
Browse files Browse the repository at this point in the history
  • Loading branch information
coutoPL authored Jul 11, 2024
1 parent 2ee9d70 commit f593358
Show file tree
Hide file tree
Showing 14 changed files with 79 additions and 53 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ Changing the version of the Scala is done by setting `NUSSKNACKER_SCALA_VERSION`
#### Running using integration environment
- Clone [nussknacker-quickstart](https://github.com/TouK/nussknacker-quickstart)
- Clone [nussknacker-quickstart](https://github.com/TouK/nussknacker-quickstart/tree/old-quickstart)
- Run `docker-compose -f docker-compose-env.yml -f docker-compose-custom.yml up -d` inside it
#### Running Designer with model classes on the same classes as designer
Expand All @@ -146,7 +146,7 @@ and add dependency to `designer` module like in flink-streaming case.
#### Setting up Kubernetes environment
To run streaming Lite scenarios with K8s, we recommend using [k3d](https://k3d.io) with
[nussknacker-quickstart](https://github.com/TouK/nussknacker-quickstart) setup
[nussknacker-quickstart](https://github.com/TouK/nussknacker-quickstart/tree/old-quickstart) setup
- run integration environment, as described above
- `K3D_FIX_DNS=1 PROJECT_ROOT=$(pwd) k3d cluster create --network nussknacker_network --config=.k3d/single-cluster.yml`
This will create K8s cluster, which has access to Docker network used by integration environment. [K3D_FIX_DNS](https://github.com/rancher/k3d/issues/209).
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
<h3 align="center">
<a href="https://demo.nussknacker.io"><b>Demo</b></a> &bull;
<a href="https://nussknacker.io/documentation"><b>Documentation</b></a> &bull;
<a href="https://nussknacker.io/documentation/quickstart/lite-streaming/"><b>Quickstart</b></a> &bull;
<a href="https://nussknacker.io/documentation/quickstart/docker/"><b>Quickstart</b></a> &bull;
<a href="https://nussknacker.io/documentation/docs/installation/"><b>Installation</b></a> &bull;
<a href="https://cloud.nussknacker.io"><b>Nu Cloud</b></a>

Expand Down Expand Up @@ -86,8 +86,8 @@ After it started go to http://localhost:8080 and login using credentials: admin/
REST endpoints of deployed scenarios will be exposed at `http://localhost:8181/scenario/<slug>`. Slug is defined in Properties, and by default it is scenario name.
Be aware that some things (e.g. metrics) will not work, and this engine is not intended for production use.

If you want to follow step-by-step via more complex tutorials, based on production ready engines, read one of quickstart guides for: [Streaming mode on Lite engine](https://nussknacker.io/documentation/quickstart/lite-streaming)
or [Streaming mode on Flink engine](https://nussknacker.io/documentation/quickstart/flink) or [Request-response mode on Lite engine](https://nussknacker.io/documentation/quickstart/lite-request-response).
If you want to follow step-by-step via more complex tutorials, based on production ready engines, read
the [quickstart guide](https://nussknacker.io/documentation/quickstart/docker).

## Contact

Expand All @@ -110,7 +110,7 @@ with detailed instructions how to run Nussknacker with some of the older version

## Related projects

- [nussknacker-quickstart](https://github.com/TouK/nussknacker-quickstart) - Repository with quick setup (docker-compose or helm) presenting typical usage of Nussknacker
- [nussknacker-quickstart](https://github.com/TouK/nussknacker-quickstart) - Repository with quick setup (docker-compose) presenting typical usage of Nussknacker
- [nussknacker-sample-components](https://github.com/touk/nussknacker-sample-components) - Start here if you intend to create own Nussknacker components
- [nussknacker-sample-helpers](https://github.com/touk/nussknacker-sample-helpers) - Sample project showing how to add custom helpers (user defined functions)
- [nussknacker-helm](https://github.com/TouK/nussknacker-helm) - Helm chart of the project
Expand Down
2 changes: 1 addition & 1 deletion dockerhub/nussknacker-lite-runtime-app/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ tasksCount: 2
- `-e KAFKA_ADDRESS=localhost:3032` - Kafka address
- `-e SCHEMA_REGISTRY_URL=http://localhost:3082` - schema registry url

Both Kafka and schema registry can be exposed e.g. using `docker-compose-env.yml` inside [Nussknacker Quickstart](https://github.com/TouK/nussknacker-quickstart)
Both Kafka and schema registry can be exposed e.g. using `docker-compose-env.yml` inside [Nussknacker Quickstart](https://github.com/TouK/nussknacker-quickstart/tree/old-quickstart)

# License

Expand Down
2 changes: 1 addition & 1 deletion dockerhub/nussknacker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ where:
- `-e KAFKA_ADDRESS=localhost:3032` - Kafka address
- `-e SCHEMA_REGISTRY_URL=http://localhost:3082` - Schema Registry URL

Both Kafka and Schema Registry can be exposed e.g. using `docker-compose-env.yml` inside [Nussknacker Quickstart](https://github.com/TouK/nussknacker-quickstart)
Both Kafka and Schema Registry can be exposed e.g. using `docker-compose-env.yml` inside [Nussknacker Quickstart](https://github.com/TouK/nussknacker-quickstart/tree/old-quickstart)

After it started go to http://localhost:8080 and login using credentials: admin/admin.

Expand Down
17 changes: 7 additions & 10 deletions docs/installation/Installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Nussknacker built with Scala 2.12 works with Flink out of the box.
## Docker based installation

Nussknacker is available at [Docker Hub](https://hub.docker.com/r/touk/nussknacker/). You can check an example usage
with docker-compose at [Nussknacker Quickstart repository](https://github.com/TouK/nussknacker-quickstart) in `docker` directory.
with docker-compose at [Nussknacker Quickstart repository](https://github.com/TouK/nussknacker-quickstart).

Please note, that while you can install Designer with plain Docker (e.g. with `docker-compose`) with Lite engine configured, you still
need configured Kubernetes cluster to actually run scenarios in this mode - we recommend using Helm installation for that mode.
Expand Down Expand Up @@ -57,7 +57,7 @@ We provide [Helm chart](https://artifacthub.io/packages/helm/touk/nussknacker) w
Please note that Kafka (and Flink if chosen) are installed in basic configuration - for serious production deployments you probably
want to customize those to meet your needs.

You can check example usage at [Nussknacker Quickstart repository](https://github.com/TouK/nussknacker-quickstart) in `k8s-helm` directory.
You can check example usage at [Nussknacker Quickstart repository](https://github.com/TouK/nussknacker-quickstart/tree/old-quickstart) in `k8s-helm` directory.

## Configuration with environment variables

Expand Down Expand Up @@ -142,7 +142,7 @@ We assume that `java` (recommended version is JDK 11) is on path.
Please note that default environment variable configuration assumes that Flink, InfluxDB, Kafka and Schema registry are
running on `localhost` with their default ports configured. See [environment variables](#environment-variables) section
for the details. Also, `GRAFANA_URL` is set to `/grafana`, which assumes that reverse proxy
like [NGINX](https://github.com/TouK/nussknacker-quickstart/tree/main/docker/common/nginx) is used to access both Designer and
like [NGINX](https://github.com/TouK/nussknacker-installation-example/tree/master/nginx) is used to access both Designer and
Grafana. For other setups you should change this value to absolute Grafana URL.

`WORKING_DIR` environment variable is used as base place where Nussknacker stores its data such as:
Expand Down Expand Up @@ -249,18 +249,15 @@ Typical Nussknacker deployment includes Nussknacker Designer and a few additiona

Some of them need to be configured properly to be fully integrated with Nussknacker.

The [quickstart](https://github.com/TouK/nussknacker-quickstart) contains `docker-compose` based sample installation of
all needed applications (and a few more that are needed for the demo).
The [installation example](https://github.com/TouK/nussknacker-installation-example/) contains `docker-compose` based
sample installation of all needed applications.

If you want to install them from the scratch or use already installed at your organisation pay attention to:

- Metrics setup (please see quickstart for reference):
- Metrics setup (please see installation example for reference):
- Configuration of metric reporter in Flink setup
- Telegraf's configuration - some metric tags and names need to be cleaned
- Importing scenario dashboard to Grafana configuration
- Flink savepoint configuration. To be able to use scenario verification
(see `shouldVerifyBeforeDeploy` property in [scenario deployment configuration](../installation_configuration_guide/ScenarioDeploymentConfiguration.md))
you have to make sure that savepoint location is available from Nussknacker designer (e.g. via NFS like in quickstart
setup)


you have to make sure that savepoint location is available from Nussknacker designer (e.g. via NFS)
4 changes: 2 additions & 2 deletions docs/installation_configuration_guide/Common.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ Environment variables are described in the [Installation guide](../installation/

* We use HOCON (see the [introduction](https://github.com/lightbend/config#using-hocon-the-json-superset) or the [full specification](https://github.com/lightbend/config/blob/master/HOCON.md) for details) as our main configuration format. [Lightbend config library](https://github.com/lightbend/config/tree/master) is used for parsing configuration files - you can check the [documentation](https://github.com/lightbend/config#standard-behavior) for details on conventions of file names and merging of configuration files.
* `nussknacker.config.locations` Java system property (`CONFIG_FILE` environment variable for Docker image) defines location of configuration files (separated by comma). The files are read in order, entries from later files can override the former (using HOCON fallback mechanism). This mechanism is used to extend or override default configuration contained in the [minimal configuration file](#minimal-configuration-file) - see docker demo for example:
* [setting multiple configuration files](https://github.com/TouK/nussknacker-quickstart/blob/main/docker/common/docker-compose.yml#L13)
* [file with configuration override](https://github.com/TouK/nussknacker-quickstart/blob/main/docker/streaming/nussknacker/nussknacker.conf)
* [setting multiple configuration files](https://github.com/TouK/nussknacker-installation-example/blob/master/docker-compose.yml#L29)
* [file with configuration override](https://github.com/TouK/nussknacker-installation-example/blob/master/designer/application-customizations.conf)
* If `config.override_with_env_vars` Java system property is set to true, it is possible to override settings with env variables. This property is set to true in the official Nussknacker Docker image.

It’s important to remember that model configuration is prepared a bit differently. Please read [model configuration](./model/ModelConfiguration.md) for the details.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,11 @@ The table below presents most important options, or the ones that have Nussknack

### Metric dashboard

Each scenario can have a link to Grafana dashboard. In [Docker setup](https://github.com/TouK/nussknacker-quickstart/tree/main/docker/common/grafana) we
provide a sample `nussknacker-scenario` dashboard.
You can modify/configure your own, the only assumption that we make is that [variable](https://grafana.com/docs/grafana/latest/variables/) `scenarioName` is used to display metrics for particular scenario.
Each scenario can have a link to Grafana dashboard.
In [Docker setup](https://github.com/TouK/nussknacker-quickstart/tree/main/grafana/dashboards)
we provide a sample `nussknacker-scenario` dashboard. You can modify/configure your own, the only assumption that
we make is that [variable](https://grafana.com/docs/grafana/latest/variables/) `scenarioName` is used to display
metrics for particular scenario.

Each scenario type can have different dashboard, this is configured by
`metricsSettings.scenarioTypeToDashboard` settings. If no mapping is configured, `metricsSettings.defaultDashboard` is used.
Expand Down
8 changes: 6 additions & 2 deletions docs/integration/KafkaIntegration.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,15 @@ This section provides important details of Nussknacker's integration with Kafka

Schema defines the format of data. Nussknacker expects that messages in topics are described by the schema.
Nussknacker uses information contained in schemas for code completion and validation of messages.
Schema of message can be described in [Avro Schema format](https://avro.apache.org/docs/#schemas) or [JSON Schema format](https://json-schema.org) (Confluent Schema Registry only)
Schema of message can be described in [Avro Schema format](https://avro.apache.org/docs/#schemas) or
[JSON Schema format](https://json-schema.org) (Confluent Schema Registry only)

Schemas are managed by Schema Registry - *Confluent Schema Registry* and *Azure Schema Registry* are supported.

To preview schemas or add a new version, you can use tools available on your cloud platform or tools like [AKHQ](https://akhq.io). The Nussknacker Quickstart (Streaming Processing Mode) comes with bundled AKHQ, so you can add and modify schemas without the need to install additional tools. The link to AKHQ is available in the Designer in Scenarios tab under Data label.
To preview schemas or add a new version, you can use tools available on your cloud platform or tools like [AKHQ](https://akhq.io).
The [Nussknacker Quickstart](https://github.com/TouK/nussknacker-quickstart/tree/main) comes with bundled AKHQ,
so you can add and modify schemas without the need to install additional tools. The link to AKHQ is available in
the Designer in Scenarios tab under Data label.

#### Association between schema with topic

Expand Down
2 changes: 1 addition & 1 deletion docs/integration/OpenAPI.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,6 @@ level to `DEBUG` will turn on logging on all enrichers.
Enricher level logging can be enabled:

- in Flink
TaskManager [configuration](https://github.com/TouK/nussknacker-quickstart/blob/main/docker/streaming/flink/log4j-console.properties)
TaskManager [configuration](https://nightlies.apache.org/flink/flink-docs-release-1.18/docs/deployment/advanced/logging/)
- in Lite
runtime [configuration](../installation_configuration_guide/ScenarioDeploymentConfiguration.md#configuring-runtime-logging)
3 changes: 1 addition & 2 deletions docs/operations_guide/Flink.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,8 +271,7 @@ Diagnosing most of the problems below requires access to:
| Checkpoints are failing | Check jobmanager logs and/or Flink console |
| Redeploy of scenario times out | Check jobmanager logs and/or Flink console |
| `State is incompatible, please stop process and start again with clean state` during deploy | <ul><li>Check if Nussknacker has access to savepoints</li><li>Analyze if new state was added - if this is the case probably cancel before deploy is needed (to get rid of incompatible state)</li></ul> |
| Aggregate events are not emitted by aggregate in time windows nodes | Idle source (Kafka topic) or idle Kafka partition confuse Flink's watermark mechanism. To avoid this problem ensure that each Kafka source partition continually gets events |
| Aggregate events are not emitted by aggregate in time windows nodes | Idle source (Kafka topic) or idle Kafka partition confuse Flink's watermark mechanism. To avoid this problem ensure that each Kafka source partition continually gets events. Alternatively change [idleTimeout](../integration/KafkaIntegration.md/#configuration-for-flink-engine) configuration to ensure that idle source emits watermarks at acceptable intervals. |
### Nussknacker metrics
One of the crucial aspects of running production streaming jobs is monitoring. In this section we'll explain how the Nussknacker scenario running on the Flink cluster gives rise to certain metrics, how to process them and display them in Grafana.
Expand Down
Loading

0 comments on commit f593358

Please sign in to comment.