k8s-deploy-helper 1.0.0 → 1.3.0

package/README.md

@@ -1,176 +1,154 @@
-# 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.
+# 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.
 
-## ✨ Overview
+-----
 
-`k8s-deploy-helper` simplifies the process of:
-- Building Docker images
-- Pushing images to container registries
-- Generating Kubernetes manifests
-- Deploying applications to Kubernetes clusters
+### PROBLEM THIS TOOL SOLVES 🧩
 
-The tool is **configuration-driven**, **CI/CD-friendly**, and uses **native Docker and kubectl** instead of opaque SDK abstractions.
+## 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
 
-## 🚀 Features
+# For beginners and even intermediate developers, this process can be confusing, time-consuming, and error-prone.
 
-- 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
+# k8s-deploy-helper removes this complexity by automating these steps and guiding the user through a clear, predictable workflow.
 
----
+-----
 
-## 📦 Installation
+### WHAT THIS TOOL DOES ⚙️
 
-Install globally from npm:
-npm install -g k8s-deploy-helper
+## k8s-deploy-helper automates the full deployment process by:
 
-Verify installation:
-k8s-deploy --version
+• 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
 
-🛠 Prerequisites
-Ensure the following are installed and configured:
+You focus on building your application.
+The tool handles the deployment.
 
-Node.js (v18+)
+-----
 
-Docker (running)
+### REQUIREMENTS (BEGINNER FRIENDLY) 🛠️
 
-kubectl
+# Minimum setup for local usage:
+• Docker Desktop installed
+• Kubernetes enabled inside Docker Desktop
 
-Kubernetes cluster:
+# Docker Desktop already includes:
+• Docker
+• kubectl
+• A local Kubernetes cluster
 
-Docker Desktop Kubernetes
+# To verify Kubernetes is running:
+  kubectl get nodes
 
-Minikube
+-----
 
-EKS / GKE / AKS
+### INSTALLATION 📦
 
-Container registry access (Docker Hub, ECR, GHCR, etc.)
+# Install the package globally using npm:
+  npm install -g k8s-deploy-helper
 
-📄 Configuration
-Create a k8s.config.json file in your project root.
+# Verify the installation:
+  k8s-deploy --version
 
-Example configuration:
-json
-Copy code
-{
-  "appName": "my-app",
-  "namespace": "default",
+-----
 
-  "docker": {
-    "image": "username/my-app",
-    "tag": "latest",
-    "context": ".",
-    "dockerfile": "Dockerfile"
-  },
+### HOW TO USE (STEP-BY-STEP) ▶️
 
-  "kubernetes": {
-    "replicas": 2,
-    "containerPort": 3000,
-    "servicePort": 80,
-    "serviceType": "ClusterIP"
-  },
+## STEP 1: INITIALIZE THE PROJECT ⭐
 
-  "resources": {
-    "limits": {
-      "cpu": "500m",
-      "memory": "512Mi"
-    },
-    "requests": {
-      "cpu": "250m",
-      "memory": "256Mi"
-    }
-  },
+# If your project does not already have a Dockerfile or k8s.config.json, run:
+  k8s-deploy init
 
-  "env": {
-    "NODE_ENV": "production"
-  }
-}
-▶️ Usage
-Deploy your application using a single command:
+# This command will:
+• Create a basic Dockerfile
+• Create a k8s.config.json configuration file
+• Prepare your project for Kubernetes deployment
 
-bash
-Copy code
-k8s-deploy deploy
-What this command does:
-Builds the Docker image
+# You can modify these files later to match your application needs.
 
-Pushes the image to the registry (if authorized)
+## STEP 2: DEPLOY LOCALLY (RECOMMENDED FOR BEGINNERS) 🧪
 
-Generates Kubernetes manifests:
+## For first-time users, deploy without using Docker Hub or any container registry:
+  k8s-deploy deploy --local
 
-deployment.yaml
-
-service.yaml
-
-Applies the resources to the Kubernetes cluster using kubectl
+## 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
 
-If the image push fails, deployment continues using the existing image tag.
+# No Docker Hub account or login is required.
 
-📁 Generated Files
-text
-Copy code
-deployment.yaml
-service.yaml
-These files can be reviewed, committed to version control, or applied independently.
+## STEP 3: STANDARD DEPLOYMENT (OPTIONAL) 🌐
 
-🔐 Authentication
-This tool does not manage credentials.
+# Once you are comfortable and logged into a container registry, run:
+  k8s-deploy deploy
 
-Authentication must be handled externally:
+### This will:
+• Build the Docker image
+• Push the image to the configured registry
+• Deploy the application to Kubernetes
 
-docker login for container registries
+-----
 
-kubectl config for Kubernetes clusters
+### FILES CREATED BY THE TOOL 📁
 
-This mirrors real-world CI/CD environments and avoids secret leakage.
+# After running the commands, the following files will exist in your project:
 
-🧠 Design Principles
-Explicit over implicit — no hidden magic
+Dockerfile
+k8s.config.json
+deployment.yaml
+service.yaml
 
-Fail loud, fail early — CI-friendly logs
+# These files can be:
+• Reviewed
+• Modified
+• Committed to Git
+• Used independently if needed
 
-Idempotent operations — safe re-runs
+-----
 
-No vendor lock-in — relies on standard tools
+### WHAT HAPPENS INTERNALLY 🔍
 
-🧪 Example Output
-text
-Copy code
-🐳 Building Docker image: username/my-app:latest
-📤 Pushing Docker image: username/my-app:latest
-⚠️ Image push failed — continuing deployment
+# When you run the deploy command, the tool performs the following steps:
 
-☸️ 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:
+• Checks for required files
+• Verifies Docker and Kubernetes availability
+• Builds the Docker image
+• Generates Kubernetes YAML files
+• Applies resources using kubectl
 
---dry-run mode
+# Each step is logged clearly so you can understand what is happening.
 
-Rollback support
+-----
 
-Helm chart generation
+### WHY THIS TOOL IS VALUABLE ⭐
 
-Deployment health checks
+## Without this tool:
+• You manually write Kubernetes YAML
+• You manage Docker commands yourself
+• You deal with registry authentication issues
+• Kubernetes feels complex and fragile
 
-GitHub Actions CI template
+## With this tool:
+• One-command deployment
+• Beginner-safe defaults
+• Hands-on Kubernetes experience
+• Production-ready deployment workflow
 
-📜 License
-MIT License
+-----
 
-👨‍💻 Author
-Lokesh Shimpi
+### AUTHOR 👨‍💻
+Lokesh Shimpi

package/package.json

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

package/src/preflight/checkEnvironment.js

@@ -0,0 +1,33 @@
+import { execa } from 'execa';
+
+export async function checkEnvironment() {
+  // 1. Check Docker availability
+  try {
+    await execa('docker', ['info'], { stdio: 'ignore' });
+  } catch {
+    throw new Error(
+      'Docker is not running.\n' +
+      '👉 Please start Docker Desktop and try again.'
+    );
+  }
+
+  // 2. Check kubectl availability
+  try {
+    await execa('kubectl', ['version', '--client'], { stdio: 'ignore' });
+  } catch {
+    throw new Error(
+      'kubectl is not available.\n' +
+      '👉 Enable Kubernetes in Docker Desktop or install kubectl.'
+    );
+  }
+
+  // 3. Check Kubernetes cluster connectivity
+  try {
+    await execa('kubectl', ['cluster-info'], { stdio: 'ignore' });
+  } catch {
+    throw new Error(
+      'Kubernetes cluster is not reachable.\n' +
+      '👉 Enable Kubernetes in Docker Desktop and wait until it is ready.'
+    );
+  }
+}