{"id":13449096,"url":"https://github.com/bloomberg/goldpinger","last_synced_at":"2025-05-14T02:00:32.485Z","repository":{"id":38050859,"uuid":"160401768","full_name":"bloomberg/goldpinger","owner":"bloomberg","description":"Debugging tool for Kubernetes which tests and displays connectivity between nodes in the cluster.","archived":false,"fork":false,"pushed_at":"2024-11-11T14:32:08.000Z","size":3014,"stargazers_count":2587,"open_issues_count":25,"forks_count":179,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-04-10T16:59:30.740Z","etag":null,"topics":["kubernetes","kubernetes-monitoring","prometheus"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2018-12-04T18:31:10.000Z","updated_at":"2025-04-09T06:37:50.000Z","dependencies_parsed_at":"2023-10-20T18:29:04.158Z","dependency_job_id":"16cd0ec3-30b9-4fc9-b5dc-8a0b6ea7654a","html_url":"https://github.com/bloomberg/goldpinger","commit_stats":{"total_commits":293,"total_committers":41,"mean_commits":7.146341463414634,"dds":0.4812286689419796,"last_synced_commit":"36b0aed3b13fc4fdbb8ac9a9d276a210ae7da068"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fgoldpinger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fgoldpinger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fgoldpinger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fgoldpinger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/goldpinger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052658,"owners_count":22006716,"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":["kubernetes","kubernetes-monitoring","prometheus"],"created_at":"2024-07-31T06:00:30.917Z","updated_at":"2025-05-14T02:00:32.396Z","avatar_url":"https://github.com/bloomberg.png","language":"JavaScript","readme":"# Goldpinger\n\n[![Publish](https://github.com/bloomberg/goldpinger/actions/workflows/publish.yml/badge.svg)](https://github.com/bloomberg/goldpinger/actions/workflows/publish.yml)\n\n__Goldpinger__ makes calls between its instances to monitor your networking.\nIt runs as a [`DaemonSet`](#example-yaml) on `Kubernetes` and produces `Prometheus` metrics that can be [scraped](#prometheus), [visualised](#grafana) and [alerted](#alert-manager) on.\n\nOh, and it gives you the graph below for your cluster. Check out the [video explainer](https://youtu.be/DSFxRz_0TU4).\n\n![](./extras/screenshot.png)\n\n[:tada: 1M+ pulls from docker hub!](https://hub.docker.com/r/bloomberg/goldpinger/tags)\n\n## On the menu\n\n- [Goldpinger](#goldpinger)\n  - [On the menu](#on-the-menu)\n  - [Rationale](#rationale)\n  - [Quick start](#quick-start)\n  - [Building](#building)\n    - [Compiling using a multi-stage Dockerfile](#compiling-using-a-multi-stage-dockerfile)\n    - [Compiling locally](#compiling-locally)\n  - [Installation](#installation)\n    - [Authentication with Kubernetes API](#authentication-with-kubernetes-api)\n    - [Example YAML](#example-yaml)\n    - [Note on DNS](#note-on-dns)\n  - [Usage](#usage)\n    - [UI](#ui)\n    - [API](#api)\n    - [Prometheus](#prometheus)\n    - [Grafana](#grafana)\n    - [Alert Manager](#alert-manager)\n    - [Chaos Engineering](#chaos-engineering)\n  - [Authors](#authors)\n  - [Contributions](#contributions)\n  - [License](#license)\n\n## Rationale\n\nWe built __Goldpinger__ to troubleshoot, visualise and alert on our networking layer while adopting `Kubernetes` at Bloomberg. It has since become the go-to tool to see connectivity and slowness issues.\n\nIt's small (~16MB), simple and you'll wonder why you hadn't had it before.\n\nIf you'd like to know more, you can watch [our presentation at Kubecon 2018 Seattle](https://youtu.be/DSFxRz_0TU4).\n\n## Quick start\n\nGetting from sources:\n\n```sh\ngo get github.com/bloomberg/goldpinger/cmd/goldpinger\ngoldpinger --help\n```\n\nGetting from [docker hub](https://hub.docker.com/r/bloomberg/goldpinger):\n\n```sh\n# get from docker hub\ndocker pull bloomberg/goldpinger:v3.0.0\n```\n\n## Building\n\nThe repo comes with two ways of building a `docker` image: compiling locally, and compiling using a multi-stage `Dockerfile` image. :warning: Depending on your `docker` setup, you might need to prepend the commands below with `sudo`.\n\n### Compiling using a multi-stage Dockerfile\n\nYou will need `docker` version 17.05+ installed to support multi-stage builds.\n\n```sh\n# Build a local container without publishing\nmake build\n\n# Build \u0026 push the image somewhere\nnamespace=\"docker.io/myhandle/\" make build-release\n```\n\nThis was contributed via [@michiel](https://github.com/michiel) - kudos !\n\n### Compiling locally\n\nIn order to build `Goldpinger`, you are going to need `go` version 1.15+ and `docker`.\n\nBuilding from source code consists of compiling the binary and building a [Docker image](./Dockerfile):\n\n```sh\n# step 0: check out the code\ngit clone https://github.com/bloomberg/goldpinger.git\ncd goldpinger\n\n# step 1: compile the binary for the desired architecture\nmake bin/goldpinger\n# at this stage you should be able to run the binary\n./bin/goldpinger --help\n\n# step 2: build the docker image containing the binary\nnamespace=\"docker.io/myhandle/\" make build\n\n# step 3: push the image somewhere\ndocker push $(namespace=\"docker.io/myhandle/\" make version)\n```\n\n## Installation\n`Goldpinger` works by asking `Kubernetes` for pods with particular labels (`app=goldpinger`). While you can deploy `Goldpinger` in a variety of ways, it works very nicely as a `DaemonSet` out of the box.\n\n### Helm Installation\nGoldpinger can be installed via [Helm](https://helm.sh/) using the following:\n\n```\nhelm repo add goldpinger https://bloomberg.github.io/goldpinger\nhelm repo update\nhelm install goldpinger goldpinger/goldpinger\n```\n\n### Manual Installation\n`Goldpinger` can be installed manually via configuration similar to the following:\n\n#### Authentication with Kubernetes API\n\n`Goldpinger` supports using a `kubeconfig` (specify with `--kubeconfig-path`) or service accounts.\n\n#### Example YAML\n\nHere's an example of what you can do (using the in-cluster authentication to `Kubernetes` apiserver).\n\n```yaml\n---\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n  name: goldpinger-serviceaccount\n  namespace: default\n---\napiVersion: apps/v1\nkind: DaemonSet\nmetadata:\n  name: goldpinger\n  namespace: default\n  labels:\n    app: goldpinger\nspec:\n  updateStrategy:\n    type: RollingUpdate\n  selector:\n    matchLabels:\n      app: goldpinger\n  template:\n    metadata:\n      annotations:\n        prometheus.io/scrape: 'true'\n        prometheus.io/port: '8080'\n      labels:\n        app: goldpinger\n    spec:\n      serviceAccount: goldpinger-serviceaccount\n      tolerations:\n        - key: node-role.kubernetes.io/master\n          effect: NoSchedule\n      securityContext:\n        runAsNonRoot: true\n        runAsUser: 1000\n        fsGroup: 2000\n      containers:\n        - name: goldpinger\n          env:\n            - name: HOST\n              value: \"0.0.0.0\"\n            - name: PORT\n              value: \"8080\"\n            # injecting real hostname will make for easier to understand graphs/metrics\n            - name: HOSTNAME\n              valueFrom:\n                fieldRef:\n                  fieldPath: spec.nodeName\n            # podIP is used to select a randomized subset of nodes to ping.\n            - name: POD_IP\n              valueFrom:\n                fieldRef:\n                  fieldPath: status.podIP\n          image: \"docker.io/bloomberg/goldpinger:v3.0.0\"\n          imagePullPolicy: Always\n          securityContext:\n            allowPrivilegeEscalation: false\n            readOnlyRootFilesystem: true\n          resources:\n            limits:\n              memory: 80Mi\n            requests:\n              cpu: 1m\n              memory: 40Mi\n          ports:\n            - containerPort: 8080\n              name: http\n          readinessProbe:\n            httpGet:\n              path: /healthz\n              port: 8080\n            initialDelaySeconds: 20\n            periodSeconds: 5\n          livenessProbe:\n            httpGet:\n              path: /healthz\n              port: 8080\n            initialDelaySeconds: 20\n            periodSeconds: 5\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: goldpinger\n  namespace: default\n  labels:\n    app: goldpinger\nspec:\n  type: NodePort\n  ports:\n    - port: 8080\n      nodePort: 30080\n      name: http\n  selector:\n    app: goldpinger\n```\n\nNote, that you will also need to add an RBAC rule to allow `Goldpinger` to list other pods. If you're just playing around, you can consider a view-all default rule:\n\n```yaml\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\n  name: default\nroleRef:\n  apiGroup: rbac.authorization.k8s.io\n  kind: ClusterRole\n  name: view\nsubjects:\n  - kind: ServiceAccount\n    name: goldpinger-serviceaccount\n    namespace: default\n```\n\nYou can also see [an example of using `kubeconfig` in the `./extras`](./extras/example-with-kubeconfig.yaml).\n\n### Using with IPv4/IPv6 dual-stack\n\nIf your cluster IPv4/IPv6 dual-stack and you want to force IPv6, you can set the `IP_VERSIONS` environment variable to \"6\" (default is \"4\") which will use the IPv6 address on the pod and host.\n\n![ipv6](./extras/screenshot-ipv6.png)\n\n### Note on DNS\n\nNote, that on top of resolving the other pods, all instances can also try to resolve arbitrary DNS. This allows you to test your DNS setup.\n\nFrom `--help`:\n\n```sh\n--host-to-resolve=      A host to attempt dns resolve on (space delimited) [$HOSTS_TO_RESOLVE]\n```\n\nSo in order to test two domains, we could add an extra env var to the example above:\n\n```yaml\n            - name: HOSTS_TO_RESOLVE\n              value: \"www.bloomberg.com one.two.three\"\n```\n\nand `goldpinger` should show something like this:\n\n![screenshot-DNS-resolution](./extras/dns-screenshot.png)\n\n### TCP and HTTP checks to external targets\n\nInstances can also be configured to do simple TCP or HTTP checks on external targets. This is useful for visualizing more nuanced connectivity flows.\n\n```sh\n      --tcp-targets=             A list of external targets(\u003chost\u003e:\u003cport\u003e or \u003cip\u003e:\u003cport\u003e) to attempt a TCP check on (space delimited) [$TCP_TARGETS]\n      --http-targets=            A  list of external targets(\u003chttp or https\u003e://\u003curl\u003e) to attempt an HTTP{S} check on. A 200 HTTP code is considered successful. (space delimited) [$HTTP_TARGETS]\n      --tcp-targets-timeout=  The timeout for a tcp check on the provided tcp-targets (default: 500) [$TCP_TARGETS_TIMEOUT]\n      --dns-targets-timeout=  The timeout for a tcp check on the provided udp-targets (default: 500) [$DNS_TARGETS_TIMEOUT]\n```\n\n```yaml\n        - name: HTTP_TARGETS\n          value: http://bloomberg.com\n        - name: TCP_TARGETS\n          value: 10.34.5.141:5000 10.34.195.193:6442\n```\n\nthe timeouts for the TCP, DNS and HTTP checks can be configured via `TCP_TARGETS_TIMEOUT`, `DNS_TARGETS_TIMEOUT` and `HTTP_TARGETS_TIMEOUT` respectively. \n\n![screenshot-tcp-http-checks](./extras/tcp-checks-screenshot.png)\n\n## Usage\n\n### UI\n\nOnce you have it running, you can hit any of the nodes (port 30080 in the example above) and see the UI.\n\n![](./extras/screenshot-big.png)\n\nYou can click on various nodes to gray out the clutter and see more information.\n\n### API\n\nThe API exposed is via a well-defined [`Swagger` spec](./swagger.yml).\n\nThe spec is used to generate both the server and the client of `Goldpinger`. If you make changes, you can re-generate them using [go-swagger](https://github.com/go-swagger/go-swagger) via [`make swagger`](./Makefile)\n\n### Prometheus\n\nOnce running, `Goldpinger` exposes `Prometheus` metrics at `/metrics`. All the metrics are prefixed with `goldpinger_` for easy identification.\n\nYou can see the metrics by doing a `curl http://$POD_ID:80/metrics`.\n\nThese are probably the droids you are looking for:\n\n```sh\ngoldpinger_peers_response_time_s_*\ngoldpinger_peers_response_time_s_*\ngoldpinger_nodes_health_total\ngoldpinger_stats_total\ngoldpinger_errors_total\n```\n\n### Grafana\n\nYou can find an example of a `Grafana` dashboard that shows what's going on in your cluster in [extras](./extras/goldpinger-dashboard.json). This should get you started, and once you're on the roll, why not :heart: contribute some kickass dashboards for others to use ?\n\n### Alert Manager\n\nOnce you've gotten your metrics into `Prometheus`, you have all you need to set useful alerts.\n\nTo get you started, here's a rule that will trigger an alert if there are any nodes reported as unhealthy by any instance of `Goldpinger`.\n\n```yaml\nalert: goldpinger_nodes_unhealthy\nexpr: sum(goldpinger_nodes_health_total{status=\"unhealthy\"})\n  BY (instance, goldpinger_instance) \u003e 0\nfor: 5m\nannotations:\n  description: |\n    Goldpinger instance {{ $labels.goldpinger_instance }} has been reporting unhealthy nodes for at least 5 minutes.\n  summary: Instance {{ $labels.instance }} down\n```\n\nSimilarly, why not :heart: contribute some amazing alerts for others to use ?\n\n### Chaos Engineering\n\nGoldpinger also makes for a pretty good monitoring tool in when practicing Chaos Engineering. Check out [PowerfulSeal](https://github.com/bloomberg/powerfulseal), if you'd like to do some Chaos Engineering for Kubernetes.\n\n## Authors\n\nGoldpinger was created by [Mikolaj Pawlikowski](https://github.com/seeker89) and ported to Go by Chris Green.\n\n\n## Contributions\n\nWe :heart: contributions.\n\nHave you had a good experience with `Goldpinger` ? Why not share some love and contribute code, dashboards and alerts ?\n\nIf you're thinking of making some code changes, please be aware that most of the code is auto-generated from the `Swagger` spec. The spec is used to generate both the server and the client of `Goldpinger`. If you make changes, you can re-generate them using [go-swagger](https://github.com/go-swagger/go-swagger) via [`make swagger`](./Makefile).\n\nBefore you create that PR, please make sure you read [CONTRIBUTING](./CONTRIBUTING.md) and [DCO](./DCO.md).\n\n## License\n\nPlease read the [LICENSE](./LICENSE) file here.\n\nFor each version built by travis, there is also an additional version, appended with `-vendor`, which contains all source code of the dependencies used in `goldpinger`.\n","funding_links":[],"categories":["JavaScript","Monitoring Services","Observability \u0026 Monitoring","Tools and Libraries","kubernetes","prometheus","Virtualization"],"sub_categories":["[Jenkins](#jenkins)","Monitoring, Alerts, and Visualization","Containers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fgoldpinger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fgoldpinger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fgoldpinger/lists"}