enablement-k8s-replacements

A CLI tool and Node.js library for applying version, replica, resource, and string replacements to Kubernetes YAML files as part of a CI/CD pipeline.

Installation

pnpm add enablement-k8s-replacements

CLI Usage

npx enablement-k8s-replacements [options]

Options

| Option | Description | Default | |---|---|---| | --searchPatterns <patterns> | Comma-separated glob patterns for YAML files | **/*.yaml | | --versionFile <paths> | Comma-separated paths to version config JSON files | tests/versions.json | | --scanPackage | Scan package.json files to auto-populate versions | false | | --noupdate | Dry-run; do not write changes to disk | false | | --test | Write modified files as <file>.debug instead of overwriting | false | | --debug | Emit verbose logging | false |

Example

# Apply versions from a version file to all YAML files under deploy/
npx enablement-k8s-replacements --searchPatterns deploy/**/*.yaml --versionFile versions.json

# Preview changes without writing
npx enablement-k8s-replacements --test --versionFile versions.json

Version File Format

The version file is JSON. It can be a flat key/value map of name → version, or a structured object with versions, replicas, resources, and strings sections.

{
  "versions": {
    "my-service": "1.4.2",
    "other-service": "2.0.0"
  },
  "replicas": {
    "_default": 0,
    "api": 3,
    "worker": 1
  },
  "resources": {
    "_defaults": {
      "requests": { "cpu": "100m", "memory": "128Mi" },
      "limits":   { "cpu": "500m", "memory": "512Mi" }
    },
    "api": {
      "limits": { "memory": "1Gi" }
    }
  },
  "strings": {
    "_defaults": {
      "CLUSTER_ENV": "production"
    },
    "api": {
      "MY_TOKEN": "abc123"
    }
  }
}

YAML Placeholder Syntax

| Syntax | Type | Example | |---|---|---| | name:REPLACE | Docker image tag | my-service:REPLACE → my-service:1.4.2 | | name==REPLACE | Python/pip pin | my-service==REPLACE → my-service==1.4.2 | | name@REPLACE | npm package | my-service@REPLACE → [email protected] |

Programmatic API

import {
  replaceVersions,
  replaceReplicas,
  replaceResources,
  replaceStrings,
  defaultOptions,
  parseArgs,
  main,
} from 'enablement-k8s-replacements/src/lib.js';

replaceVersions(txt, versions)

Replaces all name:REPLACE, name==REPLACE, and name@REPLACE placeholders in txt.

replaceReplicas(txt, replicas, name, options)

Replaces replicas: N in a deployment YAML using the value for name in the replicas map, or _default if not specified.

replaceResources(txt, resources, name, doc)

Merges resource limits and requests into container specs inside a parsed YAML document. Set a resource value to "0" or 0 to delete that key.

replaceStrings(txt, strings, name)

Applies regex-based string substitutions from the strings._defaults and strings[name] maps.

defaultOptions()

Returns the default options object used by the CLI.

parseArgs(argv, options)

Parses process.argv-style arguments into an options object. Throws Error('Expected a known option') for unrecognized flags.

main(options)

Runs the full replacement pipeline and returns 'DONE'. Does not call process.exit.

Development

# Run unit tests
pnpm test

# Watch mode
pnpm test:watch

License

MIT