Starship v1 vs v2: Architecture Differences and Migration Guide

Starship v2 replaces the Helm-based shell command architecture of v1 with a programmatic KubernetesJS client, enabling direct API deployment and manifest generation while maintaining backward-compatible configuration files.

Starship v1 and v2 represent two distinct architectural approaches for orchestrating Cosmos blockchain development environments in Kubernetes. While v1 relies on Helm charts and external shell commands for deployment, v2 introduces a KubernetesJS-based workflow that generates manifests programmatically and applies them via the Kubernetes API. This guide examines the technical differences between Starship v1 vs v2 and provides a concrete migration path based on the hyperweb-io/starship source code.

Architectural Differences Between Starship v1 and v2

Deployment Model: Helm Charts vs KubernetesJS API

Starship v1 uses a hybrid deployment approach combining TypeScript client libraries with Helm charts located in starship/charts/devnet. The infrastructure is managed through external shell commands including helm, kubectl, and docker, with the client orchestrating these tools to render and apply templates.

Starship v2 eliminates all shell-command dependencies. According to the repository's main README, the architecture migrates to a KubernetesJS-based system where the @starship-ci/generator package programmatically creates YAML manifests from configuration files. The CLI then applies these resources directly via the Kubernetes API rather than invoking Helm, as implemented in starship/cmd/starship/root.go.

Core Services and Client Architecture

Both versions maintain identical Go microservices for blockchain operations. The services in starship/faucet/main.go, starship/registry/main.go, and starship/exposer/main.go remain largely unchanged between versions, preserving business logic for token distribution, chain registry, and endpoint exposure.

The critical architectural shift occurs in the client layer. In v2, the CLI commands (start, stop, list, connect) are implemented using a k8s.io/client-go-style API client that communicates directly with the cluster. This replaces the v1 pattern where the TypeScript client invoked Helm to manage the lifecycle of these services.

Configuration Handling

Both versions consume the same config.yaml format without syntax changes. However, the processing differs significantly:

• v1: Passes config.yaml directly to Helm for template rendering within the starship/charts/devnet directory
• v2: Uses the KubernetesGenerator class from @starship-ci/generator to transform the StarshipConfig object into concrete Kubernetes resources programmatically

Step-by-Step Migration Path from v1 to v2

1. Switch to the v2 branch

   Checkout the current development branch from hyperweb-io/starship:

   git checkout main   # main == v2
   

2. Install the v2 CLI

   Replace legacy tooling with the new NPM package that communicates via KubernetesJS:

   npm i -g @starship-ci/cli

3. Add the manifest generator

   Install the package responsible for converting configurations to Kubernetes YAML:

   npm i @starship-ci/generator

4. Generate Kubernetes manifests

   Convert your existing config.yaml into inspectable, version-controlled YAML files:

   import { KubernetesGenerator } from '@starship-ci/generator';
   import { StarshipConfig } from '@starship-ci/types';
   
   const config: StarshipConfig = {/* your config.yaml parsed as JSON */};
   const generator = new KubernetesGenerator(config);
   
   // Produce all manifests
   const manifests = await generator.generateAll();
   
   // Write to disk for review and version control
   await generator.writeManifests('./k8s-manifests');

5. Review generated manifests

   Inspect the plain YAML files in ./k8s-manifests before deployment. This step allows manual adjustment and ensures the generated resources match your infrastructure requirements.

6. Deploy via Kubernetes API

   Use the v2 CLI to apply manifests directly without Helm intermediaries:

   starship start ./k8s-manifests

7. Remove Helm artifacts

   Once you verify the v2 workflow functions correctly for all required chains, delete legacy Helm-specific files such as starship/charts/* from your repository to prevent configuration drift.

8. Update CI/CD pipelines

   Replace Helm-centric pipeline steps (helm install, helm upgrade) with the new CLI commands:

   starship start ./k8s-manifests
   starship stop --name my-starship --namespace default

9. Adopt advanced v2 features

   Leverage additional capabilities documented in packages/packages/generator/README.md, including programmatic resource tweaking, enhanced error handling, and KubernetesJS client mocking for unit tests.

Code Examples: Old vs New Workflows

v1 Helm-Based Deployment

The legacy workflow requires repository setup and chart installation with value overrides:

helm repo add starship https://hyperweb-io.github.io/starship
helm repo update
helm install -f custom-values.yaml starship/devnet --generate-name

v2 Programmatic Deployment

The new workflow generates manifests first, then deploys via the Kubernetes API:

import { KubernetesGenerator } from '@starship-ci/generator';
import { StarshipConfig } from '@starship-ci/types';
import { execSync } from 'child_process';

// Load config and generate manifests
const config: StarshipConfig = /* parsed config.yaml */;
const generator = new KubernetesGenerator(config);
await generator.writeManifests('./k8s-manifests');

// Deploy using KubernetesJS client under the hood
execSync('starship start ./k8s-manifests', { stdio: 'inherit' });

Lifecycle Management Commands

v2 provides direct CLI commands for managing deployment lifecycles:

# Stop a specific deployment

starship stop --name my-starship --namespace default

# Establish port-forwarding

starship connect --config config.yaml --namespace default

Key Source Files and Repository Structure

Understanding the file structure clarifies the architectural shift from shell-command orchestration to programmatic API access:

• starship/charts/devnet/values.yaml – Helm chart configuration used by v1 for templating and deployment parameters.

• starship/cmd/starship/root.go – v2 CLI entry point implementing start, list, stop, and connect commands using the KubernetesJS client rather than shell invocations.

• packages/packages/generator/README.md – Documentation for the @starship-ci/generator package, detailing how StarshipConfig objects transform into Kubernetes YAML manifests via the KubernetesGenerator class.

• starship/faucet/main.go, starship/registry/main.go, starship/exposer/main.go – Core Go microservices maintaining consistent business logic across both versions, handling blockchain-specific operations independent of the deployment layer.

• starship/tools/main.go – Shared utility functions supporting both CLI versions and providing common helper methods.

Summary

• Starship v1 utilizes Helm charts and shell commands (helm, kubectl) for Kubernetes deployment, while Starship v2 employs a KubernetesJS client for direct API communication and programmatic manifest generation.
• Both versions share identical config.yaml formats and core Go services (faucet, registry, exposer), ensuring continuity in blockchain business logic.
• Migration requires installing @starship-ci/cli and @starship-ci/generator, generating manifests from existing configurations, and replacing Helm commands with starship start.
• v2 enables manifest version control, programmatic resource adjustment, and improved testing capabilities through KubernetesJS client mocking.
• v2 remains under active development; production environments should continue using the stable v1 branch until v2 reaches general availability.

Frequently Asked Questions

Is Starship v2 production-ready?

No. According to the hyperweb-io/starship repository documentation, v2 is currently under active development and not yet recommended for production use. Mission-critical environments should continue using the stable v1 branch available at the v1 branch until v2 receives an official release designation.

Do I need to modify my config.yaml when migrating to v2?

No. The config.yaml syntax remains unchanged between versions. The v2 KubernetesGenerator accepts the same StarshipConfig type used in v1, allowing you to migrate existing configuration files without modification. The generator handles the transformation into Kubernetes manifests programmatically.

What happens to the Go microservices in Starship v2?

The core Go services—including starship/faucet, starship/registry, and starship/exposer—remain largely unchanged. These microservices continue to provide identical business logic for blockchain operations; only the deployment mechanism changes from Helm-managed pod templates to programmatically generated manifests applied via the Kubernetes API.

Can I use Helm alongside Starship v2?

While technically possible during the migration period, the recommended approach involves completely replacing Helm workflows with v2's KubernetesJS-based deployment. Once you verify the v2 workflow functions correctly for your specific chains, you should remove Helm artifacts such as starship/charts/* to avoid configuration drift and reduce maintenance overhead.

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