To-do List Runner
First step in building this application will be development of the runner, which will facilitate read/write operations to a MongoDB collection.
Last updated
Core Platform
First step in building this application will be development of the runner, which will facilitate read/write operations to a MongoDB collection.
Last updated
Open the Element screen from your Devops app. Unless you've modified your implementation, this screen is located at https://[YOUR_ADMIN_UI_DOMAIN]/app/devops/common/element.
Next, you will create the configuration for a new data store which will maintain to-do list records in a MongoDB collection.
Click on "CREATE NEW" button on top of the menu lister of Element screen. This will clear the contents of Element design page, and allow you to create a new Element from scratch.
Provide a unique identifier to your new element from top left corner marked with "ID: " tag and a pencil icon. For this example, we are using "state-todo-0001" as the id.
Enter the following details from "DEFINITION" and "SETTINGS" tabs and save:
DEFINITION
Element Name: Todo
Element Type: STATE
Element Status: ACTIVE
Element Description (optional): Example todo list data store
SETTINGS
Name: manager, Value: com.rierino.state.manager.MongoStateManager
Name: system, Value: mongo_master
Name: collection, Value: todo
These settings will mean that this state will be managed by a MongoStateManager using connection settings provided by the already existing "mongo_master" system element and records will be stored in a collection named "todo".
Why do you need Elements?
Elements provide reusable building blocks for runners. Without such an element structure, you would need to define all configurations, settings and parameters within the runners, which would mean replications and maintenance issues for systems, states or handlers shared between different runners.
Next, you will create a new runner, which will be responsible for executing read/write operations on the new todo state you defined.
Click on the Runner icon on navigation bar to switch to the Runner screen on your Devops app. Unless you've modified your implementation, this screen is located at https://[YOUR_ADMIN_UI_DOMAIN]/app/devops/common/runner.
Click on "CREATE NEW" button on top of the menu lister of Runner screen and provide the unique identifier "todo-0001".
Click on the circled edit icon for displaying Runner definition screen.
Enter the following details on displayed screen for describing your new Runner graph:
Runner Name: Todo
Runner Status: ACTIVE
Runner Domain (optional): admin
Base Runners: Command Base, Spring Base
Runner Description (optional): This is an example runner for todo list management.
These settings will mean that the new runner will inherit features from the "Command Base" and "Spring Base" runners, making it possible to receive commands from a central Kafka topic, as well as providing common Spring deployment properties.
For this example, you do not need to set I/O or Settings details. Click on the close icon on top right corner to apply changes.
From the stencil, drag and drop a System element to the runner graph.
Similarly, drag and drop , a State and 2 Handler elements from the stencil. Your graph should look like the following after these actions:
Click on the System element and you will see an edit icon displayed on its top left corner, click on it to edit element details as follows:
Element: system-mongo_master-0001
Member Type: OPERATION
Alias: mongo_master
Description(optional): MongoDB system for master collections
These settings will add the predefined "system-mongo_master-0001" system element to the runner with "mongo_master" alias. This assigned alias automatically links the system to related other elements (such as the State element).
Why do you need Aliases?
We use aliases in addition to element ids when assigning elements to runners. This allows us to replace core elements such as Systems when needed without having to update all other elements dependent on them. It also allows reusing same elements multiple times within a runner, which can be preferred for organization or configuration purposes (e.g. using 2 copies of the same Handler with different parameter overrides).
If you click on the "ELEMENT" tab, you can see parameters assigned to this elements during its initial definition.
Click on APPLY button to apply changes and close the dialog.
Next, edit the State element in a similar way, with the following details:
Element: state-todo-0001 (as created in earlier step)
Member Type: OPERATION
Alias: todo
Description (optional): State for todo list records
Click on APPLY button to apply changes and close the dialog.
Next, edit the 2 handler elements in a similar way, with the following details:
Element: handler-read-0001
Member Type: OPERATION
Alias: read
Description (optional): Event handler for reading from a state manager
"handler-read-0001" element is a predefined event handler which allows reading from any state manager assigned to a runner.
This time, also switch to the "I/O" tab, and add following details:
Role: event
Inputs: todor
These settings mean that if this runner receives a request from "todor" (short for "todo read") stream, it should be processed by read event handler.
Please note that for web based requests, it is not required to add Stream elements to runners, as they are automatically detected from the request paths. If you would like this runner to receive requests from a Kafka stream, you need to also create the "todor" stream as an element and add it to the runner.
Similar to the read handler, also add a write handler which will allow storing todo records on the State:
Element: handler-write-0001
Member Type: OPERATION
Alias: write
Description (optional): Event handler for writing to a state manager
"handler-write-0001" element is a predefined event handler which allows writing to any state manager assigned to a runner.
Why are Read & Write Handlers separate?
This approach providing ability to create "Read-only" runners which do not have write handler elements added, when needed.
Again, switch to the "I/O" tab, and add following details:
Role: event
Inputs: todow
These settings mean that if this runner receives a request from "todow" (short for "todo write") stream, it should be processed by write event handler.
Once you've completed all these steps, you will notice that the Runner graph is labelled and all relations between different elements automatically linked as follows:
Once your runner is defined, next step is to deploy it to get it up and running. It is possible to deploy multiple runners within a single deployment package, but for this example, you will be deploying the runner as a stand-alone package.
First, open the Deployment screen from your Devops app. Unless you've modified your implementation, this screen is located at https://[YOUR_ADMIN_UI_DOMAIN]/app/devops/common/deployment.
Click on "CREATE NEW" button on top of the menu lister of Deployment screen and provide the unique identifier "example-0001".
Fill in the "DEFINITION" tab with following details:
Name: Example Runners
Status: ACTIVE
Description (optional): Deployment package for execution of example runners
Runners:
Name: todo
Class: com.rierino.runner.spring.CRUDEventRunner
Element: todo-0001
Deployment Version: 1
These settings assign 1 runner with "todo-0001" identifier, which is created in previous steps to this deployment. Runner name has various uses, such as log labeling, targeting runners for commands, forming URL paths, as well as application / consumer naming. Runner class defines the type of Runner to be used for execution (such as CRUD, RPC, Socket or Samza). Deployment version is useful when multiple versions of a runner needs to be running at the same time (e.g. during a systems migration).
Why do you need a Deployment?
Runners define "how" and "what" of microservices to be used, providing an abstraction over "where" these services are deployed. This approach allows separation of configuration and infrastructure responsibilities, while allowing deployment of same runners in different servers (e.g. for multi-national deployments, replication). It also allows coupling of multiple runners into single deployment, for microservices that do not require heavy resources.
Next, switch to the "PARAMETERS" tab and enter the following parameter key-value pairs:
rierinoVersion: 0.1.1
template: spring
namespace: admin-backend
pool: admin-node-pool
These settings specify the Rierino core libraries and settings to deploy, as well as the Kubernetes namespace and node pool to utilize for creating this runner.
You can increase scalability of your runner by setting replicaCount parameter to 2 or more, or increase its log level by setting logLevel to "DEBUG".
Click on SAVE button to finalize creation of the deployment.
Next, from the dropdown menu on top right side of the Deployment screen, click on "DEPLOY" button.
This will automatically trigger a deployment request and you will receive a notification of successful delivery of the request.
In case you have access rights to your infrastructure, you can check deployment status of your Runner through the Jenkins interface as well as Kubernetes management portal of your cloud service provider.
Once the runner is up and running, there are 2 ways you can use to test its status:
First option is to ping your runner, which can be done clicking on "PING" button on the Deployment screen you've used in previous step. Once you click on the "EXECUTE" button on displayed dialog, you should receive your ping results in a few seconds:
Response column in this table indicates that the runner acknowledged the ping request and responded successfully.
Second option is to use your new runner's endpoints for read / write operations on your todo list records. By default, all runners are deployed in a secure cluster without exposing a public endpoint and are only accessible from within that cluster or through the Gateway Servers.
If you don't wish to wait for setting up the gateway access as described in next section, you can use kubectl commands for this test as follows:
This will establish connection to your deployed runner, from which you can do REST calls using curl:
