{"id":20567779,"url":"https://github.com/isometry/platform-health","last_synced_at":"2026-02-24T23:03:56.600Z","repository":{"id":230602884,"uuid":"779727202","full_name":"isometry/platform-health","owner":"isometry","description":"Lightweight \u0026 extensible platform health monitoring","archived":false,"fork":false,"pushed_at":"2025-10-07T05:39:48.000Z","size":515,"stargazers_count":2,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-07T07:22:06.993Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isometry.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-30T16:00:58.000Z","updated_at":"2025-10-07T05:39:12.000Z","dependencies_parsed_at":"2024-03-30T19:29:40.287Z","dependency_job_id":"2e3a5a08-d62a-4d5b-960e-55bde8a78205","html_url":"https://github.com/isometry/platform-health","commit_stats":null,"previous_names":["isometry/platform-health"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/isometry/platform-health","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fplatform-health","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fplatform-health/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fplatform-health/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fplatform-health/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isometry","download_url":"https://codeload.github.com/isometry/platform-health/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fplatform-health/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016627,"owners_count":26085855,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-11-16T04:48:30.318Z","updated_at":"2026-02-24T23:03:56.592Z","avatar_url":"https://github.com/isometry.png","language":"Go","readme":"# Platform Health\n\nLightweight \u0026 extensible platform health monitoring.\n\n## Overview\n\nPlatform Health is a simple client/server system for lightweight health monitoring of platform components and systems.\n\nThe Platform Health client (`ph client`) sends a gRPC health check request to a Platform Health server which is configured to probe a set of network services. Probes run asynchronously on the server (subject to configurable timeouts), with the accumulated response returned to the client.\n\n## Providers\n\nProbes use a compile-time [provider plugin system](pkg/provider) that supports extension to monitoring of arbitrary services. Integrated providers include:\n\n* [`system`](pkg/provider/system): Hierarchical grouping of related health checks with status aggregation\n* [`satellite`](pkg/provider/satellite): A separate satellite instance of the Platform Health server\n* [`ssh`](pkg/provider/ssh): SSH protocol handshake with host key verification\n* [`tcp`](pkg/provider/tcp): TCP connectivity checks\n* [`tls`](pkg/provider/tls): TLS handshake and certificate verification\n* [`http`](pkg/provider/http): HTTP(S) health checks with CEL-based response validation, full REST/GraphQL API support, and TLS details\n* [`grpc`](pkg/provider/grpc): gRPC Health v1 service status checks\n* [`kubernetes`](pkg/provider/kubernetes): Kubernetes resource existence and readiness\n* [`helm`](pkg/provider/helm): Helm release existence and deployment status\n* [`vault`](pkg/provider/vault): [Vault](https://www.vaultproject.io/) cluster initialization and seal status\n\nEach provider implements the `Instance` interface, with the health of each instance obtained asynchronously, and contributing to the overall response.\n\n## Installation\n\n### macOS/Linux\n\n```bash\nbrew install isometry/tap/platform-health\n```\n\n```console\n$ ph server -l \u0026 sleep 1 \u0026\u0026 ph client \u0026\u0026 kill %1\n{\"status\":\"HEALTHY\", \"duration\":\"0.000004833s\"}\n```\n\n### Kubernetes\n\n#### Install via `helm` chart\n\n```console\nhelm upgrade \\\n    --install platform-health \\\n    -n platform-health --create-namespace \\\n    oci://ghcr.io/isometry/charts/platform-health\n```\n\n#### Install via `kubectl`\n\n```bash\nkubectl create configmap platform-health --from-file=platform-health.yaml=/dev/stdin \u003c\u003c-EOF\ncomponents:\n  ssh@localhost:\n    type: tcp\n    spec:\n      host: localhost\n      port: 22\n  gmail:\n    type: tls\n    spec:\n      host: smtp.gmail.com\n      port: 465\n  google:\n    type: http\n    spec:\n      url: https://google.com\nEOF\n\nkubectl create deployment platform-health --image ghcr.io/isometry/platform-health:latest --port=8080\n\nkubectl patch deployment platform-health --patch-file=/dev/stdin \u003c\u003c-EOF\n  spec:\n    template:\n      spec:\n        volumes:\n          - name: config\n            configMap:\n              name: platform-health\n        containers:\n          - name: platform-health\n            args:\n              - -vv\n            volumeMounts:\n              - name: config\n                mountPath: /config\nEOF\n\nkubectl create service loadbalancer platform-health --tcp=8080:8080\n```\n\n## Usage\n\n### Client\n\n```bash\n# Check all components\nph client\n\n# Check specific components\nph client -c google -c github\n\n# Check with hierarchical path (system/component)\nph client -c fluxcd/source-controller\n\n# Connect to remote server\nph client prod:8080 -c google\n```\n\n### One-Shot Mode\n\nRun health checks once and exit without starting a server:\n\n```bash\nph check\n\n# Check specific components only\nph check -c google -c fluxcd/source-controller\n```\n\nThis is useful for:\n- Validating configuration files\n- Local health check verification\n- CI/CD pipeline integration\n- Testing specific components\n\n### Ad-hoc Checks\n\nCreate and run health checks without a configuration file:\n\n```bash\n# TCP connectivity check\nph check tcp --host example.com --port 443\n\n# HTTP health check\nph check http --url https://api.example.com/health\n\n# HTTP check with CEL expression\nph check http --url https://api.example.com/health \\\n  --check 'response.status == 200'\n\n# TLS certificate check\nph check tls --host example.com --port 443\n```\n\n### Context Inspection\n\nInspect the CEL evaluation context for debugging expressions:\n\n```bash\n# View context for a configured component\nph context my-app\n\n# View context for nested system components\nph context fluxcd/source-controller\n\n# View context for ad-hoc provider\nph context http --url https://api.example.com/health\n```\n\n## Configuration\n\nThe Platform Health server reads configuration from a YAML file. By default, it searches for `platform-health.yaml` in standard config paths (`.` and `/config`).\n\nYou can customize this with:\n- `--config-path`: Override config file search paths (can be specified multiple times)\n- `--config-name`: Change the config file name (without extension)\n\n```bash\n# Use custom config file\nph server --config-name myconfig\n\n# Add search paths\nph server --config-path /custom/path --config-path ./local\n```\n\n### Configuration Structure\n\nAll health check components are defined under the `components` key:\n\n```yaml\ncomponents:\n  \u003ccomponent-name\u003e:\n    type: \u003cprovider-type\u003e      # required\n    spec:                      # provider-specific configuration\n      \u003ckey\u003e: \u003cvalue\u003e\n    checks: [...]              # optional CEL expressions\n    timeout: \u003cduration\u003e        # optional per-instance timeout\n    components: {...}          # optional nested children (system provider)\n```\n\nComponent names can contain any characters valid in YAML keys, but should avoid `/` which is used for path-filtered queries. The `type` field specifies which provider to use, and provider-specific configuration goes under `spec`.\n\n### Example\n\nThe following configuration will monitor that /something/ is listening on `tcp/22` of localhost; validate connectivity and TLS handshake to the Gmail SSL mail-submission port; and validate that Google is accessible and returning a 200 status code:\n\n```yaml\ncomponents:\n  ssh@localhost:\n    type: tcp\n    spec:\n      host: localhost\n      port: 22\n  gmail:\n    type: tls\n    spec:\n      host: smtp.gmail.com\n      port: 465\n  google:\n    type: http\n    spec:\n      url: https://google.com\n  api-health:\n    type: http\n    spec:\n      url: https://api.example.com/health\n      method: GET\n    checks:\n      - check: 'response.status == 200'\n        message: \"Expected HTTP 200\"\n      - check: 'response.json.status == \"healthy\"'\n        message: \"Service unhealthy\"\n```\n\n### Hierarchical Grouping\n\nUse the `system` provider to group related checks:\n\n```yaml\ncomponents:\n  fluxcd:\n    type: system\n    components:\n      source-controller:\n        type: kubernetes\n        spec:\n          kind: Deployment\n          namespace: flux-system\n          name: source-controller\n      kustomize-controller:\n        type: kubernetes\n        spec:\n          kind: Deployment\n          namespace: flux-system\n          name: kustomize-controller\n```\n\nThe system is reported \"healthy\" only if all sub-components are healthy.\n\n### CEL Expressions\n\nSeveral providers support CEL (Common Expression Language) expressions for custom health check validation:\n\n- [`http`](pkg/provider/http): HTTP request and response details with JSON parsing for REST/GraphQL API validation\n- [`tls`](pkg/provider/tls): TLS connection and certificate details\n- [`ssh`](pkg/provider/ssh): SSH host key and connection details\n- [`kubernetes`](pkg/provider/kubernetes): Full resource(s), including metadata, spec, status, etc.\n- [`helm`](pkg/provider/helm): Release info, chart metadata, values and manifests\n\nUse `ph context` to inspect the evaluation context available to your expressions. See [pkg/checks/README.md](pkg/checks/README.md) for CEL syntax examples and patterns.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fplatform-health","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisometry%2Fplatform-health","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fplatform-health/lists"}