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

```bash
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

```bash
# 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

```bash
# 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:

```bash
# 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

```python
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

```python
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:

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

### Copy files from a running service

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

### Store output from a shell command

```python
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:

```bash
# 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:

```bash
# 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 |