If you add a docstring in a specific format to the
run function inside your package's
main.star file, you will be able to run your package in Kurtosis Cloud using a user-friendly form interface.
For example, this is the form produced by Kurtosis for running the Postgres package:
which Kurtosis autogenerates based on the docstring comment on the package's
"""Launches a Postgresql database instance, optionally seeding it with a SQL file script
image (string): The container image that the Postgres service will be started with
service_name (string): The name to give the Postgres service
user (string): The user to create the Postgres database with
password (string): The password to give to the created user
database (string): The name of the database to create
config_file_artifact_name (string): The name of a files artifact that contains a Postgres config file in it
If not empty, this will be used to configure the Postgres server
seed_file_artifact_name (string): The name of a files artifact containing seed data
If not empty, the Postgres server will be populated with the data upon start
extra_configs (list[string]): Each argument gets passed as a '-c' argument to the Postgres server
persistent (bool): Whether the data should be persisted. Defaults to True; Note that this isn't supported on multi node k8s cluster as of 2023-10-16
launch_adminer (bool): Whether to launch adminer which launches a website to inspect postgres database entries. Defaults to False.
An object containing useful information about the Postgres database running inside the enclave:
The syntax for this docstring is the Google function docstring syntax, with optional PEP-484 type annotations in parentheses:
def run(plan, required_arg, optional_arg=True, untyped_arg=None):
This is the `run` function description. It can even spill
over into multiple lines.
required_arg (string): This is the first argument description. It is required, and is of string type.
Note that argument descriptions can spill into the second line, so long as they're indented.
optional_arg (bool): This is the second argument description. It is optional, and it is a boolean-type argument.
untyped_arg: This argument doesn't have a PEP-484 type annotation.
Several things to note about this docstring syntax:
- Every function MUST have a description before the
Argsblock (until this issue is resolved)
- The description after the
:(including continuation lines) is rendered in the form using Markdown. For example, entering the following:would render a link in the description of the argument in the generated form.
some_arg (string): Some description about this argument.
See [this link](https://some-location.com) for more information.
- The names of the arguments in the docstring must exactly correspond to the names of the function arguments
planargument does not need to be documented; it corresponds to the
Planobject and Kurtosis will inject it automatically
- If an argument has no default value, it will be marked as required in the Kurtosis-generated form
- If an argument has a default value, it will be marked as optional in the Kurtosis-generated form
- The type of an argument (specified within
()) is optional
The values available for use within the
() to document the type of a function argument are as follows:
Xis a primitive type
Xis a primitive type
If a type argument is not specified, Kurtosis will instead generate a JSON field for inputting arbitrary values into the field. The JSON value that the user enters will be transliterated to a Starlark
For example, if the user enters the following JSON in the form field of an argument without a type specified:
"inner_key": "Inner key value"
then the equivalent Starlark that will be passed in for the function parameter will be:
"inner_key": "Inner key value",