{"id":20661797,"url":"https://github.com/mirantis/k8s-netchecker-server","last_synced_at":"2025-04-19T15:51:11.182Z","repository":{"id":57549617,"uuid":"78005922","full_name":"Mirantis/k8s-netchecker-server","owner":"Mirantis","description":"Basic network checker service to check DNS and connectivity in kubernetes cluster","archived":false,"fork":false,"pushed_at":"2020-02-26T12:08:05.000Z","size":316,"stargazers_count":67,"open_issues_count":11,"forks_count":18,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-29T09:41:36.150Z","etag":null,"topics":["golang","k8s-netchecker-server","kubernetes","netchecker-server","network-checker"],"latest_commit_sha":null,"homepage":null,"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/Mirantis.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}},"created_at":"2017-01-04T10:29:19.000Z","updated_at":"2024-07-14T22:26:11.000Z","dependencies_parsed_at":"2022-08-27T00:40:56.458Z","dependency_job_id":null,"html_url":"https://github.com/Mirantis/k8s-netchecker-server","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mirantis%2Fk8s-netchecker-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mirantis%2Fk8s-netchecker-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mirantis%2Fk8s-netchecker-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mirantis%2Fk8s-netchecker-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mirantis","download_url":"https://codeload.github.com/Mirantis/k8s-netchecker-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249730656,"owners_count":21317328,"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":["golang","k8s-netchecker-server","kubernetes","netchecker-server","network-checker"],"created_at":"2024-11-16T19:11:37.836Z","updated_at":"2025-04-19T15:51:11.136Z","avatar_url":"https://github.com/Mirantis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Status\n\n[![Build Status](https://goo.gl/XzSwDu)](https://goo.gl/bx20uy)\n[![Stories in Progress](https://goo.gl/Y3SfPH)](https://goo.gl/eY1d9l)\n[![Go Report Card](https://goo.gl/EN7y2i)](https://goo.gl/ultF3D)\n[![Code Climate](https://goo.gl/F5iNWP)](https://goo.gl/mGsQj1)\n[![License Apache 2.0](https://goo.gl/joRzTI)](https://goo.gl/pbOuG0)\n[![Docker Pulls](https://goo.gl/ZYz1nt)](https://goo.gl/nAfD9C)\n\n## What it is and how it works\n\n![Diagram](diagram.png)\n\nNetwork checker is a Kubernetes application. Its main purpose is checking\nof connectivity between the cluster's nodes. Network checker consists of two\nparts: server (this repository) and agent\n([developed here](https://github.com/Mirantis/k8s-netchecker-agent)). Agents\nare deployed on every Kubernetes node using\n[Daemonset](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/).\nAgents come in two flavors - and default setup includes two corresponding\ndaemonsets. The difference between them is that \"Agent-hostnet\" is tapped into\nhost network namespace via supplying `hostNetwork: True` key-value for the\ncorresponding Pod's specification. As shown on the diagram, both daemonsets\nare enabled for each node meaning exactly one pod of each kind will be deployed\non each node.\n\nThe agents periodically gather network related information\n(e.g. interfaces' info, results of nslookup, results of latencies measurement,\netc.) and send it to the server as periodic agent reports.\nReport includes agent pod name and its node name so that the report is uniquely\nidentified using them.\n\nThe server is deployed in a dedicated pod using\n[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)\nand exposed inside of the cluster via Kubernetes service resource. Thus, every\nagent can access the server by the service's DNS name.\n\nServer processes the incoming agent data (agents' reports) and store it in a\npersistent data storage. Server is capable to use either Kubernetes third party\nresources (TPR) or etcd as a persistent data storage:\n\n- TPR. New data type called `agent` was added into TPR, Kubernetes API was extended\n  with this new type, and all agent data is stored using it. When using TPR,\n  the server is vulnerable to [date change issue](https://github.com/Mirantis/k8s-netchecker-server/issues/80).\n  The issue was solved by using etcd and its TTL feature. Please also note\n  that TPR is deprecated starting from Kubernetes v.1.7 and can be removed in\n  future Kubrenetes versions. It will not be supported in Netchecker then. No\n  migration to Kubernetes CRD (substitution for TPR) is planned either.\n- etcd. The recommended storage provider. When using etcd, the server is resistant\n  to issues described in TPR section. Agent data is stored in etcd in this case,\n  under `/netchecker` path.\n\nServer also calculates metrics based on agent data. Metrics data is stored in\nserver's memory for now - this implicates loss of metrics data when server\napplication is shutdown or restarted; it is going to be reworked by moving to\na persistent storage (to etcd only) in future.\n\nServer provides HTTP RESTful interface which currently includes the following\nrequests (verb - URI designator - meaning of the operation):\n\n- GET/POST - /api/v1/agents/{agent_name} - get, create/update agent's data record\n  in a persistant storage.\n- GET - /api/v1/agents/ - get the whole agent data dump.\n- GET - /api/v1/connectivity_check - get result of connectivity check between\n  the server and the agents.\n- GET - /metrics - get the network checker metrics.\n\nThe main logic of network checking is implemented behind `connectivity_check`\nendpoint. It is the only user-facing URI.\nIn order to determine whether connectivity is present between the server and\nagents, former retrieves the list of pods using Kubernetes API\n(filtering by labels `netchecker-agent` and `netchecker-agent-hostnet`), then\nanalyses stored agent data.\nSuccess of the checking is determined based on two criteria.\nFirst - there is an entry in the stored data for the each retrieved agent's pod;\nit means an agent request has got through the network to the server. Consequently,\nlink is established and active within the agent-server pair.\nSecond - difference between the time of the check and the time when the data\nwas received from particular agent must not exceed two periods of agent's\nreporting (there is a field in the payload holding the report interval). In\nopposite case, it will indicate that connection is lost and requests are not\ncoming through. In case of using etcd, period of agent's data obsolescence is\nset explicitly in parameters to the server (`-report-ttl` parameter, in seconds).\nLet us remember that each agent corresponds to one particular pod, unique for\nparticular node, so connection between agents and server means connection\nbetween the corresponding nodes.\n\nResults of the connectivity check which are represented in response from the\nendpoint particularly indicate possible connectivity issue (e.g. there is an\n`Absent` field listing agents which haven't reported at all and `Outdated` one\nlisting those which reports are out of data obsolescence period).\n\nOne aspect of functioning of network checker is worth mentioning. Payloads sent\nby the agents are of relatively small byte size which in some cases can be less\nthan MTU value set for the cluster's network links. When this happens, the\nnetwork checker will not catch problems with network packet's fragmentation.\nFor that reason, special option can be used with the agent application -\n`-zeroextenderlength`. By default, it has value of 1500. The parameter tells\nthe agent to extend each payload by given length to exceed packet fragmentation\ntrigger threshold. This dummy data has no effect on the server's processing\nof the agent's requests (reports).\n\n## Usage\n\nTo start the server inside Kubernetes pod using Kubernetes TPR as a persistent storage\nand listen on port 8081, use the following command:\n\n```bash\nserver -v 5 -logtostderr -kubeproxyinit -endpoint 0.0.0.0:8081\n```\n\nTo start the server using etcd as a persistent storage, use the following setting:\n\n```\n-kubeproxyinit=false\n```\n\nAlso, a few parameters are required to establish the connection with etcd:\n\n```\n-etcd-endpoints=https://192.0.10.11:4001,https://192.0.10.12:4001\n-etcd-key=/var/lib/etcd/client.key (optional, ommited when using http)\n-etcd-cert=/var/lib/etcd/client.pem (optional, ommited when using http)\n-etcd-ca=/var/lib/etcd/ca.pem (optional, can be ommited even when using https)\n```\n\nFor other possibilities regarding testing, code and Docker images building etc.\nplease refer to the Makefile.\n\n## Deployment in Kubernetes cluster\n\nIn order to deploy the application, two options can be used.\n\nFirst - using `./examples/deploy.sh` script. Users must provide all the needed\nenvironment variables (e.g. name and tag for Docker images) before running the\nscript.\n\nSecond - deploy as a helm chart. If users have\n[Helm](https://github.com/kubernetes/helm) installed on their Kubernetes cluster\nthey can build the chart from its description (`./helm-chart/`) and then deploy\nit (please, use Helm's documentation for details).\n\n## Additional documentation\n\n- [Metrics](doc/metrics.md) - metrics and Prometheus configuration how to.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirantis%2Fk8s-netchecker-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmirantis%2Fk8s-netchecker-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirantis%2Fk8s-netchecker-server/lists"}