tessl/npm-pulumi--pulumi

Pulumi's Node.js SDK for infrastructure-as-code platform that allows you to create, deploy, and manage infrastructure using familiar programming languages and tools.

1.02x

Overview

Eval results

Files

Automation

Name: tessl/npm-pulumi--pulumi
Rating: 0.85 (1 reviews)
Author: tessl

Pulumi's Automation API enables programmatic management of Pulumi stacks and workspaces, allowing you to build custom deployment tools, CI/CD integrations, and infrastructure management applications.

Core Workspace Classes

abstract class Workspace {
  abstract workDir: string;
  abstract pulumiHome?: string;
  abstract program?: PulumiFn;
  abstract envVars: { [key: string]: string };
  abstract secretsProvider?: string;
  abstract projectSettings(): Promise<ProjectSettings>;
  abstract saveProjectSettings(settings: ProjectSettings): Promise<void>;
  abstract stackSettings(stackName: string): Promise<StackSettings>;
  abstract saveStackSettings(stackName: string, settings: StackSettings): Promise<void>;
  abstract serializeArgsForOp(stackName: string): Promise<string[]>;
  abstract postCommandCallback(stackName: string): Promise<void>;
}

class LocalWorkspace extends Workspace {
  static create(args?: LocalWorkspaceOptions): Promise<LocalWorkspace>;
  static createStack(args: LocalProgramArgs): Promise<Stack>;
  static selectStack(args: LocalProgramArgs): Promise<Stack>;
  static createOrSelectStack(args: LocalProgramArgs): Promise<Stack>;
  
  workDir: string;
  pulumiHome?: string;
  program?: PulumiFn;
  envVars: { [key: string]: string };
  secretsProvider?: string;
  
  constructor(opts?: LocalWorkspaceOptions);
  
  projectSettings(): Promise<ProjectSettings>;
  saveProjectSettings(settings: ProjectSettings): Promise<void>;
  stackSettings(stackName: string): Promise<StackSettings>;
  saveStackSettings(stackName: string, settings: StackSettings): Promise<void>;
  installPlugin(name: string, version: string, kind?: string): Promise<void>;
  removePlugin(name: string, versionRange?: string, kind?: string): Promise<void>;
  listPlugins(): Promise<PluginInfo[]>;
  exportStack(stackName: string): Promise<Deployment>;
  importStack(stackName: string, state: Deployment): Promise<void>;
  whoAmI(): Promise<string>;
  pulumiVersion(): Promise<string>;
}

Stack Management

class Stack {
  readonly name: string;
  readonly workspace: Workspace;
  
  constructor(name: string, workspace: Workspace);
  
  // Core operations
  up(opts?: UpOptions): Promise<UpResult>;
  preview(opts?: PreviewOptions): Promise<PreviewResult>;
  refresh(opts?: RefreshOptions): Promise<RefreshResult>;
  destroy(opts?: DestroyOptions): Promise<DestroyResult>;
  
  // Import/Export operations
  import(opts: ImportOptions): Promise<ImportResult>;
  export(): Promise<Deployment>;
  
  // Configuration management
  getConfig(key: string): Promise<ConfigValue>;
  getAllConfig(): Promise<{ [key: string]: ConfigValue }>;
  setConfig(key: string, value: ConfigValue): Promise<void>;
  setAllConfig(config: { [key: string]: ConfigValue }): Promise<void>;
  removeConfig(key: string): Promise<void>;
  removeAllConfig(keys: string[]): Promise<void>;
  
  // Stack information
  outputs(): Promise<OutputMap>;
  history(pageSize?: number, page?: number): Promise<UpdateSummary[]>;
  info(): Promise<StackSummary>;
  
  // Stack lifecycle
  rename(newName: string): Promise<void>;
  cancel(): Promise<void>;
}

Operation Options and Results

interface UpOptions {
  parallel?: number;
  message?: string;
  expectNoChanges?: boolean;
  diff?: boolean;
  replace?: string[];
  target?: string[];
  targetDependents?: boolean;
  policyPacks?: string[];
  policyPackConfigs?: { [key: string]: PolicyPackConfig };
  refresh?: boolean;
  userAgent?: string;
  colorMode?: "always" | "never" | "raw" | "auto";
  continueOnError?: boolean;
}

interface UpResult {
  stdout: string;
  stderr: string;
  summary: UpdateSummary;
  outputs: OutputMap;
}

interface PreviewOptions {
  parallel?: number;
  message?: string;
  expectNoChanges?: boolean;
  diff?: boolean;
  replace?: string[];
  target?: string[];
  targetDependents?: boolean;
  policyPacks?: string[];
  policyPackConfigs?: { [key: string]: PolicyPackConfig };
  refresh?: boolean;
  userAgent?: string;
  colorMode?: "always" | "never" | "raw" | "auto";
}

interface PreviewResult {
  stdout: string;
  stderr: string;
  summary: UpdateSummary;
  changeSummary: { [key: string]: number };
}

interface DestroyOptions {
  parallel?: number;
  message?: string;
  target?: string[];
  targetDependents?: boolean;
  refresh?: boolean;
  userAgent?: string;
  colorMode?: "always" | "never" | "raw" | "auto";
  continueOnError?: boolean;
}

interface DestroyResult {
  stdout: string;
  stderr: string;  
  summary: UpdateSummary;
}

Configuration Types

interface LocalWorkspaceOptions {
  workDir?: string;
  pulumiHome?: string;
  program?: PulumiFn;
  envVars?: { [key: string]: string };
  secretsProvider?: string;
  kubeconfig?: string;
  projectSettings?: ProjectSettings;
  stackSettings?: { [key: string]: StackSettings };
  repo?: GitRepo;
}

interface LocalProgramArgs {
  stackName: string;
  workDir?: string;
  program?: PulumiFn;
  opts?: LocalWorkspaceOptions;
}

interface InlineProgramArgs {
  stackName: string;
  projectName: string;
  program: PulumiFn;
  opts?: LocalWorkspaceOptions;
}

type PulumiFn = () => Promise<void> | void;

interface ProjectSettings {
  name: string;
  runtime: ProjectRuntimeInfo;
  main?: string;
  description?: string;
  author?: string;
  website?: string;
  license?: string;
  config?: { [key: string]: ProjectConfigType };
  template?: ProjectTemplate;
  backend?: ProjectBackend;
  options?: ProjectOptions;
  plugins?: PluginOptions;
}

interface StackSettings {
  secretsProvider?: string;
  encryptedKey?: string;
  encryptionSalt?: string;
  config?: { [key: string]: ConfigValue };
}

interface ConfigValue {
  value: string;
  secret?: boolean;
}

type OutputMap = { [key: string]: OutputValue };

interface OutputValue {
  value: any;
  secret: boolean;
}

Event System

interface EngineEvent {
  sequence: number;
  timestamp: number;
}

interface CancelEvent extends EngineEvent {
  type: "cancelEvent";
}

interface DiagnosticEvent extends EngineEvent {
  type: "diagnosticEvent";
  urn?: string;
  prefix: string;
  message: string;
  color: string;
  severity: "debug" | "info" | "warning" | "error";
  streamId?: number;
  ephemeral?: boolean;
}

interface PreludeEvent extends EngineEvent {
  type: "preludeEvent";
  config: { [key: string]: string };
}

interface SummaryEvent extends EngineEvent {
  type: "summaryEvent";
  maybeCorrupt: boolean;
  durationSeconds: number;
  resourceChanges?: { [key: string]: number };
  policyPacks?: PolicyPackRunInfo[];
}

interface ResourcePreEvent extends EngineEvent {
  type: "resourcePreEvent";
  metadata: StepEventMetadata;
}

interface ResOutputsEvent extends EngineEvent {
  type: "resOutputsEvent";
  metadata: StepEventMetadata;
}

interface ResOpFailedEvent extends EngineEvent {
  type: "resOpFailedEvent";
  metadata: StepEventMetadata;
}

Usage Examples

Basic Stack Operations

import * as pulumi from "@pulumi/pulumi";
import { LocalWorkspace } from "@pulumi/pulumi/automation";

// Create inline program
const program = async () => {
  const bucket = new pulumi.aws.s3.Bucket("my-bucket");
  return { bucketName: bucket.id };
};

// Create and deploy stack
const stack = await LocalWorkspace.createStack({
  stackName: "dev",
  projectName: "my-project",
  program,
});

// Configure stack
await stack.setConfig("aws:region", { value: "us-east-1" });

// Deploy
const upResult = await stack.up();
console.log(`Update succeeded. Outputs: ${JSON.stringify(upResult.outputs)}`);

Workspace from Existing Project

import { LocalWorkspace, Stack } from "@pulumi/pulumi/automation";

// Create workspace from existing Pulumi project
const workspace = await LocalWorkspace.create({
  workDir: "./my-pulumi-project",
});

// Select existing stack
const stack = await Stack.select("production", workspace);

// Preview changes
const previewResult = await stack.preview();
console.log(`Preview completed: ${previewResult.changeSummary}`);

// Apply if changes look good
if (previewResult.changeSummary.create > 0) {
  const upResult = await stack.up();
  console.log("Deployment completed");
}

Configuration Management

import { LocalWorkspace, Stack } from "@pulumi/pulumi/automation";

const workspace = await LocalWorkspace.create({
  workDir: "./project",
});

const stack = await Stack.select("staging", workspace);

// Set multiple configuration values
await stack.setAllConfig({
  "app:environment": { value: "staging" },
  "app:replica-count": { value: "3" },
  "app:database-password": { value: "secret123", secret: true },
  "aws:region": { value: "us-west-2" },
});

// Get configuration
const config = await stack.getAllConfig();
console.log("Current configuration:", config);

// Remove configuration
await stack.removeConfig("app:old-setting");

Event Monitoring

import { LocalWorkspace, Stack } from "@pulumi/pulumi/automation";

const stack = await Stack.select("production", workspace);

// Monitor deployment events
const upResult = await stack.up({
  onOutput: (out: string) => {
    console.log(`Output: ${out}`);
  },
  onEvent: (event) => {
    if (event.type === "diagnosticEvent") {
      console.log(`${event.severity}: ${event.message}`);
    } else if (event.type === "resourcePreEvent") {
      console.log(`Starting ${event.metadata.op} on ${event.metadata.type}`);
    }
  },
});

Stack History and Rollback

import { LocalWorkspace, Stack } from "@pulumi/pulumi/automation";

const stack = await Stack.select("production", workspace);

// Get deployment history
const history = await stack.history();
console.log(`Found ${history.length} deployments`);

// Find last successful deployment
const lastSuccessful = history.find(h => h.result === "succeeded");

if (lastSuccessful) {
  console.log(`Last successful deployment: ${lastSuccessful.version}`);
  
  // Rollback to previous version (manual process)
  // This would typically involve:
  // 1. Export the target state
  // 2. Import it as the current state
  // 3. Run refresh to sync
}

Multi-Stack Management

import { LocalWorkspace, Stack } from "@pulumi/pulumi/automation";

const workspace = await LocalWorkspace.create({
  workDir: "./infrastructure",
});

const environments = ["dev", "staging", "production"];

for (const env of environments) {
  const stack = await Stack.select(env, workspace);
  
  // Environment-specific configuration
  const envConfig = {
    "app:environment": { value: env },
    "app:replica-count": { value: env === "production" ? "5" : "2" },
    "aws:region": { value: env === "production" ? "us-east-1" : "us-west-2" },
  };
  
  await stack.setAllConfig(envConfig);
  
  // Deploy with environment-specific options
  const upResult = await stack.up({
    parallel: env === "production" ? 1 : 10, // More careful in prod
    message: `Automated deployment to ${env}`,
  });
  
  console.log(`${env} deployment completed`);
}

Custom Deployment Tool

import { LocalWorkspace, Stack } from "@pulumi/pulumi/automation";

class DeploymentManager {
  private workspace: LocalWorkspace;
  
  constructor(private projectPath: string) {}
  
  async initialize() {
    this.workspace = await LocalWorkspace.create({
      workDir: this.projectPath,
    });
  }
  
  async deployToEnvironment(environment: string, config: Record<string, any>) {
    const stack = await Stack.createOrSelect(environment, this.workspace);
    
    // Apply configuration
    const configValues = Object.entries(config).reduce((acc, [key, value]) => {
      acc[key] = typeof value === "object" && value.secret
        ? { value: value.value, secret: true }
        : { value: String(value) };
      return acc;
    }, {} as Record<string, any>);
    
    await stack.setAllConfig(configValues);
    
    // Preview first
    console.log(`Previewing changes for ${environment}...`);
    const previewResult = await stack.preview();
    
    if (previewResult.changeSummary.create === 0 && 
        previewResult.changeSummary.update === 0 && 
        previewResult.changeSummary.delete === 0) {
      console.log("No changes required");
      return;
    }
    
    // Confirm deployment
    console.log("Changes detected:", previewResult.changeSummary);
    
    // Deploy
    console.log(`Deploying to ${environment}...`);
    const upResult = await stack.up();
    
    console.log("Deployment completed successfully");
    console.log("Outputs:", upResult.outputs);
    
    return upResult;
  }
  
  async listStacks() {
    const stacks = await this.workspace.listStacks();
    return stacks.map(s => ({
      name: s.name,
      current: s.current,
      lastUpdate: s.lastUpdate,
      resourceCount: s.resourceCount,
    }));
  }
}

// Usage
const manager = new DeploymentManager("./my-infrastructure");
await manager.initialize();

await manager.deployToEnvironment("staging", {
  "app:environment": "staging",
  "app:database-password": { value: "secret123", secret: true },
  "aws:region": "us-west-2",
});

Best Practices

Use inline programs for simple, dynamic infrastructure
Leverage existing projects for complex, version-controlled infrastructure
Always preview changes before applying in production environments
Use configuration management for environment-specific settings
Monitor deployment events for better observability
Implement proper error handling and rollback strategies
Use parallel deployment settings appropriate for your environment
Store sensitive configuration as secrets
Implement proper access controls for production deployments

Install with Tessl CLI

npx tessl i tessl/npm-pulumi--pulumi