Getting Started with Kuranto #

The objective of this guide is to end up with a running instance of Kuranto, able to receive and execute Forgejo Actions jobs in a Kubernetes cluster.

Prerequisites #

This guide will assume you already have:

• A running Forgejo instance
• A running Kubernetes cluster
• The Helm CLI installed

Installing Kuranto #

Register a runner in Forgejo #

The first thing we'll need to do is register a runner in our Forgejo instance. You can do this however you like: at the instance level for a global runner, in an organization, or in a specific repository. You can follow the official Forgejo Docs to get a step-by-step guide on how to do this.

After registering a new runner, you will be given a configuration snippet by Forgejo, that looks like this:

server:
  connections:
    primary:
      url: http://your.forgejo.url.com
      uuid: A_RANDOM_UUID
      token: A_RANDOM_TOKEN

Copy this snippet and put it in a file named server.yml on your computer. Here, we'll put it in /tmp/server.yml.

Create a namespace in Kubernetes #

Kuranto works by spawning pods in your Kubernetes cluster for each job it receives. It can do this in the same namespace where Kuranto is deployed, or in a separate dedicated namespace, if you prefer.

For the purposes of this guide, we'll have Kuranto start pods in the same namespace it is deployed in.

Let's create that namespace:

kubectl create namespace kuranto

We'll use this namespace throughout the rest of this guide.

Create the runner secret #

With our namespace created, we can start populating it. The first thing we'll need is to put the server.yml file we created earlier in a Kubernenetes Secret, so that our Helm chart can reference it, and use it to build the final Forgejo Runner config:

kubectl -n kuranto create secret generic runner-server-config --from-file=server.yml=/tmp/server.yml

The Kuranto deployment managed by Helm uses an init container to merge the non-secret config we provide to it as values, with this secret part, and create a new config file that contains everything the Forgejo Runner needs to both work with our Forgejo instance, as well as send jobs to Kuranto.

Deploy Kuranto #

For this deployment, we'll be using the official Helm chart provided for Kuranto, with a very minimal configuration.

Create a values.yaml file somewhere with the following contents:

kuranto:
  image:
    repository: blurrycat/kuranto
    tag: "0.3.0"
    pullPolicy: IfNotPresent

runner:
  image:
    repository: code.forgejo.org/forgejo/runner
    tag: "13.2.0"
    pullPolicy: IfNotPresent
  server:
    existingSecret: runner-server-config
  labels:
    - name: kubernetes
      image: data.forgejo.org/oci/node:lts
  config:
    log:
      level: info
      job_level: info
    runner:
      capacity: 2

This will deploy a Forgejo Runner with the label kubernetes configured, capable of running two jobs at a time. Alongside it, the chart will also deploy Kuranto.

For labels, choose the name you want, and the image you need jobs to run on by default when using this label. These are the same labels used in the runner configuration file usually, but in a managed form, since we control the scheme part of the label in the chart directly. The example label above will get formatted to kubernetes:kubernetes://data.forgejo.org/oci/node:lts in the final runner configuration file.

Let's say we saved this file as /tmp/values.yml, we can now use it to deploy Kuranto:

helm install kuranto oci://registry-1.docker.io/blurrycat/kuranto-chart \
    --namespace kuranto

We should now have a deployment for the Forgejo Runner and Kuranto. We can check this is the case by running kubectl -n kuranto get pods, which will be showing a single running pod, with two running containers (and a defunct init container):

• Forgejo Runner
• Kuranto

Running jobs #

Now that we have a fully working runner, we can run jobs on it! If you already have workflows, you can simply set their runs-on to kubernetes.

If you do not have existing workflows, we can create a simple dummy one to make sure everything is working as expected:

• Create a new repository in your Forgejo instance
• Add a .forgejo/workflows/test.yml file in this repository, with the following contents:

  name: Basic
  on:
    workflow_dispatch:
  jobs:
    test:
      runs-on: kubernetes
      steps:
        - name: It works
          run: echo "it works"
  

• Commit this file, and push it to the repository we just created
• Go into the Actions tab, click on the test.yml workflow, and start a new run on the UI.

This should trigger a new run, that will get picked up by the runner and sent to Kuranto. After a few seconds (depending on how long the pull takes for the job image), you should have a successful workflow.

And, voilà! We have a fully functioning runner, executing jobs as pods in a Kubernetes cluster!

Going further #

This guide only shows a very basic deployment of Kuranto. You can refer to the Helm chart values to see everything you can configure on Kuranto.

To control placement of all generated job Pods, including service sidecars, use jobs.nodeSelector, jobs.affinity, and jobs.tolerations. See the chart's scheduling examples for simple selectors, required or preferred node affinity, and tolerations. Kuranto reads these settings at startup, so changing them requires a restart.

The Forgejo Runner itself can be configured through these same values. For details on its configuration, you can refer to the sample configuration in its official repository.

Please note that some values in the runner configuration are managed by the chart itself, and cannot be set through the runner.config value. There are:

• server, this comes from the secret we made at the start of this guide
• runner.labels, this comes from another value in the Helm chart
• plugins.kubernetes, this is managed by the chart directly