kurtosis-core


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

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.

getEnclaveId() -> EnclaveID

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

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

Starts a new Kurtosis module (configured using the serialized params) inside the enclave, 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

Gets the 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) -> ContainerConfig containerConfigSupplier) -> (ServiceContext serviceContext)

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

Returns

addServicesToPartition(Map<ServiceID, Func(String ipAddr) -> ContainerConfig> serviceConfigSuppliers, PartitionID partitionId) -> (Map<ServiceID, ServiceContext> successfulServices, Map<ServiceID, Error> failedServices)

Start services in bulk in the enclave with the given service IDs, inside the partition with the given ID, using the given config suppliers.

Args

Returns

addService(ServiceID serviceId, Func(String ipAddr) -> ContainerConfig containerConfigSupplier) -> (ServiceContext serviceContext)

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.

addServices(Map<ServiceID, Func(String ipAddr) -> ContainerConfig> serviceConfigSuppliers) -> (Map<ServiceID, ServiceContext> successfulServices, Map<ServiceID, Error> failedServices)

Convenience wrapper around EnclaveContext.addServicesToPartition, that adds the services to the default partition. Note that if the enclave 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 enclave.

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

Args

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

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

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

Returns

getModules() -> Set<ModuleID> moduleIds

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

Returns

uploadFiles(String pathToUpload)

Takes a filepath or directory path that will be compressed and uploaded to the Kurtosis filestore for use with ContainerConfig.filesArtifactMountpoints.

Args

Returns

storeWebFiles(String urlToDownload)

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

Returns

storeServiceFiles(ServiceID serviceId, String absoluteFilepathOnServiceContainer)

Copy a file or folder from a service container to the Kurtosis filestore for use with ContainerConfig.filesArtifactMountpoints

Args

Returns

pauseService(ServiceID serviceId)

Pauses all running processes in the specified service, but does not shut down the service. Processes can be restarted with EnclaveContext.unpauseService.

Args

unpauseService(ServiceID serviceId)

Unpauses all paused processes in the specified service. Specified service must have been previously paused.

Args

PartitionConnection

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.

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

Map<PortID, PortSpec> usedPorts

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.

Map<String, String> filesArtifactMountpoints

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"}.

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.

uint64 cpuAllocationMillicpus

Allows you to set an allocation for CPU resources available in the underlying host container of a service. The metric used to measure cpuAllocation is millicpus, 1000 millicpus is equivalent to 1 CPU on the underlying machine. This metric is identical Docker’s measure of cpus and Kubernetes measure of cpus for limits. Setting cpuAllocationMillicpus=1500 is equivalent to setting cpus=1.5 in Docker and cpus=1.5 or cpus=1500m in Kubernetes. If set, the value must be a nonzero positive integer. If unset, there will be no constraints on CPU usage of the host container.

uint64 memoryAllocationMegabytes

Allows you to set an allocation for memory resources available in the underlying host container of a service. The metric used to measure memoryAllocation is megabytes. Setting memoryAllocation=1000 is equivalent to setting the memory limit of the underlying host machine to 1e9 bytes or 1GB. If set, the value must be a nonzero positive integer of at least 6 megabytes as Docker requires this as a minimum. If unset, there will be no constraints on memory usage of the host container. For information on memory limits in your underlying container engine, view Docker’s and Kubernetes` docs.

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.

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 ID set in ContainerConfig.usedPorts when the service was created.

getMaybePublicIpAddress() -> String

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.

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

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


Found a bug? File it on the repo!