kurtosis-client


Project maintained by kurtosis-tech Hosted on GitHub Pages — Theme by mattgraham

Kurtosis Client Documentation

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. These objects are heavily used inside the Kurtosis testing framework. Note that any comments specific to a language implementation will be found in the code comments.

Found a bug? File it on the repo!

ModuleContext

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.

execute(String serializedParams) -> String serializedResult

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

Returns

Network

This interface provides the option to define a higher level of abstraction for manipulating your test network than is provided by NetworkContext, so that test-writing is easier. This commonly looks like wrapping several NetworkContext methods into a single one - e.g. if you’re running a Cassandra cluster that must bootstrap off three nodes, you might define a CassandraNetwork implementation with a startBootstrappers method that does the gruntwork so each test doesn’t need to add the services manually. Each of your tests will then receive this custom implementation in their Test.run method.

NetworkContext

This Kurtosis-provided class is the lowest-level representation of a test network, and provides methods for inspecting and manipulating the network. All Network implementations will encapsulate an instance of this class.

loadModule(String moduleId, String image, String serializedParams) -> [ModuleContext][modulecontext] moduleContext

Starts a new Kurtosis module (configured using the serialized params) inside the test network, which makes it available for use.

Args

Returns

unloadModule(String moduleId)

Stops and removes a Kurtosis module from the enclave.

Args

getModuleContext(String moduleId) -> [ModuleContext][modulecontext] moduleContext

Gets the [ModuleContext][modulecontext] associated with an already-running module container identified by the given ID.

Args

Returns

registerFilesArtifacts(Map<FilesArtifactID, String> filesArtifactUrls)

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

addServiceToPartition(ServiceID serviceId, PartitionID partitionId, Func(String ipAddr, SharedPath sharedDirectory) -> ContainerConfig containerConfigSupplier) -> (ServiceContext serviceContext, Map<String, PortBinding> hostPortBindings)

Starts a new service in the network with the given service ID, inside the partition with the given ID, using the given config supplier.

Args

Returns

addService(ServiceID serviceId, Func(String ipAddr, SharedPath sharedDirectory) -> ContainerConfig containerConfigSupplier) -> (ServiceContext serviceContext, Map<String, PortBinding> hostPortBindings)

Convenience wrapper around NetworkContext.addServiceToPartition, that adds the service to the default partition. Note that if the network has been repartitioned and the default partition doesn’t exist anymore, this method will fail.

getServiceContext(ServiceID serviceId) -> ServiceContext

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

Args

Returns

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

removeService(ServiceID serviceId, uint64 containerStopTimeoutSeconds)

Stops the container with the given service ID and removes it from the network.

Args

repartitionNetwork(Map<PartitionID, Set<ServiceID>> partitionServices, Map<PartitionID, Map<PartitionID, PartitionConnectionInfo>> partitionConnections, PartitionConnectionInfo defaultConnection)

Repartitions the network so that the connections between services match the specified new state. All services currently in the network must be allocated to a new partition.

NOTE: For this to work, partitioning must be turned on in the Test.configure method.

Args

waitForHttpGetEndpointAvailability(ServiceID serviceId, uint32 port, String path, String requestBody, uint32 initialDelayMilliseconds, uint32 retries, uint32 retriesDelayMilliseconds, String bodyText)

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

waitForHttpPostEndpointAvailability(ServiceID serviceId, uint32 port, String path, String requestBody, uint32 initialDelayMilliseconds, uint32 retries, uint32 retriesDelayMilliseconds, String bodyText)

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

getServices() -> Set<ServiceID> serviceIDs

Gets the IDs of the current services in the test network

Returns

getModules() -> Set<ModuleID> moduleIds

Gets the IDs of the Kurtosis modules that have been loaded into the enclave.

Returns

PartitionConnectionInfo

This class is a plain old object defining the state between two partitions (e.g. whether network traffic is blocked or not). It is auto-generated from a gRPC API, so exploring it in code is the best way to view its properties.

NOTE: These objects will often have several gRPC-specific fields inside them, but which don’t need to be considered; you can construct the object however you normally instantiate objects in your language of choice (e.g. new in Java, PartitionConnectionInfo{....fields...} in Go, etc.).

ContainerConfig

Object containing information Kurtosis needs to create and run the container. This config should be created using ContainerConfigBuilder instances.

String image

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).

Set<String> usedPortsSet

The set of ports that the container will be listening on, in the format NUM/PROTOCOL (e.g. 80/tcp, 9090/udp, etc.).

Map<String, String> filesArtifactMountpoints

Sometimes a service needs files to be available before it starts, but creating those files manually is slow, difficult, or would require committing a very large artifact to the testsuite’s Git repo (e.g. starting a service with a 5 GB Postgres database mounted). To ease this pain, Kurtosis allows you to specify URLs of gzipped TAR files that Kurtosis will download, uncompress, and mount inside your service containers.

This property is therefore a map of the file artifact ID -> path on the container where the uncompressed artifact contents should be mounted, with the file artifact IDs corresponding to the files artifacts registered via NetworkContext.registerFilesArtifacts.

E.g. if my test declares an artifact called 5gb-database that lives at https://my-site.com/test-artifacts/5gb-database.tgz, I might return the following map from this function to mount the artifact at the /database path inside my container: {"5gb-database": "/database"}.

List<String> entrypointOverrideArgs

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.

List<String> cmdOverrideArgs

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.

Map<String, String> environmentVariableOverrides

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.

ContainerConfigBuilder

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).

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.

getServiceId() -> ServiceID

Gets the ID that Kurtosis uses to identify the service.

Returns

The service’s ID.

getIpAddress() -> String

Gets the IP address of the Docker container that the service is running inside.

Returns

The service’s IP address.

getSharedDirectory() -> SharedPath

Get the directory that is mounted on both the current container running this code and the service container, so that files can be passed back and forth. The directory is expressed as a SharedPath object, so file inside can be referenced by absolute filepath on either this container or the service contianer.

Returns

The SharedPath object.

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

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

Args

Returns

SharedPath

Simple structure that holds information about a filepath shared between two containers: this container, and a container running a service in a testnet. The actual object referenced by this path could be anything - a file, a directory, a symlink, nonexistent, etc.

getAbsPathOnThisContainer() -> String

For the object in the shared directory represented by this SharedPath object, gets the absolute filepath on the container where this code is running.

getAbsPathOnServiceContainer() -> String

For the object in the shared directory represented by this SharedPath object, gets the absolute filepath on the remote service container where the shared directory is also mounted.

getChildPath(String relativePath) -> SharedPath

Gets a new SharedPath object that represents another path inside the shared directory, relative to the current path object. E.g. if the shared directory had a subdirectory called my-dir which has some-file.txt, sharedDirRoot.getChildPath("my-dir") would represent that subdirectory and sharedDirRoot.getChildPath("my-dir/some-file.txt") would get the file inside.

Args

Returns

The new SharedPath object.


Found a bug? File it on the repo!

TODO MODIFY [modulecontext]: #modulecontext