k8s-deploy-helper 0.1.1 → 1.0.0

package/README.md

@@ -1 +1,176 @@
-## K8s-deploy-helper
+# k8s-deploy-helper
+
+A production-grade CLI tool that automates Docker image builds and Kubernetes deployments using a single command.  
+Designed for real-world CI/CD pipelines and local developer workflows.
+
+---
+
+## ✨ Overview
+
+`k8s-deploy-helper` simplifies the process of:
+- Building Docker images
+- Pushing images to container registries
+- Generating Kubernetes manifests
+- Deploying applications to Kubernetes clusters
+
+The tool is **configuration-driven**, **CI/CD-friendly**, and uses **native Docker and kubectl** instead of opaque SDK abstractions.
+
+---
+
+## 🚀 Features
+
+- Docker image build automation
+- Registry push support (Docker Hub, ECR, GHCR, etc.)
+- Kubernetes Deployment & Service YAML generation
+- Automatic `kubectl apply`
+- Graceful handling of partial failures
+- Idempotent deployments
+- Works locally and in CI pipelines
+
+---
+
+## 📦 Installation
+
+Install globally from npm:
+npm install -g k8s-deploy-helper
+
+Verify installation:
+k8s-deploy --version
+
+🛠 Prerequisites
+Ensure the following are installed and configured:
+
+Node.js (v18+)
+
+Docker (running)
+
+kubectl
+
+Kubernetes cluster:
+
+Docker Desktop Kubernetes
+
+Minikube
+
+EKS / GKE / AKS
+
+Container registry access (Docker Hub, ECR, GHCR, etc.)
+
+📄 Configuration
+Create a k8s.config.json file in your project root.
+
+Example configuration:
+json
+Copy code
+{
+  "appName": "my-app",
+  "namespace": "default",
+
+  "docker": {
+    "image": "username/my-app",
+    "tag": "latest",
+    "context": ".",
+    "dockerfile": "Dockerfile"
+  },
+
+  "kubernetes": {
+    "replicas": 2,
+    "containerPort": 3000,
+    "servicePort": 80,
+    "serviceType": "ClusterIP"
+  },
+
+  "resources": {
+    "limits": {
+      "cpu": "500m",
+      "memory": "512Mi"
+    },
+    "requests": {
+      "cpu": "250m",
+      "memory": "256Mi"
+    }
+  },
+
+  "env": {
+    "NODE_ENV": "production"
+  }
+}
+▶️ Usage
+Deploy your application using a single command:
+
+bash
+Copy code
+k8s-deploy deploy
+What this command does:
+Builds the Docker image
+
+Pushes the image to the registry (if authorized)
+
+Generates Kubernetes manifests:
+
+deployment.yaml
+
+service.yaml
+
+Applies the resources to the Kubernetes cluster using kubectl
+
+If the image push fails, deployment continues using the existing image tag.
+
+📁 Generated Files
+text
+Copy code
+deployment.yaml
+service.yaml
+These files can be reviewed, committed to version control, or applied independently.
+
+🔐 Authentication
+This tool does not manage credentials.
+
+Authentication must be handled externally:
+
+docker login for container registries
+
+kubectl config for Kubernetes clusters
+
+This mirrors real-world CI/CD environments and avoids secret leakage.
+
+🧠 Design Principles
+Explicit over implicit — no hidden magic
+
+Fail loud, fail early — CI-friendly logs
+
+Idempotent operations — safe re-runs
+
+No vendor lock-in — relies on standard tools
+
+🧪 Example Output
+text
+Copy code
+🐳 Building Docker image: username/my-app:latest
+📤 Pushing Docker image: username/my-app:latest
+⚠️ Image push failed — continuing deployment
+
+☸️ Deploying to Kubernetes namespace: default
+📦 Applying deployment.yaml
+deployment.apps/my-app created
+📦 Applying service.yaml
+service/my-app created
+✅ Kubernetes resources applied successfully
+🗺 Roadmap
+Planned enhancements:
+
+--dry-run mode
+
+Rollback support
+
+Helm chart generation
+
+Deployment health checks
+
+GitHub Actions CI template
+
+📜 License
+MIT License
+
+👨‍💻 Author
+Lokesh Shimpi

package/bin/cli.js

@@ -1,18 +1,25 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { Command } from 'commander';
 import { runDeploy } from '../src/index.js';
+import { initProject } from '../src/init/initProject.js';
 
 const program = new Command();
 
 program
   .name('k8s-deploy')
   .description('Build and deploy apps to Kubernetes')
-  .version('0.1.0');
+  .version('0.3.0');
+
+program
+  .command('init')
+  .description('Initialize Dockerfile and k8s.config.json')
+  .action(initProject);
 
 program
   .command('deploy')
-  .description('Build Docker image and deploy to Kubernetes')
+  .description('Build and deploy app to Kubernetes')
   .option('-c, --config <path>', 'Config file path', 'k8s.config.json')
+  .option('--local', 'Deploy using local Docker image (skip push)')
   .action(runDeploy);
 
-program.parse();
+program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s-deploy-helper",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "CLI tool to build, push and deploy applications to Kubernetes",
   "type": "module",
   "bin": {

package/src/docker/buildPush.js

@@ -1,18 +1,16 @@
 import { execa } from 'execa';
 import fs from 'fs';
 
-export async function buildAndPushImage(config) {
+export async function buildAndPushImage(config, isLocal) {
   const { image, tag, context, dockerfile } = config.docker;
-
+  const fullImageName = `${image}:${tag}`;
   const dockerfilePath = dockerfile || 'Dockerfile';
 
   if (!fs.existsSync(dockerfilePath)) {
-    throw new Error(`Dockerfile not found at path: ${dockerfilePath}`);
+    throw new Error(`Dockerfile not found at ${dockerfilePath}`);
   }
 
-  const fullImageName = `${image}:${tag}`;
-
-  console.log(`\n🐳 Building Docker image: ${fullImageName}`);
+  console.log(`🐳 Building Docker image: ${fullImageName}`);
 
   await execa(
     'docker',
@@ -20,8 +18,12 @@ export async function buildAndPushImage(config) {
     { stdio: 'inherit' }
   );
 
-  console.log(`\n📤 Pushing Docker image: ${fullImageName}`);
+  if (isLocal) {
+    console.log('📦 Local mode enabled — skipping image push');
+    return fullImageName;
+  }
 
+  console.log(`📤 Pushing Docker image: ${fullImageName}`);
   await execa('docker', ['push', fullImageName], { stdio: 'inherit' });
 
   return fullImageName;

package/src/index.js

@@ -1,27 +1,48 @@
 import { loadConfig } from './config/loadConfig.js';
 import { validateConfig } from './config/validateConfig.js';
+
+import { checkRequiredFiles } from './preflight/checkFiles.js';
+import { checkEnvironment } from './preflight/checkEnvironment.js';
+
 import { buildAndPushImage } from './docker/buildPush.js';
+
 import { generateDeployment } from './k8s/deployment.js';
 import { generateService } from './k8s/service.js';
 import { applyKubernetes } from './k8s/apply.js';
 
 export async function runDeploy(options) {
-  console.log('Loading config...');
-  const config = loadConfig(options.config);
-  validateConfig(config);
+  try {
+    console.log('🔍 Checking required files...');
+    checkRequiredFiles();
 
-  console.log(`App: ${config.appName}`);
+    console.log('🔍 Checking environment...');
+    await checkEnvironment();
 
-  let image = `${config.docker.image}:${config.docker.tag}`;
+    const configPath = options.config || 'k8s.config.json';
+    const isLocal = options.local === true;
 
-  try {
-    image = await buildAndPushImage(config);
-  } catch {
-    console.warn('\n⚠️ Image push failed — continuing deployment');
-  }
+    console.log('📄 Loading configuration...');
+    const config = loadConfig(configPath);
+    validateConfig(config);
+
+    console.log(`🚀 Deploying application: ${config.appName}`);
+    if (isLocal) {
+      console.log('📦 Local mode enabled (image push will be skipped)');
+    }
+
+    const image = await buildAndPushImage(config, isLocal);
 
-  generateDeployment(config, image);
-  generateService(config);
+    console.log('🛠 Generating Kubernetes manifests...');
+    generateDeployment(config, image, isLocal);
+    generateService(config);
 
-  await applyKubernetes(config);
+    console.log('☸️ Applying resources to Kubernetes...');
+    await applyKubernetes(config);
+
+    console.log('\n✅ Deployment completed successfully');
+  } catch (err) {
+    console.error('\n❌ Deployment failed');
+    console.error(err.message || err);
+    process.exit(1);
+  }
 }

package/src/init/generateFiles.js

@@ -0,0 +1,49 @@
+import fs from 'fs';
+
+export function generateDockerfile() {
+  if (fs.existsSync('Dockerfile')) return;
+
+  const dockerfile = `
+FROM node:18-alpine
+WORKDIR /app
+COPY server/package*.json ./
+RUN npm install
+COPY server .
+EXPOSE 5000
+CMD ["npm", "start"]
+`.trim();
+
+  fs.writeFileSync('Dockerfile', dockerfile);
+  console.log('✅ Dockerfile created');
+}
+
+export function generateK8sConfig() {
+  if (fs.existsSync('k8s.config.json')) return;
+
+  const config = {
+    appName: 'my-app',
+    namespace: 'default',
+    docker: {
+      image: 'your-docker-username/my-app',
+      tag: 'latest',
+      context: '.',
+      dockerfile: 'Dockerfile'
+    },
+    kubernetes: {
+      replicas: 1,
+      containerPort: 5000,
+      servicePort: 80,
+      serviceType: 'ClusterIP'
+    },
+    env: {
+      NODE_ENV: 'production'
+    }
+  };
+
+  fs.writeFileSync(
+    'k8s.config.json',
+    JSON.stringify(config, null, 2)
+  );
+
+  console.log('✅ k8s.config.json created');
+}

package/src/init/initProject.js

@@ -0,0 +1,11 @@
+import { generateDockerfile, generateK8sConfig } from './generateFiles.js';
+
+export function initProject() {
+  console.log('🔧 Initializing project for Kubernetes deployment...\n');
+
+  generateDockerfile();
+  generateK8sConfig();
+
+  console.log('\n🎉 Initialization complete');
+  console.log('👉 Update k8s.config.json with your Docker username');
+}

package/src/k8s/deployment.js

@@ -1,7 +1,7 @@
 import yaml from 'js-yaml';
 import fs from 'fs';
 
-export function generateDeployment(config, image) {
+export function generateDeployment(config, image, isLocal = false) {
   const deployment = {
     apiVersion: 'apps/v1',
     kind: 'Deployment',
@@ -10,7 +10,7 @@ export function generateDeployment(config, image) {
       namespace: config.namespace || 'default'
     },
     spec: {
-      replicas: config.kubernetes.replicas,
+      replicas: config.kubernetes.replicas || 1,
       selector: {
         matchLabels: {
           app: config.appName
@@ -27,15 +27,19 @@ export function generateDeployment(config, image) {
             {
               name: config.appName,
               image,
+              imagePullPolicy: isLocal ? 'IfNotPresent' : 'Always',
               ports: [
                 {
                   containerPort: config.kubernetes.containerPort
                 }
               ],
               env: Object.entries(config.env || {}).map(
-                ([key, value]) => ({ name: key, value })
+                ([key, value]) => ({
+                  name: key,
+                  value: String(value)
+                })
               ),
-              resources: config.resources
+              resources: config.resources || undefined
             }
           ]
         }
@@ -43,8 +47,8 @@ export function generateDeployment(config, image) {
     }
   };
 
-  const yamlContent = yaml.dump(deployment);
+  const yamlContent = yaml.dump(deployment, { noRefs: true });
   fs.writeFileSync('deployment.yaml', yamlContent);
 
-  return 'deployment.yaml';
+  console.log('📄 deployment.yaml generated');
 }

package/src/preflight/checkFiles.js

@@ -0,0 +1,16 @@
+import fs from 'fs';
+
+export function checkRequiredFiles() {
+  const missing = [];
+
+  if (!fs.existsSync('Dockerfile')) missing.push('Dockerfile');
+  if (!fs.existsSync('k8s.config.json')) missing.push('k8s.config.json');
+
+  if (missing.length) {
+    console.error('\n❌ Missing required files:');
+    missing.forEach(f => console.error(` - ${f}`));
+
+    console.error('\n👉 Run: k8s-deploy init');
+    process.exit(1);
+  }
+}