# How the Starship Generator Package Creates Kubernetes Manifests

> Discover how the Starship generator package transforms declarative configurations into production-ready Kubernetes YAML manifests using a modular builder pattern for efficient deployment.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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](https://github.com/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/src/builders/relayers/index.ts)): Construct ConfigMaps, Services, and StatefulSets for each relayer implementation.
- **Registry Builder** ([`src/builders/registry.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/registry.ts)): Generates the Registry service components including ConfigMaps, Deployments, and Services.
- **Monitoring Builder** ([`src/builders/monitoring.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/monitoring.ts)): Produces Prometheus and Grafana objects for network observability.
- **Ingress Builder** ([`src/builders/ingress.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/ingress.ts)): Creates Ingress resources and optional CertificateIssuer objects for external access.
- **Frontend Builder** ([`src/builders/frontend.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/frontend.ts)): Generates UI services and deployments for explorers and faucets.
- **Explorer Builder** ([`src/builders/explorer.ts`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/hyperweb-io/starship/blob/main/src/index.ts)**: Public entry point; creates the top-level `Generator` that coordinates all sub-generators.
- **[`src/builders/chains/index.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/chains/index.ts)**: Dispatches per-chain builders for Cosmos, Ethereum, and other protocols.
- **[`src/builders/relayers/index.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/relayers/index.ts)**: Builds ConfigMaps, Services, and StatefulSets for relayer implementations.
- **[`src/builders/registry.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/registry.ts)**: Generates the Registry service resources.
- **[`src/builders/monitoring.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/monitoring.ts)**: Creates Prometheus and Grafana monitoring objects.
- **[`src/builders/ingress.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/ingress.ts)**: Produces Ingress resources and optional CertificateIssuer configurations.
- **[`src/builders/frontend.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/frontend.ts)**: Generates UI services and deployments for explorers and faucets.
- **[`src/builders/explorer.ts`](https://github.com/hyperweb-io/starship/blob/main/src/builders/explorer.ts)**: Handles blockchain explorer component generation.
- **[`src/configs/defaults.yaml`](https://github.com/hyperweb-io/starship/blob/main/src/configs/defaults.yaml)**: Default configuration used when no custom config is supplied.
- **[`src/scripts.ts`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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.