RiotKit-Do (RKD) usage and development manual ¶

RKD is a stable, open-source, multi-purpose automation tool which balance flexibility with simplicity. The primary language is Python and YAML syntax.

RiotKit-Do can be compared to Gradle and to GNU Make , by allowing both Python and Makefile-like YAML syntax.

What can be achieved with RKD?

Simplify the scripts
Put your Python and Bash scripts inside a YAML file (like in GNU Makefile)
Do not reinvent the wheel (argument parsing, logs, error handling for example)
Share the code across projects and organizations, use native Python Packaging to share tasks (like in Gradle)
Natively integrate scripts with .env files
Automatically generate documentation for your scripts
Maintain your scripts in a good standard

RKD can be used on PRODUCTION, for development, for testing, to replace some of Bash scripts inside docker containers, and for many more, where Makefile was used.

           version: org.riotkit.rkd/yaml/v1
tasks:
    :hello1:
        extends: rkd.core.standardlib.syntax.PythonSyntaxTask
        arguments:
            "--name":
                required: True
                help: "Allows to specify a name"
        description: Prints your name
        execute: |
            self.io().info_msg(f'Hello {ctx.get_arg("--name")}, I\'m talking from YAML, and you?')
            return True

          

           from argparse import ArgumentParser
from rkd.core.api.contract import ExecutionContext
from rkd.core.api.decorators import extends
from rkd.core.api.syntax import ExtendedTaskDeclaration
from rkd.core.standardlib.syntax import PythonSyntaxTask


@extends(PythonSyntaxTask)
def hello_task():
    """
    Prints your name
    """

    def configure_argparse(task: PythonSyntaxTask, parser: ArgumentParser):
        parser.add_argument('--name', required=True, help='Allows to specify a name')

    def execute(task: PythonSyntaxTask, ctx: ExecutionContext):
        task.io().info_msg(f'Hello {ctx.get_arg("--name")}, I\'m talking in Python, and you?')
        return True

    return [configure_argparse, execute]


IMPORTS = [
    ExtendedTaskDeclaration(hello_task, name=':hello2')
]

          

           from argparse import ArgumentParser
from rkd.core.api.contract import TaskInterface, ExecutionContext
from rkd.core.api.syntax import TaskDeclaration


class HelloFromPythonTask(TaskInterface):
    """
    Prints your name
    """

    def get_name(self) -> str:
        return ':hello3'

    def get_group_name(self) -> str:
        return ''

    def configure_argparse(self, parser: ArgumentParser):
        parser.add_argument('--name', required=True, help='Allows to specify a name')

    def execute(self, ctx: ExecutionContext) -> bool:
        self.io().info_msg(f'Hello {ctx.get_arg("--name")}, I\'m talking classic Python syntax, and you?')
        return True


IMPORTS = [
    TaskDeclaration(HelloFromPythonTask()),
]

          

Example use cases ¶

Docker based production environment with multiple configuration files, procedures (see: Harbor project )
Database administrator workspace (importing dumps, creating new user accounts, plugging/unplugging databases)
Development environment (executing migrations, importing test database, splitting tests and running parallel)
On CI (prepare project to run on eg. Jenkins or Gitlab CI) - RKD is reproducible on local computer which makes inspection easier
Application cluster management, deploying applications, adding users, setting permissons
Automate things like certificate regeneration on production server, RKD can generate any application configs using JINJA2
Installers (RKD has built-in commands for replacing lines in files, modifying .env files, asking user questions and validating answers)

Install RKD ¶

RiotKit-Do is delivered as a Python package that can be installed system-wide or in a virtual environment. The virtual environment installation is similar in concept to the Gradle wrapper (gradlew)

         # download a wrapper that will automatically setup virtual environment and install RKD
# do not forget to commit wrapper to the GIT repository
wget https://github.com/riotkit-org/riotkit-do/blob/master/src/core/rkd/core/misc/initial-structure/rkdw.py -O rkdw
chmod +x rkdw
./rkdw

        

Getting started in freshly created structure ¶

The “Quick start” section ends up with a .rkd directory, a requirements.txt and ./rkdw

Call RKD using a wrapper in project directory ./rkdw
Each time you install anything from pip in your project - add it to requirements.txt (or use pipenv install ), additional RKD tasks can be installed from PIP
In .rkd/makefile.yaml add your tasks, pipelines and imports

Create your first task with Getting started ¶

Check how to use commandline to run tasks in RKD with Commandline usage ¶

See how to import existing tasks to your Makefile with Importing tasks page ¶

Keep learning ¶

YAML syntax is described also in Tasks development - more examples section
Writing Python code in makefile.yaml requires to lookup Tasks API
Learn how to import installed tasks via pip - Importing tasks
You can also write tasks code in pure Python and redistribute those tasks via Python’s PIP - see Tasks development - more examples
With RKD you can create interactive installers - check the Creating installer wizards with RKD section

Contents: