This documentation describes how to interact with the Kurtosis API from within a testnet. It includes information about starting services, stopping services, repartitioning the network, etc. Note that any comments specific to a language implementation will be found in the code comments.
Found a bug? File it on the repo!
This Kurtosis-provided class is the lowest-level representation of a Kurtosis module - a Docker container with a connection to the Kurtosis engine that responds to commands.
Some modules are considered executable, meaning they respond to an “execute” command. This function will send the execute command to the module with the given serialized args, returning the serialized result. The serialization format of args & response will depend on the module. If the module isn’t executable (i.e. doesn’t respond to an “execute” command) then an error will be thrown.
Args
serializedParams: Serialized data containing args to the module’s execute function. Consult the documentation for the module you’re using to determine what this should contain.Returns
serializedResult: Serialized data containing the results of executing the module. Consult the documentation for the module you’re using to determine what this will contain.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.
Gets the ID of the enclave that this EnclaveContext object represents.
Starts a new Kurtosis module (configured using the serialized params) inside the enclave, which makes it available for use.
Args
moduleId: The ID that the new module should receive (must not exist).image: The container image of the module to be loaded.serializedParams: Serialized parameter data that will be passed to the module as it starts, to control overall module behaviour.Returns
moduleContext: The ModuleContext representation of the running module container, which allows execution of the execute function (if it exists).Stops and removes a Kurtosis module from the enclave.
Args
moduleId: The ID of the module to remove.Gets the ModuleContext associated with an already-running module container identified by the given ID.
Args
moduleId: The ID of the module to retrieve the context for.Returns
moduleContext: The ModuleContext representation of the running module container, which allows execution of the module’s execute function (if it exists).Downloads the given files artifacts to the Kurtosis engine, associating them with the given IDs, so they can be mounted inside a service’s filespace at creation time via ContainerConfig.filesArtifactMountpoints.
Args
filesArtifactUrls: A map of files_artifact_id -> url, where the ID is how the artifact will be referenced in ContainerConfig.filesArtifactMountpoints and the URL is the URL on the web where the files artifact should be downloaded from.Starts a new service in the enclave with the given service ID, inside the partition with the given ID, using the given config supplier.
Args
serviceId: The ID that the new service should have.partitionId: The ID of the partition that the new service should be started in. This can be left blank to start the service in the default partition if it exists (i.e. if the enclave hasn’t been repartitioned and the default partition removed).containerConfigSupplier: An anonymous function, used to produce the ContainerConfig for starting the service, which receives the private IP address of the service being started (the IP address of the service inside the service’s enclave)Returns
serviceContext: The ServiceContext representation of a service running in a Docker container.hostPortBindings: The port spec strings that the service declared (as defined in ContainerConfig.usedPorts), mapped to the port on the host machine where the port has been bound to. This allows you to make requests to a service running in Kurtosis by making requests to a port on your local machine. If a port was not bound to a host machine port, it will not be present in the map (and if no ports were bound to host machine ports, the map will be empty).Convenience wrapper around EnclaveContext.addServiceToPartition, that adds the service to the default partition. Note that if the enclave has been repartitioned and the default partition doesn’t exist anymore, this method will fail.
Gets relevant information about a service (identified by the given service ID) that is running in the enclave.
Args
serviceId: The ID of the service to pull the information from.Returns
The ServiceContext representation of a service running in a Docker container.
Stops the container with the given service ID and removes it from the enclave.
Args
serviceId: The ID of the service to remove.containerStopTimeoutSeconds: The number of seconds to wait for the container to gracefully stop before hard-killing it.Repartitions the enclave so that the connections between services match the specified new state. All services currently in the enclave must be allocated to a new partition.
NOTE: For this to work, partitioning must be turned on when the Enclave is created with KurtosisContext.createEnclave().
Args
partitionServices: A definition of the new partitions in the enclave, and the services allocated to each partition. A service can only be allocated to a single partition.partitionConnections: Definitions of the connection state between the new partitions. If a connection between two partitions isn’t defined in this map, the default connection will be used. Connections are not directional, so an error will be thrown if the same connection is defined twice (e.g. Map[A][B] = someConnection, and Map[B][A] = otherConnection).defaultConnection: The network state between two partitions that will be used if the connection isn’t defined in the partition connections map.Waits until a service endpoint is available by making requests to the endpoint using the given parameters, and the HTTP GET method. An error is thrown if the number of retries is exceeded.
Args
serviceId: The ID of the service to check.port: The port (e.g. 8080) of the endpoint to check.path: The path of the service to check, which must not start with a slash (e.g. service/health).initialDelayMilliseconds: Number of milliseconds to wait until executing the first HTTP callretries: Max number of HTTP call attempts that this will execute until giving up and returning an errorretriesDelayMilliseconds: Number of milliseconds to wait between retriesbodyText: If this value is non-empty, the endpoint will not be marked as available until this value is returned (e.g. Hello World). If this value is emptystring, no body text comparison will be done.Waits until a service endpoint is available by making requests to the endpoint using the given parameters, and the HTTP POST method. An error is thrown if the number of retries is exceeded.
Args
serviceId: The ID of the service to check.port: The port (e.g. 8080) of the endpoint to check.path: The path of the service to check, which must not start with a slash (e.g. service/health).requestBody: The request body content that will be sent to the endpoint being checked.initialDelayMilliseconds: Number of milliseconds to wait until executing the first HTTP callretries: Max number of HTTP call attempts that this will execute until giving up and returning an errorretriesDelayMilliseconds: Number of milliseconds to wait between retriesbodyText: If this value is non-empty, the endpoint will not be marked as available until this value is returned (e.g. Hello World). If this value is emptystring, no body text comparison will be done.Gets the IDs of the current services in the enclave.
Returns
serviceIDs: A set of service IDsGets the IDs of the Kurtosis modules that have been loaded into the enclave.
Returns
moduleIds: A set of Kurtosis module IDs that are running in the enclaveTakes a filepath or directory path that will be compressed and uploaded to the Kurtosis filestore for use with ContainerConfig.filesArtifactMountpoints.
Args
pathToUpload: Filepath or dirpath on the local machine to compress and upload to Kurtosis.Returns
uuid: A unique ID as a string identifying the uploaded files, which can be used in ContainerConfig.filesArtifactMountpoints.Downloads a files-containing .tgz from the given URL to the Kurtosis engine, so that the files inside can be mounted inside a service’s filespace at creation time via ContainerConfig.filesArtifactMountpoints.
Args
urlToDownload: The URL on the web where the files-containing .tgz should be downloaded from.Returns
uuid: A unique ID as a string identifying the downloaded, which can be used in ContainerConfig.filesArtifactMountpoints.Copy a file or folder from a service container to the Kurtosis filestore for use with ContainerConfig.filesArtifactMountpoints
Args
serviceId: The ID of the service which contains the file or the folder.absoluteFilepathOnServiceContainer: The absolute filepath on the service where the file or folder should be copied fromReturns
uuid: A unique ID as a string identifying the generated files artifact, which can be used in ContainerConfig.filesArtifactMountpoints.Pauses all running processes in the specified service, but does not shut down the service. Processes can be restarted with EnclaveContext.unpauseService.
Args
serviceId: The ID of the service to pause.Unpauses all paused processes in the specified service. Specified service must have been previously paused.
Args
serviceId: The ID of the service to unpause.This interface represents the network state between two partitions (e.g. whether network traffic is blocked, being partially dropped, etc.).
The three types of partition connections are: unblocked (all traffic is allowed), blocked (no traffic is allowed), and soft (packets are partially dropped). Each type of partition connection has a constructor that can be used to create them.
The soft partition constructor receives one parameter, packetLossPercentage, which sets the percentage of packet loss in the connection between the services that are part of the partition.
Unblocked partitions and blocked partitions have parameter-less constructors.
Object containing information Kurtosis needs to create and run the container. This config should be created using ContainerConfigBuilder instances.
The name of the container image that Kurtosis should use when creating the service’s container (e.g. my-repo/my-image:some-tag-name).
The ports that the container will be listening on, identified by a user-friendly ID that can be used to select the port again in the future (e.g. via ServiceContext.getPublicPorts.
Sometimes a service needs files to be available before it starts (e.g. starting a service with a 5 GB Postgres database mounted). To ease this pain, Kurtosis allows you to specify gzipped TAR files that Kurtosis will uncompress and mount at locations on your service containers. These “files artifacts” will need to have been stored in Kurtosis beforehand using methods like EnclaveContext.uploadFiles.
This property is therefore a map of the files artifact ID -> path on the container where the uncompressed artifact contents should be mounted, with the file artifact IDs corresponding to the ID returned by files-storing methods like EnclaveContext.uploadFiles.
E.g. if I’ve previously uploaded a set of files using EnclaveContext.uploadFiles and Kurtosis has returned me the ID 813bdb20-3aab-4c5b-a0f5-a7deba7bf0d7, I might ask Kurtosis to mount the contents inside my container at the /database path using a map like {"813bdb20-3aab-4c5b-a0f5-a7deba7bf0d7": "/database"}.
You often won’t control the container images that you’ll be using in your testnet, and the ENTRYPOINT statement hardcoded in their Dockerfiles might not be suitable for what you need. This function allows you to override these statements when necessary.
You often won’t control the container images that you’ll be using in your testnet, and the CMD statement hardcoded in their Dockerfiles might not be suitable for what you need. This function allows you to override these statements when necessary.
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.
The builder that should be used to create ContainerConfig instances. The functions on this builder will correspond to the properties on the ContainerConfig object, in the form withPropertyName (e.g. withUsedPorts sets the ports used by the container).
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.
Gets the ID that Kurtosis uses to identify the service.
Returns
The service’s ID.
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.
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 ID set in ContainerConfig.usedPorts when the service was created.
If the service declared used ports in ContainerConfig.usedPorts, 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.
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 ContainerConfig.usedPorts, 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 ContainerConfig.usedPorts when the service was created.
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!Found a bug? File it on the repo!