You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a2cc5e4
Browse filesBrowse the repository at this point in the historyBrowse files
demos/{sandbox,jupyter,multi-template}: fix tutorial prerequisites, walkthroughs, and counter volume (agent-substrate#3500)
The `sandbox`, `jupyter`, and `multi-template` tutorials linked to
retired root `README.md` anchors, omitted required ingress and `ko`
settings, and had walkthrough steps out of sync with current CLI and
runtime behavior. `demos/multi-template/counter-template.yaml.tmpl` also
omitted the `/home/counter` volume mount, so `counter` printed
`preserved file counter: -1`.
- Mount a `durableDir` volume at `/home/counter` in
`demos/multi-template/counter-template.yaml.tmpl` and update the
expected `curl` output for all three counters.
- List the `atenet-router` `--ingress-allowed-spiffe-ids`,
`SNAPSHOT_LOCATION`, and `KO_DOCKER_REPO` (`ko.dockerRepo`)
prerequisites in all three tutorials (including the
`ATE_INSTALL_KIND=true` defaults on `kind`), and point their install
links to `docs/get-started/quickstart.md` and
`docs/guides/operator-install.md`.
- Clarify per-request subprocess execution in `demos/sandbox/README.md`
(`sandbox-client` sends `sh -c` to `/process`), add a non-interactive
piped `sandbox-client` command, and remove the duplicate `go install
./cmd/kubectl-ate` step.
- Update `demos/jupyter/README.md` and
`cmd/ate-setup/internal/demos/jupyter/jupyter.go` to remove
unimplemented idle-suspend claims, use `quay.io/jupyter/base-notebook`
and `ACTOR_STATE_SUSPENDED`, add a `curl -s http://localhost:8888/api`
check, fix step numbering, and document full teardown.
- Drop the retired actor DNS routing claim and inaccurate delete-suspend
note in `demos/multi-template/README.md`, and stop the background
`kubectl ate proxy actor` processes during cleanup.
Fixesagent-substrate#3494
AI use: AI-assisted, I reviewed and verified the changes on `kind` and
Kubernetes clusters and built the docsite locally.
- [x] Tests pass (`./hack/verify/gofmt.sh`,
`./hack/verify/boilerplate.sh`, `go test -race ./cmd/ate-setup/...`,
`./hack/site.sh build`, and live walkthrough verification)
- [x] Docs updated
---------
Signed-off-by: Mofi Rahman <[email protected]>
Copy file name to clipboardExpand all lines: demos/jupyter/README.md
+23-20Lines changed: 23 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,18 +5,18 @@ weight: 3
5
5
estimated_time: "10 mins"
6
6
card_icon: "fa-solid fa-book-open"
7
7
description: >
8
-
Run an unmodified Jupyter Notebook container that suspends when idle and resumes on browser access.
8
+
Run an unmodified Jupyter Notebook container that checkpoints on suspend and resumes on browser access.
9
9
---
10
10
11
11
# Jupyter Notebook Demo
12
12
13
-
This demo runs a Jupyter Notebook on Agent Substrate. It demonstrates how standard unmodified container images (like `jupyter/base-notebook`) can be deployed as Substrate actors that transparently suspend when idle and resume when you access them via your browser.
13
+
This demo runs a Jupyter Notebook on Agent Substrate. It shows how an unmodified container image (`quay.io/jupyter/base-notebook`) runs as a Substrate actor that checkpoints on suspend and resumes when accessed through your browser.
14
14
15
15
## Prerequisites
16
16
17
-
- A k8s cluster with Agent Substrate installed as in the [Quickstart](../../README.md#quickstart-development)
18
-
(with `ATE_INSTALL_KIND=true` exported in your shell) or [GKE Quickstart](../../README.md#gke-quickstart-development).
19
-
- A snapshot location set at install (`SNAPSHOT_LOCATION`). The demo stores its snapshots there.
17
+
- A Kubernetes cluster with Agent Substrate installed as in the [Quickstart](../../docs/get-started/quickstart.md) or [Operator Install Guide](../../docs/guides/operator-install.md).
18
+
-`atenet-router` configured with `--ingress-allowed-spiffe-ids=spiffe://cluster.local/ns/ate-system/sa/atenet-client` (`ATE_INGRESS_ALLOWED_SPIFFE_IDS`); see [Ingress to actors](../../docs/guides/operator-install.md#ingress-to-actors).
19
+
- A snapshot location (`SNAPSHOT_LOCATION`, see [Snapshot storage](../../docs/guides/operator-install.md#snapshot-storage)) and image repository (`KO_DOCKER_REPO`, or `ko.dockerRepo` in `--config`) for `ate-setup deploy demo`. On [kind](https://kind.sigs.k8s.io/), `export ATE_INSTALL_KIND=true` configures local defaults (`gs://ate-snapshots/` and `localhost:5001`) automatically.
20
20
21
21
## Deploy the Jupyter Notebook Demo
22
22
@@ -37,14 +37,14 @@ go install ./cmd/kubectl-ate
37
37
```
38
38
39
39
The deploy created the `jupyter` actor template in the `ate-demo-jupyter`
40
-
atespace. Create your `jupyter` actor there — `--template` names the
41
-
template, resolved in the actor's atespace:
40
+
atespace. Create your `jupyter-notebook` actor there (`--template` names the
41
+
templatein the actor's atespace):
42
42
43
43
```bash
44
44
kubectl ate create actor jupyter-notebook -a ate-demo-jupyter --template jupyter
45
45
```
46
46
47
-
### 2. Access Jupyter via the Proxy!
47
+
### 2. Access Jupyter via the Proxy
48
48
49
49
1.**Start the local actor proxy:**
50
50
@@ -53,43 +53,46 @@ kubectl ate create actor jupyter-notebook -a ate-demo-jupyter --template jupyter
53
53
kubectl ate proxy actor jupyter-notebook 8888:80 -a ate-demo-jupyter
54
54
```
55
55
56
-
2.**Open your browser!**
56
+
2.**Verify from the command line or open your browser:**
Or open your web browser and visit `http://localhost:8888/lab`.
60
64
61
-
You should see the Jupyter Notebook interface without any password (because we passed `--ServerApp.password=''`in our template config)!
65
+
The JupyterLab interface opens without a password because the template passes `--ServerApp.token=''`and `--ServerApp.password=''`.
62
66
Create a new notebook and try running:
63
67
```python
64
68
print("hello world")
65
69
```
66
70
67
-
### 4. Suspending and Resuming the Notebook
71
+
### 3. Suspending and Resuming the Notebook
68
72
69
-
When you're not using the notebook, instead of leaving the container running, Substrate can checkpoint and suspend it to disk.
73
+
When you are finished using the notebook, checkpoint and suspend the actor:
70
74
71
75
```bash
72
76
kubectl ate suspend actor jupyter-notebook -a ate-demo-jupyter
73
77
```
74
78
75
-
Check the actor status to confirm it's suspended:
79
+
Check the actor status to confirm it is suspended:
76
80
```bash
77
81
kubectl ate get actor jupyter-notebook -a ate-demo-jupyter
78
82
```
79
-
Notice how it shows `STATUS_SUSPENDED`.
83
+
The `STATE` column shows `ACTOR_STATE_SUSPENDED`.
80
84
81
85
To **resume** the notebook, you can either explicitly resume it via CLI:
82
86
83
87
```bash
84
88
kubectl ate resume actor jupyter-notebook -a ate-demo-jupyter
85
89
```
86
90
87
-
Or, even easier, you can rely on "transparent resume" — just refresh the page in your browser or make another request to the URL while it's suspended. Substrate will automatically restore its state and serve your request without any downtime.
91
+
Orrefresh `http://localhost:8888/lab`in your browser (or run `curl -s http://localhost:8888/api`) while the actor is suspended. `atenet-router`automatically resumes the actor from its snapshot and serves the request.
88
92
89
-
###Clean up
93
+
## Clean up
90
94
91
-
Uninstall the demo deployment — this deletes the demo's actors, the actor
92
-
template, and the `ate-demo-jupyter` atespace:
95
+
Stop the `kubectl ate proxy actor` process in your proxy terminal, then uninstall the demo deployment. This deletes the demo's actors, the `jupyter` actor template, the `ate-demo-jupyter` atespace, the `jupyter``WorkerPool`, and the `ate-demo-jupyter` namespace:
Copy file name to clipboardExpand all lines: demos/multi-template/README.md
+10-11Lines changed: 10 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,9 +19,9 @@ or namespace.
19
19
20
20
## Prerequisites
21
21
22
-
- A k8s cluster with Agent Substrate installed as in the [Quickstart](../../README.md#quickstart-development)
23
-
(with `ATE_INSTALL_KIND=true` exported in your shell) or [GKE Quickstart](../../README.md#gke-quickstart-development).
24
-
- A snapshot location set at install (`SNAPSHOT_LOCATION`). The demo stores its snapshots there.
22
+
- A Kubernetes cluster with Agent Substrate installed as in the [Quickstart](../../docs/get-started/quickstart.md) or [Operator Install Guide](../../docs/guides/operator-install.md).
23
+
-`atenet-router` configured with `--ingress-allowed-spiffe-ids=spiffe://cluster.local/ns/ate-system/sa/atenet-client` (`ATE_INGRESS_ALLOWED_SPIFFE_IDS`); see [Ingress to actors](../../docs/guides/operator-install.md#ingress-to-actors).
24
+
- A snapshot location (`SNAPSHOT_LOCATION`, see [Snapshot storage](../../docs/guides/operator-install.md#snapshot-storage)) and image repository (`KO_DOCKER_REPO`, or `ko.dockerRepo` in `--config`) for `ate-setup deploy demo`. On [kind](https://kind.sigs.k8s.io/), `export ATE_INSTALL_KIND=true` configures local defaults (`gs://ate-snapshots/` and `localhost:5001`) automatically.
25
25
26
26
## How to Run on Agent Substrate
27
27
@@ -44,8 +44,7 @@ This command will:
44
44
45
45
### 2. Create one actor per template
46
46
47
-
Each actor goes in its template's atespace — `--template` names the template,
48
-
resolved in the actor's atespace — and their DNS names embed that atespace:
47
+
Each actor goes in its template's atespace (`--template` names the template, resolved in the actor's atespace):
49
48
50
49
```bash
51
50
# Install the CLI as a kubectl plugin if not already installed
@@ -62,7 +61,9 @@ Start a local proxy for each actor:
62
61
63
62
```bash
64
63
kubectl ate proxy actor c1 8000:80 -a ate-demo-multi-template-counter &
64
+
PROXY_C1=$!
65
65
kubectl ate proxy actor f1 8001:80 -a ate-demo-multi-template-fspersist &
66
+
PROXY_F1=$!
66
67
```
67
68
68
69
## How to Use
@@ -72,7 +73,7 @@ When you send an HTTP request through the proxy, `atenet-router` automatically a
@@ -87,9 +88,7 @@ Confirm both actors landed on workers in the one `shared-pool`:
87
88
kubectl ate get workers
88
89
```
89
90
90
-
The `counter` increments its in-memory count on each request, while `fspersist` prepends
91
-
a line to its history file on each request. Suspending and re-requesting an actor
92
-
preserves that state across the snapshot/restore cycle:
91
+
The `counter` actor increments its in-memory, durable-volume (`/home/counter/a.txt`), and rootfs (`/rootfs-counter.txt`) counters on each request, while `fspersist` prepends a line to its history file on each request. Suspending and re-requesting an actor preserves that state across the snapshot/restore cycle:
93
92
94
93
```bash
95
94
kubectl ate suspend actor f1 -a ate-demo-multi-template-fspersist
Copy file name to clipboardExpand all lines: demos/sandbox/README.md
+15-11Lines changed: 15 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,22 +12,22 @@ description: >
12
12
13
13
This directory contains a demo of a stateful sandbox execution environment running on Agent Substrate.
14
14
15
-
It allows you to run arbitrary commands in an sandboxed, isolated container (running Alpine Linux) and preserves the execution state across suspends and resumes.
15
+
It runs commands in a sandboxed, isolated container (Alpine Linux) and preserves container filesystem and memory state across suspends and resumes. `sandbox-client` sends each command as `sh -c` to `/process`, which spawns a fresh subprocess per request, so working-directory changes (`cd`) and shell variables reset between commands while files written inside the container persist across requests and snapshots.
16
16
17
17
> [!WARNING]
18
18
> **Security Disclaimer:** This demo is not secured by any authorization checks, and the sandbox actor will execute any client-provided commands with no validation. Do not deploy this configuration in production or expose it to untrusted networks.
19
19
20
20
## Components
21
21
22
-
1.**Sandbox Server (`main.go`)**: The application that runs inside the Agent Substrate actor. It exposes a simple, stateless `/process` endpoint to execute commands.
22
+
1.**Sandbox Server (`main.go`)**: The application that runs inside the Agent Substrate actor. It exposes a `/process` endpoint that runs each command in a fresh subprocess, while files in the container persist across requests.
23
23
2.**Sandbox Client (`client/`)**: A CLI REPL tool that allows you to interact with the sandbox actor interactively.
24
24
25
25
## Prerequisites
26
26
27
-
- A k8s cluster with Agent Substrate installed as in the [Quickstart](../../README.md#quickstart-development)
28
-
(with `ATE_INSTALL_KIND=true` exported in your shell) or [GKE Quickstart](../../README.md#gke-quickstart-development).
29
-
- A snapshot location set at install (`SNAPSHOT_LOCATION`). The demo stores its snapshots there.
30
-
-`kubectl-ate` CLI installed (can be installed via `go install ./cmd/kubectl-ate`).
27
+
- A Kubernetes cluster with Agent Substrate installed as in the [Quickstart](../../docs/get-started/quickstart.md) or [Operator Install Guide](../../docs/guides/operator-install.md).
28
+
-`atenet-router` configured with `--ingress-allowed-spiffe-ids=spiffe://cluster.local/ns/ate-system/sa/atenet-client` (`ATE_INGRESS_ALLOWED_SPIFFE_IDS`); see [Ingress to actors](../../docs/guides/operator-install.md#ingress-to-actors).
29
+
- A snapshot location (`SNAPSHOT_LOCATION`, see [Snapshot storage](../../docs/guides/operator-install.md#snapshot-storage)) and image repository (`KO_DOCKER_REPO`, or `ko.dockerRepo` in `--config`) for `ate-setup deploy demo`. On [kind](https://kind.sigs.k8s.io/), `export ATE_INSTALL_KIND=true` configures local defaults (`gs://ate-snapshots/` and `localhost:5001`) automatically.
@@ -54,12 +54,9 @@ kubectl ate get actor-template sandbox-template -a ate-demo-sandbox
54
54
55
55
### 2. Create a Sandbox Actor
56
56
57
-
Create the sandbox actor in the demo's atespace with a chosen name (e.g., `my-sandbox-1`) — `--template` names the template, resolved in the actor's atespace:
57
+
Create the sandbox actor in the demo's atespace with a chosen name (e.g., `my-sandbox-1`). `--template` names the template in the actor's atespace:
58
58
59
59
```bash
60
-
# Install the CLI as a kubectl plugin if not already installed
61
-
go install ./cmd/kubectl-ate
62
-
63
60
kubectl ate create actor my-sandbox-1 -a ate-demo-sandbox --template sandbox-template
64
61
```
65
62
@@ -83,7 +80,7 @@ go build -o bin/sandbox-client ./demos/sandbox/client
83
80
84
81
Once in the `sandbox>` prompt, you can run commands:
85
82
86
-
```bash
83
+
```text
87
84
sandbox> ls -la
88
85
sandbox> pwd
89
86
sandbox> echo "Hello" > test.txt
@@ -92,6 +89,13 @@ sandbox> cat test.txt
92
89
93
90
Type `exit` to leave. This will automatically trigger the suspension of the actor.
94
91
92
+
To resume the actor non-interactively and verify `test.txt` persisted across the snapshot, pipe commands into `sandbox-client`:
0 commit comments