feat(cloud-regions): honor custom templates and add --cluster-type filter

CLI_REFERENCE.adoc

@@ -1027,6 +1027,9 @@ Git reference (branch, tag, or commit SHA) (default: "integration")
 `--template <path>`::
 Path to custom Handlebars template (relative to repo root)
 
+`--cluster-type <type>`::
+Only include regions/tiers available for this cluster type: BYOC or Dedicated
+
 `--dry-run`::
 Print output to stdout instead of writing file
 
@@ -1054,6 +1057,12 @@ export GITHUB_TOKEN=ghp_xxx
 npx doc-tools generate cloud-regions \
   --output custom/path/regions.md
 
+# Generate an AsciiDoc partial for one cluster type with a custom template
+export GITHUB_TOKEN=ghp_xxx
+npx doc-tools generate cloud-regions --format adoc --cluster-type BYOC \
+  --template docs-data/templates/cloud-regions.hbs \
+  --output modules/reference/partials/generated/regions-byoc.adoc
+
 # Use different branch for testing
 export GITHUB_TOKEN=ghp_xxx
 npx doc-tools generate cloud-regions --ref staging

__tests__/tools/generate-cloud-regions.test.js

@@ -0,0 +1,85 @@
+const { processCloudRegions } = require('../../tools/cloud-regions/generate-cloud-regions');
+
+const sampleYaml = `
+regions:
+  - name: us-east-1
+    cloudProvider: CLOUD_PROVIDER_AWS
+    zones: [use1-az1, use1-az2]
+    redpandaProductAvailability:
+      tier-1-aws:
+        redpandaProductName: tier-1-aws
+        clusterTypes: [CLUSTER_TYPE_BYOC, CLUSTER_TYPE_DEDICATED]
+      tier-2-aws:
+        redpandaProductName: tier-2-aws
+        clusterTypes: [CLUSTER_TYPE_BYOC]
+      tier-private-aws:
+        redpandaProductName: tier-private-aws
+        clusterTypes: [CLUSTER_TYPE_BYOC]
+  - name: eu-west-3
+    cloudProvider: CLOUD_PROVIDER_AWS
+    zones: [euw3-az1]
+    redpandaProductAvailability:
+      tier-1-aws:
+        redpandaProductName: tier-1-aws
+        clusterTypes: [CLUSTER_TYPE_DEDICATED]
+  - name: us-west1
+    cloudProvider: CLOUD_PROVIDER_GCP
+    zones: [us-west1-a]
+    redpandaProductAvailability:
+      tier-1-gcp:
+        redpandaProductName: tier-1-gcp
+        clusterTypes: [CLUSTER_TYPE_FMC]
+products:
+  - name: tier-1-aws
+    isPublic: true
+  - name: tier-2-aws
+    isPublic: true
+  - name: tier-1-gcp
+    isPublic: true
+  - name: tier-private-aws
+    isPublic: false
+`;
+
+function regionNames(providers, providerName) {
+  const provider = providers.find((p) => p.name === providerName);
+  return provider ? provider.regions.map((r) => r.name) : [];
+}
+
+describe('processCloudRegions', () => {
+  it('includes all cluster types when no filter is given', () => {
+    const providers = processCloudRegions(sampleYaml);
+    expect(providers.map((p) => p.displayName)).toEqual(['Google Cloud Platform (GCP)', 'Amazon Web Services (AWS)']);
+    expect(regionNames(providers, 'AWS')).toEqual(['us-east-1', 'eu-west-3']);
+    expect(regionNames(providers, 'GCP')).toEqual(['us-west1']);
+    const usEast = providers.find((p) => p.name === 'AWS').regions[0];
+    expect(usEast.tiers).toContain('tier-1-aws: BYOC, Dedicated');
+    expect(usEast.tiers.join()).not.toContain('tier-private-aws');
+  });
+
+  it('filters regions and tiers by cluster type BYOC', () => {
+    const providers = processCloudRegions(sampleYaml, { clusterType: 'BYOC' });
+    // eu-west-3 is Dedicated-only, so it must be dropped
+    expect(regionNames(providers, 'AWS')).toEqual(['us-east-1']);
+    // us-west1 is FMC-only, which maps to Dedicated
+    expect(regionNames(providers, 'GCP')).toEqual([]);
+    const usEast = providers.find((p) => p.name === 'AWS').regions[0];
+    expect(usEast.tiers).toEqual(['tier-1-aws: BYOC', 'tier-2-aws: BYOC']);
+  });
+
+  it('filters by cluster type Dedicated and maps FMC to Dedicated', () => {
+    const providers = processCloudRegions(sampleYaml, { clusterType: 'Dedicated' });
+    expect(regionNames(providers, 'AWS')).toEqual(['us-east-1', 'eu-west-3']);
+    expect(regionNames(providers, 'GCP')).toEqual(['us-west1']);
+    const usEast = providers.find((p) => p.name === 'AWS').regions[0];
+    expect(usEast.tiers).toEqual(['tier-1-aws: Dedicated']);
+  });
+
+  it('accepts the cluster type case-insensitively', () => {
+    const providers = processCloudRegions(sampleYaml, { clusterType: 'byoc' });
+    expect(regionNames(providers, 'AWS')).toEqual(['us-east-1']);
+  });
+
+  it('throws on an unsupported cluster type', () => {
+    expect(() => processCloudRegions(sampleYaml, { clusterType: 'Serverless' })).toThrow(/Unsupported cluster type/);
+  });
+});

__tests__/tools/render-cloud-regions.test.js

@@ -1,3 +1,6 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const renderCloudRegions = require('../../tools/cloud-regions/render-cloud-regions');
 
 const sampleProviders = [
@@ -48,4 +51,22 @@ describe('renderCloudRegions', () => {
   it('throws for empty providers', () => {
     expect(() => renderCloudRegions({ providers: [], format: 'md' })).toThrow();
   });
+
+  it('renders a custom template when one is provided', () => {
+    const templateFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'cloud-regions-')), 'custom.hbs');
+    fs.writeFileSync(templateFile, '{{#each providers}}PROVIDER:{{name}} {{#each regions}}[{{name}}]{{/each}}\n{{/each}}', 'utf8');
+    try {
+      const out = renderCloudRegions({ providers: sampleProviders, format: 'adoc', template: templateFile });
+      expect(out).toContain('PROVIDER:GCP [europe-west1][us-central1]');
+      expect(out).toContain('PROVIDER:AWS [us-east-1]');
+      expect(out).not.toContain('=== GCP');
+    } finally {
+      fs.rmSync(path.dirname(templateFile), { recursive: true, force: true });
+    }
+  });
+
+  it('falls back to the bundled template when no custom template is provided', () => {
+    const out = renderCloudRegions({ providers: sampleProviders, format: 'adoc' });
+    expect(out).toContain('=== GCP');
+  });
 });

bin/doc-tools-mcp.js

@@ -318,6 +318,11 @@ const tools = [
           type: 'string',
           description: 'Path to custom Handlebars template relative to repo root (optional)'
         },
+        cluster_type: {
+          type: 'string',
+          description: 'Only include regions/tiers available for this cluster type (optional)',
+          enum: ['BYOC', 'Dedicated']
+        },
         dry_run: {
           type: 'boolean',
           description: 'Print output to stdout instead of writing file (optional, defaults to false)'

bin/doc-tools.js

@@ -1813,6 +1813,12 @@ automation
  * npx doc-tools generate cloud-regions \
  *   --output custom/path/regions.md
  *
+ * # Generate an AsciiDoc partial for one cluster type with a custom template
+ * export GITHUB_TOKEN=ghp_xxx
+ * npx doc-tools generate cloud-regions --format adoc --cluster-type BYOC \
+ *   --template docs-data/templates/cloud-regions.hbs \
+ *   --output modules/reference/partials/generated/regions-byoc.adoc
+ *
  * # Use different branch for testing
  * export GITHUB_TOKEN=ghp_xxx
  * npx doc-tools generate cloud-regions --ref staging
@@ -1832,6 +1838,7 @@ automation
   .option('--path <path>', 'Path to YAML file in repository', 'apps/master-data-reconciler/manifests/overlays/production/master-data.yaml')
   .option('--ref <ref>', 'Git reference (branch, tag, or commit SHA)', 'integration')
   .option('--template <path>', 'Path to custom Handlebars template (relative to repo root)')
+  .option('--cluster-type <type>', 'Only include regions/tiers available for this cluster type: BYOC or Dedicated')
   .option('--dry-run', 'Print output to stdout instead of writing file')
   .action(async (options) => {
     const { generateCloudRegions } = require('../tools/cloud-regions/generate-cloud-regions.js')
@@ -1858,7 +1865,8 @@ automation
         ref: options.ref,
         format: fmt,
         token,
-        template: templatePath
+        template: templatePath,
+        clusterType: options.clusterType
       })
       if (options.dryRun) {
         process.stdout.write(out)

bin/mcp-tools/cloud-regions.js

@@ -16,6 +16,7 @@ const { getAntoraStructure } = require('./antora');
  * @param {string} [args.path] - Path to YAML file in repository
  * @param {string} [args.ref] - Git reference (branch, tag, or commit SHA)
  * @param {string} [args.template] - Path to custom Handlebars template
+ * @param {string} [args.cluster_type] - Only include regions/tiers available for this cluster type ('BYOC' or 'Dedicated')
  * @param {boolean} [args.dry_run] - Print output to stdout instead of writing file
  * @returns {Object} Generation results
  */
@@ -73,6 +74,11 @@ function generateCloudRegions(args = {}) {
       baseArgs.push(args.template);
     }
 
+    if (args.cluster_type) {
+      baseArgs.push('--cluster-type');
+      baseArgs.push(args.cluster_type);
+    }
+
     if (args.dry_run) {
       baseArgs.push('--dry-run');
     }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

tools/cloud-regions/generate-cloud-regions.js

@@ -40,6 +40,11 @@ const providerMap = {
   CLOUD_PROVIDER_AZURE: 'Azure',
 };
 const providerOrder = ['GCP', 'AWS', 'Azure'];
+const providerDisplayNames = {
+  GCP: 'Google Cloud Platform (GCP)',
+  AWS: 'Amazon Web Services (AWS)',
+  Azure: 'Azure',
+};
 const clusterTypeMap = {
   CLUSTER_TYPE_BYOC: 'BYOC',
   CLUSTER_TYPE_DEDICATED: 'Dedicated',
@@ -110,10 +115,20 @@ async function fetchYaml({ owner, repo, path, ref = 'main', token }) {
  * The function expects YAML content with a top-level `regions` array and an optional `products` array. It groups regions by cloud provider, includes only those with at least one public product tier, and formats tier and cluster type information for each region. Providers and regions without public tiers are excluded from the result.
  *
  * @param {string} yamlText - The YAML content to parse and process.
+ * @param {Object} [options] - Processing options.
+ * @param {string} [options.clusterType] - Optional cluster type display name ('BYOC' or 'Dedicated', case-insensitive). When set, only tiers available for that cluster type are included, and regions with no matching tiers are dropped.
  * @return {Array<Object>} An array of provider objects, each containing a name and a list of regions with their available public product tiers.
  * @throws {Error} If the YAML is malformed or missing the required `regions` array.
  */
-function processCloudRegions(yamlText) {
+function processCloudRegions(yamlText, { clusterType } = {}) {
+  let clusterTypeFilter;
+  if (clusterType) {
+    const validClusterTypes = [...new Set(Object.values(clusterTypeMap))];
+    clusterTypeFilter = validClusterTypes.find((ct) => ct.toLowerCase() === String(clusterType).toLowerCase());
+    if (!clusterTypeFilter) {
+      throw new Error(`Unsupported cluster type: ${clusterType}. Use one of: ${validClusterTypes.join(', ')}.`);
+    }
+  }
   let data;
   try {
     data = jsYaml.load(yamlText);
@@ -152,7 +167,8 @@ function processCloudRegions(yamlText) {
     .map((prov) => {
       // Only include regions that have at least one public product/tier
       const filteredRegions = grouped[prov].map((region) => {
-        const zones = Array.isArray(region.zones) ? region.zones.join(',') : (region.zones || '');
+        // Join with ', ' so long zone lists can wrap inside table cells
+        const zones = Array.isArray(region.zones) ? region.zones.join(', ') : (region.zones || '');
         let tiers = [];
         if (region.redpandaProductAvailability && typeof region.redpandaProductAvailability === 'object') {
           // Group by tier name, collect all cluster types for that tier
@@ -161,11 +177,14 @@ function processCloudRegions(yamlText) {
             if (!t.redpandaProductName || !publicProductNames.has(t.redpandaProductName)) {
               continue;
             }
+            let displayTypes = Array.isArray(t.clusterTypes) ? t.clusterTypes.map(displayClusterType) : [];
+            if (clusterTypeFilter) {
+              displayTypes = displayTypes.filter((ct) => ct === clusterTypeFilter);
+              if (displayTypes.length === 0) continue;
+            }
             const productName = t.redpandaProductName;
             if (!tierMap[productName]) tierMap[productName] = new Set();
-            if (Array.isArray(t.clusterTypes)) {
-              for (const ct of t.clusterTypes) tierMap[productName].add(displayClusterType(ct));
-            }
+            for (const ct of displayTypes) tierMap[productName].add(ct);
           }
           tiers = Object.entries(tierMap)
             .map(([productName, cts]) => `${productName}: ${Array.from(cts).sort().join(', ')}`)
@@ -182,6 +201,7 @@ function processCloudRegions(yamlText) {
       }
       return {
         name: prov,
+        displayName: providerDisplayNames[prov] || prov,
         regions: filteredRegions,
       };
     })
@@ -206,10 +226,11 @@ function processCloudRegions(yamlText) {
  * @param {string} [options.format='md'] - The output format (for example, 'md' for Markdown).
  * @param {string} [options.token] - Optional GitHub token for authentication.
  * @param {string} [options.template] - Optional path to custom Handlebars template.
+ * @param {string} [options.clusterType] - Optional cluster type filter ('BYOC' or 'Dedicated', case-insensitive).
  * @returns {string} The rendered cloud regions output.
  * @throws {Error} If fetching, processing, or rendering fails, or if no valid providers or regions are found.
  */
-async function generateCloudRegions({ owner, repo, path, ref = 'main', format = 'md', token, template }) {
+async function generateCloudRegions({ owner, repo, path, ref = 'main', format = 'md', token, template, clusterType }) {
   let yamlText;
   try {
     yamlText = await fetchYaml({ owner, repo, path, ref, token });
@@ -219,7 +240,7 @@ async function generateCloudRegions({ owner, repo, path, ref = 'main', format =
   }
   let providers;
   try {
-    providers = processCloudRegions(yamlText);
+    providers = processCloudRegions(yamlText, { clusterType });
   } catch (err) {
     console.error(`[cloud-regions] ERROR: Failed to process cloud regions: ${err.message}`);
     throw err;

tools/cloud-regions/render-cloud-regions.js

@@ -12,10 +12,11 @@ const handlebars = require('handlebars');
  * @param {Array} opts.providers - List of cloud provider objects, each with a name and an array of regions.
  * @param {string} opts.format - Output format, either 'md' (Markdown) or 'adoc' (AsciiDoc).
  * @param {string} [opts.lastUpdated] - Optional ISO timestamp indicating when the data was last updated.
+ * @param {string} [opts.template] - Optional absolute path to a custom Handlebars template. Overrides the bundled template for the given format.
  * @returns {string} The rendered output string.
  * @throws {Error} If the providers array is missing or empty.
  */
-function renderCloudRegions({ providers, format, lastUpdated }) {
+function renderCloudRegions({ providers, format, lastUpdated, template }) {
   if (!Array.isArray(providers) || providers.length === 0) {
     throw new Error('No providers/regions found in YAML.');
   }
@@ -27,19 +28,19 @@ function renderCloudRegions({ providers, format, lastUpdated }) {
     ...provider,
     regions: [...provider.regions].sort((a, b) => a.name.localeCompare(b.name))
   }));
-  const templateFile = path.join(__dirname, `cloud-regions-table-${format}.hbs`);
+  const templateFile = template || path.join(__dirname, `cloud-regions-table-${format}.hbs`);
   if (!fs.existsSync(templateFile)) {
     throw new Error(`Template file not found: ${templateFile}`);
   }
-  let templateSrc, template;
+  let compiledTemplate;
   try {
-    templateSrc = fs.readFileSync(templateFile, 'utf8');
-    template = handlebars.compile(templateSrc);
+    const templateSrc = fs.readFileSync(templateFile, 'utf8');
+    compiledTemplate = handlebars.compile(templateSrc);
   } catch (err) {
     throw new Error(`Failed to compile Handlebars template at ${templateFile}: ${err.message}`);
   }
   try {
-    return template({ providers: sortedProviders, lastUpdated });
+    return compiledTemplate({ providers: sortedProviders, lastUpdated });
   } catch (err) {
     throw new Error(`Failed to render Handlebars template at ${templateFile}: ${err.message}`);
   }