Skip to main content

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

Returns

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

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 serializedStarlarkScript, StarlarkRunConfig runConfig) -> (Stream<StarlarkRunResponseLine> responseLines, Error error)​

Run a provided Starlark script inside the enclave.

Args

  • serializedStarlarkScript: The Starlark script provided as a string
  • starlarkRunConfig: A configuration object of type StarlarkRunConfig

Returns

runStarlarkPackage(String packageRootPath, StarlarkRunConfig starlarkRunConfig) -> (Stream<StarlarkRunResponseLine> responseLines, Error error)​

Run a provided Starlark script inside the enclave.

Args

  • packageRootPath: The path to the root of the package
  • starlarkRunConfig: A configuration object of type StarlarkRunConfig

Returns

runStarlarkRemotePackage(String packageId, StarlarkRunConfig starlarkRunConfig) -> (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
  • starlarkRunConfig: A configuration object of type StarlarkRunConfig

Returns

runStarlarkScriptBlocking(String mainFunctionName, StarlarkRunConfig starlarkRunConfig) -> (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, StarlarkRunConfig starlarkRunConfig) -> (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, StarlarkRunConfig starlarkRunConfig) -> (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

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

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.

getStarlarkRun() -> (GetStarlarkRunResponse getStarlarkResponse, Error error)​

Get the last Starlark run from the enclave.

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)

StarlarkRunConfig​

This is a configuration object for Starlark Runs:

  • RelativePathToMainFile: The relative filepath (relative to the package's root) to the main file, if not set will 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. Configurable using WithRelativePathToMainFile
  • MainFunctionName: The main function name, if not set will use the default value 'run'. Configurable using WithMainFunctionName
  • SerializedParams: The parameters to pass to the package for the run. It should be a serialized JSON/YAML string. Configurable using WithSerializedParams; defaults to {} if not set.
  • DryRun: When set to true, the Kurtosis instructions are not executed. Configurable using WithDryRun; defaults to false.
  • Parallelism: The level of parallelism for instructions that support parallelism. Configurable using WithParallelism; defaults to 4
  • ExperimentalFeatureFlags: List of experimental features to turn on for this run. Leave empty to leave any experimental feature disabled. Configurable using WithExperimentalFeatureFlags; defaults to empty
  • CloudInstanceId: The CloudInstanceId if running on Cloud Kurtosis. Configurable using WithCloudInstanceID; defaults to "".
  • CloudUserId: The CloudUserId if running on Cloud Kurtosis. Configurable using WithCloudUserId; defaults to "".

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!