Engine & APIC Reference

Interactions with Kurtosis happen via API. To facilitate interaction with Kurtosis, we provide client libraries for interacting with the Kurtosis API. These can be used to, for example, write Kurtosis-based tests using your test framework of choice.

This page documents the objects and functions in the client libraries.

tip

The sidebar on the right can be used to quickly navigate classes.

KurtosisContext

A connection to a Kurtosis engine, used for manipulating enclaves.

createEnclave(String enclaveName) -> [EnclaveContext][enclavecontext] enclaveContext

Creates a new Kurtosis enclave using the given parameters. The enclave will be created in default mode (when services fail, it won't restart)

Args

• enclaveName: The name to give the new enclave.

Returns

• enclaveContext: An EnclaveContext object representing the new enclave.

createProductionEnclave(String enclaveName) -> [EnclaveContext][enclavecontext] enclaveContext

Same as above, but creates an enclave in production mode (services will restart upon failure)

getEnclaveContext(String enclaveIdentifier) -> [EnclaveContext][enclavecontext] enclaveContext

Gets the EnclaveContext object for the given enclave ID.

Args

• enclaveIdentifier: The identifier of the enclave.

Returns

• enclaveContext: The EnclaveContext representation of the enclave.

getEnclaves() -> Enclaves enclaves

Gets the enclaves that the Kurtosis engine knows about.

Returns

• enclaves: The Enclaves representation of all enclaves that Kurtosis the engine knows about.

getEnclave(String enclaveIdentifier) -> EnclaveInfo enclaveInfo

Gets information about the enclave for the given identifier

Args

• enclaveIdentifier: The identifier of the enclave.

Returns

• enclaves: The EnclaveInfo object representing the enclave

stopEnclave(String enclaveIdentifier)

Stops the enclave with the given identifier, but doesn't destroy the enclave objects (containers, networks, etc.) so they can be further examined.

NOTE: Any EnclaveContext objects representing the stopped enclave will become unusable.

Args

• enclaveIdentifier: Identifier of the enclave to stop.

destroyEnclave(String enclaveIdentifier)

Stops the enclave with the given identifier and destroys the enclave objects (containers, networks, etc.).

NOTE: Any EnclaveContext objects representing the stopped enclave will become unusable.

Args

• enclaveIdentifier: Identifier of the enclave to destroy.

clean(boolean shouldCleanAll) -> []EnclaveNameAndUuid RemovedEnclaveNameAndUuids

Destroys enclaves in the Kurtosis engine.

Args

• shouldCleanAll: If set to true, destroys running enclaves in addition to stopped ones.

Returns

• RemovedEnclaveNameAndUuids: A list of enclave uuids and names that were removed successfully

getServiceLogs(String enclaveIdentifier, Set<ServiceUUID> serviceUuids, Boolean shouldFollowLogs, LogLineFilter logLineFilter) -> ServiceLogsStreamContent serviceLogsStreamContent

Get and start a service container logs stream (showed in ascending order, with the oldest line first) from services identified by their UUID.

Args

• enclaveIdentifier: Identifier of the services' enclave.
• serviceUuids: A set of service UUIDs identifying the services from which logs should be retrieved.
• shouldFollowLogs: If it's true, the stream will constantly send the new log lines. if it's false, the stream will be closed after the last created log line is sent.
• logLineFilter: The filter that will be used for filtering the returned log lines

Returns

• serviceLogsStreamContent: The ServiceLogsStreamContent object which wrap all the information coming from the logs stream.

getExistingAndHistoricalEnclaveIdentifiers() -> EnclaveIdentifiers enclaveIdentifiers

Get all (active & deleted) historical identifiers for the currently running Kurtosis engine.

Returns

• enclaveIdentifiers The EnclaveIdentifiers which provides user-friendly ways to lookup enclave identifier information.

EnclaveIdentifiers

This class is a representation of identifiers of enclaves.

getEnclaveUuidForIdentifier(string identifier) -> EnclaveUUID enclaveUuid, Error

Returns the UUID that matches the given identifier. If there are no matches it returns an error instead.

Args

• identifier: A enclave identifier string

Returns

• enclaveUuid: The UUID for the enclave identified by the identifier.

getOrderedListOfNames() -> []String enclaveNames

Returns an ordered list of names for all the enclaves registered with the engine. This is useful if users want to enumerate all enclave names, say for an autocomplete like function.

Returns

• enclaveNames: This is a sorted list of enclave names

ServiceLogsStreamContent

This class is the representation of the content sent during a service logs stream communication. This wrapper includes the service's logs content and the not found service UUIDs.

getServiceLogsByServiceUuids() -> Map<ServiceUUID, Array<ServiceLog>> serviceLogsByServiceUuids

Returns the user service logs content grouped by the service's UUID.

Returns

• serviceLogsByServiceUuids: A map containing a list of the ServiceLog objects grouped by service UUID.

getNotFoundServiceUuids() -> Set<ServiceUUID> notFoundServiceUuids

Returns the not found service UUIDs. The UUIDs may not be found either because they don't exist, or because the services haven't sent any logs.

Returns

• notFoundServiceUuids: A set of not found service UUIDs

ServiceLog

This class represents single service's log line information

getContent() -> String content

Returns

• content: The log line string content

LogLineFilter

This class is used to specify the match used for filtering the service's log lines. There are a couple of helpful constructors that can be used to generate the filter type

NewDoesContainTextLogLineFilter(String text) -> LogLineFilter logLineFilter

Returns a LogLineFilter type which must be used for filtering the log lines containing the text match

Args

• text: The text that will be used to match in the log lines

Returns

• logLineFilter: The does-contain-text-match log line filter

NewDoesNotContainTextLogLineFilter(String text) -> LogLineFilter logLineFilter

Returns a LogLineFilter type which must be used for filtering the log lines that do not contain the text match

Args

• text: The text that will be used to match in the log lines

Returns

• logLineFilter: The does-not-contain-text-match log line filter

NewDoesContainMatchRegexLogLineFilter(String regex) -> LogLineFilter logLineFilter

Returns a LogLineFilter type which must be used for filtering the log lines containing the regex match, re2 syntax regex may be used

Args

• regex: The regex expression that will be used to match in the log lines

Returns

• logLineFilter: The does-contain-regex-match log line filter

NewDoesNotContainMatchRegexLogLineFilter(String regex) -> LogLineFilter logLineFilter

Returns a LogLineFilter type which must be used for filtering the log lines that do not contain the regex match, re2 syntax regex may be used

Args

• regex: The regex expression that will be used to match in the log lines

Returns

• logLineFilter: The does-not-contain-regex-match log line filter

Enclaves

This Kurtosis provided class is a collection of various different EnclaveInfo objects, by UUID, shortened UUID, and name.

Map<String, EnclaveInfo> enclavesByUuid

A map from UUIDs to the enclave info for the enclave with the given UUID.

Map<String, EnclaveInfo> enclavesByName

A map from names to the enclave info for the enclave with the given name

Map<String, EnclaveInfo[]> enclavesByShortenedUuid

A map from shortened UUID (first 12 characters of UUID) to the enclave infos of the enclaves it matches too.

EnclaveInfo

This Kurtosis provided class contains information about enclaves. This class just contains data and no methods to manipulate enclaves. Users must use EnclaveContext to modify the state of an enclave.

getEnclaveUuid() -> EnclaveUuid

Gets the UUID of the enclave that this EnclaveInfo object represents.

getShortenedUuid() -> String

Gets the shortened UUID of the enclave that this EnclaveInfo object represents.

getName() -> String

Gets the name of the enclave that this EnclaveInfo object represents.

getCreationTime() -> Timestamp

Gets the timestamp at which the enclave that this EnclaveInfo object represents was created.

getCreationTime() -> Timestamp

Gets the timestamp at which the enclave that this EnclaveInfo object represents was created.

getContainersStatus() -> Status

Gets the current status of the container running the enclave represented by this EnclaveInfo. Is one of 'EMPTY', 'RUNNING' and 'STOPPED'.

EnclaveContext

This Kurtosis-provided class is the lowest-level representation of a Kurtosis enclave, and provides methods for inspecting and manipulating the contents of the enclave.

getEnclaveUuid() -> EnclaveUuid

Gets the UUID of the enclave that this EnclaveContext object represents.

getEnclaveName() -> String

Gets the name of the enclave that this EnclaveContext object represents.

runStarlarkScript(String mainFunctionName, String serializedStarlarkScript, Boolean dryRun, List<String> experimentalFeatureFlags, String connect) -> (Stream<StarlarkRunResponseLine> responseLines, Error error)

Run a provided Starlark script inside the enclave.

Args

• mainFunctionName: The main function name, an empty string can be passed to use the default value 'run'
• serializedStarlarkScript: The Starlark script provided as a string
• dryRun: When set to true, the Kurtosis instructions are not executed.
• experimentalFeatureFlags: List of experimental features to turn on for this run. Leave empty to leave any experimental feature disabled.
• connect: When set to 'CONNECT', the user service ports are forwarded. When set to 'NO_CONNECT', the user service ports are not forwarded.

Returns

• responseLines: A stream of StarlarkRunResponseLine objects

runStarlarkPackage(String packageRootPath, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun, List<String> experimentalFeatureFlags, String connect) -> (Stream<StarlarkRunResponseLine> responseLines, Error error)

Run a provided Starlark script inside the enclave.

Args

• packageRootPath: The path to the root of the package
• relativePathToMainFile: The relative filepath (relative to the package's root) to the main file, and empty string can be passed to use the default value 'main.star'. Example: if your main file is located in a path like this github.com/my-org/my-package/src/internal/my-file.star you should set src/internal/my-file.star as the relative path.
• mainFunctionName: The main function name, an empty string can be passed to use the default value 'run'.
• serializedParams: The parameters to pass to the package for the run. It should be a serialized JSON string.
• dryRun: When set to true, the Kurtosis instructions are not executed.
• experimentalFeatureFlags: List of experimental features to turn on for this run. Leave empty to leave any experimental feature disabled.
• connect: When set to 'CONNECT', the user service ports are forwarded. When set to 'NO_CONNECT', the user service ports are not forwarded.

Returns

• responseLines: A stream of StarlarkRunResponseLine objects

runStarlarkRemotePackage(String packageId, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun, String connect) -> (Stream<StarlarkRunResponseLine> responseLines, Error error)

Run a Starlark script hosted in a remote github.com repo inside the enclave.

Args

• packageId: The ID of the package pointing to the github.com repo hosting the package. For example github.com/kurtosistech/datastore-army-package
• relativePathToMainFile: The relative filepath (relative to the package's root) to the main file, and empty string can be passed to use the default value 'main.star'. Example: if your main file is located in a path like this github.com/my-org/my-package/src/internal/my-file.star you should set src/internal/my-file.star as the relative path.
• mainFunctionName: The main function name, an empty string can be passed to use the default value 'run'.
• serializedParams: The parameters to pass to the package for the run. It should be a serialized JSON string.
• dryRun: When set to true, the Kurtosis instructions are not executed.
• connect: When set to 'CONNECT', the user service ports are forwarded. When set to 'NO_CONNECT', the user service ports are not forwarded.

Returns

• responseLines: A stream of StarlarkRunResponseLine objects

runStarlarkScriptBlocking(String mainFunctionName, String serializedStarlarkScript, Boolean dryRun, String connect) -> (StarlarkRunResult runResult, Error error)

Convenience wrapper around EnclaveContext.runStarlarkScript, that blocks until the execution of the script is finished and returns a single StarlarkRunResult object containing the result of the run.

runStarlarkPackageBlocking(String packageRootPath, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun, String connect) -> (StarlarkRunResult runResult, Error error)

Convenience wrapper around EnclaveContext.runStarlarkPackage, that blocks until the execution of the package is finished and returns a single StarlarkRunResult object containing the result of the run.

runStarlarkRemotePackageBlocking(String packageId, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun, String connect) -> (StarlarkRunResult runResult, Error error)

Convenience wrapper around EnclaveContext.runStarlarkRemotePackage, that blocks until the execution of the package is finished and returns a single StarlarkRunResult object containing the result of the run.

getServiceContext(String serviceIdentifier) -> ServiceContext serviceContext

Gets relevant information about a service (identified by the given service identifier) that is running in the enclave.

Args

• serviceIdentifier: The identifier(name, UUID or short name) of the target service

Returns

The ServiceContext representation of a service running in a Docker container.

getServices() -> Map<ServiceName, ServiceUUID> serviceIdentifiers

Gets the Name and UUID of the current services in the enclave.

Returns

• serviceIdentifiers: A map of objects containing a mapping of Name -> UUID for all the services inside the enclave

uploadFiles(String pathToUpload, String artifactName) -> FilesArtifactUUID, FilesArtifactName, Error

Uploads a filepath or directory path as a files artifact. The resulting files artifact can be used in ServiceConfig.files when adding a service.

If a directory is specified, the contents of the directory will be uploaded to the archive without additional nesting. Empty directories cannot be uploaded.

Args

• pathToUpload: Filepath or dirpath on the local machine to compress and upload to Kurtosis.
• artifactName: The name to refer the artifact with.

Returns

• FilesArtifactUUID: A UUID identifying the new files artifact, which can be used in ServiceConfig.files.
• FilesArtifactName: The name of the file-artifact, it is auto-generated if artitfactName is an empty string.

storeWebFiles(String urlToDownload, String artifactName)

Downloads a files-containing .tgz from the given URL as a files artifact. The resulting files artifact can be used in ServiceConfig.files when adding a service.

Args

• urlToDownload: The URL on the web where the files-containing .tgz should be downloaded from.
• artifactName: The name to refer the artifact with.

Returns

• UUID: A UUID identifying the new files artifact, which can be used in ServiceConfig.files.

getExistingAndHistoricalServiceIdentifiers() -> ServiceIdentifiers serviceIdentifiers

Get all (active & deleted) historical identifiers for services for the enclave represented by the EnclaveContext.

Returns

• serviceIdentifiers: The ServiceIdentifiers which provides user-friendly ways to lookup service identifier information.

getAllFilesArtifactNamesAndUuids() -> []FilesArtifactNameAndUuid filesArtifactNamesAndUuids

Get a list of all files artifacts that are registered with the enclave represented by the EnclaveContext

Returns

• filesArtifactNameAndUuids: A list of files artifact names and their corresponding uuids.

ServiceIdentifiers

This class is a representation of service identifiers for a given enclave.

getServiceUuidForIdentifier(string identifier) -> ServiceUUID serviceUUID, Error

Returns the UUID that matches the given identifier. If there are no matches it returns an error instead.

Args

• identifier: A service identifier string

Returns

• enclaveUuid: The UUID for the service identified by the identifier.

getOrderedListOfNames() -> []String serviceNames

Returns an ordered list of names for all the services in the enclave. This is useful if users want to enumerate all service names, say for an autocomplete like function.

Returns

• serviceNames: This is a sorted list of service names

StarlarkRunResponseLine

This is a union object representing a single line returned by Kurtosis' Starlark runner. All Starlark run endpoints will return a stream of this object.

Each line is one of:

StarlarkInstruction instruction

An instruction that is about to be executed.

StarlarkInstructionResult instructionResult

The result of an instruction that was successfully executed

StarlarkError error

The error that was thrown running the Starlark code

StarlarkRunProgress progressInfo

Regularly during the run of the code, Kurtosis Starlark engine will send progress information through the stream to account for progress that was made running the code.

StarlarkRunFinishedEvent runFinishedEvent

This object will be sent once at the end of the execution to signify it has ended.

StarlarkWarning warning

A warning, non-fatal, message

StarlarkInstruction

StarlarkInstruction represents a Starlark instruction that is currently being executed. It contains the following fields:

• instructionName: the name of the instruction

• instructionPosition: the position of the instruction in the source code. It iscomposed of (filename, line number, column number)

• arguments: The list of arguments provided to this instruction. Each argument is composed of an optional name (if it was named in the source script) and its serialized value

• executableInstruction: A single string representing the instruction in valid Starlark code

StarlarkInstructionResult

StarlarkInstructionResult is the result of an instruction that was successfully run against Kurtosis engine. It is a single string field corresponding to the output of the instruction.

StarlarkError

Errors can be of three kind:

• Interpretation error: these errors happen before Kurtosis was able to execute the script. It typically means there's a syntax error in the provided Starlark code. The error message should point the users to where the code is incorrect.

• Validation error: these errors happen after interpretation was successful, but before the execution actually started in Kurtosis. Before starting the execution, Kurtosis runs some validation on the instructions that are about to be executed. The error message should contain more information on which instruction is incorrect.

• Execution error: these errors happen during the execution of the script against Kurtosis engine. More information is available in the error message.

StarlarkRunProgress

StarlarkRunProgress accounts for progress that is made during a Starlark run. It contains three fields:

• totalSteps: The total number of steps for this run

• currentStepNumber: The number of the step that is currently being executed

• currentStepInfo: A string field with some information on the current step being executed.

StarlarkRunFinishedEvent

StarlarkRunFinishedEvent is the object returned when the execution of the Starlark code is finished. Is composed of two fields:

• isRunSuccessful: whether the run successfully finished or not

• serializedOutput: when the run is successful and the Starlark code has returned an object, the returned object is automatically serialized to JSON by Kurtosis and returned via this field.

StarlarkWarning

StarlarkWarning is a warning message returned by Kurtosis Starlark engine. Warnings are by definition non-fatal, they typically point out an antipattern in the code or a deprecated feature still being used

StarlarkRunResult

StarlarkRunResult is the object returned by the blocking functions to run Starlark code. It is similar to StarlarkRunResponseLine except that it is not a union object:

• instructions: the Starlark Instruction that were run

• insterpretationError: a potential Starlark Interpretation error (see StarlarkError

• validationErrors: potential Starlark Validation errors (see StarlarkError

• executionError: a potential Starlark Execution error (see StarlarkError

• runOutput: The full output of the run, composed of the concatenated output for each instruction that was executed (separated by a newline)

ServiceContext

This Kurtosis-provided class is the lowest-level representation of a service running inside a Docker container. It is your handle for retrieving container information and manipulating the container.

getServiceName() -> ServiceName

Gets the Name that Kurtosis uses to identify the service.

Returns

The service's Name.

getServiceUuid() -> ServiceUUID

Gets the UUID (Universally Unique Identifier) that Kurtosis creates and uses to identify the service. The differences with the Name is that this one is created by Kurtosis, users can't specify it, and this never can be repeated, every new execution of the same service will have a new UUID

Returns

The service's UUID.

getPrivateIpAddress() -> String

Gets the IP address where the service is reachable at from inside the enclave that the container is running inside. This IP address is how other containers inside the enclave can connect to the service.

Returns

The service's private IP address.

getPrivatePorts() -> Map<PortID, PortSpec>

Gets the ports that the service is reachable at from inside the enclave that the container is running inside. These ports are how other containers inside the enclave can connect to the service.

Returns

The ports that the service is reachable at from inside the enclave, identified by the user-chosen port ID set in ServiceConfig.ports when the service was created.

getMaybePublicIpAddress() -> String

If the service declared used ports in ServiceConfig.ports, then this function returns the IP address where the service is reachable at from outside the enclave that the container is running inside. This IP address is how clients on the host machine can connect to the service. If no used ports were declared, this will be empty.

Returns

The service's public IP address, or an empty value if the service didn't declare any used ports.

getPublicPorts() -> Map<PortID, PortSpec>

Gets the ports that the service is reachable at from outside the enclave that the container is running inside. These ports are how clients on the host machine can connect to the service. If the service didn't declare any used ports in ServiceConfig.ports, this value will be an empty map.

Returns

The ports (if any) that the service is reachable at from outside the enclave, identified by the user-chosen ID set in ServiceConfig.ports when the service was created.

execCommand(List<String> command) -> (int exitCode, String logs)

Uses Docker exec functionality to execute a command inside the service's running Docker container.

Args

• command: The args of the command to execute in the container.

Returns

• exitCode: The exit code of the command.
• logs: The output of the run command, assuming a UTF-8 encoding. NOTE: Commands that output non-UTF-8 output will likely be garbled!