The Registry Pattern: Service Discovery for Ephemeral Nodes

Service discovery is a solved problem. Until your services exist for hours, not months.

The Discovery Problem

Starship spins up multi-chain blockchain environments on Kubernetes. A typical test environment might include three Cosmos SDK chains, a relayer, and a faucet. Each chain runs its own RPC, gRPC, and REST endpoints. Each node has a unique ID and public key generated at startup.

These environments are ephemeral. They exist for a CI run, a demo, or a few hours of local development. Then they're torn down and rebuilt with potentially different topology.

The nodes need to find each other. External test clients need to find the nodes. And traditional service discovery patterns (Consul, etcd watches, gossip protocols) are overkill for something that lives for two hours.

The question isn't "how do services find each other." It's "how do services find each other when the whole environment is disposable."

Implicit Registration

Here's the key insight: in an ephemeral environment, the deployment process already knows the full topology. It knows which chains are running, how many validators each has, and what ports they're using. It knows all of this because it just generated the Kubernetes manifests.

So why would you make nodes register themselves at runtime?

Implicit registration means the deployment step generates the discovery data. No heartbeats, no gossip, no registration API. The act of creating the manifests also creates the service discovery configuration.

flowchart LR
    A["User Config<br/>(chains, validators, relayers)"] --> B["Manifest Generator"]
    B --> C["K8s Deployments<br/>& Services"]
    B --> D["ConfigMap<br/>(registry-config)"]
    D --> E["Registry Service"]
    C --> F["Running Nodes"]
    F --> G["Exposer Sidecars"]
    E --> H["gRPC/HTTP API"]
    G --> H

The RegistryConfigMapGenerator runs during manifest generation. It takes the same configuration that produces Deployments and Services, and outputs a ConfigMap called registry-config. This ConfigMap contains JSON strings with every chain's name, API endpoints (RPC, gRPC, REST), and asset lists.

The registry service reads this ConfigMap at startup. No runtime registration needed.

The Registry Service

The registry itself is a Go microservice deployed as a standard Kubernetes Deployment. It exposes two interfaces:

• HTTP on port 8080 for simple queries and browser-friendly access
• gRPC on port 9090 for programmatic clients and test frameworks

Six gRPC methods cover the discovery surface:

The ConfigMap is mounted as a volume into the registry container. At startup, the service reads the JSON files and builds its internal knowledge base. No database, no external dependencies. Just files on disk that were generated alongside the rest of the infrastructure.

The registry doesn't discover anything. It already knows everything because the same process that deployed the nodes also wrote the registry's configuration.

The Exposer Sidecar

Static configuration gets you most of the way there. But some metadata only exists at runtime: a node's ID, its public key, its genesis file.

Each blockchain node runs an exposer sidecar, a small Go service that serves node-specific metadata over gRPC:

• NodeID: the unique identifier generated at node startup
• PubKey: the node's public key
• GenesisFile: the chain's genesis configuration
• ConfigFile: the node's runtime configuration
• Keys: key material for the node

The registry service knows the exposer addresses for each node (provided as environment variables during deployment). When a client queries the registry for detailed node info, the registry can reach out to the exposer to get live, runtime data.

This creates a two-tier discovery model:

• Static tier: ConfigMap holds topology, endpoints, and asset lists (known at deploy time)
• Dynamic tier: Exposer sidecars hold node-specific metadata (known at runtime)

Both tiers feed into the registry's API, giving clients a single entry point for all discovery queries.

Chain-Registry Adaptation

The Cosmos ecosystem has an existing standard for chain discovery: the chain-registry. It's a JSON format that describes a chain's name, API endpoints, asset lists, and network metadata. Wallets, explorers, and other tooling consume this format.

Starship's registry generates configs that conform to this standard. Each chain's ConfigMap entry follows the chain-registry JSON schema: chain_name, apis (with rpc, grpc, and rest arrays), and assets.

This means ecosystem tooling works against Starship environments without modification. A wallet that reads chain-registry data can point at a Starship registry and discover ephemeral test chains the same way it discovers mainnet.

Conforming to an ecosystem standard means you get an entire tooling ecosystem for free. That's the difference between building a service registry and building a service registry that actually gets used.

When This Pattern Fits

Implicit registration works when two conditions are true:

1. Topology is known at deploy time. You decide what's running before anything starts. No auto-scaling, no dynamic service joining.
2. The environment is ephemeral. Nodes don't come and go during the lifetime of the environment. They start together and stop together.

If your services scale dynamically, if nodes join and leave at runtime, or if you need health-based deregistration, you want active registration (Consul, etcd, Kubernetes native service discovery with readiness probes).

But for test environments, CI pipelines, demo setups, and dev clusters with known topology, implicit registration removes an entire category of complexity. No registration protocol, no heartbeat failures, no stale entries. The source of truth is the deployment manifest, and the registry is just a queryable view of it.

Resources

• Starship: universal interchain development and testing environment
• chain-registry: Cosmos ecosystem chain metadata standard
• Kubernetes ConfigMaps: official documentation for ConfigMap resources
• gRPC: high-performance RPC framework used by the registry and exposer services