Packages

info

Packages are a part of the Kurtosis package system. To read about the package system in detail, see here.

A Kurtosis package is a:

• A directory
• Plus all its contents
• That contains a kurtosis.yml file with the package's name, which will be the locator root for the package

Kurtosis packages are the system by which Starlark scripts can include external resources.

Note that, when developing locally, the GitHub repo referred to in the package name does not need to exist.

Kurtosis packages are shared simply by pushing to GitHub (e.g. these are the packages we administer).

For example, suppose there is a repo called package-repo by the author package-author whose internal directory structure looks like so:

/
    package-repo
        my-package
            kurtosis.yml
            main.star
            helpers
                helpers.star

whose kurtosis.yml file looked like so:

name: github.com/package-author/package-repo/my-package

The package would be called github.com/package-author/package-repo/my-package. It should get pushed to the package-repo repo owned by the package-author user on GitHub.

Packages are referenced indirectly, as the locators used to specify external resources in a Starlark script will contain the package name where the resource lives.

For example:

helpers = import_module("github.com/package-author/package-repo/my-package/helpers/helpers.star")

would be used to import the helpers.star file into a Starlark script.

The Kurtosis engine will automatically download dependency packages from GitHub when running a Starlark script.

Runnable Packages

A Kurtosis package that has a main.star file next to its kurtosis.yml file is called a "runnable package". The main.star file of a runnable package must have a run(plan) method like so:

def run(plan):
    print("Hello, world.")

info

More on the plan parameter here.

Runnable packages can be executed from the CLI in one of three ways:

# OPTION 1: Point to a directory with a `kurtosis.yml` and `main.star` on local filesystem
kurtosis run /path/to/runnable/package/root

# OPTION 2: Point to a `kurtosis.yml` on the local filesystem with a `main.star` next to it on local fileesystem
kurtosis run /path/to/runnable/package/root/kurtosis.yml

# OPTION 3: Pass in a remote package name to run from GitHub
kurtosis run github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml

tip

If you want to run a non-main branch, tag or commit use the following syntax kurtosis run github.com/package-author/package-repo@tag-branch-commit

All these will call the run(plan) function of the package's main.star.

Arguments

To accept parameters to the run(plan) function, the function should accept an args parameter:

def run(plan, args):
    print("Hello, " + args["name"])

To pass parameters to the run(plan, args) function, a JSON object should be passed as the second positional argument after the script or package path:

kurtosis run github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml '{"name": "Joseph"}'