Starlark Types

This page lists out the Kurtosis types that are available in Starlark.

Type definitions

ConnectionConfig

The ConnectionConfig is used to configure a connection between two subnetworks (see set_connection).

connection_config = ConnectionConfig(
    # Percentage of packet lost each way between subnetworks 
    # OPTIONAL
    # DEFAULT: 0.0
    packet_loss_percentage = 50.0,

    # Amount of delay added to packets each way between subnetworks
    # OPTIONAL: Valid value are UniformPacketDelayDistribution or NormalPacketDelayDistribution
    packet_delay_distribution = UniformPacketDelayDistribution(
        # Delay in ms
        ms = 500 
    ) 
)

tip

See kurtosis.connection for pre-built ConnectionConfig objects

ExecRecipe

The ExecRecipe can be used to run the command on the service (see exec or wait)

exec_recipe = ExecRecipe(
    # The service name to execute the command on.
    # MANDATORY
    service_name = "my_service",

    # The actual command to execute. 
    # Each item corresponds to one shell argument, so ["echo", "Hello world"] behaves as if you ran "echo 'Hello World'" in the shell.
    # MANDATORY
    command = ["echo", "Hello, World"],
)

HttpRequestRecipe

The HttpRequestRecipe is used to make HTTP requests to an endpoint. Currently, we support GET and POST requests. (see request or wait).

GetHttpRequestRecipe

The GetHttpRequestRecipe can be used to make GET requests.

get_request_recipe = GetHttpRequestRecipe(
    # The service name that is the server for the request
    # MANDATORY
    service_name = "my_service",

    # The port ID that is the server port for the request
    # MANDATORY
    port_id = "my_port",

    # The endpoint for the request
    # MANDATORY
    endpoint = "/endpoint?input=data",

    # The extract dictionary takes in key-value pairs where:
    # Key is a way you refer to the extraction later on
    # Value is a 'jq' string that contains logic to extract from response body
    # To lean more about jq, please visit https://devdocs.io/jq/
    # OPTIONAL
    extract = {
        "extractfield" : ".name.id"
    }
)

PostHttpRequestRecipe

The PostHttpRequestRecipe can be used to make POST requests.

post_request_recipe = PostHttpRequestRecipe(
    # The service name that is the server for the request
    # MANDATORY
    service_name = "my_service",

    # The port ID that is the server port for the request
    # MANDATORY
    port_id = "my_port",

    # The endpoint for the request
    # MANDATORY
    endpoint = "/endpoint",

    # The content type header of the request (e.g. application/json, text/plain, etc)
    # MANDATORY
    content_type = "application/json",

    # The body of the request
    # MANDATORY
    body = "{\"data\": \"this is sample body for POST\"}",
    
    # The extract dictionary takes in key-value pairs where:
    # Key is a way you refer to the extraction later on
    # Value is a 'jq' string that contains logic to extract from response body
    # # To lean more about jq, please visit https://devdocs.io/jq/
    # OPTIONAL
    extract = {
        "extractfield" : ".name.id"
    }

caution

Make sure that the endpoint returns valid JSON response for both POST and GET requests.

PacketDelayDistribution

The PacketDelayDistribution can be used in conjuction with ConnectionConfig to introduce latency between two subnetworks. See set_connection instruction to learn more about its usage.

UniformPacketDelayDistribution

The UniformPacketDelayDistribution creates a packet delay distribution with constant delay in ms

delay  = UniformPacketDelayDistribution(
    # Non-Negative Integer
    # Amount of constant delay added to outgoing packets from the subnetwork
    # MANDATORY
    ms = 1000
)

NormalPacketDelayDistribution

The NormalPacketDelayDistribution can be used to create packet delays that are distributed according to a normal distribution.

delay  = NormalPacketDelayDistribution(
    # Non-Negative Integer
    # Amount of mean delay added to outgoing packets from the subnetwork
    # MANDATORY
    mean_ms = 1000

    # Non-Negative Integer
    # Amount of variance (jitter) added to outgoing packets from the subnetwork
    # MANDATORY
    std_dev_ms = 10
    
    # Non-Negative Float
    # Percentage of correlation observed among packets. It means that the delay observed in next packet
    # will exhibit a corrlation factor of 10.0% with the previous packet. 
    # OPTIONAL
    # DEFAULT = 0.0
    correlation = 10.0
)   

PortSpec

This PortSpec constructor creates a PortSpec object that encapsulates information pertaining to a port.

port_spec = PortSpec(
    # The port number which we want to expose
    # MANDATORY
    number = 3000,
    
    # Transport protocol for the port (can be either "TCP" or "UDP")
    # Optional (DEFAULT:"TCP")
    transport_protocol = "TCP",

    # Application protocol for the port
    # Optional
    application_protocol = "http"
)

The above constructor returns a PortSpec object that contains port information in the form of a future reference and can be used with add_service to create services.

ServiceConfig

The ServiceConfig is used to configure a service when it is added to an enclave (see add_service).

config = ServiceConfig(
    # The name of the container image that Kurtosis should use when creating the service’s container.
    # MANDATORY
    image = "kurtosistech/example-datastore-server",

    # The ports that the container should listen on, identified by a user-friendly ID that can be used to select the port again in the future.
    # If no ports are provided, no ports will be exposed on the host machine, unless there is an EXPOSE in the Dockerfile
    # OPTIONAL (Default: {})
    ports = {
        "grpc": PortSpec(
            # The port number which we want to expose
            # MANDATORY
            number = 3000,

            # Transport protocol for the port (can be either "TCP" or "UDP")
            # Optional (DEFAULT:"TCP")
            transport_protocol = "TCP",

            # Application protocol for the port
            # Optional
            application_protocol = "http"
        ),
    },

    # A mapping of path_on_container_where_contents_will_be_mounted -> files_artifact_id_to_mount
    # For more info on what a files artifact is, see below
    # OPTIONAL (Default: {})
    files = {
        "path/to/file/1": "files_artifact_1",
        "path/to/file/2": "files_artifact_2",
    },

    # The ENTRYPOINT statement hardcoded in a container image's Dockerfile might not be suitable for your needs.
    # This field allows you to override the ENTRYPOINT when the container starts.
    # OPTIONAL (Default: [])
    entrypoint = [
        "bash",
    ],

    # The CMD statement hardcoded in a container image's Dockerfile might not be suitable for your needs.
    # This field allows you to override the CMD when the container starts.
    # OPTIONAL (Default: [])
    cmd = [
        "-c",
        "sleep 99",
    ],

    # Defines environment variables that should be set inside the Docker container running the service. 
    # This can be necessary for starting containers from Docker images you don’t control, as they’ll often be parameterized with environment variables.
    # OPTIONAL (Default: {})
    env_vars = {
        "VAR_1": "VALUE_1",
        "VAR_2": "VALUE_2",
    },

    # ENTRYPOINT, CMD, and ENV variables sometimes need to refer to the container's own IP address. 
    # If this placeholder string is referenced inside the 'entrypoint', 'cmd', or 'env_vars' properties, the Kurtosis engine will replace it at launch time
    # with the container's actual IP address.
    # OPTIONAL (Default: "KURTOSIS_IP_ADDR_PLACEHOLDER")
    private_ip_address_placeholder = "KURTOSIS_IP_ADDRESS_PLACEHOLDER",

    # The maximum amount of CPUs the service can use, in millicpu/millicore.
    # OPTIONAL (Default: no limit)
    cpu_allocation = 1000,

    # The maximum amount of memory, in megabytes, the service can use.
    # OPTIONAL (Default: no limit)
    memory_allocation = 1024,

    # Defines the subnetwork in which the service will be started.
    # OPTIONAL (Default: "default")
    subnetwork = "service_subnetwork",
)

The ports dictionary argument accepts a key value pair, where key is a user defined unique port identifier and value is a PortSpec object.

For more info about the subnetwork argument, see Kurtosis subnetworks.

UpdateServiceConfig

The UpdateServiceConfig contains the attributes of ServiceConfig that are live-updatable. For now, only the subnetworksubnetworks-reference attribute of a service can be updated once the service is started.

update_service_config = UpdateServiceConfig(
    # The subnetwork to which the service will be moved.
    # "default" can be used to move the service to the default subnetwork
    # MANDATORY
    subnetwork = "subnetwork_1"
)

The global kurtosis object

Kurtosis provides "pre-built" values for types that will be broadly used. Those values are provided through the kurtosis object. It is available globally and doesn't need to be imported.

connection

ALLOWED

kurtosis.connection.ALLOWED is equivalent to ConnectionConfig with packet_loss_percentage set to 0 and packet_delay set to PacketDelay(delay_ms=0). It represents a ConnectionConfig that allows all connection between two subnetworks with no delay and packet loss.

BLOCKED

kurtosis.connection.BLOCKED is equivalent to ConnectionConfig with packet_loss_percentage set to 100 and packet_delay set to PacketDelay(delay_ms=0). It represents a ConnectionConfig that blocks all connection between two subnetworks.