{"id":13877955,"url":"https://github.com/platbr/kubernetes-health","last_synced_at":"2025-04-28T19:53:18.878Z","repository":{"id":54673110,"uuid":"113362710","full_name":"platbr/kubernetes-health","owner":"platbr","description":"This gem allows kubernetes monitoring your app while it is running migrates and after it starts.","archived":false,"fork":false,"pushed_at":"2024-10-11T15:47:23.000Z","size":100,"stargazers_count":30,"open_issues_count":1,"forks_count":11,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T10:38:05.770Z","etag":null,"topics":["gem","health","kubernetes","migrates","rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/platbr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2017-12-06T20:14:00.000Z","updated_at":"2025-01-29T00:55:01.000Z","dependencies_parsed_at":"2023-02-01T09:31:05.945Z","dependency_job_id":"e79ae687-a938-40b4-b196-78e8512ba214","html_url":"https://github.com/platbr/kubernetes-health","commit_stats":{"total_commits":67,"total_committers":5,"mean_commits":13.4,"dds":"0.19402985074626866","last_synced_commit":"6fe56c9874c9847fda8c0596015e9470b437f54f"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platbr%2Fkubernetes-health","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platbr%2Fkubernetes-health/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platbr%2Fkubernetes-health/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platbr%2Fkubernetes-health/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/platbr","download_url":"https://codeload.github.com/platbr/kubernetes-health/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251156225,"owners_count":21544800,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["gem","health","kubernetes","migrates","rails"],"created_at":"2024-08-06T08:01:35.894Z","updated_at":"2025-04-28T19:53:18.856Z","avatar_url":"https://github.com/platbr.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Kubernetes::Health\nThis gem opens a dedicated HTTP port to allow Kubernetes to monitor your Rails app while it is running migrations, Rake tasks, Sidekiq, or Puma.\n\n# Features\n- Puma and Sidekiq metrics for autoscaling.\n- Prometheus and JSON metrics.\n- add routes `/_readiness`, `/_liveness` on Rails Stack.\n- add routes `/_readiness`, `/_liveness` and `/_metrics` as a puma plugin at another port to avoid problems when your app get busy. (code copied from `puma-metrics` gem).\n- add routes `/_readiness` and `/_liveness` while `rake db:migrate` runs. (optional)\n- add routes `/_metrics` while `sidekiq` runs. (optional)\n- add support to avoid parallel running of `rake db:migrate` while keep kubernetes waiting (PostgreSQL required for default config, read `Customizing locking` section.).\n- allow custom checks for `/_readiness` and `/_liveness`.\n \n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'kubernetes-health', '~\u003e 3.14'\n```\n\n## Enabling puma plugin\n\nadd in `config/puma.rb`\n```\nplugin 'kubernetes'\nkubernetes_url 'tcp://0.0.0.0:9393'\n```\n\nIn Kubernetes you need to configure your deployment `readinessProbe` and `livenessProbe` like this:\n\n```\n        livenessProbe:\n          httpGet:\n            path: /_liveness\n            port: 9393\n          initialDelaySeconds: 30\n          timeoutSeconds: 5\n          failureThreshold: 3\n          successThreshold: 1\n        readinessProbe:\n          httpGet:\n            path: /_readiness\n            port: 9393\n          initialDelaySeconds: 30\n          timeoutSeconds: 5\n          failureThreshold: 3\n          successThreshold: 1\n```\n\nSetting `failureThreshold` is import to avoid problems when app finish migrates and is starting the web process.\n\n## Enabling liveness/readiness routes while `rake db:migrate` runs\n\nYour Dockerfile's entry script needs to run migrates before start your web app.\n\nAdd `KUBERNETES_HEALTH_ENABLE_RACK_ON_MIGRATE=true` environment variable.\n\nor add in your `application.rb`.\n\n```\n# default: false\nKubernetes::Health::Config.enable_rack_on_migrate = true\n```\nThe defined port at `config/puma.rb` will be used but can be overrided by `KUBERNETES_HEALTH_METRICS_PORT` env var.\n\n## Enabling liveness/readiness routes while any `rake` tasks runs\n\nIf you need to run another rake tasks than `db:migrate`, like `assets:precompile`, you can enable the monitoring routes by this way:\n\nAdd a `rake` file enhancing the original task by using `kubernetes_health:rack_on_rake` task. For example:\n\n```\n# File: lib/tasks/kubernetes_health_enable_rack_on_assets_precompile.rake\nRake::Task['assets:precompile'].enhance(['kubernetes_health:rack_on_rake'])\n```\n\n```\n# File: lib/tasks/kubernetes_health_enable_rack_on_assets_clobber.rake\nRake::Task['assets:clobber'].enhance(['kubernetes_health:rack_on_rake'])\n```\n\nI do recommend doing some checks to make it only enabled in the K8S environment.\nThe defined port at `config/puma.rb` will be used but can be overrided by `KUBERNETES_HEALTH_METRICS_PORT` env var.\n\n## Enabling liveness/readiness routes for `sidekiq`\n\nAdd `KUBERNETES_HEALTH_ENABLE_RACK_ON_SIDEKIQ=true` environment variable.\n\nor add in your `application.rb`.\n\n```\n# default: false\nKubernetes::Health::Config.enable_rack_on_sidekiq = true\n```\nThe defined port at `config/puma.rb` will be used but can be overrided by `KUBERNETES_HEALTH_METRICS_PORT` env var.\n\n### How `rake` and `sidekiq` monitoring works\nIt will run a rack server for `/_readiness`, `/_liveness` and `/_metrics` for rake and `/_metrics` for Sidekiq.\nThe liveness route will respond using `200` but readiness `503`.\n\n## Avoiding migrations running in parallel and making kubernetes happy.\nRails already avoid migrations running in parallel, but it raises exceptions. This gem will just wait for other migrations without exit.\nIf you enable `rack_on_migrate` together with this, kubernetes will just wait, avoiding erros.\n\n\nAdd `KUBERNETES_HEALTH_ENABLE_LOCK_ON_MIGRATE=true` environment variable.\n\nor add in your `application.rb`.\n\n```\n# default: false\nKubernetes::Health::Config.enable_lock_on_migrate = true\n```\n\n### Customizing locking\nBy default it is working for PostgreSQL, but you can customize it using a lambda:\n```\nKubernetes::Health::Config.lock_or_wait = lambda {\n  ActiveRecord::Base.connection.execute \"SET lock_timeout TO '3600s'; SELECT pg_advisory_lock(123456789123456789);\"\n}\n\nKubernetes::Health::Config.unlock = lambda {\n    ActiveRecord::Base.connection.execute 'select pg_advisory_unlock(123456789123456789);'\n}\n```\n\n## Customizing checks\n\nIt only works for routes in rails stack, they are not executed while `rake db:migrate` runs.\n\nI prefer do nothing else on `liveness` to avoid unnecessary `CrashLoopBackOff` status. `params` is optional (request params).\n\n```\nKubernetes::Health::Config.live_if = lambda { |params|\n  true\n}\n\n```\nEx. Check if PostgreSQL is reachable on `readiness` indicating that credentials are setup right and keeps cache to avoid doing it a lot. `params` is optional (request params).\n```\nKubernetes::Health::Config.ready_if = lambda { |params|\n  return $kubernetes_health_test_db_connection if $kubernetes_health_test_db_connection\n  $kubernetes_health_test_db_connection = ActiveRecord::Base.connection.execute(\"SELECT 1\").cmd_tuples == 1\n}\n```\n\n## Customizing routes\n```\nKubernetes::Health::Config.route_liveness = '/liveness'\nKubernetes::Health::Config.route_readiness = '/readiness'\nKubernetes::Health::Config.route_metrics = '/metrics'\n```\nor using env\n```\nKUBERNETES_HEALTH_LIVENESS_ROUTE='/liveness'\nKUBERNETES_HEALTH_READINESS_ROUTE='/readiness'\nKUBERNETES_HEALTH_RESPONSE_FORMAT='/metrics'\n```\n\n## Response format\nIf you are using `https://github.com/zalando-incubator/kube-metrics-adapter` you will want to use `json` format.\n\nDefault is `prometheus`.\n```\nKubernetes::Health::Config.response_format = 'json'\n```\nor using env\n```\nKUBERNETES_HEALTH_RESPONSE_FORMAT=json\n```\n\n## Customizing requests logs\n\n```\nKubernetes::Health::Config.request_log_callback = lambda { |req, http_code, content|\n  Rails.logger.debug \"Kubernetes Health: Rack on Migrate - Request: Path: #{req.path_info} / Params: #{req.params} /  HTTP Code: #{http_code}\\n#{content}\"  rescue nil\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplatbr%2Fkubernetes-health","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplatbr%2Fkubernetes-health","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplatbr%2Fkubernetes-health/lists"}