Self-hosted deployment docs, auth config, and selfmanaged naming cleanup by mhotan · Pull Request #762 · unionai/unionai-docs

mhotan · 2026-02-23T01:57:31Z

Summary

Rename byok → selfmanaged: Rename byok-data-plane-setup-on-* files to selfmanaged-* with shorter, cleaner URLs (e.g. selfmanaged-aws instead of selfmanaged-data-plane-setup-on-aws)
Add self-hosted deployment guides: New content/deployment/selfhosted-deployment/ section with control plane, data plane, and authentication guides for deploying both planes in the same Kubernetes cluster
Add authentication configuration docs: Comprehensive OIDC auth documentation covering Okta setup, control plane Helm values, service-to-service auth, SDK/CLI PKCE, and troubleshooting (absorbs Add selfmanaged authentication configuration docs #729)
Add deployment glossary: Define key terminology (self-managed, self-hosted, control plane, data plane, intra-cluster, IRSA, Workload Identity)
Terminology cleanup: Replace "customer" with neutral terms ("overrides") across selfhosted docs
GitHub-linked values files: Prose references to helm-charts values files now link to the GitHub source
AWS-only support notice: GCP selfhosted guides marked as Preview with notices that AWS is the officially supported platform

New pages

content/deployment/selfhosted-deployment/_index.md — Overview with architecture diagram
content/deployment/selfhosted-deployment/control-plane-aws.md — AWS control plane deployment
content/deployment/selfhosted-deployment/control-plane-gcp.md — GCP control plane deployment (Preview)
content/deployment/selfhosted-deployment/data-plane-aws.md — AWS data plane deployment
content/deployment/selfhosted-deployment/data-plane-gcp.md — GCP data plane deployment (Preview)
content/deployment/selfhosted-deployment/authentication.md — OIDC auth with all 5 OAuth apps
content/deployment/configuration/authentication.md — OIDC auth configuration (Okta, Helm values, troubleshooting)
content/deployment/glossary.md — Deployment terminology

Renamed pages

byok-data-plane-setup-on-aws/ → selfmanaged-aws/
byok-data-plane-setup-on-azure.md → selfmanaged-azure.md
byok-data-plane-setup-on-gcp.md → selfmanaged-gcp.md
byok-data-plane-setup-on-generic.md → selfmanaged-generic.md
byok-data-plane-setup-on-oci.md → selfmanaged-oci.md

Test plan

make dev renders selfmanaged variant correctly
New selfhosted pages appear in sidebar under Platform deployment
GCP pages show Preview notices
Values file links resolve to helm-charts GitHub
Renamed selfmanaged pages render at new URLs
Glossary page renders correctly
Auth config page renders at /deployment/configuration/authentication/
Mermaid diagrams and tabbed content (Terraform vs Manual) render correctly
Auth page does not appear in non-selfmanaged variants

🤖 Generated with Claude Code

mhotan · 2026-02-23T02:36:21Z

/aviator merge

mhotan · 2026-02-24T16:59:58Z

/aviator merge

cloudflare-workers-and-pages · 2026-02-28T02:12:49Z

Deploying docs with Cloudflare Pages

Latest commit:	`709994b`
Status:	✅ Deploy successful!
Preview URL:	https://c8569032.docs-dog.pages.dev
Branch Preview URL:	https://mike-self-onboarding-doc-upd.docs-dog.pages.dev

View logs

mhotan · 2026-02-28T02:20:02Z

/aviator cancel

mhotan · 2026-03-01T00:00:36Z

/aviator cancel

Points Claude Code sessions to the canonical Notion doc for selfmanaged and selfhosted project context. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename all data plane setup documentation files from the outdated "byok" (Bring Your Own Kubernetes) naming to "selfmanaged" to align with the Hugo variant system naming convention. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Create comprehensive documentation for self-hosted (intra-cluster) deployments where both control plane and data plane run in the same Kubernetes cluster. Includes: - Overview with architecture diagram and prerequisites - Control plane guides for AWS and GCP - Data plane guides for AWS and GCP - Authentication guide documenting all 5 OAuth apps required for self-hosted deployments, with comparison to self-managed where app provisioning is automated via uctl Migrated from helm-charts SELFHOSTED_INTRA_CLUSTER docs with Hugo shortcode conversion and shared authentication section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add link card for the self-hosted deployment guides under the selfmanaged variant, giving users a clear entry point to the intra-cluster deployment documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Points to mike/exclude-legacy-oci-redirect branch which excludes the legacy uppercase byok-data-plane-setup-on-OCI.md from the redirect check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename selfmanaged-data-plane-setup-on-* to selfmanaged-* for cleaner URLs and reduced redundancy. Update internal cross-references in the generic and GCP guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…GitHub Rename example values file from selfhosted-customer to selfhosted-overrides across all selfhosted docs. Add GitHub links to repo-hosted values files (selfhosted-intracluster, registry) in prose references. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Define key deployment terminology: self-managed vs self-hosted, control plane, data plane, intra-cluster, IRSA, Workload Identity. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Self-hosted intra-cluster deployment is officially supported on AWS only. Mark GCP guides as preview with notices linking to AWS guides, and add (Preview) labels to GCP link cards on the overview page. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds comprehensive authentication documentation for the selfmanaged variant covering: - OIDC browser auth flow with sequence diagram - Okta configuration (automated via Terraform and manual) - Control plane Helm values (flyteadmin OIDC, service-to-service auth, trustedIdentityClaims, ingress auth annotations) - Secret delivery via External Secrets Operator - Dataplane auth (operator + eager mode) - SDK/CLI PKCE auth and CI/CD client credentials - Troubleshooting guide Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Abstract union_extension module specifics to generic IdP requirements. Replace Okta-specific references with provider-agnostic language. Add multiple secret delivery options (ESO + direct K8s secret). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Consolidate OAuth apps from 5 to 3 (matching actual values files) - Add complete control plane config (flyteadmin OIDC, admin SDK client, scheduler secrets, service-to-service auth, executions auth, ingress) - Add complete dataplane config (CRS, operator, propeller, secrets, executor) - Add comprehensive secret delivery table with all K8s secrets - Remove disableForGrpc configuration - Remove Okta-specific references, use generic OIDC/OAuth2 language - Fix incorrect service terminology (no "monolith" in selfhosted) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mhotan · 2026-03-02T21:12:09Z

@ppiegaze I am looking at this docs as they are rendered. I think renaming byok to selfmanaged makes sense for files. selfhosted and selfmanaged are finalized now. We are kind of forcing selfhosted awkwardly into selfmanaged here. I am not convinced it's the right long term structure. It may make sense to discuss should we consider breaking out selfhosted into it's own variant or restructure selfmanaged and selfhosted platform deployment pages?

* Add namespace mapping configuration docs Documents the namespace_mapping Helm value for customizing how project-domain pairs map to Kubernetes namespaces. Covers dataplane configuration, self-hosted control plane requirements (V1 only), template syntax, and the cascade to downstream services. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix namespace mapping docs: correct nesting, V1-only CP config - Fix double nesting: namespace_config.namespace_config → namespace_config - Clarify V2 does not need CP namespace_mapping (resolves on DP) - Add note that V2 namespace resolution happens on data plane Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

ppiegaze · 2026-03-05T17:29:01Z

@mhotan I think that making self-hosted a separate variant is the correct thing to do given our current set up. Hwoever, I am not sure that we want to publically publish docs that talk about self-hosted yet. I'll talk to Votta.

I will take a look at how this PR mixes self-hosted and self-managed.

# Conflicts: # unionai-docs-infra

Replace absolute https://www.union.ai/docs URL with relative link to fix Cloudflare build pre-check failure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

# Conflicts: # unionai-docs-infra

ppiegaze · 2026-03-12T14:25:31Z

@mhotan Would it make sense to separate out the self-hosted parts ofthis PR into separate PR? Then I could merge the other parts and leave the self-hosted for when we actually publically release that as a deployment option for the product. I can do this and then you can just review. WDYT?

Resolve submodule conflict by taking main's infra pointer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- unionai-docs-infra: 6673d5e (pydantic models: show actual fields) - unionai-examples: 12005fd (update-jsonl with missing fragments) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Self-hosted deployment guides, glossary, and link card moved to peeter/selfhosted-docs branch to hold for product announcement. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Moved to peeter/selfhosted-docs branch with selfhosted variant tag. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Points to unionai-docs-infra#43 (2f329df). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Points to unionai-docs-infra#44. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

mhotan requested review from cosmicBboy, kumare3, nelsonjr and ppiegaze as code owners February 23, 2026 01:57

jmonty42 approved these changes Feb 24, 2026

View reviewed changes

mhotan requested review from EngHabu, jpvotta and samhita-alla as code owners February 28, 2026 02:12

mhotan changed the title ~~Add selfmanaged/selfhosted Notion guide reference to CLAUDE.md~~ Rename byok→selfmanaged and add self-hosted deployment docs Feb 28, 2026

mhotan force-pushed the mike/self-onboarding-doc-updates branch from 77be26f to 8dd12b4 Compare February 28, 2026 02:32

mhotan changed the title ~~Rename byok→selfmanaged and add self-hosted deployment docs~~ Self-hosted deployment docs and selfmanaged naming cleanup Feb 28, 2026

mhotan force-pushed the mike/self-onboarding-doc-updates branch from 39452cf to db06cf5 Compare February 28, 2026 23:26

mhotan changed the title ~~Self-hosted deployment docs and selfmanaged naming cleanup~~ Self-hosted deployment docs, auth config, and selfmanaged naming cleanup Feb 28, 2026

mhotan mentioned this pull request Feb 28, 2026

Add selfmanaged authentication configuration docs #729

Closed

4 tasks

mhotan and others added 11 commits March 2, 2026 12:04

Add selfmanaged/selfhosted Notion guide reference to CLAUDE.md

ec8949d

Points Claude Code sessions to the canonical Notion doc for selfmanaged and selfhosted project context. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add self-hosted deployment section to deployment index

4a7ffc8

Add link card for the self-hosted deployment guides under the selfmanaged variant, giving users a clear entry point to the intra-cluster deployment documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Update unionai-docs-infra submodule for redirect exclusion

2970fcc

Points to mike/exclude-legacy-oci-redirect branch which excludes the legacy uppercase byok-data-plane-setup-on-OCI.md from the redirect check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Shorten selfmanaged file names and update cross-references

479dbf6

Rename selfmanaged-data-plane-setup-on-* to selfmanaged-* for cleaner URLs and reduced redundancy. Update internal cross-references in the generic and GCP guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add deployment glossary

c37b665

Define key deployment terminology: self-managed vs self-hosted, control plane, data plane, intra-cluster, IRSA, Workload Identity. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mhotan force-pushed the mike/self-onboarding-doc-updates branch from 2136101 to e6cb909 Compare March 2, 2026 20:28

ctxswitch approved these changes Mar 3, 2026

View reviewed changes

mhotan assigned ppiegaze Mar 4, 2026

mhotan mentioned this pull request Mar 4, 2026

Add namespace mapping configuration docs #816

Merged

3 tasks

ppiegaze and others added 2 commits March 5, 2026 18:32

Merge branch 'main' into mike/self-onboarding-doc-updates

e066c90

# Conflicts: # unionai-docs-infra

Fix absolute URL in dataplane helm chart reference

8e12ff7

Replace absolute https://www.union.ai/docs URL with relative link to fix Cloudflare build pre-check failure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mhotan mentioned this pull request Mar 7, 2026

Add monitoring configuration docs for selfmanaged deployments #826

Merged

4 tasks

mhotan and others added 2 commits March 10, 2026 08:28

Updates to authentication and namespace mapping docs

8c8d3e2

Merge branch 'main' into mike/self-onboarding-doc-updates

f75618b

# Conflicts: # unionai-docs-infra

ppiegaze and others added 6 commits March 13, 2026 14:20

merge main into mike/self-onboarding-doc-updates

209c66a

Resolve submodule conflict by taking main's infra pointer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

update

6a54887

update submodule pointers to latest main

64db9a4

- unionai-docs-infra: 6673d5e (pydantic models: show actual fields) - unionai-examples: 12005fd (update-jsonl with missing fragments) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

remove self-hosted content from this PR

01eec3c

Self-hosted deployment guides, glossary, and link card moved to peeter/selfhosted-docs branch to hold for product announcement. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

restore selfmanaged/selfhosted Notion link in CLAUDE.md

fdb062b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

remove self-hosted section from namespace-mapping docs

a299314

Moved to peeter/selfhosted-docs branch with selfhosted variant tag. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ppiegaze mentioned this pull request Mar 13, 2026

Add redirects for byok to selfmanaged renames unionai/unionai-docs-infra#43

Merged

update infra submodule to include byok→selfmanaged redirects

4239ccc

Points to unionai-docs-infra#43 (2f329df). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ppiegaze mentioned this pull request Mar 13, 2026

Fix case-sensitive redirect matching in check_deleted_pages unionai/unionai-docs-infra#44

Merged

1 task

update infra submodule for case-insensitive redirect check

709994b

Points to unionai-docs-infra#44. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ppiegaze merged commit 6f16abf into main Mar 13, 2026
10 checks passed

ppiegaze deleted the mike/self-onboarding-doc-updates branch March 13, 2026 14:25

ppiegaze mentioned this pull request Mar 16, 2026

Add identity injection configuration docs #755

Closed

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Self-hosted deployment docs, auth config, and selfmanaged naming cleanup#762

Self-hosted deployment docs, auth config, and selfmanaged naming cleanup#762
ppiegaze merged 25 commits intomainfrom
mike/self-onboarding-doc-updates

mhotan commented Feb 23, 2026 •

edited

Loading

Uh oh!

mhotan commented Feb 23, 2026

Uh oh!

mhotan commented Feb 24, 2026

Uh oh!

cloudflare-workers-and-pages bot commented Feb 28, 2026 •

edited

Loading

Uh oh!

mhotan commented Feb 28, 2026

Uh oh!

mhotan commented Mar 1, 2026

Uh oh!

mhotan commented Mar 2, 2026

Uh oh!

ppiegaze commented Mar 5, 2026

Uh oh!

ppiegaze commented Mar 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

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

Uh oh!

Summary

New pages

Renamed pages

Test plan

Uh oh!

mhotan commented Feb 23, 2026

Uh oh!

mhotan commented Feb 24, 2026

Uh oh!

cloudflare-workers-and-pages bot commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying docs with Cloudflare Pages

Uh oh!

mhotan commented Feb 28, 2026

Uh oh!

mhotan commented Mar 1, 2026

Uh oh!

mhotan commented Mar 2, 2026

Uh oh!

ppiegaze commented Mar 5, 2026

Uh oh!

ppiegaze commented Mar 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mhotan commented Feb 23, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Feb 28, 2026 •

edited

Loading