docs: generate the Omni Helm chart reference from the chart README

.github/workflows/build-omni-helm-chart-gen.yaml

@@ -0,0 +1,55 @@
+name: Build and Publish omni-helm-chart-gen Container
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "tools/omni-helm-chart-gen/**"
+      - ".github/workflows/build-omni-helm-chart-gen.yaml"
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: siderolabs/omni-helm-chart-gen
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: ./tools/omni-helm-chart-gen
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64,linux/arm64
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -21,6 +21,7 @@ tools/docs-convert/docs-convert
 tools/docs-validate/docs-validate
 tools/mdx-normalize/mdx-normalize
 tools/omni-config-gen/omni-config-gen
+tools/omni-helm-chart-gen/omni-helm-chart-gen
 tools/style-guide-checker/style-guide-checker
 tools/doc-accuracy/doc-accuracy
 tools/canonical-gen/canonical-gen

Makefile

@@ -11,6 +11,7 @@ VERSION_UPGRADE_IMAGE := ghcr.io/siderolabs/version-upgrade-gen:latest
 TALOSCTL_IMAGE := ghcr.io/siderolabs/talosctl:v1.15.0-alpha.1
 OMNI_CLI_GEN_IMAGE := ghcr.io/siderolabs/omni-cli-gen:latest
 OMNI_CONFIG_GEN_IMAGE := ghcr.io/siderolabs/omni-config-gen:latest
+OMNI_HELM_CHART_GEN_IMAGE := ghcr.io/siderolabs/omni-helm-chart-gen:latest
 MDX_NORMALIZE_IMAGE := ghcr.io/siderolabs/mdx-normalize:latest
 CANONICAL_GEN_IMAGE := ghcr.io/siderolabs/canonical-gen:latest
 STYLE_CHECK_IMAGE := ghcr.io/siderolabs/style-guide-checker:latest
@@ -274,6 +275,11 @@ OMNI_CONFIG_SCHEMA_URL ?= https://raw.githubusercontent.com/siderolabs/omni/refs
 OMNI_CONFIG_REF_PATH := public/omni/reference/omni-configuration.mdx
 OMNI_CLI_REF_PATH := public/omni/reference/cli.mdx
 IMAGE_FACTORY_REF_PATH := public/omni/reference/image-factory-configuration.mdx
+OMNI_HELM_CHART_REF_PATH := public/omni/reference/helm-chart.mdx
+# Tag or branch of siderolabs/omni to take the chart README from. Defaults to
+# omni_release in custom-variables.mdx, so the page matches the Omni version the
+# rest of the docs use. Bump the variable, then regenerate.
+OMNI_HELM_CHART_REF ?= $(shell sed -n "s/^export const omni_release = '\(.*\)'$$/\1/p" public/snippets/custom-variables.mdx)
 IMAGE_FACTORY_CONFIG_URL ?= https://raw.githubusercontent.com/siderolabs/image-factory/main/docs/configuration.md
 
 # Frontmatter for the generated pages. Defined here (not read from the existing
@@ -297,6 +303,10 @@ build-omni-cli-gen-container: ## Build the omni-cli-gen container locally
 build-omni-config-gen-container: ## Build the omni-config-gen container locally
 	docker build -t $(OMNI_CONFIG_GEN_IMAGE) ./tools/omni-config-gen
 
+.PHONY: build-omni-helm-chart-gen-container
+build-omni-helm-chart-gen-container: ## Build the omni-helm-chart-gen container locally
+	docker build -t $(OMNI_HELM_CHART_GEN_IMAGE) ./tools/omni-helm-chart-gen
+
 .PHONY: build-mdx-normalize-container
 build-mdx-normalize-container: ## Build the mdx-normalize container locally
 	docker build -t $(MDX_NORMALIZE_IMAGE) ./tools/mdx-normalize
@@ -533,13 +543,28 @@ generate-omni-image-factory-reference-local: ## Generate the Image Factory confi
 	@$(MAKE) --no-print-directory normalize-doc-local NORMALIZE_PATHS="$(IMAGE_FACTORY_REF_PATH)"
 	@echo "Reference documentation generated at $(IMAGE_FACTORY_REF_PATH)"
 
+.PHONY: generate-omni-helm-chart-reference
+generate-omni-helm-chart-reference: ## Generate the Omni Helm chart reference from the chart README (container). Pin with OMNI_HELM_CHART_REF=<tag>
+	@echo "Generating Omni Helm chart reference..."
+	@$(call pull_if_missing,$(OMNI_HELM_CHART_GEN_IMAGE))
+	docker run --rm $(OMNI_HELM_CHART_GEN_IMAGE) $(OMNI_HELM_CHART_REF) > $(OMNI_HELM_CHART_REF_PATH).tmp && mv $(OMNI_HELM_CHART_REF_PATH).tmp $(OMNI_HELM_CHART_REF_PATH) || { rm -f $(OMNI_HELM_CHART_REF_PATH).tmp; exit 1; }
+	@$(MAKE) --no-print-directory normalize-doc NORMALIZE_PATHS="$(OMNI_HELM_CHART_REF_PATH)"
+	@echo "Reference documentation generated at $(OMNI_HELM_CHART_REF_PATH)"
+
+.PHONY: generate-omni-helm-chart-reference-local
+generate-omni-helm-chart-reference-local: ## Generate the Omni Helm chart reference using local Go build. Pin with OMNI_HELM_CHART_REF=<tag>
+	@echo "Generating Omni Helm chart reference..."
+	cd tools/omni-helm-chart-gen && go run . $(OMNI_HELM_CHART_REF) > ../../$(OMNI_HELM_CHART_REF_PATH).tmp && mv ../../$(OMNI_HELM_CHART_REF_PATH).tmp ../../$(OMNI_HELM_CHART_REF_PATH) || { rm -f ../../$(OMNI_HELM_CHART_REF_PATH).tmp; exit 1; }
+	@$(MAKE) --no-print-directory normalize-doc-local NORMALIZE_PATHS="$(OMNI_HELM_CHART_REF_PATH)"
+	@echo "Reference documentation generated at $(OMNI_HELM_CHART_REF_PATH)"
+
 # ---- Aggregate -------------------------------------------------------------
 
 .PHONY: generate-omni-reference
-generate-omni-reference: generate-omni-cli-reference generate-omni-config-reference generate-omni-image-factory-reference ## Regenerate all Omni reference pages (containers)
+generate-omni-reference: generate-omni-cli-reference generate-omni-config-reference generate-omni-image-factory-reference generate-omni-helm-chart-reference ## Regenerate all Omni reference pages (containers)
 
 .PHONY: generate-omni-reference-local
-generate-omni-reference-local: generate-omni-cli-reference-local generate-omni-config-reference-local generate-omni-image-factory-reference-local ## Regenerate all Omni reference pages using local tools
+generate-omni-reference-local: generate-omni-cli-reference-local generate-omni-config-reference-local generate-omni-image-factory-reference-local generate-omni-helm-chart-reference-local ## Regenerate all Omni reference pages using local tools
 
 .PHONY: changelog
 changelog: ## Generate the changelog from GitHub releases

common.yaml

@@ -85,6 +85,8 @@ redirects:
     destination: "/talos/v1.14/:slug*"
   - source: "/omni/cluster-management/expose-an-http-service-from-a-cluster"
     destination: "/omni/cluster-management/expose-a-workload-via-service-proxy"
+  - source: "/omni/how-to-guides/self-hosted/how-to-expose-http-service-from-a-cluster"
+    destination: "/omni/cluster-management/expose-a-workload-via-service-proxy"
   - source: "/omni/cluster-management/omni-terraform"
     destination: "/omni/cluster-management/terraform-and-omni"
   - source: "/talos/v1.13/deploy-and-manage-workloads/workers-on-controlplane"

omni.yaml

@@ -141,6 +141,7 @@ navigation:
             - "omni-configuration.mdx"
             - "manage-omni-resources-with-omnictl.mdx"
             - "image-factory-configuration.mdx"
+            - "helm-chart.mdx"
 
         - group: Troubleshooting and Support
           folder: omni/troubleshooting

public/docs.json

@@ -86,6 +86,10 @@
       "source": "/omni/cluster-management/expose-an-http-service-from-a-cluster",
       "destination": "/omni/cluster-management/expose-a-workload-via-service-proxy"
     },
+    {
+      "source": "/omni/how-to-guides/self-hosted/how-to-expose-http-service-from-a-cluster",
+      "destination": "/omni/cluster-management/expose-a-workload-via-service-proxy"
+    },
     {
       "source": "/omni/cluster-management/omni-terraform",
       "destination": "/omni/cluster-management/terraform-and-omni"
@@ -2840,7 +2844,8 @@
               "omni/reference/cluster-templates",
               "omni/reference/omni-configuration",
               "omni/reference/manage-omni-resources-with-omnictl",
-              "omni/reference/image-factory-configuration"
+              "omni/reference/image-factory-configuration",
+              "omni/reference/helm-chart"
             ]
           },
           {