How the Starship Generator Package Creates Kubernetes Manifests

The generator package is the core engine that transforms Starship's declarative configuration into production-ready Kubernetes YAML manifests through a modular builder pattern.

The generator package within the hyperweb-io/starship monorepo serves as the primary translation layer between high-level infrastructure definitions and executable Kubernetes objects. By implementing a builder pattern architecture, it reads a single configuration file—such as src/configs/defaults.yaml—and orchestrates the creation of ConfigMaps, StatefulSets, Services, and Ingress resources required to run blockchain networks, relayers, and monitoring components.

Core Architecture: Builder Pattern and Sub-Generators

The generator implements a builder pattern where a top-level Generator class coordinates multiple specialized sub-generators. Each sub-generator is responsible for emitting specific Kubernetes resource types based on the configuration provided.

Top-Level Orchestration

In src/index.ts, the public Generator class serves as the entry point that instantiates and coordinates all sub-generators. This top-level orchestrator reads the complete Starship configuration and delegates resource creation to specialized builders for chains, relayers, monitoring, and frontend components.

Specialized Sub-Generators

Each sub-generator implements the IGenerator interface and focuses on a specific domain:

• Chain Builders (src/builders/chains/index.ts): Dispatch per-chain implementations for Cosmos, Ethereum, and other blockchain types, generating StatefulSets and Services for node containers.
• Relayer Builders (src/builders/relayers/index.ts): Construct ConfigMaps, Services, and StatefulSets for each relayer implementation.
• Registry Builder (src/builders/registry.ts): Generates the Registry service components including ConfigMaps, Deployments, and Services.
• Monitoring Builder (src/builders/monitoring.ts): Produces Prometheus and Grafana objects for network observability.
• Ingress Builder (src/builders/ingress.ts): Creates Ingress resources and optional CertificateIssuer objects for external access.
• Frontend Builder (src/builders/frontend.ts): Generates UI services and deployments for explorers and faucets.
• Explorer Builder (src/builders/explorer.ts): Specifically handles the blockchain explorer component.

Configuration Ingestion and Processing

The generator begins by ingesting a single configuration file that describes the desired infrastructure state. By default, it references src/configs/defaults.yaml when no custom configuration is supplied.

This configuration specifies which chains, relayers, monitoring components, ingress rules, and UI services should be deployed. The Generator class parses this declarative specification and initializes the appropriate sub-generators based on the detected components.

The Manifest Generation Pipeline

Every sub-generator implements a generate(): string[] method that returns an array of YAML strings representing Kubernetes manifests. The top-level generator collects these arrays from all active sub-generators and flattens them into a single manifest list.

This pipeline produces ready-to-apply YAML documents that can be written to disk or piped directly to kubectl apply. The generate() method ensures each component outputs properly formatted Kubernetes resources including ConfigMaps for chain-specific scripts and genesis data, Services and StatefulSets for blockchain nodes, and Deployments for auxiliary services.

Extending the Generator with Custom Builders

Adding support for new chain types or custom components requires implementing the IGenerator interface. Developers create a new builder class that exposes the standard generate() method, and the top-level orchestrator automatically discovers and invokes it based on the configuration.

Generating Complete Manifest Sets

To produce the full set of Kubernetes manifests from a configuration file:

import { Generator } from '@starship/generator'   // ← package entry point
import * as fs from 'fs'

// Load a Starship config (YAML or JSON)
const config = fs.readFileSync('starship.yaml', 'utf8')

// Instantiate the generator
const gen = new Generator(config)

// Produce the full set of Kubernetes manifests
const manifests = gen.generate()   // returns string[] of YAML docs

// Write each manifest to a separate file (optional)
manifests.forEach((doc, i) => {
  fs.writeFileSync(`manifest-${i}.yaml`, doc)
})

Targeting Specific Components

For generating manifests for only a specific component, such as the monitoring stack:

import { MonitoringBuilder } from '@starship/generator/builders/monitoring'

// `config` must contain the monitoring section
const monitoring = new MonitoringBuilder(config)
const yamlDocs = monitoring.generate()   // Deployments, Services, ConfigMaps, etc.
console.log(yamlDocs.join('\n---\n'))

Adding Custom Chain Support

To extend the generator with a custom Cosmos chain:

import { CosmosChainBuilder } from '@starship/generator/builders/chains/cosmos'

// Extend the default config with your chain definition
const myChainConfig = { name: 'mychain', … }
const chainBuilder = new CosmosChainBuilder(myChainConfig, fullConfig)

// Generate the chain-specific manifests (StatefulSet, Service, ConfigMaps)
const chainManifests = chainBuilder.generate()

Key Source Files and Responsibilities

The generator package consists of the following critical files:

• src/index.ts: Public entry point; creates the top-level Generator that coordinates all sub-generators.
• src/builders/chains/index.ts: Dispatches per-chain builders for Cosmos, Ethereum, and other protocols.
• src/builders/relayers/index.ts: Builds ConfigMaps, Services, and StatefulSets for relayer implementations.
• src/builders/registry.ts: Generates the Registry service resources.
• src/builders/monitoring.ts: Creates Prometheus and Grafana monitoring objects.
• src/builders/ingress.ts: Produces Ingress resources and optional CertificateIssuer configurations.
• src/builders/frontend.ts: Generates UI services and deployments for explorers and faucets.
• src/builders/explorer.ts: Handles blockchain explorer component generation.
• src/configs/defaults.yaml: Default configuration used when no custom config is supplied.
• src/scripts.ts: Helper utilities for loading scripts and templates that become ConfigMap data.

Summary

• The generator package translates Starship's declarative configuration into executable Kubernetes YAML manifests.
• It implements a builder pattern with a top-level Generator class coordinating specialized sub-generators.
• Each sub-generator implements generate(): string[] to produce YAML strings for specific resource types like ConfigMaps, StatefulSets, and Services.
• The architecture is extensible via the IGenerator interface, allowing new chain types and components to be added without modifying core logic.
• Key entry points include src/index.ts for orchestration and src/builders/ directories for domain-specific resource generation.

Frequently Asked Questions

What is the primary function of the generator package in Starship?

The generator package functions as the core translation engine that converts high-level Starship configuration files into production-ready Kubernetes manifests. It bridges the gap between declarative infrastructure definitions and the concrete ConfigMaps, Services, StatefulSets, and Ingress objects required to deploy blockchain networks and supporting services.

How does the generator package handle different blockchain types?

The generator handles diverse blockchain types through specialized chain builders located in src/builders/chains/index.ts. Each builder—such as CosmosChainBuilder for Cosmos SDK chains—implements the IGenerator interface and knows how to generate the specific Kubernetes resources required for that chain's node architecture, allowing the system to support Cosmos, Ethereum, and other protocols through a unified extensibility model.

What Kubernetes resources does the generator produce?

The generator produces a comprehensive set of Kubernetes resources including ConfigMaps for chain scripts and genesis data, Services and StatefulSets for blockchain node containers, Deployments for auxiliary services, Ingress resources for external access, CertificateIssuer objects for TLS management, and monitoring stack components for Prometheus and Grafana.

How can developers extend the generator to support new components?

Developers can extend the generator by creating a new builder class that implements the IGenerator interface and its generate(): string[] method. After placing the builder in the appropriate src/builders/ directory, the top-level Generator class automatically discovers and invokes it based on the configuration file, enabling seamless integration of new chains, relayers, or monitoring tools without modifying existing code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}