docs: Add page descriptions to the Kubernetes, concepts and guides pages (#895)

lfrancke · web-flow · commit 1f51229089ef · 2026-07-28T14:57:33.000Z
* docs: Add page descriptions to the Kubernetes, concepts and guides pages

27 pages had no :description: attribute, so search engines and the
generated llms.txt fall back to nothing or the raw title. Skipped on
purpose: modules/concepts/pages/stackable_resource_requests.adoc is an
include target published as a page; a :description: entry there would
leak into every including page and override their descriptions.

* docs: Delete the customer personas page

The internal module was never registered in the antora.yml nav and
nothing links to it, but Antora still published it at
/internal/personas/. Internal working material does not belong on the
public docs site.

* docs: Block /internal/ on every published docs version

The internal module is deleted on main, but the release branches still
contain it and Antora publishes their content too. A forced netlify 404
covers all versions at the serving layer without backporting the
deletion.

* docs: Describe the Kubernetes pages as notes, not instructions

Review feedback: descriptions state what a page covers instead of
telling the reader what to do.

* docs: Redirect the internal module to /404 without the extension

Review feedback: redirects to .html files cause issues.
diff --git a/modules/ROOT/pages/kubernetes/aks.adoc b/modules/ROOT/pages/kubernetes/aks.adoc
@@ -1,4 +1,5 @@
 = Azure Kubernetes Service (AKS)
+:description: Notes on running the Stackable Data Platform on Azure Kubernetes Service (AKS), covering cluster creation, networking and inbound traffic.
 
 https://azure.microsoft.com/en-us/products/kubernetes-service[https://azure.microsoft.com/en-us/products/kubernetes-service{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/eks.adoc b/modules/ROOT/pages/kubernetes/eks.adoc
@@ -1,4 +1,5 @@
 = Amazon Elastic Kubernetes Service (EKS)
+:description: Notes on running the Stackable Data Platform on Amazon Elastic Kubernetes Service (EKS), covering StorageClass requirements.
 
 https://aws.amazon.com/eks/[https://aws.amazon.com/eks/{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/gke.adoc b/modules/ROOT/pages/kubernetes/gke.adoc
@@ -1,4 +1,5 @@
 = Google Kubernetes Engine (GKE)
+:description: Notes on running the Stackable Data Platform on Google Kubernetes Engine (GKE). Autopilot clusters are not supported.
 
 https://cloud.google.com/kubernetes-engine[https://cloud.google.com/kubernetes-engine{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/huawei-cloud.adoc b/modules/ROOT/pages/kubernetes/huawei-cloud.adoc
@@ -1,4 +1,5 @@
 = Huawei Cloud Container Engine (CCE)
+:description: Notes on running the Stackable Data Platform on Huawei Cloud Container Engine (CCE), covering the non-standard Kubelet state directory.
 
 https://www.huaweicloud.com/intl/en-us/product/cce.html[https://www.huaweicloud.com/intl/en-us/product/cce.html{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/ibm-cloud.adoc b/modules/ROOT/pages/kubernetes/ibm-cloud.adoc
@@ -1,4 +1,5 @@
 = IBM Cloud Kubernetes Service
+:description: Notes on running the Stackable Data Platform on IBM Cloud Kubernetes Service, covering the non-standard Kubelet state directory.
 
 https://www.ibm.com/products/kubernetes-service[https://www.ibm.com/products/kubernetes-service{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/ionos-managed-k8s.adoc b/modules/ROOT/pages/kubernetes/ionos-managed-k8s.adoc
@@ -1,4 +1,5 @@
 = IONOS managed Kubernetes
+:description: Notes on running the Stackable Data Platform on IONOS managed Kubernetes.
 
 https://cloud.ionos.com/managed/kubernetes[https://cloud.ionos.com/managed/kubernetes{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/ionos-managed-stackable.adoc b/modules/ROOT/pages/kubernetes/ionos-managed-stackable.adoc
@@ -1,4 +1,5 @@
 = IONOS managed Stackable
+:description: Overview of Managed Stackable, the managed Stackable Data Platform offering from IONOS Cloud.
 
 https://cloud.ionos.com/managed/managed-stackable[https://cloud.ionos.com/managed/managed-stackable{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/k0s.adoc b/modules/ROOT/pages/kubernetes/k0s.adoc
@@ -1,4 +1,5 @@
 = k0s
+:description: Notes on running the Stackable Data Platform on k0s, covering the non-standard Kubelet state directory.
 
 https://k0sproject.io/[https://k0sproject.io/{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/kind.adoc b/modules/ROOT/pages/kubernetes/kind.adoc
@@ -1,3 +1,4 @@
 = kind
+:description: Notes on running the Stackable Data Platform on kind.
 
 https://kind.sigs.k8s.io/[https://kind.sigs.k8s.io/{external-link-icon}^]
diff --git a/modules/ROOT/pages/kubernetes/microk8s.adoc b/modules/ROOT/pages/kubernetes/microk8s.adoc
@@ -1,4 +1,5 @@
 = Microk8s
+:description: Notes on running the Stackable Data Platform on Microk8s, covering the non-standard Kubelet state directory.
 
 https://microk8s.io/[https://microk8s.io/{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/oke.adoc b/modules/ROOT/pages/kubernetes/oke.adoc
@@ -1,3 +1,4 @@
 = Oracle Kubernetes Engine (OKE)
+:description: Notes on running the Stackable Data Platform on Oracle Kubernetes Engine (OKE).
 
 https://www.oracle.com/cloud/cloud-native/kubernetes-engine/[https://www.oracle.com/cloud/cloud-native/kubernetes-engine/{external-link-icon}^]
diff --git a/modules/ROOT/pages/kubernetes/openshift.adoc b/modules/ROOT/pages/kubernetes/openshift.adoc
@@ -1,4 +1,5 @@
 = Red Hat OpenShift
+:description: Notes on running the Stackable Data Platform on Red Hat OpenShift, covering certified operators, Subscription customization and security context constraints.
 
 https://www.redhat.com/en/technologies/cloud-computing/openshift[https://www.redhat.com/en/technologies/cloud-computing/openshift{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/ovh-mks.adoc b/modules/ROOT/pages/kubernetes/ovh-mks.adoc
@@ -1,4 +1,5 @@
 = OVH Managed Kubernetes Service (MKS)
+:description: Notes on running the Stackable Data Platform on OVH Managed Kubernetes Service, covering the recommended ListenerClass preset.
 
 https://www.ovhcloud.com/en/public-cloud/kubernetes/[https://www.ovhcloud.com/en/public-cloud/kubernetes/{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/plusserver.adoc b/modules/ROOT/pages/kubernetes/plusserver.adoc
@@ -1,3 +1,4 @@
 = plusserver Kubernetes as a Service
+:description: Notes on running the Stackable Data Platform on plusserver's Kubernetes as a Service.
 
 https://www.plusserver.com/en/product/managed-kubernetes/[https://www.plusserver.com/en/product/managed-kubernetes/{external-link-icon}^]
diff --git a/modules/ROOT/pages/kubernetes/ske.adoc b/modules/ROOT/pages/kubernetes/ske.adoc
@@ -1,4 +1,5 @@
 = STACKIT Kubernetes Engine (SKE)
+:description: Notes on running the Stackable Data Platform on the STACKIT Kubernetes Engine (SKE), covering public IP assignment for nodes.
 
 https://www.stackit.de/de/produkt/stackit-kubernetes-engine/[https://www.stackit.de/de/produkt/stackit-kubernetes-engine/{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/kubernetes/suse-k3s.adoc b/modules/ROOT/pages/kubernetes/suse-k3s.adoc
@@ -1,3 +1,4 @@
 = SUSE K3S
+:description: Notes on running the Stackable Data Platform on SUSE K3S.
 
 https://www.suse.com/products/k3s/[https://www.suse.com/products/k3s/{external-link-icon}^]
diff --git a/modules/ROOT/pages/kubernetes/suse-rancher.adoc b/modules/ROOT/pages/kubernetes/suse-rancher.adoc
@@ -1,3 +1,4 @@
 = SUSE Rancher
+:description: Notes on running the Stackable Data Platform on SUSE Rancher.
 
 https://www.rancher.com/products/rancher[https://www.rancher.com/products/rancher{external-link-icon}^]
diff --git a/modules/ROOT/pages/kubernetes/vmware_tanzu.adoc b/modules/ROOT/pages/kubernetes/vmware_tanzu.adoc
@@ -1,4 +1,5 @@
 = VMware Tanzu
+:description: Notes on running the Stackable Data Platform on VMware Tanzu, covering the Kubelet path on BOSH-deployed clusters.
 
 https://www.vmware.com/products/app-platform/tanzu[https://www.vmware.com/products/app-platform/tanzu{external-link-icon}^]
 
diff --git a/modules/ROOT/pages/release-guide.adoc b/modules/ROOT/pages/release-guide.adoc
@@ -1,3 +1,4 @@
+:description: Work-in-progress internal guide with the git and cargo steps to cut a release and bump the next development version.
 
 
 (this is work in progress that is why it's not explicitely linked in nav.doc)
@@ -33,4 +34,3 @@ Bump dev version:
     git commit -am 'Bump next development version'
 
     git push -u origin bump-version
-
diff --git a/modules/compliance/pages/cra.adoc b/modules/compliance/pages/cra.adoc
@@ -1,4 +1,5 @@
 = Cyber Resilience Act (CRA)
+:description: Central hub for Cyber Resilience Act (CRA) information on the Stackable Data Platform, covering its classification and the Annex II user information.
 
 NOTE: The https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32024R2847[Cyber Resilience Act (CRA)] is a European regulation that establishes cybersecurity requirements for products with digital elements placed on the EU market.
 It aims to ensure that hardware and software products are designed, developed, and maintained with adequate cybersecurity throughout their lifecycle.
diff --git a/modules/concepts/pages/maintenance/crds.adoc b/modules/concepts/pages/maintenance/crds.adoc
@@ -1,4 +1,5 @@
 = CustomResourceDefinition (CRD) maintenance
+:description: How Stackable operators manage their own CRD lifecycle, including conversion webhook certificates and how to disable CRD maintenance.
 :k8s-webhook-config: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#configure-customresourcedefinition-to-use-conversion-webhooks
 
 Starting with SDP 25.11.0, specific operators now manage their own CRD lifecycle independently of Helm or other deployment tools.
diff --git a/modules/concepts/pages/maintenance/eos.adoc b/modules/concepts/pages/maintenance/eos.adoc
@@ -1,4 +1,5 @@
 = End-of-Support (EoS) check
+:description: Operators warn on startup and at regular intervals when reaching end-of-support, with Helm values to adjust the interval or disable the check.
 
 Starting with SDP 25.11.0, operators emit a warning message on startup and in a regular interval when it may have reached end-of-support.
 Most of the operators reach end-of-support one year after they have been released, which roughly translates to three SDP releases.
diff --git a/modules/concepts/pages/observability/containerdebug.adoc b/modules/concepts/pages/observability/containerdebug.adoc
@@ -1,4 +1,5 @@
 = Container environment
+:description: How the containerdebug tool regularly logs the container environment of Stackable-managed products, including interval and output locations.
 
 All Stackable-managed products regularly log information about their operating
 environment, such as available disk interfaces and network interfaces.
diff --git a/modules/concepts/pages/observability/telemetry.adoc b/modules/concepts/pages/observability/telemetry.adoc
@@ -1,4 +1,5 @@
 = Telemetry signals in operators
+:description: Helm values for operator telemetry: console logs, file logs and OpenTelemetry logs and traces via OTLP. Also covers collecting operator signals with Vector.
 :page-aliases: ../telemetry.adoc
 :env-filter-syntax: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax
 :vector-helm-chart: https://github.com/vectordotdev/helm-charts/tree/develop/charts/vector
diff --git a/modules/guides/pages/deploy-operators-and-csi-drivers-separately.adoc b/modules/guides/pages/deploy-operators-and-csi-drivers-separately.adoc
@@ -1,4 +1,5 @@
 = Deploying operators and CSI drivers on separate nodes
+:description: Guide to scheduling Stackable operators on dedicated nodes while running the Secret and Listener Operator CSI node drivers alongside workloads.
 :related-issue: https://github.com/stackabletech/issues/issues/763
 :secret-operator-values: https://github.com/stackabletech/secret-operator/blob/{stackable-operator-branch}/deploy/helm/secret-operator/values.yaml
 :listener-operator-values: https://github.com/stackabletech/listener-operator/blob/{stackable-operator-branch}/deploy/helm/listener-operator/values.yaml
diff --git a/modules/guides/pages/index.adoc b/modules/guides/pages/index.adoc
@@ -1,3 +1,4 @@
 = Guides
+:description: Overview of the guides section, which collects instructions for completing particular tasks with the Stackable Data Platform.
 
 The guides in this section are useful to complete particular tasks.
diff --git a/modules/internal/nav.adoc b/modules/internal/nav.adoc
diff --git a/modules/internal/pages/personas.adoc b/modules/internal/pages/personas.adoc
diff --git a/netlify.toml b/netlify.toml
@@ -7,6 +7,14 @@
   to = "https://hub.stackable.tech/crds"
   status = 301
 
+# The internal module is deleted on main but still exists on the release
+# branches; this blocks it for every published version without backports.
+[[redirects]]
+  from = "/home/:version/internal/*"
+  to = "/404"
+  status = 404
+  force = true
+
 [[redirects]]
   from = "/home/stable/release_notes.html"
   to = "/home/stable/release-notes"

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= Azure Kubernetes Service (AKS)`
	`2`	`+:description: Notes on running the Stackable Data Platform on Azure Kubernetes Service (AKS), covering cluster creation, networking and inbound traffic.`
`2`	`3`
`3`	`4`	`https://azure.microsoft.com/en-us/products/kubernetes-service[https://azure.microsoft.com/en-us/products/kubernetes-service{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= Amazon Elastic Kubernetes Service (EKS)`
	`2`	`+:description: Notes on running the Stackable Data Platform on Amazon Elastic Kubernetes Service (EKS), covering StorageClass requirements.`
`2`	`3`
`3`	`4`	`https://aws.amazon.com/eks/[https://aws.amazon.com/eks/{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= Google Kubernetes Engine (GKE)`
	`2`	`+:description: Notes on running the Stackable Data Platform on Google Kubernetes Engine (GKE). Autopilot clusters are not supported.`
`2`	`3`
`3`	`4`	`https://cloud.google.com/kubernetes-engine[https://cloud.google.com/kubernetes-engine{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= Huawei Cloud Container Engine (CCE)`
	`2`	`+:description: Notes on running the Stackable Data Platform on Huawei Cloud Container Engine (CCE), covering the non-standard Kubelet state directory.`
`2`	`3`
`3`	`4`	`https://www.huaweicloud.com/intl/en-us/product/cce.html[https://www.huaweicloud.com/intl/en-us/product/cce.html{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= IBM Cloud Kubernetes Service`
	`2`	`+:description: Notes on running the Stackable Data Platform on IBM Cloud Kubernetes Service, covering the non-standard Kubelet state directory.`
`2`	`3`
`3`	`4`	`https://www.ibm.com/products/kubernetes-service[https://www.ibm.com/products/kubernetes-service{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= IONOS managed Kubernetes`
	`2`	`+:description: Notes on running the Stackable Data Platform on IONOS managed Kubernetes.`
`2`	`3`
`3`	`4`	`https://cloud.ionos.com/managed/kubernetes[https://cloud.ionos.com/managed/kubernetes{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= IONOS managed Stackable`
	`2`	`+:description: Overview of Managed Stackable, the managed Stackable Data Platform offering from IONOS Cloud.`
`2`	`3`
`3`	`4`	`https://cloud.ionos.com/managed/managed-stackable[https://cloud.ionos.com/managed/managed-stackable{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= k0s`
	`2`	`+:description: Notes on running the Stackable Data Platform on k0s, covering the non-standard Kubelet state directory.`
`2`	`3`
`3`	`4`	`https://k0sproject.io/[https://k0sproject.io/{external-link-icon}^]`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
`1`	`1`	`= kind`
	`2`	`+:description: Notes on running the Stackable Data Platform on kind.`
`2`	`3`
`3`	`4`	`https://kind.sigs.k8s.io/[https://kind.sigs.k8s.io/{external-link-icon}^]`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`= Microk8s`
	`2`	`+:description: Notes on running the Stackable Data Platform on Microk8s, covering the non-standard Kubelet state directory.`
`2`	`3`
`3`	`4`	`https://microk8s.io/[https://microk8s.io/{external-link-icon}^]`
`4`	`5`