[opensourcedex]

kala is a free, open source orchestration & scheduling project written in Go and released under MIT. It has 2,156 GitHub stars, 190 forks and 15 open issues, and was last pushed 10 months ago. On this registry it ranks #45 of 64 tracked projects in Orchestration & Scheduling, with 5 head-to-head comparisons available.

What is kala?

What it is

Kala is an open-source job scheduler written in Go under the MIT license. It sits in the Infrastructure & Operations / Orchestration & Scheduling category and describes itself as a modern service for scheduling jobs. The project ships as a single binary with no external dependencies, exposes a JSON over HTTP API, includes a web UI, and supports persistent storage through several database drivers.

Kala solves the problem of running recurring and dependent jobs without deploying a heavy distributed scheduler. Its README says it was inspired by the desire for a simpler Chronos, developed by Airbnb, and calls itself Chronos for the rest of us, especially start-ups. The same documentation warns that Kala is not battle-tested and recommends Chronos if fault tolerance, distributed features, or massive scale are required.

Key capabilities

  • Kala schedules jobs with ISO 8601 date and interval notation.
  • It exposes a JSON over HTTP API, listens on 127.0.0.1:8000 by default, and offers a stats endpoint at /api/v1/stats/.
  • It tracks job stats, including active jobs, disabled jobs, total jobs, error count, success count, next run time, and last attempted run time.
  • It supports configurable retries for failed jobs.
  • It supports dependent jobs for jobs that depend on other jobs.
  • It persists state with BoltDB by default and can use Redis, Consul, MongoDB, PostgreSQL, MariaDB, or MySQL through command-line parameters.
  • It includes a web UI for viewing jobs.

Who uses it and how

  • Start-ups can use Kala when they need a simpler alternative to Chronos rather than a fault-tolerant distributed system.
  • Operators can run it as a single service on one machine and keep it alive with supervisord, using autorestart and log files.
  • Developers can create and manage jobs through curl, the official Go client, or the examples directory.
  • Teams that need durable job metadata can choose a backend with flags such as --jobdb=redis, --jobdb=postgres, or --jobdb=consul.
  • Users can monitor state through the stats endpoint or the web UI.

Getting started

Typical installation is go get github.com/ajvb/kala, followed by kala serve, optionally with -p to change the port. The README also shows deployment through supervisord and Docker.

When to use it — and when not to

Kala fits single-node or small-team scheduling where a simple binary and HTTP API matter more than distributed coordination. It is not suitable when fault tolerance, distributed features, or massive scale are required, because the README recommends Chronos for those cases. A self-hoster must operate the chosen persistence backend and process supervision, and must accept that Kala is not battle-tested.

project readme (upstream, from github) — read inline

Kala

GoDoc golangci-lint Circle CI Coverage Status

Dashboard

Kala is a simplistic, modern, and performant job scheduler written in Go. Features:

  • Single binary
  • No dependencies
  • JSON over HTTP API
  • Job Stats
  • Configurable Retries
  • Scheduling with ISO 8601 Date and Interval notation
  • Dependent Jobs
  • Persistent with several database drivers
  • Web UI

Note that it is not battle-tested. Use at your own risk.

Kala was inspired by the desire for a simpler Chronos (developed by Airbnb). Kala is Chronos for the rest of us.

If you need fault tolerance, distributed features, massive scale, then I recommend checking out Chronos. This is designed to be the Chronos for start-ups.

Installing Kala

Kala uses Go Modules

  1. Get Kala

    go get github.com/ajvb/kala

  2. Run Kala

    kala serve

Getting Started

Once you have installed Kala onto the machine you would like to use, you can follow the below steps to start using it.

To run Kala as a server:

$ kala serve
INFO[0000] Preparing cache
INFO[0000] Starting server on port :8000

$ kala serve -p 2222
INFO[0000] Preparing cache
INFO[0000] Starting server on port :2222

Kala uses BoltDB by default for the job database by using jobdb and boltpath params:

kala serve --jobdb=boltdb --boltpath=/path/to/dir

use Redis by using the jobdb, jobdb-address and jobdb-password params:

kala serve --jobdb=redis --jobdb-address=127.0.0.1:6379 --jobdb-password=password

use Consul by using the jobdb and jobdb-address params:

kala serve --jobdb=consul --jobdb-address=127.0.0.1:8500

use Mongo by using the jobdb, jobdb-address, jobdb-username, and jobdb-password params:

kala serve --jobdb=mongo --jobdb-address=server1.example.com,server2.example.com --jobdb-username=admin --jobdb-password=password

use Postgres by using the jobdb, jobdb-address params:

kala serve --jobdb=postgres --jobdb-address=server1.example.com/kala --jobdb-username=admin --jobdb-password=password

use MariaDB, MySQL by using the jobdb, jobdb-address, jobdb-tls-capath, jobdb-tls-certpath, jobdb-tls-keypath, jobdb-tls-servername params:

kala serve --jobdb=mariadb --jobdb-address=(server1.example.com)/kala --jobdb-username=admin --jobdb-password=password

kala serve --jobdb=mysql --jobdb-address="tcp(server1.example.com:3306)/kala?tls=custom" --jobdb-username=admin --jobdb-password=password --jobdb-tls-capath=/path/to/server-ca.pem --jobdb-tls-certpath=/path/to/client-cert.pem --jobdb-tls-keypath=/path/to/client-key.pem --jobdb-tls-servername=server1.example.com

Kala runs on 127.0.0.1:8000 by default. You can easily test it out by curling the metrics path.

$ curl http://127.0.0.1:8000/api/v1/stats/
{"Stats":{"ActiveJobs":2,"DisabledJobs":0,"Jobs":2,"ErrorCount":0,"SuccessCount":0,"NextRunAt":"2015-06-04T19:25:16.82873873-07:00","LastAttemptedRun":"0001-01-01T00:00:00Z","CreatedAt":"2015-06-03T19:58:21.433668791-07:00"}}

Once it's up in running, you can utilize curl or the official go client to interact with Kala. Also check out the examples directory.

Examples of Usage

There are more examples in the examples directory within this repo. Currently its pretty messy. Feel free to submit a new example if you have one.

Deployment

Supervisord

After installing supervisord, open its config file (/etc/supervisor/supervisord.conf is the default usually) and add something like:

[program:kala]
command=kala serve
autorestart=true
stdout_logfile=/var/log/kala.stdout.log
stderr_logfile=/var/log/kala.stderr.log

Docker

If you have docker installed, you can build the dockerfile in this directory with

docker build -t kala . and run it as a daemon with: docker run -it -d -p 8000:8000 kala

API v1 Docs

All routes have a prefix of /api/v1

Client Libraries

Official:

Contrib:

  • Node.js

    npm install kala-node

  • Python

    pip install git+https://github.com/dmajere/kala-python.git

Job Data Struct

Docs can be found here

Things to Note

  • If schedule is omitted, the job will run immediately.

Job JSON Example


{
        "name":"test_job",
        "id":"93b65499-b211-49ce-57e0-19e735cc5abd",
        "command":"bash /home/ajvb/gocode/src/github.com/ajvb/kala/examples/example-kala-commands/example-command.sh",
        "owner":"",
        "disabled":false,
        "dependent_jobs":null,
        "parent_jobs":null,
        "schedule":"R2/2015-06-04T19:25:16.828696-07:00/PT10S",
        "retries":0,
        "epsilon":"PT5S",
        "success_count":0,
        "last_success":"0001-01-01T00:00:00Z",
        "error_count":0,
        "last_error":"0001-01-01T00:00:00Z",
        "last_attempted_run":"0001-01-01T00:00:00Z",
        "next_run_at":"2015-06-04T19:25:16.828794572-07:00"
}

Breakdown of schedule string. (ISO 8601 Notation)

Example schedule string:


R2/2017-06-04T19:25:16.828696-07:00/PT10S

This string can be split into three parts:


Number of times to repeat/Start Datetime/Interval Between Runs
Number of times to repeat

This is designated with a number, prefixed with an R. Leave out the number if it should repeat forever.

Examples:

  • R - Will repeat forever
  • R1 - Will repeat once
  • R231 - Will repeat 231 times.
Start Datetime

This is the datetime for the first time the job should run.

Kala will return an error if the start datetime has already passed.

Examples:

  • 2017-06-04T19:25:16
  • 2017-06-04T19:25:16.828696
  • 2017-06-04T19:25:16.828696-07:00
  • 2017-06-04T19:25:16-07:00

To Note: It is recommended to include a timezone within your schedule parameter.

Interval Between Runs

This is defined by the ISO8601 Interval Notation.

It starts with a P, then you can specify years, months, or days, then a T, preceded by hours, minutes, and seconds.

Lets break down a long interval: P1Y2M10DT2H30M15S

  • P - Starts the notation
  • 1Y - One year
  • 2M - Two months
  • 10D - Ten days
  • T - Starts the time second
  • 2H - Two hours
  • 30M - Thirty minutes
  • 15S - Fifteen seconds

Now, there is one alternative. You can optionally use just weeks. When you use the week operator, you only get that. An example of using the week operator for an interval of every two weeks is P2W.

Examples:

  • P1DT1M - Interval of one day and one minute
  • P1W - Interval of one week
  • PT1H - Interval of one hour.

More Information on ISO8601

Overview of routes

Task Method Route
Creating a Job POST /api/v1/job/
Getting a list of all Jobs GET /api/v1/job/
Getting a Job GET /api/v1/job/{id}/
Deleting a Job DELETE /api/v1/job/{id}/
Deleting all Jobs DELETE /api/v1/job/all/
Getting metrics about a certain Job GET /api/v1/job/stats/{id}/
Starting a Job manually POST /api/v1/job/start/{id}/
Disabling a Job POST /api/v1/job/disable/{id}/
Enabling a Job POST /api/v1/job/enable/{id}/
Getting app-level metrics GET /api/v1/stats/

/job

This route accepts both a GET and a POST. Performing a GET request will return a list of all currently running jobs. Performing a POST (with the correct JSON) will create a new Job.

Note: When creating a Job, the only fields that are required are the Name and the Command field. But, if you omit the Schedule field, the job will be ran immediately.

Example:

$ curl http://127.0.0.1:8000/api/v1/job/
{"jobs":{}}
$ curl http://127.0.0.1:8000/api/v1/job/ -d '{"epsilon": "PT5S", "command": "bash /home/ajvb/gocode/src/github.com/ajvb/kala/examples/example-kala-commands/example-command.sh", "name": "test_job", "schedule": "R2/2017-06-04T19:25:16.828696-07:00/PT10S"}'
{"id":"93b65499-b211-49ce-57e0-19e735cc5abd"}
$ curl http://127.0.0.1:8000/api/v1/job/
{
    "jobs":{
        "93b65499-b211-49ce-57e0-19e735cc5abd":{
            "name":

readme truncated — read the full docs on github

Frequently asked questions

Is kala free to use?

kala is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does kala do?

Modern Job Scheduler

What is kala written in?

kala is primarily written in Go. Its source is publicly available at https://github.com/ajvb/kala, and it has 2,156 GitHub stars.