akernel-sdk 0.2.0rc2__tar.gz → 0.2.0rc3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/PKG-INFO +52 -2
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/README.md +51 -1
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_backends/adx.py +57 -19
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/sandbox.py +3 -1
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/types.py +37 -6
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk.egg-info/PKG-INFO +52 -2
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/pyproject.toml +1 -1
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/__init__.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_addresses.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_backends/__init__.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_backends/base.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_backends/errors.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_backends/registry.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_dockercontext.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_dockerfile.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_dockerfile_launch.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_dockerfile_runner.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_instance.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_pty_transport.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_resource_api.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_resources.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_sandbox_resources.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/_tls.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/cli.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/commands.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/filesystem.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/pty.py +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk/py.typed +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk.egg-info/SOURCES.txt +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk.egg-info/dependency_links.txt +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk.egg-info/entry_points.txt +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk.egg-info/requires.txt +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/akernel_sdk.egg-info/top_level.txt +0 -0
- {akernel_sdk-0.2.0rc2 → akernel_sdk-0.2.0rc3}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: akernel-sdk
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.0rc3
|
|
4
4
|
Summary: Python SDK and CLI for AKernel remote sandboxes
|
|
5
5
|
Author: AKernel Authors
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -737,6 +737,55 @@ mount = Mount(target="/opt/tools", image_url="ubuntu:24.04")
|
|
|
737
737
|
Firecracker mounts must instead use `type="erofs"` with an S3 object containing
|
|
738
738
|
a raw EROFS image; it rejects `image_url` and directory-backed mounts.
|
|
739
739
|
|
|
740
|
+
### Node HostPath bind mounts
|
|
741
|
+
|
|
742
|
+
Trusted management clients can bind an existing node-visible path into a
|
|
743
|
+
sandbox. For example, expose a prepared log directory on a selected runsc node:
|
|
744
|
+
|
|
745
|
+
```python
|
|
746
|
+
from akernel_sdk import Mount, Sandbox
|
|
747
|
+
|
|
748
|
+
logs = Mount(
|
|
749
|
+
target="/apps/logs", # Path inside the sandbox.
|
|
750
|
+
host_path="/apps/logs", # Path visible to sandboxd on the selected node.
|
|
751
|
+
read_only=False, # Explicitly allow application log writes.
|
|
752
|
+
)
|
|
753
|
+
with Sandbox(node_id="<prepared-node-id>", mounts=[logs]) as sandbox:
|
|
754
|
+
print(sandbox.commands.run("ls -ld /apps/logs").stdout)
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
`read_only=True` is the default. HostPath supports `type="bind"` only;
|
|
758
|
+
`read_only=False` is rejected for Image/S3 mounts, which remain read-only.
|
|
759
|
+
Exactly one of `image_url`, `s3_config`, or `host_path` is required. The source
|
|
760
|
+
must be an absolute POSIX path without traversal components or control
|
|
761
|
+
characters. The SDK does not inspect the client machine's filesystem or create
|
|
762
|
+
the source directory; it sends `create_if_missing=false`. An absent source or
|
|
763
|
+
insufficient filesystem permissions is a node-side error.
|
|
764
|
+
|
|
765
|
+
In Kubernetes, the node Pod must first see the source, for example through an
|
|
766
|
+
operator-managed `hostPath` volume and matching `volumeMount`. An ECS directory
|
|
767
|
+
does not become visible to sandboxd merely because its path is in the SDK
|
|
768
|
+
request. Directory ownership and permissions must allow the sandbox's process
|
|
769
|
+
UID/GID to use it. Separate workers' local directories are separate data;
|
|
770
|
+
`node_id` selects the prepared node but does not replicate storage. Data written
|
|
771
|
+
through a bind can outlive the sandbox. Runtime-specific mount restrictions
|
|
772
|
+
still apply; Firecracker does not support these directory-backed binds.
|
|
773
|
+
|
|
774
|
+
Restrict HostPath creation to trusted management clients and source paths
|
|
775
|
+
controlled by the operator. These mounts do not provide per-tenant source-path
|
|
776
|
+
isolation; SDK path validation and read-only defaults do not authorize access
|
|
777
|
+
to the node's filesystem. Server permission errors are returned through the
|
|
778
|
+
normal `BackendOperationError` fields.
|
|
779
|
+
|
|
780
|
+
The maintained example requires an explicit node and source. It lists the
|
|
781
|
+
read-only mount by default; `--write` creates one uniquely named log file and
|
|
782
|
+
leaves that file on the node:
|
|
783
|
+
|
|
784
|
+
```bash
|
|
785
|
+
python sdk/python/examples/hostpath_mounts.py \
|
|
786
|
+
--node-id <prepared-node-id> --host-path /apps/logs --write
|
|
787
|
+
```
|
|
788
|
+
|
|
740
789
|
## Launch from a Dockerfile
|
|
741
790
|
|
|
742
791
|
Dockerfile direct launch is a supported AKernel SDK capability and will remain
|
|
@@ -852,6 +901,7 @@ Maintained examples are under [`examples/`](./examples):
|
|
|
852
901
|
- `dockerfile_launch.py`
|
|
853
902
|
- `failover_reload.py`
|
|
854
903
|
- `gpu_sandbox.py`
|
|
904
|
+
- `hostpath_mounts.py`
|
|
855
905
|
- `named_sandbox.py`
|
|
856
906
|
- `network_policy.py`
|
|
857
907
|
- `pty.py`
|
|
@@ -896,7 +946,7 @@ not part of the default test suite.
|
|
|
896
946
|
| `SandboxInfo` | `id`, `state`, `cpu`, `memory`, `image`, `xpu`, `storage_mb` |
|
|
897
947
|
| `NodeInfo` | `id`, `status`, `capacity`, `allocatable`, `labels` |
|
|
898
948
|
| `S3Config` | `endpoint`, `bucket`, `object`, optional credentials |
|
|
899
|
-
| `Mount` | `target`, one
|
|
949
|
+
| `Mount` | `target`, exactly one of `image_url` / `s3_config` / `host_path`, `type`, `read_only` (default `True`; writable only for HostPath) |
|
|
900
950
|
| `HttpReverseTunnel` | `target`, `reverse_port`, `listen_port`, `connect_timeout` |
|
|
901
951
|
| `PortRange` | `first`, `last` |
|
|
902
952
|
| `NetworkRule` | action, direction, protocol, peer and sandbox port selectors, priority |
|
|
@@ -701,6 +701,55 @@ mount = Mount(target="/opt/tools", image_url="ubuntu:24.04")
|
|
|
701
701
|
Firecracker mounts must instead use `type="erofs"` with an S3 object containing
|
|
702
702
|
a raw EROFS image; it rejects `image_url` and directory-backed mounts.
|
|
703
703
|
|
|
704
|
+
### Node HostPath bind mounts
|
|
705
|
+
|
|
706
|
+
Trusted management clients can bind an existing node-visible path into a
|
|
707
|
+
sandbox. For example, expose a prepared log directory on a selected runsc node:
|
|
708
|
+
|
|
709
|
+
```python
|
|
710
|
+
from akernel_sdk import Mount, Sandbox
|
|
711
|
+
|
|
712
|
+
logs = Mount(
|
|
713
|
+
target="/apps/logs", # Path inside the sandbox.
|
|
714
|
+
host_path="/apps/logs", # Path visible to sandboxd on the selected node.
|
|
715
|
+
read_only=False, # Explicitly allow application log writes.
|
|
716
|
+
)
|
|
717
|
+
with Sandbox(node_id="<prepared-node-id>", mounts=[logs]) as sandbox:
|
|
718
|
+
print(sandbox.commands.run("ls -ld /apps/logs").stdout)
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
`read_only=True` is the default. HostPath supports `type="bind"` only;
|
|
722
|
+
`read_only=False` is rejected for Image/S3 mounts, which remain read-only.
|
|
723
|
+
Exactly one of `image_url`, `s3_config`, or `host_path` is required. The source
|
|
724
|
+
must be an absolute POSIX path without traversal components or control
|
|
725
|
+
characters. The SDK does not inspect the client machine's filesystem or create
|
|
726
|
+
the source directory; it sends `create_if_missing=false`. An absent source or
|
|
727
|
+
insufficient filesystem permissions is a node-side error.
|
|
728
|
+
|
|
729
|
+
In Kubernetes, the node Pod must first see the source, for example through an
|
|
730
|
+
operator-managed `hostPath` volume and matching `volumeMount`. An ECS directory
|
|
731
|
+
does not become visible to sandboxd merely because its path is in the SDK
|
|
732
|
+
request. Directory ownership and permissions must allow the sandbox's process
|
|
733
|
+
UID/GID to use it. Separate workers' local directories are separate data;
|
|
734
|
+
`node_id` selects the prepared node but does not replicate storage. Data written
|
|
735
|
+
through a bind can outlive the sandbox. Runtime-specific mount restrictions
|
|
736
|
+
still apply; Firecracker does not support these directory-backed binds.
|
|
737
|
+
|
|
738
|
+
Restrict HostPath creation to trusted management clients and source paths
|
|
739
|
+
controlled by the operator. These mounts do not provide per-tenant source-path
|
|
740
|
+
isolation; SDK path validation and read-only defaults do not authorize access
|
|
741
|
+
to the node's filesystem. Server permission errors are returned through the
|
|
742
|
+
normal `BackendOperationError` fields.
|
|
743
|
+
|
|
744
|
+
The maintained example requires an explicit node and source. It lists the
|
|
745
|
+
read-only mount by default; `--write` creates one uniquely named log file and
|
|
746
|
+
leaves that file on the node:
|
|
747
|
+
|
|
748
|
+
```bash
|
|
749
|
+
python sdk/python/examples/hostpath_mounts.py \
|
|
750
|
+
--node-id <prepared-node-id> --host-path /apps/logs --write
|
|
751
|
+
```
|
|
752
|
+
|
|
704
753
|
## Launch from a Dockerfile
|
|
705
754
|
|
|
706
755
|
Dockerfile direct launch is a supported AKernel SDK capability and will remain
|
|
@@ -816,6 +865,7 @@ Maintained examples are under [`examples/`](./examples):
|
|
|
816
865
|
- `dockerfile_launch.py`
|
|
817
866
|
- `failover_reload.py`
|
|
818
867
|
- `gpu_sandbox.py`
|
|
868
|
+
- `hostpath_mounts.py`
|
|
819
869
|
- `named_sandbox.py`
|
|
820
870
|
- `network_policy.py`
|
|
821
871
|
- `pty.py`
|
|
@@ -860,7 +910,7 @@ not part of the default test suite.
|
|
|
860
910
|
| `SandboxInfo` | `id`, `state`, `cpu`, `memory`, `image`, `xpu`, `storage_mb` |
|
|
861
911
|
| `NodeInfo` | `id`, `status`, `capacity`, `allocatable`, `labels` |
|
|
862
912
|
| `S3Config` | `endpoint`, `bucket`, `object`, optional credentials |
|
|
863
|
-
| `Mount` | `target`, one
|
|
913
|
+
| `Mount` | `target`, exactly one of `image_url` / `s3_config` / `host_path`, `type`, `read_only` (default `True`; writable only for HostPath) |
|
|
864
914
|
| `HttpReverseTunnel` | `target`, `reverse_port`, `listen_port`, `connect_timeout` |
|
|
865
915
|
| `PortRange` | `first`, `last` |
|
|
866
916
|
| `NetworkRule` | action, direction, protocol, peer and sandbox port selectors, priority |
|
|
@@ -19,6 +19,7 @@ from __future__ import annotations
|
|
|
19
19
|
import logging
|
|
20
20
|
import time
|
|
21
21
|
from collections.abc import Mapping
|
|
22
|
+
from dataclasses import dataclass
|
|
22
23
|
from typing import Any
|
|
23
24
|
|
|
24
25
|
import adx_environment
|
|
@@ -29,6 +30,7 @@ from ..types import (
|
|
|
29
30
|
DNSPolicy,
|
|
30
31
|
DNSRule,
|
|
31
32
|
EntryInfo,
|
|
33
|
+
Mount,
|
|
32
34
|
NetworkPolicy,
|
|
33
35
|
NetworkRule,
|
|
34
36
|
PortRange,
|
|
@@ -49,6 +51,60 @@ _DEFAULT_LISTEN_PORT = 8766
|
|
|
49
51
|
logger = logging.getLogger(__name__)
|
|
50
52
|
|
|
51
53
|
|
|
54
|
+
@dataclass(frozen=True)
|
|
55
|
+
class _NativeHostPathMount(adx_environment.Mount):
|
|
56
|
+
"""Adapt node HostPath sources through the pinned native Mount serializer.
|
|
57
|
+
|
|
58
|
+
The pinned native SDK checks isinstance(Mount) before calling to_dict, but
|
|
59
|
+
its stock value type only represents Image/S3. Keep that constructor and
|
|
60
|
+
transport intact without replacing native classes or mutating global state.
|
|
61
|
+
"""
|
|
62
|
+
|
|
63
|
+
host_path: str = ""
|
|
64
|
+
read_only: bool = True
|
|
65
|
+
|
|
66
|
+
def __post_init__(self) -> None:
|
|
67
|
+
self._public_mount()
|
|
68
|
+
|
|
69
|
+
def _public_mount(self) -> Mount:
|
|
70
|
+
if self.image_url is not None or self.s3_config is not None:
|
|
71
|
+
raise ValueError("HostPath adapter requires only a host_path source")
|
|
72
|
+
return Mount(
|
|
73
|
+
target=self.target,
|
|
74
|
+
type=self.type,
|
|
75
|
+
host_path=self.host_path,
|
|
76
|
+
read_only=self.read_only,
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
def to_dict(self) -> dict[str, Any]:
|
|
80
|
+
return self._public_mount().to_dict()
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _native_mount(mount: Mount) -> Any:
|
|
84
|
+
if mount.host_path is not None:
|
|
85
|
+
return _NativeHostPathMount(
|
|
86
|
+
target=mount.target,
|
|
87
|
+
host_path=mount.host_path,
|
|
88
|
+
read_only=mount.read_only,
|
|
89
|
+
)
|
|
90
|
+
return adx_environment.Mount(
|
|
91
|
+
target=mount.target,
|
|
92
|
+
image_url=mount.image_url,
|
|
93
|
+
s3_config=(
|
|
94
|
+
adx_environment.S3Config(
|
|
95
|
+
endpoint=mount.s3_config.endpoint,
|
|
96
|
+
bucket=mount.s3_config.bucket,
|
|
97
|
+
object=mount.s3_config.object,
|
|
98
|
+
access_key=mount.s3_config.access_key,
|
|
99
|
+
secret_key=mount.s3_config.secret_key,
|
|
100
|
+
)
|
|
101
|
+
if mount.s3_config is not None
|
|
102
|
+
else None
|
|
103
|
+
),
|
|
104
|
+
type=mount.type,
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
|
|
52
108
|
def _control_pty_connection(connection: Any) -> Any:
|
|
53
109
|
"""PTY direct routing uses the control TLS entrypoint, not the data port."""
|
|
54
110
|
|
|
@@ -559,25 +615,7 @@ class AdxBackend:
|
|
|
559
615
|
network = None
|
|
560
616
|
if spec.network_policy is not None:
|
|
561
617
|
network = _native_network_policy(spec.network_policy)
|
|
562
|
-
mounts = [
|
|
563
|
-
adx_environment.Mount(
|
|
564
|
-
target=mount.target,
|
|
565
|
-
image_url=mount.image_url,
|
|
566
|
-
s3_config=(
|
|
567
|
-
adx_environment.S3Config(
|
|
568
|
-
endpoint=mount.s3_config.endpoint,
|
|
569
|
-
bucket=mount.s3_config.bucket,
|
|
570
|
-
object=mount.s3_config.object,
|
|
571
|
-
access_key=mount.s3_config.access_key,
|
|
572
|
-
secret_key=mount.s3_config.secret_key,
|
|
573
|
-
)
|
|
574
|
-
if mount.s3_config is not None
|
|
575
|
-
else None
|
|
576
|
-
),
|
|
577
|
-
type=mount.type,
|
|
578
|
-
)
|
|
579
|
-
for mount in spec.mounts
|
|
580
|
-
]
|
|
618
|
+
mounts = [_native_mount(mount) for mount in spec.mounts]
|
|
581
619
|
create_timeout = spec.schedule_timeout + 60
|
|
582
620
|
create_args = dict(
|
|
583
621
|
image=spec.image,
|
|
@@ -199,7 +199,9 @@ class Sandbox:
|
|
|
199
199
|
which uses the image's OCI WORKDIR when
|
|
200
200
|
``inherit_entrypoint=True``.
|
|
201
201
|
port_forwardings: Sandbox TCP ports exposed through the gateway.
|
|
202
|
-
mounts: Additional read-only OCI or
|
|
202
|
+
mounts: Additional read-only OCI/S3 mounts or explicit node HostPath
|
|
203
|
+
bind mounts for trusted management callers. HostPath writes
|
|
204
|
+
require ``Mount(..., read_only=False)``.
|
|
203
205
|
reverse_tunnel: SDK-side HTTP service exposed inside the sandbox.
|
|
204
206
|
detached: Keep the sandbox alive when this client closes.
|
|
205
207
|
node_id: Require placement on a specific AKernel node.
|
|
@@ -507,31 +507,59 @@ class S3Config:
|
|
|
507
507
|
|
|
508
508
|
@dataclass(frozen=True)
|
|
509
509
|
class Mount:
|
|
510
|
-
"""
|
|
510
|
+
"""OCI/S3 read-only mount or a trusted-management node HostPath bind.
|
|
511
511
|
|
|
512
|
-
|
|
513
|
-
|
|
512
|
+
Supply exactly one of ``image_url``, ``s3_config``, or ``host_path``.
|
|
513
|
+
HostPath sources must already be visible to the node runtime; they are not
|
|
514
|
+
resolved on the client. HostPath supports ``type="bind"`` and defaults to
|
|
515
|
+
read-only; writes require ``read_only=False``. Image/S3 sources are always
|
|
516
|
+
read-only. This type does not authorize access to the node's filesystem.
|
|
514
517
|
"""
|
|
515
518
|
|
|
516
519
|
target: str
|
|
517
520
|
image_url: str | None = None
|
|
518
521
|
s3_config: S3Config | None = None
|
|
519
522
|
type: str = "bind"
|
|
523
|
+
host_path: str | None = None
|
|
524
|
+
read_only: bool = True
|
|
520
525
|
|
|
521
526
|
def __post_init__(self) -> None:
|
|
522
527
|
if not isinstance(self.target, str) or not self.target.startswith("/"):
|
|
523
528
|
raise ValueError("target must be an absolute sandbox path")
|
|
524
529
|
source_count = sum(
|
|
525
|
-
source is not None
|
|
530
|
+
source is not None
|
|
531
|
+
for source in (self.image_url, self.s3_config, self.host_path)
|
|
526
532
|
)
|
|
527
533
|
if source_count != 1:
|
|
528
|
-
raise ValueError(
|
|
534
|
+
raise ValueError(
|
|
535
|
+
"exactly one of image_url, s3_config, host_path must be specified"
|
|
536
|
+
)
|
|
529
537
|
if self.image_url is not None and (
|
|
530
538
|
not isinstance(self.image_url, str) or not self.image_url.strip()
|
|
531
539
|
):
|
|
532
540
|
raise ValueError("image_url must be a non-empty string")
|
|
533
541
|
if self.type not in ("bind", "erofs"):
|
|
534
542
|
raise ValueError("type must be 'bind' or 'erofs'")
|
|
543
|
+
if not isinstance(self.read_only, bool):
|
|
544
|
+
raise TypeError("read_only must be a boolean")
|
|
545
|
+
if self.host_path is not None:
|
|
546
|
+
if (
|
|
547
|
+
not isinstance(self.host_path, str)
|
|
548
|
+
or not self.host_path.startswith("/")
|
|
549
|
+
or any(part in (".", "..") for part in self.host_path.split("/"))
|
|
550
|
+
or any(
|
|
551
|
+
ord(char) < 32 or 127 <= ord(char) <= 159
|
|
552
|
+
for char in self.host_path
|
|
553
|
+
)
|
|
554
|
+
):
|
|
555
|
+
raise ValueError(
|
|
556
|
+
"host_path must be an absolute path without traversal "
|
|
557
|
+
"or control characters"
|
|
558
|
+
)
|
|
559
|
+
if self.type != "bind":
|
|
560
|
+
raise ValueError("host_path supports only type='bind'")
|
|
561
|
+
elif not self.read_only:
|
|
562
|
+
raise ValueError("image and S3 mounts must be read-only")
|
|
535
563
|
|
|
536
564
|
def to_dict(self) -> dict[str, Any]:
|
|
537
565
|
"""Return the JSON-compatible representation expected by AKernel."""
|
|
@@ -539,12 +567,15 @@ class Mount:
|
|
|
539
567
|
value: dict[str, Any] = {
|
|
540
568
|
"type": self.type,
|
|
541
569
|
"target": self.target,
|
|
542
|
-
"options": ["ro"],
|
|
570
|
+
"options": ["ro" if self.read_only else "rw"],
|
|
543
571
|
}
|
|
544
572
|
if self.image_url is not None:
|
|
545
573
|
value["image_url"] = self.image_url
|
|
546
574
|
if self.s3_config is not None:
|
|
547
575
|
value["s3_config"] = self.s3_config.to_dict()
|
|
576
|
+
if self.host_path is not None:
|
|
577
|
+
value["host_path"] = self.host_path
|
|
578
|
+
value["create_if_missing"] = False
|
|
548
579
|
return value
|
|
549
580
|
|
|
550
581
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: akernel-sdk
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.0rc3
|
|
4
4
|
Summary: Python SDK and CLI for AKernel remote sandboxes
|
|
5
5
|
Author: AKernel Authors
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -737,6 +737,55 @@ mount = Mount(target="/opt/tools", image_url="ubuntu:24.04")
|
|
|
737
737
|
Firecracker mounts must instead use `type="erofs"` with an S3 object containing
|
|
738
738
|
a raw EROFS image; it rejects `image_url` and directory-backed mounts.
|
|
739
739
|
|
|
740
|
+
### Node HostPath bind mounts
|
|
741
|
+
|
|
742
|
+
Trusted management clients can bind an existing node-visible path into a
|
|
743
|
+
sandbox. For example, expose a prepared log directory on a selected runsc node:
|
|
744
|
+
|
|
745
|
+
```python
|
|
746
|
+
from akernel_sdk import Mount, Sandbox
|
|
747
|
+
|
|
748
|
+
logs = Mount(
|
|
749
|
+
target="/apps/logs", # Path inside the sandbox.
|
|
750
|
+
host_path="/apps/logs", # Path visible to sandboxd on the selected node.
|
|
751
|
+
read_only=False, # Explicitly allow application log writes.
|
|
752
|
+
)
|
|
753
|
+
with Sandbox(node_id="<prepared-node-id>", mounts=[logs]) as sandbox:
|
|
754
|
+
print(sandbox.commands.run("ls -ld /apps/logs").stdout)
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
`read_only=True` is the default. HostPath supports `type="bind"` only;
|
|
758
|
+
`read_only=False` is rejected for Image/S3 mounts, which remain read-only.
|
|
759
|
+
Exactly one of `image_url`, `s3_config`, or `host_path` is required. The source
|
|
760
|
+
must be an absolute POSIX path without traversal components or control
|
|
761
|
+
characters. The SDK does not inspect the client machine's filesystem or create
|
|
762
|
+
the source directory; it sends `create_if_missing=false`. An absent source or
|
|
763
|
+
insufficient filesystem permissions is a node-side error.
|
|
764
|
+
|
|
765
|
+
In Kubernetes, the node Pod must first see the source, for example through an
|
|
766
|
+
operator-managed `hostPath` volume and matching `volumeMount`. An ECS directory
|
|
767
|
+
does not become visible to sandboxd merely because its path is in the SDK
|
|
768
|
+
request. Directory ownership and permissions must allow the sandbox's process
|
|
769
|
+
UID/GID to use it. Separate workers' local directories are separate data;
|
|
770
|
+
`node_id` selects the prepared node but does not replicate storage. Data written
|
|
771
|
+
through a bind can outlive the sandbox. Runtime-specific mount restrictions
|
|
772
|
+
still apply; Firecracker does not support these directory-backed binds.
|
|
773
|
+
|
|
774
|
+
Restrict HostPath creation to trusted management clients and source paths
|
|
775
|
+
controlled by the operator. These mounts do not provide per-tenant source-path
|
|
776
|
+
isolation; SDK path validation and read-only defaults do not authorize access
|
|
777
|
+
to the node's filesystem. Server permission errors are returned through the
|
|
778
|
+
normal `BackendOperationError` fields.
|
|
779
|
+
|
|
780
|
+
The maintained example requires an explicit node and source. It lists the
|
|
781
|
+
read-only mount by default; `--write` creates one uniquely named log file and
|
|
782
|
+
leaves that file on the node:
|
|
783
|
+
|
|
784
|
+
```bash
|
|
785
|
+
python sdk/python/examples/hostpath_mounts.py \
|
|
786
|
+
--node-id <prepared-node-id> --host-path /apps/logs --write
|
|
787
|
+
```
|
|
788
|
+
|
|
740
789
|
## Launch from a Dockerfile
|
|
741
790
|
|
|
742
791
|
Dockerfile direct launch is a supported AKernel SDK capability and will remain
|
|
@@ -852,6 +901,7 @@ Maintained examples are under [`examples/`](./examples):
|
|
|
852
901
|
- `dockerfile_launch.py`
|
|
853
902
|
- `failover_reload.py`
|
|
854
903
|
- `gpu_sandbox.py`
|
|
904
|
+
- `hostpath_mounts.py`
|
|
855
905
|
- `named_sandbox.py`
|
|
856
906
|
- `network_policy.py`
|
|
857
907
|
- `pty.py`
|
|
@@ -896,7 +946,7 @@ not part of the default test suite.
|
|
|
896
946
|
| `SandboxInfo` | `id`, `state`, `cpu`, `memory`, `image`, `xpu`, `storage_mb` |
|
|
897
947
|
| `NodeInfo` | `id`, `status`, `capacity`, `allocatable`, `labels` |
|
|
898
948
|
| `S3Config` | `endpoint`, `bucket`, `object`, optional credentials |
|
|
899
|
-
| `Mount` | `target`, one
|
|
949
|
+
| `Mount` | `target`, exactly one of `image_url` / `s3_config` / `host_path`, `type`, `read_only` (default `True`; writable only for HostPath) |
|
|
900
950
|
| `HttpReverseTunnel` | `target`, `reverse_port`, `listen_port`, `connect_timeout` |
|
|
901
951
|
| `PortRange` | `first`, `last` |
|
|
902
952
|
| `NetworkRule` | action, direction, protocol, peer and sandbox port selectors, priority |
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|