k8s-deploy-helper 0.1.1 → 1.2.0

package/README.md

@@ -1 +1,160 @@
-## K8s-deploy-helper
+k8s-deploy-helper 🚀
+
+k8s-deploy-helper is a simple and beginner-friendly CLI tool that helps you build Docker images and deploy applications to Kubernetes using a guided and automated workflow.
+
+It is designed to reduce the learning curve of Kubernetes while still supporting real-world DevOps practices.
+
+-----
+
+PROBLEM THIS TOOL SOLVES 🧩
+
+Deploying an application to Kubernetes usually involves many manual steps:
+
+• Creating and maintaining a Dockerfile
+• Writing Kubernetes YAML files (Deployment, Service, etc.)
+• Understanding kubectl commands
+• Managing Docker registry authentication
+• Debugging unclear or low-level runtime errors
+
+For beginners and even intermediate developers, this process can be confusing, time-consuming, and error-prone.
+
+k8s-deploy-helper removes this complexity by automating these steps and guiding the user through a clear, predictable workflow.
+
+-----
+
+WHAT THIS TOOL DOES ⚙️
+
+k8s-deploy-helper automates the full deployment process by:
+
+• Automatically generating missing Docker and Kubernetes configuration files
+• Building Docker images for your application
+• Supporting local deployments without pushing images to Docker Hub
+• Generating Kubernetes Deployment and Service YAML files automatically
+• Applying Kubernetes resources using kubectl
+• Detecting missing setup early and displaying clear, actionable error messages
+
+You focus on building your application.
+The tool handles the deployment.
+
+-----
+
+REQUIREMENTS (BEGINNER FRIENDLY) 🛠️
+
+Minimum setup for local usage:
+
+• Docker Desktop installed
+• Kubernetes enabled inside Docker Desktop
+
+Docker Desktop already includes:
+• Docker
+• kubectl
+• A local Kubernetes cluster
+
+To verify Kubernetes is running:
+
+kubectl get nodes
+
+-----
+
+INSTALLATION 📦
+
+Install the package globally using npm:
+  npm install -g k8s-deploy-helper
+
+Verify the installation:
+  k8s-deploy --version
+
+-----
+
+HOW TO USE (STEP-BY-STEP) ▶️
+
+STEP 1: INITIALIZE THE PROJECT ⭐
+
+If your project does not already have a Dockerfile or k8s.config.json, 
+run:
+  k8s-deploy init
+
+This command will:
+• Create a basic Dockerfile
+• Create a k8s.config.json configuration file
+• Prepare your project for Kubernetes deployment
+
+You can modify these files later to match your application needs.
+
+STEP 2: DEPLOY LOCALLY (RECOMMENDED FOR BEGINNERS) 🧪
+
+For first-time users, deploy without using Docker Hub or any container registry:
+  k8s-deploy deploy --local
+
+What happens during local deployment:
+• The Docker image is built locally
+• Image push to a registry is skipped
+• Kubernetes uses the local image
+• The application is deployed to the local Kubernetes cluster
+
+No Docker Hub account or login is required.
+
+STEP 3: STANDARD DEPLOYMENT (OPTIONAL) 🌐
+
+Once you are comfortable and logged into a container registry, 
+run:
+  k8s-deploy deploy
+
+This will:
+• Build the Docker image
+• Push the image to the configured registry
+• Deploy the application to Kubernetes
+
+-----
+
+FILES CREATED BY THE TOOL 📁
+
+After running the commands, the following files will exist in your project:
+
+Dockerfile
+k8s.config.json
+deployment.yaml
+service.yaml
+
+These files can be:
+• Reviewed
+• Modified
+• Committed to Git
+• Used independently if needed
+
+-----
+
+WHAT HAPPENS INTERNALLY 🔍
+
+When you run the deploy command, the tool performs the following steps:
+
+• Checks for required files
+• Verifies Docker and Kubernetes availability
+• Builds the Docker image
+• Generates Kubernetes YAML files
+• Applies resources using kubectl
+
+Each step is logged clearly so you can understand what is happening.
+
+-----
+
+WHY THIS TOOL IS VALUABLE ⭐
+
+Without this tool:
+• You manually write Kubernetes YAML
+• You manage Docker commands yourself
+• You deal with registry authentication issues
+• Kubernetes feels complex and fragile
+
+With this tool:
+• One-command deployment
+• Beginner-safe defaults
+• Hands-on Kubernetes experience
+• Production-ready deployment workflow
+
+-----
+
+AUTHOR 👨‍💻
+
+Lokesh Shimpi
+Built to simplify Kubernetes deployment and demonstrate real-world DevOps engineering.

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.2.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);
+  }
+}