kurtosis-tech/files-inspect

Files Inspect

Work with Kurtosis file artifacts — the mechanism for passing files between services and into containers.

What are file artifacts?

File artifacts are named collections of files stored in an enclave. They're created by:

• plan.upload_files() — upload local files from a package
• plan.render_templates() — render Go templates with data
• plan.store_service_files() — copy files from a running service
• plan.run_sh() / plan.run_python() — store output files from scripts

Services mount artifacts via the files parameter in ServiceConfig.

List artifacts in an enclave

kurtosis enclave inspect <enclave-name>

The "Files Artifacts" section shows each artifact's UUID and name:

========================================= Files Artifacts =========================================
UUID           Name
4a0563e5a391   1-lighthouse-geth-0-127
f49b81f30a8f   el_cl_genesis_data
88c3f17013f3   jwt_file

Download artifacts

# Download to a local directory
kurtosis files download <enclave-name> <artifact-name> /tmp/artifact-output

# Example: inspect genesis data
kurtosis files download <enclave-name> el_cl_genesis_data /tmp/genesis
ls -la /tmp/genesis/
cat /tmp/genesis/config.yaml

Upload files

# Upload a local file or directory as an artifact
kurtosis files upload <enclave-name> /path/to/local/file-or-dir

The command returns the artifact name and UUID for use in subsequent service configs.

Inspect files inside a running service

Verify files were mounted correctly by checking content matches expectations:

# List files at the mount path to confirm they exist
kurtosis service exec <enclave-name> <service-name> -- ls -la /mounted/path/

# Inspect file contents to verify correctness
kurtosis service exec <enclave-name> <service-name> -- cat /mounted/path/config.yaml

# Compare against expected content (e.g., check a key value)
kurtosis service exec <enclave-name> <service-name> -- sh -c "grep 'expected_key' /mounted/path/config.yaml"

# Or shell in for interactive exploration
kurtosis service shell <enclave-name> <service-name>

Starlark file patterns

Upload files from package

artifact = plan.upload_files(src="./static_files/config.yaml", name="my-config")

plan.add_service(
    name="my-service",
    config=ServiceConfig(
        image="my-image:latest",
        files={"/etc/myapp": artifact},
    ),
)

# Verify files were mounted correctly
plan.exec(
    service_name="my-service",
    recipe=ExecRecipe(command=["ls", "-la", "/etc/myapp/"]),
)

Render templates with variables

template = read_file("./templates/config.toml.tmpl")

artifact = plan.render_templates(
    name="rendered-config",
    config={
        "config.toml": struct(
            template=template,
            data={"port": 8080, "host": "0.0.0.0"},
        ),
    },
)

Template syntax uses Go templates:

# config.toml.tmpl
host = "{{.host}}"
port = {{.port}}

Copy files from a running service

artifact = plan.store_service_files(
    service_name="my-service",
    src="/data/output",
    name="service-output",
)

Store output from a shell command

result = plan.run_sh(
    run="echo 'hello' > /tmp/output.txt && cat /tmp/output.txt",
    store=[StoreSpec(src="/tmp/output.txt", name="shell-output")],
)

Kubernetes-specific

On Kubernetes, file artifacts are stored as files-artifacts-expander init containers:

# See init containers for a service pod
kubectl describe pod <pod-name> -n kt-<enclave-name> | grep -A10 "Init Containers"

# Check if files-artifacts-expander succeeded
kubectl logs <pod-name> -n kt-<enclave-name> -c files-artifact-expander

# If the expander image is failing (ImagePullBackOff), check image tag
kubectl describe pod <pod-name> -n kt-<enclave-name> | grep "files-artifacts-expander"

Debugging workflow

When files aren't working as expected, follow these steps:

# 1. List artifacts in the enclave to verify they exist
kurtosis enclave inspect <enclave-name>

# 2. Download the artifact and inspect its contents locally
kurtosis files download <enclave-name> <artifact-name> /tmp/debug-artifact
cat /tmp/debug-artifact/config.yaml

# 3. Verify the mount path inside the service
kurtosis service exec <enclave-name> <service-name> -- ls -la /mounted/path/

# 4. Check file contents match expectations
kurtosis service exec <enclave-name> <service-name> -- cat /mounted/path/config.yaml

# 5. If mismatch: check template data or upload source

Common issues

| Symptom | Cause | Fix | |---------|-------|-----| | File not found in service | Wrong mount path | Check files dict key matches expected path | | Empty file after render | Template syntax error | Download artifact and inspect rendered output | | Init container crash | files-artifacts-expander image issue | Check init container logs with kubectl | | Artifact name conflict | Duplicate artifact names | Use unique names for each plan.upload_files() / plan.render_templates() | | Permission denied | Container runs as non-root | Mount to a writable path or adjust image permissions |