Add namespace mapping configuration docs by mhotan · Pull Request #816 · unionai/unionai-docs

mhotan · 2026-03-04T04:46:31Z

Summary

Documents the namespace_mapping Helm value for customizing how project-domain pairs map to Kubernetes namespaces
Covers dataplane top-level configuration (cascades to CRS, propeller, operator, executor)
Documents self-hosted control plane configuration for V1 executions (flyteadmin)
Clarifies V2 executions do NOT need CP namespace_mapping (resolved on data plane by executor)
Fixes double nesting bug in CP config example (namespace_config.namespace_config → namespace_config)
Includes template syntax, examples, and component cascade table

Related: helm-charts #226 (consolidate namespace_mapping into single canonical Helm value)

Test plan

Verify make dev renders the namespace-mapping page correctly for the selfmanaged variant
Confirm V1 CP config example shows correct single-level nesting
Confirm V2 note explains no CP config needed

🤖 Generated with Claude Code

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>

cloudflare-workers-and-pages · 2026-03-04T04:47:34Z

Deploying docs with Cloudflare Pages

Latest commit:	`6c19a5b`
Status:	✅ Deploy successful!
Preview URL:	https://0d259d72.docs-dog.pages.dev
Branch Preview URL:	https://mike-selfmanaged-namespace-m.docs-dog.pages.dev

View logs

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

davidmirror-ops · 2026-03-04T15:52:43Z

content/deployment/configuration/namespace-mapping.md

+> [!NOTE]
+> The template uses Helm's backtick escaping for Go template delimiters. In your values file, wrap `{{ project }}` and `{{ domain }}` with backtick-escaped `{{` and `}}` delimiters as shown above.
+
+{{< variant selfmanaged >}}


do we need a "selfhosted" variant?
cc @ppiegaze

Asking the same question here: #762 (comment)

mhotan · 2026-03-04T21:25:16Z

Going to merge now and we can have Peeter just review the parent PR.

…nup (#762) * Add selfmanaged/selfhosted Notion guide reference to CLAUDE.md 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 byok-* to selfmanaged-* and update cross-references 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> * Add self-hosted deployment guides 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 self-hosted deployment section to deployment index 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 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 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> * Replace customer terminology with overrides and link values files to 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> * Add deployment glossary 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> * Add AWS-only support notices to selfhosted GCP docs 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> * Add selfmanaged authentication configuration docs 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> * Remove internal Terraform module references from auth docs 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> * Update selfmanaged authentication docs for consistency - 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> * Add namespace mapping configuration docs (#816) * 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> * Fix absolute URL in dataplane helm chart reference 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> * Updates to authentication and namespace mapping docs * update * update submodule pointers to latest main - 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 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 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * remove self-hosted section from namespace-mapping docs Moved to peeter/selfhosted-docs branch with selfhosted variant tag. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * update infra submodule to include byok→selfmanaged redirects Points to unionai-docs-infra#43 (2f329df). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * update infra submodule for case-insensitive redirect check Points to unionai-docs-infra#44. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

* Add selfmanaged/selfhosted Notion guide reference to CLAUDE.md 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 byok-* to selfmanaged-* and update cross-references 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> * Add self-hosted deployment guides 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 self-hosted deployment section to deployment index 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 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 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> * Replace customer terminology with overrides and link values files to 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> * Add deployment glossary 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> * Add AWS-only support notices to selfhosted GCP docs 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> * Add selfmanaged authentication configuration docs 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> * Remove internal Terraform module references from auth docs 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> * Update selfmanaged authentication docs for consistency - 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> * Add namespace mapping configuration docs (#816) * 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> * Fix absolute URL in dataplane helm chart reference 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> * Add monitoring configuration docs for selfmanaged deployments Documents the data plane monitoring architecture: - Static Prometheus for Union features (scrape targets, configuration) - Optional kube-prometheus-stack for cluster health monitoring - Prometheus Operator CRD installation via dataplane-crds chart - Integrating with existing Prometheus (static configs and ServiceMonitors) - Exporting metrics with remote write (AMP example) - Links to Prometheus official documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Clarify that Prometheus Operator CRDs are optional Static scrape configs are an alternative to CRD-based discovery. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * De-emphasize BYO Prometheus, remove remote write for features instance - Clarify Union features Prometheus is a platform dependency, not to be replaced or reconfigured - Remove remote write section for the static Prometheus instance - Move remote write guidance to the monitoring stack section where kube-prometheus-stack natively supports it - Rename and shorten BYO Prometheus section to "Scraping Union services from your own Prometheus" with note that it's for additional operational visibility only - Remove remote_write from architecture diagram - Simplify BYO scrape config to use endpoints SD instead of per-service jobs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * remove self-hosted content from this PR Self-hosted deployment guides, glossary, link card, and namespace-mapping self-hosted section 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 <noreply@anthropic.com> Co-authored-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

mhotan requested review from EngHabu, cosmicBboy, jpvotta, kumare3, ppiegaze and samhita-alla as code owners March 4, 2026 04:46

davidmirror-ops reviewed Mar 4, 2026

View reviewed changes

davidmirror-ops approved these changes Mar 4, 2026

View reviewed changes

mhotan merged commit ccb9b82 into mike/self-onboarding-doc-updates Mar 4, 2026
8 checks passed

mhotan deleted the mike/selfmanaged-namespace-mapping branch March 4, 2026 21:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add namespace mapping configuration docs#816

Add namespace mapping configuration docs#816
mhotan merged 2 commits intomike/self-onboarding-doc-updatesfrom
mike/selfmanaged-namespace-mapping

mhotan commented Mar 4, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Mar 4, 2026 •

edited

Loading

Uh oh!

davidmirror-ops Mar 4, 2026

Uh oh!

mhotan Mar 4, 2026

Uh oh!

mhotan commented Mar 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Summary

Test plan

Uh oh!

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

Uh oh!

Deploying docs with Cloudflare Pages

Uh oh!

davidmirror-ops Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

mhotan Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

mhotan commented Mar 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mhotan commented Mar 4, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Mar 4, 2026 •

edited

Loading