Much better Pro docs #4263

AlexejPenner · 2025-11-28T10:30:00Z

Describe changes

I added a section per deployment scenario - https://zenml-io.gitbook.io/alexej/zenml-pro

Pre-requisites

Please ensure you have done the following:

I have read the CONTRIBUTING.md document.
I have added tests to cover my changes.
I have based my new branch on develop and the open PR is targeting develop. If your branch wasn't based on develop read Contribution guide on rebasing branch to develop.
IMPORTANT: I made sure that my changes are reflected properly in the following resources:
- ZenML Docs
- Dashboard: Needs to be communicated to the frontend team.
- Templates: Might need adjustments (that are not reflected in the template tests) in case of non-breaking changes and deprecations.
- Projects: Depending on the version dependencies, different projects might get affected.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Other (add details above)

github-actions · 2025-11-28T10:45:49Z

Documentation Link Check Results

❌ Absolute links check failed
There are broken absolute links in the documentation. See workflow logs for details
❌ Relative links check failed
There are broken relative links in the documentation. See workflow logs for details
_{Last checked: 2025-12-05 10:01:47 UTC}

github-actions · 2025-11-28T10:49:01Z

🔍 Broken Links Report

Summary

📁 Files with broken links: 3
🔗 Total broken links: 3
📄 Broken markdown links: 2
🖼️ Broken image links: 1
⚠️ Broken reference placeholders: 0

Details

File	Link Type	Link Text	Broken Path
`zenml-pro/hybrid-deployment-helm.md`	📄	"Set up users and teams"	`../organization.md`
`zenml-pro/self-hosted-deployment.md`	🖼️	"Self-hosted deployment architecture"	`../../.gitbook/assets/air-gapped-architecture.png`
`zenml-pro/hybrid-deployment-ecs.md`	📄	"Set up users and teams"	`../organization.md`

📂 Full file paths

/home/runner/work/zenml/zenml/scripts/../docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md
/home/runner/work/zenml/zenml/scripts/../docs/book/getting-started/zenml-pro/self-hosted-deployment.md
/home/runner/work/zenml/zenml/scripts/../docs/book/getting-started/zenml-pro/hybrid-deployment-ecs.md

AlexejPenner · 2025-11-28T11:22:57Z

docs/book/getting-started/zenml-pro/on-prem-deployment.md

+1. **Code Execution**: You write code and run pipelines with your client SDK using Python
+2. **Authentication & Token Acquisition**:
+   - Users authenticate via your internal identity provider (LDAP/AD/OIDC)
+   - The ZenML Pro control plane (running in your infrastructure) handles authentication and RBAC
+   - The ZenML client fetches short-lived tokens from your ZenML workspace for:
+     - Pushing Docker images to your container registry
+     - Communicating with your artifact store
+     - Submitting workloads to your orchestrator
+   - *Note: Your local Python environment needs the client libraries for your stack components*
+3. **Authorization**: RBAC policies enforced by your control plane before token issuance
+4. **Image & Workload Submission**: The client pushes Docker images (and optionally code if no code repository is configured) to your container registry, then submits the workload to your orchestrator
+5. **Orchestrator Execution**: In the orchestrator environment within your infrastructure:
+   - The Docker image is pulled from your container registry
+   - Within the pipeline/step entrypoint, the necessary code is pulled in
+   - A connection to your ZenML workspace is established
+   - The relevant pipeline/step code is executed
+6. **Runtime Data Flow**: During execution (all within your infrastructure):
+   - Pipeline and step run metadata is logged to your ZenML workspace
+   - Logs are streamed to your log backend
+   - Artifacts are written to your artifact store
+   - Metadata pointing to these artifacts is persisted in your workspace
+7. **Observability**: The ZenML Pro dashboard (running in your infrastructure) connects to your workspace and uses all persisted metadata to provide you with a complete observability plane


@stefannica fact check pls

AlexejPenner · 2025-11-28T11:23:33Z

docs/book/getting-started/zenml-pro/self-hosted-deployment.md

+
+The diagram above illustrates a complete air-gapped ZenML Pro deployment with all components running within your organization's VPC. This architecture ensures zero external communication while providing full enterprise MLOps capabilities.
+
+### Architecture Components


@stefannica fact check pls

AlexejPenner · 2025-11-28T11:23:59Z

docs/book/getting-started/zenml-pro/self-hosted-deployment.md

+- **Backup sites** for disaster recovery
+- **Monitoring and alerting** for all components
+
+## Pre-requisites


@stefannica fact check pls

AlexejPenner · 2025-12-03T09:21:50Z

https://zenml-io.gitbook.io/alexej/zenml-pro - view here to see it in action

htahir1

I think its good for a first round. many comments apply to many pages

docs/book/getting-started/zenml-pro/saas-deployment.md

docs/book/getting-started/zenml-pro/README.md

htahir1 · 2025-12-03T09:34:05Z

docs/book/getting-started/zenml-pro/README.md

 - ✅ **Vulnerability Assessment Reports** available on request
 - ✅ **Software Bill of Materials (SBOM)** available on request


@stefannica should verify this

htahir1 · 2025-12-03T09:44:02Z

docs/book/getting-started/zenml-pro/deployments-overview.md

+
+All three deployment scenarios follow a similar pipeline execution pattern, with differences in where authentication happens and where data resides:
+
+### Standard Data Flow Steps


This definitely needs a diagram

Agreed - we might even have one laying around somewhere

htahir1 · 2025-12-03T09:44:41Z

docs/book/getting-started/zenml-pro/deployments-overview.md

+
+**SaaS**: Metadata is stored in ZenML infrastructure. Your ML data and compute remain in your infrastructure.
+
+**Hybrid**: Metadata and control plane are split — authentication/RBAC happens at ZenML control plane, but all run metadata, artifacts, and compute stay in your infrastructure.


I thnk the authentication bit is the most important here and isnt really elaborated but maybe it is later?

What more would you like to know about this at this stage?

htahir1 · 2025-12-03T09:46:20Z

docs/book/getting-started/zenml-pro/saas-deployment.md

+
+You control this access by configuring appropriate cloud IAM permissions.
+
+## Getting Started


IMO super strnage to have this whole section here...

the whole section ? maybe we dont need the example pipeline - butt i like how it shows how quickly youi're ready

Hmm really? its in the dashboard already when you sign up

well somebody in the docs here wants to know what complexity awaits them - "Is it worth my time?"

im not sure tbh

in my experience these are the questions we get very early on

docs/book/getting-started/zenml-pro/saas-deployment.md

Co-authored-by: Hamza Tahir <hamza@zenml.io>

… docs/better-pro-docs

github-actions · 2025-12-03T14:33:12Z

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 34%, saving 132.21 KB.

Filename	Before	After	Improvement	Visual comparison
`docs/book/getting-started/zenml-pro/.gitbook/assets/pro-workload-managers.png`	388.76 KB	256.55 KB	-34.0%	View diff

383 images did not require optimisation.

Update required: Update image-actions configuration to the latest version before 1/1/21. See README for instructions.

Initial commit

f4e15b8

AlexejPenner requested a review from stefannica November 28, 2025 10:30

AlexejPenner changed the base branch from develop to docs/pro-vs-oss November 28, 2025 10:33

AlexejPenner requested a review from htahir1 November 28, 2025 10:33

Fixed formatting

2946cc1

github-actions bot added internal To filter out internal PRs and issues documentation Improvements or additions to documentation labels Nov 28, 2025

Pruned away hallucinations

23a0759

AlexejPenner commented Nov 28, 2025

View reviewed changes

AlexejPenner added 11 commits December 1, 2025 23:44

Some more in depth docs

c7e7517

Adjusted time to production

299fed1

Adjusted some wording

3788483

Linking across new files properly

e7b164b

Adjusted cards

27a608f

Some streamlining

b67b31b

Adjusted naming self-hosted

53fd01f

Slight rewording in table

bb5cfc2

Slight rewording in table

8d705e9

Edited all the overview pages

d70df0b

Fixed renaming leftovers

b33baea

htahir1 requested changes Dec 3, 2025

View reviewed changes

AlexejPenner and others added 6 commits December 3, 2025 11:28

Update docs/book/getting-started/zenml-pro/saas-deployment.md

700a65c

Co-authored-by: Hamza Tahir <hamza@zenml.io>

Implemented some pr comments

21eb029

Merge branch 'docs/better-pro-docs' of github.com:zenml-io/zenml into…

21861c8

… docs/better-pro-docs

Removed diagrams from detail tabs

56fe203

Specify Pro server

053f589

Added image

0be4fc5

Optimised images with calibre/image-actions

0a6bdfa

AlexejPenner added 4 commits December 5, 2025 09:39

Applied some more reviews

02e53c8

Add actual docker image URI

2d32d12

Applied Alex's review

187b488

Merge branch 'docs/pro-vs-oss' into docs/better-pro-docs

a36e8ea


		The diagram above illustrates a complete air-gapped ZenML Pro deployment with all components running within your organization's VPC. This architecture ensures zero external communication while providing full enterprise MLOps capabilities.

		### Architecture Components

		- ✅ Vulnerability Assessment Reports available on request
		- ✅ Software Bill of Materials (SBOM) available on request


		All three deployment scenarios follow a similar pipeline execution pattern, with differences in where authentication happens and where data resides:

		### Standard Data Flow Steps


		SaaS: Metadata is stored in ZenML infrastructure. Your ML data and compute remain in your infrastructure.

		Hybrid: Metadata and control plane are split — authentication/RBAC happens at ZenML control plane, but all run metadata, artifacts, and compute stay in your infrastructure.


		You control this access by configuring appropriate cloud IAM permissions.

		## Getting Started

Much better Pro docs #4263

Are you sure you want to change the base?

Much better Pro docs #4263

Conversation

AlexejPenner commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe changes

Pre-requisites

Types of changes

Uh oh!

github-actions bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Link Check Results

Uh oh!

github-actions bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Broken Links Report

Summary

Details

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexejPenner commented Dec 3, 2025

Uh oh!

htahir1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlexejPenner commented Nov 28, 2025 •

edited

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading