coinstack.ts

Overview

The `coinstack.ts` file is a core module responsible for orchestrating the deployment of blockchain coinstacks onto Kubernetes clusters using Pulumi infrastructure-as-code. It primarily handles the creation of Kubernetes Secrets from environment variables, deployment of API services, and stateful blockchain services such as daemons and indexers. This file integrates configurations, environment variables, and Kubernetes resources to set up the full blockchain coinstack infrastructure in a consistent, automated manner.

Key functionalities include:

• Parsing and validating environment variables required for the coinstack.

• Creating Kubernetes Secrets to securely store sensitive configuration.

• Deploying stateless API services and stateful blockchain services.

• Integrating with Kubernetes via Pulumi providers.

• Supporting multiple coin services within a single coinstack deployment.

This module acts as the central coordinator that links configuration, environment, and Kubernetes resource creation for blockchain infrastructure deployment.

Detailed Explanations

Interfaces

CoinstackArgs

export interface CoinstackArgs {
  appName: string
  coinServiceArgs?: CoinServiceArgs[]
  coinstack: string
  coinstackType: CoinstackType
  config: Config
  kubeconfig: string
  namespace: string
  sampleEnv: Buffer
  volumes?: Array<k8s.types.input.core.v1.Volume>
}

**Description:** Defines the input parameters required to deploy a blockchain coinstack.

**Properties:**

Functions

deployCoinstack

export const deployCoinstack = async (args: CoinstackArgs): Promise<Outputs>

**Description:** Main entry point to deploy a blockchain coinstack on Kubernetes. Performs the following workflow:

1. Parses environment variables from a .env sample file and the current process environment, validating that all required keys are present.

2. Creates a Kubernetes Secret with sensitive environment data.

3. Deploys the API service associated with the coinstack.

4. Creates Kubernetes StatefulSets for each coin service (daemon, indexer, etc.) based on the provided service arguments.

5. Returns an empty Outputs object (placeholder for future expansion).

**Parameters:**

**Returns:** `Promise` — A promise resolving to deployment outputs. Currently an empty object.

**Usage Example:**

import { deployCoinstack } from './coinstack'

const deploymentOutputs = await deployCoinstack({
  appName: 'bitcoin-node',
  coinstack: 'bitcoin',
  coinstackType: 'node',
  config: myConfig,
  kubeconfig: myKubeConfig,
  namespace: 'blockchain-services',
  sampleEnv: fs.readFileSync('./bitcoin.sample.env'),
  coinServiceArgs: [ /* array of CoinServiceArgs for daemon and indexer */ ],
  volumes: [ /* optional volumes */ ],
})
console.log('Deployment completed:', deploymentOutputs)

**Implementation Details:**

• Secret Creation:
  Uses the getSecretData helper to extract environment variables from sampleEnv and current process.env. Throws an error if any required variable is missing or empty (except some exceptions).

• Kubernetes Provider:
  Initializes a Pulumi Kubernetes provider instance with the provided kubeconfig.

• Secret Resource:
  Creates a Kubernetes Secret resource in the target namespace to store environment variables securely.

• API Deployment:
  Calls deployApi (imported from .) to deploy the coinstack API service. Uses a fixed base image shapeshiftdao/unchained-base:latest.

• Coin Services Deployment:
  For each coin service argument passed, creates service specs via createCoinService, then uses deployStatefulService to deploy these as StatefulSets with associated volumes.

getSecretData

const getSecretData = (sampleEnv: Buffer): Record<string, string>

**Description:** Parses a `.env` sample file buffer and extracts the environment variable keys. It then retrieves values from the current process environment, validating that required variables are set. If any required variable is missing, it throws an error.

**Parameters:**

**Returns:** `Record` — An object mapping environment variable keys to their values.

**Algorithm Details:**

• Uses dotenv.parse to parse the .env sample buffer into keys.

• Iterates over each key, retrieves the value from process.env.

• Collects missing keys where values are undefined.

• Ignores empty values for some keys (INDEXER_API_KEY and RPC_API_KEY) to allow fallback deployments.

• Throws an error listing any missing required keys.

• Returns an object containing key-value pairs for the Kubernetes Secret.

**Usage Example:**

const secretData = getSecretData(fs.readFileSync('./bitcoin.sample.env'))
// Throws error if a required env var is missing in process.env

Important Implementation Details and Algorithms

• Dynamic Asset Naming:
  The asset name used for Kubernetes resources is dynamically constructed based on the configured network. For non-mainnet networks, the asset name appends the network name (assetName-network), enabling environment-specific naming and isolation.

• Provider Instantiation:
  A new Kubernetes provider is instantiated for each deployment using the provided kubeconfig. This ensures that Pulumi operates within the correct cluster context.

• Secret Creation:
  The Kubernetes Secret resource stores environment variables as string data. This secret is then referenced by deployed pods (via environment variable injection or mounted volumes) to provide sensitive configuration securely.

• API Deployment:
  The API service is deployed by delegating to the deployApi function imported from the current directory. This function manages Docker image usage and Kubernetes Deployment creation for stateless API pods.

• Stateful Service Creation:
  Each coin service (e.g., daemon, indexer) is transformed into a Kubernetes StatefulSet pod specification by createCoinService. This includes mounting lifecycle scripts, defining ports, environment variables, resource limits, and volume mounts.

• Volume Support:
  Optional volumes can be passed through and are mounted into the StatefulSet pods, enabling persistent storage or configuration sharing as needed.

• Error Handling:
  The deployment process validates environment variable presence early, preventing incomplete or misconfigured deployments.

Interaction with Other System Components

• Imports from . (current directory):

  • CoinServiceArgs, Config, deployApi, Outputs: Core types and deployment functions related to the API and configuration.

• Imports from ./statefulService:

  • createCoinService, deployStatefulService: Functions responsible for creating stateful Kubernetes services for blockchain daemons and indexers.

• Kubernetes Provider (@pulumi/kubernetes):

  • Used to define Kubernetes resources programmatically and deploy them to clusters.

• CoinstackType from ./hash:

  • Enum or type indicating the kind of coinstack, influencing deployment behavior.

• Environment Variables:

  • The file expects environment variables defined in a .env sample file and present in the process environment. These are injected into Kubernetes Secrets.

• Deployment Automation Pipeline:

  • This file is typically invoked by higher-level coinstack deployment scripts (e.g., node/coinstacks/{coin}/pulumi/index.ts).

  • It forms the backbone of deploying blockchain coinstacks by coordinating secret creation, API deployment, and stateful service deployment.

Visual Diagram: Class and Function Structure

classDiagram
    class CoinstackArgs {
        +appName: string
        +coinServiceArgs?: CoinServiceArgs[]
        +coinstack: string
        +coinstackType: CoinstackType
        +config: Config
        +kubeconfig: string
        +namespace: string
        +sampleEnv: Buffer
        +volumes?: Volume[]
    }

    class coinstack_ts {
        +deployCoinstack(args: CoinstackArgs): Promise<Outputs>
        -getSecretData(sampleEnv: Buffer): Record<string, string>
    }

    coinstack_ts ..> CoinstackArgs : uses
    coinstack_ts ..> deployApi : calls
    coinstack_ts ..> createCoinService : calls
    coinstack_ts ..> deployStatefulService : calls
    coinstack_ts ..> k8s.Provider : instantiates

Summary

The `coinstack.ts` file is a pivotal module within the blockchain deployment automation system that:

• Validates and extracts environment variables from .env samples.

• Creates Kubernetes Secrets for sensitive config injection.

• Deploys API services as Kubernetes Deployments.

• Deploys blockchain coin services (daemons, indexers) as StatefulSets.

• Coordinates Kubernetes resource creation using Pulumi providers.

• Bridges configuration inputs with Kubernetes cluster deployment to automate blockchain coinstack provisioning.

It is designed for extensibility and modularity, supporting multiple coin services and coinstack types, ensuring secure and reliable deployment of blockchain infrastructure components.