chore: add local development with SDK backends guide by Raakshass · Pull Request #261 · kubeflow/sdk

Raakshass · 2026-02-03T18:41:06Z

Closes #259

Summary

This PR adds a Local Development with SDK Backends guide to help users understand and switch between available training backends.

Content Covered

Backend comparison table (LocalProcess, Container, Kubernetes)
When to use each backend - quick prototyping vs distributed training vs production
Code examples for each backend configuration
Switching between backends - same trainer code works across all backends
Common operations (list jobs, view logs, wait, delete)
Troubleshooting tips for each backend

Changes Based on Feedback

Revised from contributor dev setup to user-facing backends guide per @Fiona-Waters feedback.

Checklist

Follows existing documentation style (RST format)
Aligned with kubeflow.org Trainer docs structure
Includes comparison table as requested in Document Local Development #259

google-oss-prow · 2026-02-03T18:41:12Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign andreyvelich for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

github-actions · 2026-02-03T18:41:15Z

🎉 Welcome to the Kubeflow SDK! 🎉

Thanks for opening your first PR! We're happy to have you as part of our community 🚀

Here's what happens next:

If you haven't already, please check out our Contributing Guide for repo-specific guidelines and the Kubeflow Contributor Guide for general community standards
Our team will review your PR soon! cc @kubeflow/kubeflow-sdk-team

Join the community:

Slack: Join our #kubeflow-ml-experience and #kubeflow-trainer Slack channels
Meetings: Attend the Kubeflow SDK and ML Experience bi-weekly meetings

Feel free to ask questions in the comments if you need any help or clarification!
Thanks again for contributing to Kubeflow! 🙏

Fiona-Waters · 2026-02-04T10:24:10Z

@Raakshass Thank you for your interest in contributing. The aim of this issue is to add a guide for customers that would like to use our local and container backends. We would like to show them how to easily switch between available backends, when to use each of them etc. Please re-read the issue description and let me know if you have any questions.

Raakshass · 2026-02-04T17:59:17Z

Thanks @Fiona-Waters for the clarification! I misunderstood the scope - I'll revise my PR to focus on the user-facing local and container backends guide instead of contributor dev setup.

I'll update it to cover:

Backend comparison (LocalProcess vs Container vs Kubernetes)
When to use each backend
Code examples for switching between backends
Common operations and troubleshooting

Will push the updated content shortly!

Raakshass · 2026-02-04T18:24:20Z

@Fiona-Waters I updated the PR content described above. I'm unable to edit the PR title to "docs: add local development with SDK backends guide" - could you please update it? Thanks!

Raakshass · 2026-02-06T10:15:52Z

@Fiona-Waters I've updated the PR content as you suggested - it now covers the user-facing backends guide with comparison table, switching examples, and troubleshooting tips. Ready for re-review when you have time!

Fiona-Waters

Thanks @Raakshass I think this is great. Could we add something around differing container_host for use on mac for example? This could be tricky if the user doesn't know about it.

Fiona-Waters

Thanks @Raakshass
You also need to add to https://github.com/kubeflow/sdk/blob/main/docs/source/index.rst?plain=1 so that the new section will show on the website.

docs/source/getting-started/index.rst

Raakshass · 2026-02-13T21:30:45Z

@Fiona-Waters — addressed both asks:

Container host info for Mac — added Container Host Configuration section with OS-specific socket paths table and macOS code example
Updated grid-item-card + main index.rst — better description + added to toctree
Ready for re-review. Thanks!

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

coveralls · 2026-02-16T02:53:12Z

Pull Request Test Coverage Report for Build 22003433482

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 72.824%

Totals
Change from base Build 21955571005:	0.0%
Covered Lines:	4092
Relevant Lines:	5619

💛 - Coveralls

- Add Container Host Configuration section with OS-specific socket paths (Linux, macOS, Windows) and macOS Docker Desktop code example - Add backend comparison table (LocalProcess, Container, Kubernetes) - Add code examples for switching between backends - Add common operations and troubleshooting tips - Update grid-item-card description in getting-started/index.rst - Add local-development to main docs/source/index.rst toctree Closes kubeflow#259 Signed-off-by: siddhant jain <siddhantjainofficial26@gmail.com>

Raakshass · 2026-02-16T18:41:18Z

@Fiona-Waters Rebased onto latest main to fix the coveralls base-commit drift. Both your review items are addressed:

Container host config for macOS — added Container Host Configuration section with OS-specific socket paths table and macOS code example
Updated index.rst — added to toctree and grid-item-card in getting-started page

All CI checks passing. Ready for re-review when you get a chance. Thanks!

Fiona-Waters

Thanks @Raakshass I've left some comments.

Fiona-Waters · 2026-03-02T13:37:53Z

docs/source/getting-started/local-development.rst

@@ -0,0 +1,239 @@
+Local Development with SDK Backends


In the UI, this menu item is quite long. Can we change it to Local Development? I think the description underneath covers the rest. WDYT?

Fiona-Waters · 2026-03-02T13:38:39Z

docs/source/getting-started/local-development.rst

+Local Development with SDK Backends
+====================================
+
+This guide explains how to run Kubeflow training jobs locally using the SDK's


Suggested change

This guide explains how to run Kubeflow training jobs locally using the SDK's

This guide explains how to run Kubeflow TrainJobs locally using the SDK's

Fiona-Waters · 2026-03-02T13:38:54Z

docs/source/getting-started/local-development.rst

+Overview
+--------
+
+The Kubeflow Trainer SDK provides three backends for running training jobs:


Suggested change

The Kubeflow Trainer SDK provides three backends for running training jobs:

The Kubeflow Trainer SDK provides three backends for running TrainJobs:

Fiona-Waters · 2026-03-02T13:45:36Z

docs/source/getting-started/local-development.rst

+   verify the socket path by running ``docker context inspect`` and check
+   the ``Host`` value in the output.
+
+**Choosing Docker vs Podman:**


I think this section can be removed.

- Shorten page title to Local Development per reviewer request - Use TrainJobs terminology instead of training jobs - Remove Choosing Docker vs Podman comparison section Signed-off-by: Siddhant Jain <siddhantjainofficial26@gmail.com>

Raakshass · 2026-03-03T17:30:36Z

@Fiona-Waters Addressed all your review comments:

Changes in commit a6d82a0:

Title shortened — Changed from "Local Development with SDK Backends" to "Local Development" as suggested
Terminology fix (line 4) — "Kubeflow training jobs" → "Kubeflow TrainJobs"
Terminology fix (line 11) — "running training jobs" → "running TrainJobs"
Section removed — Removed "Choosing Docker vs Podman" comparison table as requested

All changes are in a single new commit on top (no force-push, no history rewrite). Ready for re-review!

Fiona-Waters

Just a few more small comments. Thank you!

docs/source/getting-started/local-development.rst

Co-authored-by: Fiona Waters <fiwaters6@gmail.com> Signed-off-by: Siddhant Jain <149181251+Raakshass@users.noreply.github.com>

google-oss-prow bot requested review from andreyvelich, astefanutti and szaher February 3, 2026 18:41

google-oss-prow bot added the size/L label Feb 3, 2026

Raakshass force-pushed the docs/local-development branch from 4a0f42a to cf67ce0 Compare February 3, 2026 19:02

Raakshass marked this pull request as draft February 4, 2026 18:21

google-oss-prow bot added the do-not-merge/work-in-progress label Feb 4, 2026

Raakshass marked this pull request as ready for review February 4, 2026 18:23

google-oss-prow bot removed the do-not-merge/work-in-progress label Feb 4, 2026

google-oss-prow bot requested a review from kramaranya February 4, 2026 18:24

Fiona-Waters reviewed Feb 11, 2026

View reviewed changes

docs/source/getting-started/index.rst Show resolved Hide resolved

Copilot AI review requested due to automatic review settings February 13, 2026 21:15

Copilot started reviewing on behalf of Raakshass February 13, 2026 21:15 View session

Raakshass force-pushed the docs/local-development branch from eda32e2 to 29a9833 Compare February 13, 2026 21:27

Raakshass changed the title ~~docs: add local development guide~~ chore: add local development with SDK backends guide Feb 13, 2026

Raakshass requested a review from Fiona-Waters February 13, 2026 21:30

Copilot AI reviewed Feb 13, 2026

View reviewed changes

Raakshass force-pushed the docs/local-development branch from 29a9833 to 9e32e97 Compare February 16, 2026 18:40

Fiona-Waters reviewed Mar 2, 2026

View reviewed changes

Fiona-Waters reviewed Mar 4, 2026

View reviewed changes

docs/source/getting-started/local-development.rst Outdated Show resolved Hide resolved

docs/source/getting-started/local-development.rst Outdated Show resolved Hide resolved

docs/source/getting-started/local-development.rst Outdated Show resolved Hide resolved

Raakshass and others added 3 commits March 12, 2026 01:14

Update docs/source/getting-started/local-development.rst

2e0fdf7

Co-authored-by: Fiona Waters <fiwaters6@gmail.com> Signed-off-by: Siddhant Jain <149181251+Raakshass@users.noreply.github.com>

Update docs/source/getting-started/local-development.rst

e438b5e

Co-authored-by: Fiona Waters <fiwaters6@gmail.com> Signed-off-by: Siddhant Jain <149181251+Raakshass@users.noreply.github.com>

Update docs/source/getting-started/local-development.rst

3696121

Co-authored-by: Fiona Waters <fiwaters6@gmail.com> Signed-off-by: Siddhant Jain <149181251+Raakshass@users.noreply.github.com>

	This guide explains how to run Kubeflow training jobs locally using the SDK's
	This guide explains how to run Kubeflow TrainJobs locally using the SDK's

	The Kubeflow Trainer SDK provides three backends for running training jobs:
	The Kubeflow Trainer SDK provides three backends for running TrainJobs:

Conversation

Raakshass commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Content Covered

Changes Based on Feedback

Checklist

Uh oh!

google-oss-prow bot commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

Fiona-Waters commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Raakshass commented Feb 4, 2026

Uh oh!

Raakshass commented Feb 4, 2026

Uh oh!

Raakshass commented Feb 6, 2026

Uh oh!

Fiona-Waters left a comment

Choose a reason for hiding this comment

Uh oh!

Fiona-Waters left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Raakshass commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

coveralls commented Feb 16, 2026

Pull Request Test Coverage Report for Build 22003433482

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

Raakshass commented Feb 16, 2026

Uh oh!

Fiona-Waters left a comment

Choose a reason for hiding this comment

Uh oh!

Fiona-Waters Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Fiona-Waters Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Fiona-Waters Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Fiona-Waters Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Raakshass commented Mar 3, 2026

Uh oh!

Fiona-Waters left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Raakshass commented Feb 3, 2026 •

edited

Loading

Fiona-Waters commented Feb 4, 2026 •

edited

Loading