In this quick-start we provide only the essential information to avoid pitfalls and get you quickly up and running Kaholo pipelines.

Prerequisite: Get Kaholo!

User Accounts

Kaholo user accounts are identified by email address, authenticated by either Kaholo password, or using a single-sign-on authenticator such as Active Directory or GitHub. To access Kaholo and make use of the quick start you will require the URL of your Kaholo web application and a Kaholo account with sufficient privileges.

A common indication of insufficient privilege is features not appearing in the user interface. For example if the panel on the left side of Kaholo has only Executions and Pipelines, but not Settings, then it will be impossible to install plugins. Another indication of insufficient privilege when attempting something is the pop-up error message “You have no permission to do that.” If you find yourself in this position, please contact an individual on your team with sufficient privileges to elevate yours or if there are none, contact us at Kaholo.

Kaholo comes with one special account that has full and irrevocable privileges to do everything, similar to the root account in Linux or Administrator account in Windows. The name and email address associated with this account depends on how Kaholo was deployed. It is easily identified by looking in Kaholo Settings | IAM (key-shaped icon) | Users, as the only account without an “Activated” toggle switch in the right column. This account is needed only for the initial configuration of users, groups, and to install or update the license.

SaaS Deployment

If Kaholo was deployed using the Kaholo Sign Up Page the fully privileged account login is the email address given during the sign-up process, e.g. doe.j@acme.com. The initial password is provided during the sign-up process.

On-site or Trial Deployment

If you have a new deployment of Kaholo on-site using either Helm + Kubernetes or the kaholo-ansible Ansible playbook, the first user to use Kaholo’s URL will be prompted to create an Administrative user, and this account then becomes the special full privileged account.

Adding accounts

Adding accounts is done in Kaholo Settings | IAM (key-shaped icon) | Users. For users to have permissions to use Kaholo they must belong to at least one group. Various types of access is granted to groups, and individual users gain acccess through group membership. For more details on how IAM works, please refer to the documentation section on IAM.

License File

Kaholo provides a license file, in the form of a JSON Web Token, with each system. The license file determines the expiration date, number of registered users, and number of executions Kaholo will permit. Without a license file Kaholo will not execute pipelines. The license can be viewed in Kaholo Settings | License (certificate-shaped icon). There is also an “Upload License” button here to upload your license if you have a license file. You must log in using the aformentioned special full-privilege account to upload a new license file.

If using SaaS, the license is automatically managed for you. If you have deployed Kaholo on-site, you will need a license file from Kaholo to get started.

Plugins

Kaholo has over 100 plugins to make Kaholo work with various 3rd-party systems, for example Git, Docker, Kuberentes, AWS, Azure, GCP, databases, and test/build tools. If uses SaaS, several common plugins are already pre-installed. A list of installed plugins can be found in Kaholo Settings | Plugins (puzzle-peice-shaped icon)

Available Plugins

The second tab in Kaholo Settings | Plugins (puzzle-peice-shaped icon) is “Available Plugins”. Here is list a collection of commonly used plugins that have been packaged for one-click automatic installation from Kaholo’s Plugin Repository. This can also be used to upgrade plugins when newer versions become available.

In Available Plugins, if not already installed, install the JSON plugin. This is a simple plugin that reads and writes JSON files.

All Plugins

All 100+ community-developed plugins can be found in the Kaholo GitHub Repositories using search term “plugin”. There is also a very basic repository named kaholo-plugin-template that is a good starting point for developing your own plugins.

To install a plugin manually, zip its files into a zip file and use the “Upload Plugin” button in Kaholo Settings | Plugins. Each plugin repository includes an INSTALL.md file that explains in further detail.

Create a Project

Pipelines are organized by Project and user groups may also be granted access based on Project. If using GitOps, all pipelines within a Project are also associated with the Project’s source code repository. To create a new Project, in Kaholo Pipelines view click on the “Create” button and select “Create Project”. A Project can also be created while creating a Pipeline.

Create a Pipeline

A Pipeline is a collection of Actions and the flow that deterimines the order in which they execute. Every Pipeline belongs to a Project. To create a new (empty) Pipeline, in Kaholo Pipelines view click on the “Create” button and select “Create Blank Pipeline”. Give the Pipeline a name, e.g. “Hello World”, and select the Project to which the new Pipeline belongs.

Once the empty Pipeline is created you are put into Pipeline Designer View. This is the visual editor for Kaholo Pipelines. Try using the mousewheel to zoom in and out and click and drag on the empty background to shift the pipeline around.

Hello World Pipeline

Start with a very simple pipeline that writes a JSON-formatted “Hello World!” message to a file.

Add an Action

In order for the pipeline to do something an Action must first be added. Each Action in a pipeline corresponds to an installed Kaholo plugin so the Action to add for the Hello World Pipeline is a JSON one. Add the action by clicking on the small + in the middle of the Pipeline to invoke the Actions Menu.

The JSON plugin will be found in category “Basic Tools”, or if many plugins are installed it may be easier to type “json” into the search bar to narrow down the list of plugins to choose from. Click on JSON to add the Action.

Configure the Action

The next step is to configure the JSON Action we just added. To activate the configuration panel you may need to click on the JSON Action itself. The first step in any configuration is to select the Method. Select Method “Write JSON File”, to write a JSON file to the file system (on the Kaholo agent). Once a method is selected the parameters appear. Required parameters are marked with a red asterisk. This method has only two. A red “Issues” indicator appears if there are required parameters not configured, and a red outline shows there’s something not right about the new Action.

Parameter: File Path

Many actions include a path to a file or directory, on the Kaholo agent’s filesystem. The easiest way to work with the Kaholo agent is to use relative paths – or in this case no path at all but only the file name. This puts the file in the default working directory of the agent. Use file name hello.json.

Parameter: JSON Document

This parameter accepts a plain text version of a JSON document. Enter a “Hello World” message like so:

{"Message": "Hello World!"}

Once configured all the red outlining and issues in the Designer will disappear. Click the “Save” button at top right to save the pipeline.

Execution

To Execute the pipeline click the “Execute” button on the top right. This switches Kaholo to the Pipeline Execution view. On the left is a list of executions and details about each execution. The center column shows each Action in the pipeline as well as an “Initialization” Action which readies the Kaholo Agent for execution of the pipeline. On the right the Activity Log shows details about the configuration of the Action as well as potentially error and informational messages from the Action. Final Result shows the result of the execution, in this example the contents of the file written.

Summary

This covers how to gain access to Kaholo to create and execute a Kaholo Pipeline. For more advanced examples of pipeline creation please visit the “Tutorials” section of this documentation. Happy Kaholoing!