Build a Tool

There are 2 ways to create a tool for Kubiya Teammates: YAML or Python via Kubiya SDK.

For tools, Kubiya expects the following schema / parameters:

• Name – A unique and descriptive name for the tool that easily identifies its purpose or functionality within the Kubiya platform.

• Description – An explanation of the tool's purpose and functionality. This description should provide enough context for users and Kubiya Teammates to understand when and why to use the tool.

• Icon_url – The URL of an image that visually represents the tool. This icon is displayed in the Kubiya web app and should be relevant to the tool's purpose for easier identification by users.

• Type – Specifies the execution environment or interface for the tool, such as Docker-based, Bash, Shell, or other environments. This determines how the tool will be run or interacted with.

• Image – The name of the Docker image (or repository name) along with an optional tag (e.g., nginx:latest or python:3.11) from Dockerhub that will be used to run the tool.

• Content – The main script, code, or command that will be executed within the container or environment. This is the core logic of the tool, such as a Python script, a shell command, or any other task the tool is designed to perform.

• Args – Arguments or parameters passed to the tool at runtime. These are values or options that modify how the tool behaves, allowing for dynamic input to be provided when the tool is executed.

• With_files – files or directories from your environment that are mounted into the container's filesystem for use during its execution.

Build with YAML

Build with Python via Kubiya SDK

Create Python project called hello_world (the repo can be public or private GitHub repo, but private repos will require additional steps later on)

In the project, create a Python Module hello_world.py with the following:

from kubiya_sdk.tools import Tool
from kubiya_sdk.tools.registry import tool_registry

hello_world_tool = Tool(
    name="hello_world",
    description="prints \"hello world\"",
    type="docker",
    image="python:3.11-slim",
    content="print(\"Hello, world!\")",
    )

tool_registry.register("hell_world", hello_world_tool)

Make sure your project also has:

• __init__.py

• requirements.txt containing kubiya-sdk

• setup.py containing:

from setuptools import setup, find_packages

setup(
    name="kubiya-hello_world-tools",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[
        "kubiya-sdk",
    ],
)

Prerequisites

• Python 3.11 or later

• GitHub Repo (public is easier, but if you need private here's how you can [link])

Building with Python

1. Create repo (Python repo already includes gitignores etc)

2. Create & activate virtual environment

3. Install Kubiya SDK

4. Run kubiya init

5. Review examples (hello_tool & function tool, two different approaches)

6. Tool in Kubiya Schema, bash

7. Tool in Kubiya Schema, bash running python module

8. Tool as a Python Function

9. Onto testing...

Create repo (tip: create python repo)

r

Create & activate virtual environment

python -m venv .venv or python3 -m venv .venv

source .venv/bin/activate

Install Kubiya SDK

pip install kubiya-sdk

Run `kubiya init`

kubiya init

Includes basic files needed for your Python project to run, as well as two examples of tools. The two example tools included take different approaches.

1. hello_world_tool – This tool writes out the full Kubiya schema. In its content section, it contains bash. In this case the bash is running a python module located in the same directory, but you could also just write out an entire bash script if you prefer to.

2. function_tool – This tool is written as a Python function. The fuller schema and bash is abstracted away, and the Kubiya SDK converts it afterward into the schema.

Choosing which approach to use

Approach	Example	Flexibility	Languages
Write out full schema (content runs python module)	hello_world_tool	More flexibility	Python + Minimal Bash
Write out full schema (content runs bash script)	similar to hello_world_tool except for content	More flexibility	Python + Bash
Tool as a Python Function	function_tool	Less flexibility	Python

Review examples

hello_world_tool

• main.py – Python module containing the fucntional logic we want.

• tool_def.py – Creates a tool in Kubiya's schema that executes the Python module

Let's go through the various elements of the schema:

• Name = Name of the tool. In this case "say_hello". This is the name that'll appear in Kubiya UI and in Slack to your organizational users who have access to it.

• Type = Docker

• Image = Docker image for the container that'll run this tool

• Description = A description of the tool for your organizational users and for your Kubiya Teammates to understand what this tool does

• Args = Any arguments that can be used as inputs. An argument can be mandatory or optional.

• Content = The heart of your tool. The content is bash that will actually be run. In this example, the bash creates and activates a virtual environment, installs requirements, then runs a Python module. As mentioned previously, if you prefer bash you can write the entire functional logic in the content section in bash.

• With files = The files we want to mount into the container, including each file's source and destination. In this case, the two files

At the end of the file, the tool is registered to the tool registry.

function_tool