{"id":28955875,"url":"https://github.com/meysam81/liveness-check","last_synced_at":"2026-04-29T16:09:51.913Z","repository":{"id":298995562,"uuid":"1001769599","full_name":"meysam81/liveness-check","owner":"meysam81","description":"Kubernetes-native health checker that automatically finds and verifies your latest pods are ready before considering deployments successful - perfect for preview environments","archived":false,"fork":false,"pushed_at":"2026-04-19T05:57:59.000Z","size":3426,"stargazers_count":2,"open_issues_count":13,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T07:34:53.215Z","etag":null,"topics":["ci-cd","cli-tool","container-native","cross-platform","devops","docker","golang","health-check","http-client","kubernetes","kubernetes-health","liveness-probe","microservices","monitoring","preview-environments","readiness-probe","single-binary","site-reliability","sre","zero-dependencies"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meysam81.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"meysam81","patreon":"meysam81","buy_me_a_coffee":"meysam"}},"created_at":"2025-06-14T01:46:44.000Z","updated_at":"2025-09-09T08:43:58.000Z","dependencies_parsed_at":"2025-07-20T10:06:56.603Z","dependency_job_id":"99af027c-6ee5-4c24-b1a0-de75c5697ee4","html_url":"https://github.com/meysam81/liveness-check","commit_stats":null,"previous_names":["meysam81/liveness-check"],"tags_count":8,"template":false,"template_full_name":"meysam81/go-boilerplate","purl":"pkg:github/meysam81/liveness-check","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Fliveness-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Fliveness-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Fliveness-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Fliveness-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meysam81","download_url":"https://codeload.github.com/meysam81/liveness-check/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meysam81%2Fliveness-check/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32433087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci-cd","cli-tool","container-native","cross-platform","devops","docker","golang","health-check","http-client","kubernetes","kubernetes-health","liveness-probe","microservices","monitoring","preview-environments","readiness-probe","single-binary","site-reliability","sre","zero-dependencies"],"created_at":"2025-06-23T20:11:57.090Z","updated_at":"2026-04-29T16:09:51.907Z","avatar_url":"https://github.com/meysam81.png","language":"Go","funding_links":["https://github.com/sponsors/meysam81","https://patreon.com/meysam81","https://buymeacoffee.com/meysam"],"categories":[],"sub_categories":[],"readme":"# 🩺 liveness-check\n\n\u003cdiv align=\"center\"\u003e\n\n**Kubernetes-native health checking for your deployments**\n\n_Verify your pods are ready before traffic hits them_\n\n---\n\n\u003c!-- Project Quality \u0026 Status --\u003e\n\n[![CI/CD](https://github.com/meysam81/liveness-check/actions/workflows/ci.yml/badge.svg)](https://github.com/meysam81/liveness-check/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/meysam81/liveness-check)](https://goreportcard.com/report/github.com/meysam81/liveness-check)\n[![🛡️ Zero Vulnerabilities](https://img.shields.io/badge/🛡️_Zero_Vulnerabilities-Kubescape_Verified-brightgreen?style=flat-square)](https://github.com/meysam81/liveness-check/actions)\n\n\u003c!-- Distribution \u0026 Availability --\u003e\n\n[![Latest Release](https://img.shields.io/github/v/release/meysam81/liveness-check?style=flat-square\u0026logo=github\u0026color=blue)](https://github.com/meysam81/liveness-check/releases/latest)\n[![Docker Image](https://img.shields.io/badge/docker-meysam81%2Fliveness--check-blue?style=flat-square\u0026logo=docker)](https://hub.docker.com/r/meysam81/liveness-check)\n[![Docker Pulls](https://img.shields.io/docker/pulls/meysam81/liveness-check?style=flat-square\u0026logo=docker)](https://hub.docker.com/r/meysam81/liveness-check)\n[![Image Size](https://img.shields.io/docker/image-size/meysam81/liveness-check?style=flat-square\u0026logo=docker)](https://ghcr.io/meysam81/liveness-check)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/meysam81/liveness-check?style=flat-square\u0026logo=go)](go.mod)\n[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/meysam81/liveness-check)](https://github.com/meysam81/liveness-check)\n[![GitHub repo size](https://img.shields.io/github/repo-size/meysam81/liveness-check)](https://github.com/meysam81/liveness-check)\n\n\n\u003c!-- Features \u0026 Capabilities --\u003e\n\n[![🚀 Single Binary](https://img.shields.io/badge/🚀_Single-Binary-blueviolet?style=flat-square)](https://golang.org/)\n[![📦 Container Native](https://img.shields.io/badge/📦_Container-Native-2496ED?style=flat-square\u0026logo=docker)](https://kubernetes.io/)\n[![🔒 Air-Gap Ready](https://img.shields.io/badge/🔒_Air--Gap-Compatible-darkred?style=flat-square)](#quick-start)\n[![♾️ Smart Retries](https://img.shields.io/badge/♾️_Smart-Retries-teal?style=flat-square)](#how-it-works)\n\n\u003c!-- Code Quality \u0026 Tools --\u003e\n\n[![Pre-commit](https://img.shields.io/badge/Quality-pre--commit_hooks-FAB040?style=flat-square\u0026logo=pre-commit)](https://pre-commit.com/)\n[![12-Factor App](https://img.shields.io/badge/Architecture-12--Factor_App-blueviolet?style=flat-square)](https://12factor.net/)\n\n\u003c!-- License \u0026 Support --\u003e\n\n[![License](https://img.shields.io/badge/License-Apache--2.0-green.svg?style=flat-square)](LICENSE)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/meysam81?style=flat-square\u0026logo=github\u0026color=pink)](https://github.com/sponsors/meysam81)\n[![Community Chat](https://img.shields.io/badge/💬_Chat-Zulip-brightgreen?style=flat-square)](https://developer-friendly.zulipchat.com/)\n\n[![Sponsor](https://img.shields.io/badge/💖_Sponsor_on_GitHub-@meysam81-pink?style=for-the-badge)](https://github.com/sponsors/meysam81)\n\n\u003c/div\u003e\n\n---\n\n## ✨ What is liveness-check?\n\nA **production-ready Kubernetes tool** that automatically finds your recently deployed pods and verifies they're healthy before considering your deployment successful. Perfect for **preview environments**, **CI/CD pipelines**, and **zero-downtime deployments**.\n\n### 🎯 Why you need this\n\n- **🔍 Preview Environments**: Ensure your feature branch is actually working before showing it to stakeholders\n- **🚀 CI/CD Integration**: Block deployments until pods are genuinely ready to serve traffic\n- **⚡ Zero-Downtime**: Verify new deployments without manual intervention\n- **🛡️ Production Safety**: Catch deployment issues before they affect users\n\n---\n\n## 🚀 Quick Start\n\n### 1. Deploy the complete solution\n\nHead over to the [`deploy/`](./deploy/) directory and apply the provided Kubernetes Job manifest:\n\n```yaml\n# Example: Check if your deployment is ready\nenv:\n  - name: NAMESPACE\n    value: \"my-app-namespace\"\n  - name: LABEL_SELECTORS\n    value: \"app=my-app,version=v2.1.0\"\n  - name: ENDPOINT\n    value: \"/api/health\"\n```\n\n### 3. Run and verify\n\nThe job will automatically:\n\n- 🔎 Find your most recent pod matching the labels\n- 🩺 Perform health checks with smart retry logic\n- ✅ Exit successfully when your pod is ready\n- 🚨 Fail fast if something's wrong\n\n---\n\n## 📋 Complete Job Manifest\n\nThe [`deploy/job.yml`](./deploy/job.yml) provides a **production-ready** Kubernetes Job with:\n\n- ✅ **Security hardened** (non-root, read-only filesystem, dropped capabilities)\n- ✅ **RBAC configured** with minimal required permissions\n- ✅ **Resource limits** and best practices applied\n- ✅ **Configurable via environment variables**\n\nSimply apply it and customize the environment variables for your use case.\n\n---\n\n## ⚙️ Configuration\n\n| Environment Variable | Description                     | Default       | Example                |\n| -------------------- | ------------------------------- | ------------- | ---------------------- |\n| `NAMESPACE`          | Target namespace                | `\"\"` (all)    | `production`           |\n| `LABEL_SELECTORS`    | Pod labels (comma-separated)    | **required**  | `app=api,version=v1.2` |\n| `ENDPOINT`           | Health check path               | `/healthz`    | `/api/v1/health`       |\n| `SCHEME`             | Protocol                        | `http`        | `https`                |\n| `PORT`               | Target port                     | _auto-detect_ | `8080`                 |\n| `TIMEOUT`            | Request timeout (seconds)       | `5`           | `10`                   |\n| `RETRIES`            | Max retry attempts (0=infinite) | `0`           | `5`                    |\n| `STATUS_CODE`        | Expected HTTP status            | `200`         | `204`                  |\n\n---\n\n## 🧠 How it works\n\n```mermaid\ngraph LR\n    A[🚀 Job Starts] --\u003e B[🔍 Find Latest Pod]\n    B --\u003e C{📍 Pod has IP?}\n    C --\u003e|No| D[⏳ Wait + Retry]\n    D --\u003e C\n    C --\u003e|Yes| E[🩺 Health Check]\n    E --\u003e F{✅ Healthy?}\n    F --\u003e|No| G[⏳ Smart Retry]\n    G --\u003e E\n    F --\u003e|Yes| H[🎉 Success!]\n```\n\n**Smart Features:**\n\n- 🎯 **Jitter logic** prevents thundering herd effects\n- 🔄 **Exponential backoff** for failed requests\n- 📊 **Millisecond precision** timing\n- 🎪 **Graceful degradation** for edge cases\n\n---\n\n## 🏗️ Installation Options\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐳 Container Images\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# GitHub Container Registry (recommended)\ndocker pull ghcr.io/meysam81/liveness-check:latest\n\n# Docker Hub\ndocker pull meysam81/liveness-check:latest\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📦 Go Install\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngo install github.com/meysam81/liveness-check@latest\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔧 Build from Source\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/meysam81/liveness-check.git\ncd liveness-check\ngo build -o liveness-check\n```\n\n\u003c/details\u003e\n\n---\n\n## 💡 Use Cases\n\n### 🎭 Preview Environments\n\n```yaml\n# Verify your feature branch before demo\nenv:\n  - name: LABEL_SELECTORS\n    value: \"app=frontend,branch=feature-awesome-ui\"\n```\n\n### 🚀 Blue-Green Deployments\n\n```yaml\n# Check new version before traffic switch\nenv:\n  - name: LABEL_SELECTORS\n    value: \"app=api,version=v2.0.0,deployment=green\"\n```\n\n### 🔄 Rolling Updates\n\n```yaml\n# Ensure each pod is ready during rolling update\nenv:\n  - name: LABEL_SELECTORS\n    value: \"app=backend,release=canary\"\n```\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the Kubernetes community**\n\n[⭐ Star this repo](https://github.com/meysam81/liveness-check) • [🐛 Report issues](https://github.com/meysam81/liveness-check/issues) • [💬 Get support](https://github.com/meysam81/liveness-check/discussions)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeysam81%2Fliveness-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeysam81%2Fliveness-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeysam81%2Fliveness-check/lists"}