helm and metrics script

Signed-off-by: Art Berger <art.berger@solo.io>

Author: artberger

.github/workflows/generate-ref-docs.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Generate Helm and metrics reference documentation for the agentgateway website.
+
+Reads version config from .github/workflows/versions.json. Generates only
+agentgateway-relevant artifacts from a checked-out kgateway repo:
+- Helm: agentgateway and agentgateway-crds charts -> assets/agw-docs/pages/reference/helm/{version}/
+- Metrics: control plane metrics -> assets/agw-docs/snippets/{metricsSnippet} (metricsSnippet from versions.json, e.g. metrics-control-plane-22x.md)
+
+API reference docs are generated by the workflow (reference-docs.yaml) and are not handled here.
+
+Usage (from workflow):
+  DOC_VERSION=2.2.x python3 .github/workflows/generate-ref-docs.py
+  (run from website repo root; kgateway clone is at ./kgateway)
+"""
+
+import json
+import os
+import platform
+import subprocess
+import sys
+
+
+# Agentgateway-only Helm charts: directory under install/helm : output filename
+HELM_CHARTS = [
+    ("agentgateway", "agentgateway"),
+    ("agentgateway-crds", "agentgateway-crds"),
+]
+
+
+def generate_helm_docs(version: str, website_dir: str, kgateway_dir: str) -> bool:
+    """Generate Helm chart reference docs for agentgateway and agentgateway-crds."""
+    print(f"  → Generating Helm docs for version {version}")
+
+    assets_path = os.path.join(website_dir, "assets", "agw-docs", "pages", "reference", "helm", version)
+    os.makedirs(assets_path, exist_ok=True)
+    generated_any = False
+
+    for dir_name, file_name in HELM_CHARTS:
+        helm_path = os.path.join(kgateway_dir, "install", "helm", dir_name)
+        if not os.path.exists(helm_path):
+            print(f"    Warning: {helm_path} does not exist, skipping {file_name}")
+            continue
+
+        result = subprocess.run(
+            [
+                "go", "run", "github.com/norwoodj/helm-docs/cmd/helm-docs@v1.14.2",
+                f"--chart-search-root={helm_path}",
+                "--dry-run",
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        helm_file = os.path.join(assets_path, f"{file_name}.md")
+        with open(helm_file, "w") as f:
+            f.write(result.stdout)
+
+        # Remove version badge and first 3 lines (title, blank, description)
+        if platform.system() == "Darwin":
+            subprocess.run(["sed", "-i", "", r"/!\[Version:/,/^$/d", helm_file], check=True)
+            subprocess.run(["sed", "-i", "", "1,3d", helm_file], check=True)
+        else:
+            subprocess.run(["sed", "-i", r"/!\[Version:/,/^$/d", helm_file], check=True)
+            subprocess.run(["sed", "-i", "1,3d", helm_file], check=True)
+
+        with open(helm_file, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        content = content.replace('{{< callout type=info >}}', '{{< callout type="info" >}}')
+        if "## Values" not in content or ("## Values" in content and "|-----|" not in content):
+            note = '\n\n{{< callout type="info" >}}\nNo configurable values are currently available for this chart.\n{{< /callout >}}\n'
+            if "{{< callout" not in content:
+                content = content.rstrip() + note
+
+        # Swap Default and Description columns
+        swapped_lines = []
+        in_table = False
+        for line in content.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("| Key ") and "Default" in line and "Description" in line:
+                in_table = True
+                swapped_lines.append("| Key | Type | Description | Default |")
+                continue
+            if in_table and stripped.startswith("|-----"):
+                swapped_lines.append("|-----|------|-------------|---------|")
+                continue
+            if in_table and stripped.startswith("|"):
+                parts = [p.strip() for p in line.split("|")]
+                if len(parts) >= 6:
+                    key, typ, default, desc = parts[1], parts[2], parts[3], parts[4]
+                    swapped_lines.append(f"| {key} | {typ} | {desc} | {default} |")
+                else:
+                    swapped_lines.append(line)
+            else:
+                if in_table and not stripped.startswith("|"):
+                    in_table = False
+                swapped_lines.append(line)
+        content = "\n".join(swapped_lines)
+
+        with open(helm_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        print(f"    ✓ Generated {helm_file}")
+        generated_any = True
+
+    return generated_any
+
+
+def generate_metrics_docs(version: str, website_dir: str, kgateway_dir: str, metrics_snippet: str) -> bool:
+    """Generate control plane metrics into a versioned snippet (e.g. metrics-control-plane-22x.md)."""
+    print(f"  → Generating metrics docs for version {version}")
+
+    snippets_dir = os.path.join(website_dir, "assets", "agw-docs", "snippets")
+    os.makedirs(snippets_dir, exist_ok=True)
+    out_file = os.path.join(snippets_dir, metrics_snippet)
+
+    try:
+        result = subprocess.run(
+            ["go", "run", "./pkg/metrics/cmd/findmetrics", "--markdown", "."],
+            capture_output=True,
+            text=True,
+            check=True,
+            cwd=kgateway_dir,
+        )
+        md_content = result.stdout
+    except subprocess.CalledProcessError as e:
+        print(f"    Warning: findmetrics failed: {e.stderr or e}")
+        return False
+
+    with open(out_file, "w") as f:
+        f.write(md_content)
+    print(f"    ✓ Generated {out_file}")
+    return True
+
+
+def main() -> None:
+    doc_version = os.environ.get("DOC_VERSION", "").strip()
+    if not doc_version:
+        print("Error: DOC_VERSION must be set (e.g. 2.2.x, 2.3.x)")
+        sys.exit(1)
+
+    website_dir = os.environ.get("WEBSITE_DIR", ".")
+    kgateway_dir = os.environ.get("KGATEWAY_DIR", "kgateway")
+
+    versions_file = os.path.join(website_dir, ".github", "workflows", "versions.json")
+    if not os.path.exists(versions_file):
+        print(f"Error: {versions_file} not found")
+        sys.exit(1)
+
+    with open(versions_file) as f:
+        versions = json.load(f)
+    entry = next((v for v in versions if v.get("version") == doc_version), None)
+    if not entry:
+        print(f"Error: version {doc_version} not in versions.json")
+        sys.exit(1)
+
+    # Snippet filename for metrics (e.g. metrics-control-plane-22x.md); fallback: derive from version
+    metrics_snippet = entry.get("metricsSnippet") or f"metrics-control-plane-{doc_version.replace('.', '')}.md"
+
+    if not os.path.isdir(kgateway_dir):
+        print(f"Error: kgateway directory not found at {kgateway_dir}")
+        sys.exit(1)
+
+    print(f"Generating Helm + metrics for version {doc_version} (kgateway at {kgateway_dir})")
+    success = 0
+    if generate_helm_docs(doc_version, website_dir, kgateway_dir):
+        success += 1
+    if generate_metrics_docs(doc_version, website_dir, kgateway_dir, metrics_snippet):
+        success += 1
+    print(f"Done: generated {success}/2 doc types")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/versions.json

@@ -4,13 +4,15 @@
     "linkVersion": "main",
     "url": "main",
     "apiFile": "api-23x.md",
-    "kgatewayRef": "main"
+    "kgatewayRef": "main",
+    "metricsSnippet": "metrics-control-plane-23x.md"
   },
   {
     "version": "2.2.x",
     "linkVersion": "latest",
     "url": "latest",
     "apiFile": "api-22x.md",
-    "kgatewayRef": "v2.2.x"
+    "kgatewayRef": "v2.2.x",
+    "metricsSnippet": "metrics-control-plane-22x.md"
   }
 ]

assets/agw-docs/pages/observability/control-plane-metrics.md

@@ -41,4 +41,9 @@ Helpful terms:
 
 * Transform: The process of the control plane converting high-level resources or intermediate representations (IR) into lower-level representations into the structure that the XDS API expects for a snapshot.
 
-{{< reuse "agw-docs/snippets/latest/metrics-control-plane.md" >}}
+{{< version include-if="2.2.x" >}}
+{{< reuse "agw-docs/snippets/metrics-control-plane-22x.md" >}}
+{{< /version >}}
+{{< version include-if="2.3.x" >}}
+{{< reuse "agw-docs/snippets/metrics-control-plane-23x.md" >}}
+{{< /version >}}

assets/agw-docs/snippets/main/metrics-control-plane.md

@@ -14,9 +14,6 @@ kgateway_status_syncer_status_syncs_total|counter|name, namespace, syncer, resul
 kgateway_translator_translation_duration_seconds|histogram|name, namespace, translator|Translation duration
 kgateway_translator_translations_running|gauge|name, namespace, translator|Current number of translations running
 kgateway_translator_translations_total|counter|name, namespace, translator, result|Total number of translations
-kgateway_xds_auth_rq_failure_total|counter||Total number of failed xDS auth requests
-kgateway_xds_auth_rq_success_total|counter||Total number of successful xDS auth requests
-kgateway_xds_auth_rq_total|counter||Total number of xDS auth requests
 kgateway_xds_snapshot_resources|gauge|gateway, namespace, resource|Current number of resources in XDS snapshot
 kgateway_xds_snapshot_sync_duration_seconds|histogram|gateway, namespace|Duration of time for a gateway resource update to be synced in an XDS snapshot
 kgateway_xds_snapshot_syncs_total|counter|gateway, namespace|Total number of XDS snapshot syncs