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-09 13:38:09 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

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

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

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: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 <[email protected]>

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

stefannica

first round of reviews, more to follow...

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

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

stefannica · 2025-12-06T21:20:39Z

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

+
+1. **Code Execution**: You write code and run pipelines with your client SDK using Python
+
+2. **Token Acquisition**: The ZenML client fetches short-lived tokens from your ZenML workspace for:


note: this only happens if you use service connectors

so what would be a more generally correct statement

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

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

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

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

stefannica · 2025-12-06T22:12:32Z

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

+- Artifact lineage graphs
+- Step logs and outputs
+
+You control this access by configuring appropriate cloud IAM permissions.


This is misleading. The truth is this: if you give your users permission to access these things, you also implicitly give the UI permission to do so. You could say "you control who can access this information in the UI by configuring appropriate ZenML Pro RBAC permissions. Cloud IAM permissions do not apply here.

no don't we have some setting for our wrokspace/UI to enable/disable this?

stefannica · 2025-12-06T22:15:01Z

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

+```mermaid
+graph LR
+    A[User] -->|1. Login| B[Control Plane<br/>ZenML Infrastructure]
+    B -->|2. Auth Token| A
+    A -->|3. Access Workspace| C[Workspace<br/>Your Infrastructure]
+    C -->|4. Validate Token| B
+    B -->|5. Authorization| C
+    C -->|6. Execute| D[Your Resources]
+```


these do not render correctly

didn't we have a mermaid plugin for gitbook at some point

stefannica

I tried to review as much of this as I could. Half of it is pretty good, while the other half is clearly vibe-written and riddled with hallucinations and over-simplifications.

I would kindly ask you to give this another careful read yourself, check that it's factually correct based on the original docs and resources, then correct the mistakes.

stefannica · 2025-12-07T18:03:56Z

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

+
+| Data Type | Storage Location | Purpose |
+|-----------|-----------------|---------|
+| User credentials | Control Plane | Authentication only |


The control plane doesn't store user credentials (unless you count Personal Access Tokens or API keys). It's the customer's SSO/identity provider that stores the credentials.

would it be fair to call this user metadata?

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

docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md

stefannica · 2025-12-07T19:48:55Z

docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md

+1. Navigate to `https://zenml.mycompany.com` in your browser
+2. You should be redirected to ZenML Cloud login
+3. Sign in with your organization credentials
+4. You should see your workspace listed


This is the backwards way of doing it. You should instruct them to log in to cloud.zenml.io, access their org and then their workspace. This redirect is more of a backwards compatibility failsafe than it is an official way of accessing the workspace UI.

stefannica · 2025-12-07T20:09:38Z

docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md

+kubectl -n zenml-workload-manager create serviceaccount zenml-runner
+```
+
+### 2. Configure Workload Manager in Helm Values


This section is repeated in at least 3 different places:

here

in the self-hosted docs

in the workload managers section

Can you please just point to the workload managers section instead of duplicating this information ?

stefannica · 2025-12-07T20:12:08Z

docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md

+    external:
+      type: mysql
+      host: zenml-db.123456789.us-east-1.rds.amazonaws.com
+      port: 3306
+      username: admin
+      password: <your-rds-password>
+      database: zenml_hybrid


This is hallucinated or ill-informed. Please consult the official helm chart values.

stefannica · 2025-12-07T20:14:49Z

docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md

+    # Add other environment variables as needed
+```
+
+## Database Configuration Examples


This entire section is unnecessary. We already have a complete section on how to configure the helm chart for OSS server deployments. Duplicating oversimplified parts of that here - and incorrectly at that - isn't going to help anyone. Better to link to the correct and fully detailed OSS helm documentation here instead.

stefannica · 2025-12-07T20:15:17Z

docs/book/getting-started/zenml-pro/hybrid-deployment-helm.md

+    external:
+      type: mysql
+      host: 34.123.45.67
+      port: 3306
+      username: root
+      password: <your-cloud-sql-password>
+      database: zenml_hybrid


Hallucinated. I won't repeat this comment....

Co-authored-by: Stefan Nica <[email protected]>

… docs/better-pro-docs

Co-authored-by: Stefan Nica <[email protected]>

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

docs/book/getting-started/zenml-pro/on-prem-deployment.md Outdated Show resolved Hide resolved

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

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

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 <[email protected]>

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

stefannica requested changes Dec 6, 2025

View reviewed changes

stefannica requested changes Dec 7, 2025

View reviewed changes

stefannica added the vibecoded label Dec 7, 2025

AlexejPenner and others added 6 commits December 9, 2025 11:16

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

ee3ea6a

Co-authored-by: Stefan Nica <[email protected]>

Applied stefans review comments part 1

dadc63b

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

7c0db33

… docs/better-pro-docs

Additional PR comments applied

cb5d327

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

fb79faa

Co-authored-by: Stefan Nica <[email protected]>

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

df1a223

Co-authored-by: Stefan Nica <[email protected]>


		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


		1. Code Execution: You write code and run pipelines with your client SDK using Python

		2. Token Acquisition: The ZenML client fetches short-lived tokens from your ZenML workspace for:

Much better Pro docs #4263

Are you sure you want to change the base?

Much better Pro docs #4263

Uh oh!

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!

Uh oh!

Uh oh!

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!

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!

stefannica left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stefannica Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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 Nov 28, 2025 •

edited

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading

stefannica Dec 6, 2025 •

edited

Loading