Skip to content

Commit a2cc5e4

Browse files
authored
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. Fixes agent-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]>
1 parent 4488a66 commit a2cc5e4

5 files changed

Lines changed: 56 additions & 44 deletions

File tree

‎cmd/ate-setup/internal/demos/jupyter/jupyter.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
// limitations under the License.
1414

1515
// Package jupyter installs the Jupyter demo, which runs an unmodified
16-
// jupyter/base-notebook image as an actor that suspends when idle and resumes
17-
// when the notebook is next opened.
16+
// quay.io/jupyter/base-notebook image as an actor that checkpoints on suspend
17+
// and resumes when the notebook is next opened.
1818
package jupyter
1919

2020
import (

‎demos/jupyter/README.md‎

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,18 @@ weight: 3
55
estimated_time: "10 mins"
66
card_icon: "fa-solid fa-book-open"
77
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.
99
---
1010

1111
# Jupyter Notebook Demo
1212

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

1515
## Prerequisites
1616

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

2121
## Deploy the Jupyter Notebook Demo
2222

@@ -37,14 +37,14 @@ go install ./cmd/kubectl-ate
3737
```
3838

3939
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+
template in the actor's atespace):
4242

4343
```bash
4444
kubectl ate create actor jupyter-notebook -a ate-demo-jupyter --template jupyter
4545
```
4646

47-
### 2. Access Jupyter via the Proxy!
47+
### 2. Access Jupyter via the Proxy
4848

4949
1. **Start the local actor proxy:**
5050

@@ -53,43 +53,46 @@ kubectl ate create actor jupyter-notebook -a ate-demo-jupyter --template jupyter
5353
kubectl ate proxy actor jupyter-notebook 8888:80 -a ate-demo-jupyter
5454
```
5555

56-
2. **Open your browser!**
56+
2. **Verify from the command line or open your browser:**
5757

58-
Now, open your web browser and visit:
59-
`http://localhost:8888`
58+
Query the Jupyter Server `/api` endpoint to wake the actor and confirm it is serving (`HEAD /lab` via `curl -I` returns `405 Method Not Allowed`):
59+
```bash
60+
curl -s http://localhost:8888/api
61+
```
62+
63+
Or open your web browser and visit `http://localhost:8888/lab`.
6064

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=''`.
6266
Create a new notebook and try running:
6367
```python
6468
print("hello world")
6569
```
6670

67-
### 4. Suspending and Resuming the Notebook
71+
### 3. Suspending and Resuming the Notebook
6872

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:
7074

7175
```bash
7276
kubectl ate suspend actor jupyter-notebook -a ate-demo-jupyter
7377
```
7478

75-
Check the actor status to confirm it's suspended:
79+
Check the actor status to confirm it is suspended:
7680
```bash
7781
kubectl ate get actor jupyter-notebook -a ate-demo-jupyter
7882
```
79-
Notice how it shows `STATUS_SUSPENDED`.
83+
The `STATE` column shows `ACTOR_STATE_SUSPENDED`.
8084

8185
To **resume** the notebook, you can either explicitly resume it via CLI:
8286

8387
```bash
8488
kubectl ate resume actor jupyter-notebook -a ate-demo-jupyter
8589
```
8690

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+
Or refresh `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.
8892

89-
### Clean up
93+
## Clean up
9094

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:
9396
```bash
9497
go run ./cmd/ate-setup delete demo jupyter
9598
```

‎demos/multi-template/README.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ or namespace.
1919

2020
## Prerequisites
2121

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

2626
## How to Run on Agent Substrate
2727

@@ -44,8 +44,7 @@ This command will:
4444

4545
### 2. Create one actor per template
4646

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):
4948

5049
```bash
5150
# Install the CLI as a kubectl plugin if not already installed
@@ -62,7 +61,9 @@ Start a local proxy for each actor:
6261

6362
```bash
6463
kubectl ate proxy actor c1 8000:80 -a ate-demo-multi-template-counter &
64+
PROXY_C1=$!
6565
kubectl ate proxy actor f1 8001:80 -a ate-demo-multi-template-fspersist &
66+
PROXY_F1=$!
6667
```
6768

6869
## How to Use
@@ -72,7 +73,7 @@ When you send an HTTP request through the proxy, `atenet-router` automatically a
7273
```bash
7374
# counter binary
7475
curl -s http://localhost:8000
75-
# -> preserved memory count: 1
76+
# -> preserved memory count: 1 | preserved file counter: 1 | preserved rootfs counter: 1
7677

7778
# fspersist binary
7879
curl -s http://localhost:8001
@@ -87,9 +88,7 @@ Confirm both actors landed on workers in the one `shared-pool`:
8788
kubectl ate get workers
8889
```
8990

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:
9392

9493
```bash
9594
kubectl ate suspend actor f1 -a ate-demo-multi-template-fspersist
@@ -98,9 +97,9 @@ curl -s http://localhost:8001 # history persists; count keeps climbing
9897

9998
## How to Uninstall
10099

101-
Remove the demo — this deletes the actors (suspending running ones first), the
102-
templates, both atespaces, and then the pool and its namespace:
100+
Stop the background proxy processes and remove the demo. This deletes the actors, the templates, both atespaces, and then the pool and its namespace:
103101

104102
```bash
103+
kill "$PROXY_C1" "$PROXY_F1"
105104
go run ./cmd/ate-setup delete demo multi-template
106105
```

‎demos/multi-template/counter-template.yaml.tmpl‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ workerSelector:
2727
containers:
2828
- name: counter
2929
image: ko://go.ate.dev/substrate/demos/counter
30+
volumeMounts:
31+
- name: data
32+
mountPath: /home/counter
3033
# Sandbox size. The pool sets no worker limits, so the worker offers the
3134
# node's allocatable and these only need to fit the node.
3235
resources:
@@ -35,3 +38,6 @@ resources:
3538
memoryBytes: 536870912 # 512Mi
3639
snapshotConfig:
3740
preferredFidelity: SNAPSHOT_FIDELITY_MEMORY
41+
volumes:
42+
- name: data
43+
durableDir: {}

‎demos/sandbox/README.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,22 @@ description: >
1212

1313
This directory contains a demo of a stateful sandbox execution environment running on Agent Substrate.
1414

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

1717
> [!WARNING]
1818
> **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.
1919
2020
## Components
2121

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.
2323
2. **Sandbox Client (`client/`)**: A CLI REPL tool that allows you to interact with the sandbox actor interactively.
2424

2525
## Prerequisites
2626

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.
30+
- `kubectl-ate` CLI installed (`go install ./cmd/kubectl-ate`).
3131

3232
## How to Run on Agent Substrate
3333

@@ -54,12 +54,9 @@ kubectl ate get actor-template sandbox-template -a ate-demo-sandbox
5454

5555
### 2. Create a Sandbox Actor
5656

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:
5858

5959
```bash
60-
# Install the CLI as a kubectl plugin if not already installed
61-
go install ./cmd/kubectl-ate
62-
6360
kubectl ate create actor my-sandbox-1 -a ate-demo-sandbox --template sandbox-template
6461
```
6562

@@ -83,7 +80,7 @@ go build -o bin/sandbox-client ./demos/sandbox/client
8380

8481
Once in the `sandbox>` prompt, you can run commands:
8582

86-
```bash
83+
```text
8784
sandbox> ls -la
8885
sandbox> pwd
8986
sandbox> echo "Hello" > test.txt
@@ -92,6 +89,13 @@ sandbox> cat test.txt
9289

9390
Type `exit` to leave. This will automatically trigger the suspension of the actor.
9491

92+
To resume the actor non-interactively and verify `test.txt` persisted across the snapshot, pipe commands into `sandbox-client`:
93+
94+
```bash
95+
printf 'cat test.txt\nexit\n' | \
96+
./bin/sandbox-client --atenet=localhost:8000 --atespace=ate-demo-sandbox --name=my-sandbox-1
97+
```
98+
9599
To permanently delete the suspended actor:
96100
```bash
97101
kubectl ate delete actor my-sandbox-1 -a ate-demo-sandbox

0 commit comments

Comments
 (0)