Locators

info

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

A locator is how resources are identified when being imported in a Starlark script - namely by import_module and read_file. There are two types of locators: absolute and relative.

Absolute Locators

Absolute locators unambiguously identify a resource using a URL-like syntax. For example, this locator:

github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml/some-file.star

references a file inside a GitHub repo called package-repo, owned by package-author, that lives at the path /path/to/directory-with-kurtosis.yml/some-file.star relative to the root of the repo.

caution

A GitHub URL is not a valid locator, because GitHub adds extra /blob/main paths to the URL that don't reflect the file's path in the repo. For example, a GitHub URL of:

https://github.com/kurtosis-tech/kurtosis/blob/main/starlark/test.star

would be the following as a Kurtosis locator (dropping the https:// and /blob/main part):

github.com/kurtosis-tech/kurtosis/starlark/test.star

info

Only locators pointing to public GitHub repositories are currently allowed.

Package Restriction

Any Starlark script that wishes to use external resources must be a part of a Kurtosis package.

For example, suppose we had a Kurtosis package like so:

/
    package-repo/
        my-package/
            kurtosis.yml
            main.star
            helpers/
                random-script.star
        not-a-package/
            random-script.star

with a kurtosis.yml file like so:

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

The main.star file would import the random-script.star from the helpers subdirectory of my-package like so:

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

The import statement below will not succeed, because main.star cannot import from non-packages. (see how import works for more information)

helpers = import_module("github.com/package-author/package-repo/not-a-package/random-script.star")

Relative Locators

Relative locators like ./helper.star are allowed as a short alternative to the full absolute locator. However, a relative locator cannot be used to reference files outside the package. In other words, you cannot use a relative locator to reference files above the directory containing the kurtosis.yml file.

Suppose we had a Kurtosis package like so:

/
    package-repo/
        main.star
        src/
            lib.star

with a kurtosis.yml file like so:

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

The main.star can refer to the lib.star file using either relative or absolute imports:

# valid relative import
lib_via_relative_import = import_module("./src/lib.star")

# valid absolute import
lib_via_absolute_import = import_module("github.com/kurtosis-tech/package-repo/src/lib.star")