Skip to content

Commit 5346f19

Browse files
authored
doc(trainer): add architecture diagrams to local execution guides (#4301)
* doc(trainer): add architecture diagrams to local execution guides Signed-off-by: sh4shv4t <shashvat.k.singh.16@gmail.com> * docs(trainer): fix architecture diagrams and documentation accuracy - docker.md: show logs streaming from all nodes, clarify conditional cleanup - podman.md: correct architecture text (Docker→Podman), align diagram with implementation, remove incorrect workflow details - local_process.md: update diagram to reflect bash script generation and single subprocess execution These changes address reviewer feedback and align documentation with actual SDK implementation. Signed-off-by: sh4shv4t <shashvat.k.singh.16@gmail.com> --------- Signed-off-by: sh4shv4t <shashvat.k.singh.16@gmail.com>
1 parent b97081e commit 5346f19

3 files changed

Lines changed: 71 additions & 0 deletions

File tree

content/en/docs/components/trainer/user-guides/local-execution-mode/docker.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,30 @@ The Container Backend with Docker enables you to run distributed TrainJobs in is
1515

1616
The Docker backend uses the adapter pattern to provide a unified interface, making it easy to switch between Docker and Podman without code changes.
1717

18+
## Architecture
19+
20+
The Container Backend with Docker uses a local orchestration layer to manage TrainJobs within Docker containers. This ensures environment parity between your local machine and production Kubernetes clusters.
21+
22+
```mermaid
23+
graph LR
24+
User([User Script]) -->|TrainerClient.train| SDK[Kubeflow SDK]
25+
26+
SDK -->|1. Pull| Image[Docker Image]
27+
SDK -->|2. Net| Net[Bridge Network]
28+
SDK -->|3. Run| Daemon[Docker Daemon]
29+
30+
subgraph DockerEnv [Local Docker Environment]
31+
direction TB
32+
Daemon -->|Spawn| C1[Node 0]
33+
Daemon -->|Spawn| C2[Node 1]
34+
C1 <-->|DDP| C2
35+
end
36+
37+
C1 -->|4. Logs| Logs[Stream Logs]
38+
C2 -->|4. Logs| Logs
39+
SDK -.->|"5. Cleanup (if auto_remove)"| Remove[Delete Containers & Network]
40+
```
41+
1842
## Prerequisites
1943

2044
### Required Software

content/en/docs/components/trainer/user-guides/local-execution-mode/local_process.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,27 @@ finally:
217217
client.delete_job(job_name)
218218
```
219219

220+
## Architecture
221+
222+
The Local Process Backend operates by orchestrating native OS processes. It bypasses container runtimes like Docker, instead managing the lifecycle of your training script through isolated Python Virtual Environments (venvs).
223+
224+
```mermaid
225+
graph LR
226+
User([User Script]) -->|TrainerClient.train| SDK[Kubeflow SDK]
227+
228+
SDK -->|1. Generate| Script[Bash Script]
229+
230+
subgraph LocalExec ["Single Subprocess (bash -c)"]
231+
direction TB
232+
Script -->|2. Execute| Venv[Create Venv + pip]
233+
Venv --> Deps[Install Dependencies]
234+
Deps --> Train[Run Entrypoint]
235+
Train -.-> Clean["Delete Venv (if cleanup_venv)"]
236+
end
237+
238+
Train -->|3. Logs| Logs[Stream Logs]
239+
```
240+
220241
## How It Works
221242

222243
Understanding the internal workflow helps with debugging and optimization:

content/en/docs/components/trainer/user-guides/local-execution-mode/podman.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,32 @@ backend_config = ContainerBackendConfig(
168168
)
169169
```
170170

171+
## Architecture
172+
173+
The Container Backend with Podman uses a local orchestration layer to manage TrainJobs within Podman containers. This ensures environment parity between your local machine and production Kubernetes clusters.
174+
175+
```mermaid
176+
graph LR
177+
User([User Script]) -->|TrainerClient.train| SDK[Kubeflow SDK]
178+
179+
SDK -->|1. Pull| Image[Podman Image]
180+
SDK -->|2. Net| Net[DNS-Enabled Bridge Network]
181+
SDK -->|3. Run| Podman[Podman Engine]
182+
183+
subgraph PodmanEnv [Local Podman Environment]
184+
direction TB
185+
Podman -->|Spawn| C1[Node 0]
186+
Podman -->|Spawn| C2[Node 1]
187+
C1 <-->|DDP| C2
188+
end
189+
190+
C1 -->|4. Logs| Logs[Stream Logs]
191+
C2 -->|4. Logs| Logs
192+
SDK -.->|"5. Cleanup (if auto_remove)"| Remove[Delete Containers & Network]
193+
```
194+
195+
196+
171197
## Multi-Node Distributed Training
172198

173199
The Podman backend automatically sets up networking and environment variables for distributed training:

0 commit comments

Comments
 (0)