Pingpongkong한국어

GitOps ping checks for Kubernetes

Pingpongkong

Prove external IP and port security filtersfrom inside every Kubernetes node.

Declare the network contract in Git.Let node-local agents run TCP and UDP checks, then get notified when reality drifts.

See the Kubernetes flowOpen state repo
Private state repoCilium-ready defaultsDiscord-first alertsNo dashboard required
desiredPingState.yamldesired
worker -> controlplane : 6443 allow
worker -> 203.0.113.53 : 53 udp allow
edge -> private-db : 5432 deny
collector reportsynced
HealthyDegradedUnreachable

Git is the interface

Desired allow and deny checks live beside your cluster state, not in a separate UI.

Node-local evidence

Agents run from each node, so the result reflects what that node can actually reach.

Designed to disappear

Install, validate the security filter, keep notifications, and delete it when the check is done.

Clear intention

For teams that already guard Kuberneteswith external IP and port filters.

Pingpongkong is intentionally small: it checks whether the declared network paths are reachable or blocked, then reports the result. It is useful after firewall, Cilium, node label, cloud security group, and maintenance changes.

Allow

Confirm required paths

Make sure workers can still reach control plane ports, DNS endpoints, webhooks, or any external dependency you name.

Deny

Validate blocked paths

A deny rule is healthy only when the target is unreachable, so filter mistakes show up as failures.

GitOps

Review changes before probes

The collector syncs a private state repo and publishes the desired state into Kubernetes for agents to consume.

How to use

The Kubernetes flow is intentionally simple.

Use Git and notifications as the operating surface. There is no UI today because the check does not need one.

  1. 1

    Clone to a private repo

    Clone https://github.com/pingpongkong/pingpongkong-state into your private repo. Modify k8s/ and notification/. Defaults start with Cilium and Discord.

  2. 2

    Modify states for your needs

    Edit the desired connectivity rules for your cluster. Keep allow and deny checks close to the Git state you already review.

  3. 3

    Generate a read-only token

    Create a deploy token with read-only access. The collector only needs to fetch the private state repo.

  4. 4

    Label, set values, install

    Label nodes, set the required Helm variables, install the chart, then wait for the collector and agents to produce data.

  5. 5

    Check notification

    Check Discord or the notification provider you configured. After the validation window, uninstall it if you only needed a temporary check.

Runtime shape

One collector, one agent per node,no central dashboard to operate.

The collector continuously syncs desired connectivity and notification config from Git. Agents reconcile the current node's tasks and run bounded TCP or UDP probes on an interval.

collector

Git to ConfigMap

Fetches k8s/<cluster>.yaml and notification/*.yaml, validates them, publishes pingpongkong-{cluster}-ping-state, and sends update or failure notifications.

agent

ConfigMap to probes

Watches desiredPingState.yaml, resolves node labels and target InternalIPs, then runs only the checks that match the current node.

report

Health over HTTP and metrics

Agents expose /node-status and /metrics; the collector exposes /healthz, /readyz, and /report for the latest cluster view.

Install paths

Kubernetes now.Binary later.

The Kubernetes tab is the current supported path. The Binary tab is reserved for a future bare-metal and legacy-app version based on node/.

Kubernetes (`k8s/`)

Use this today. Prepare a private state repo, create a read-only token, label nodes, set Helm values, install, and wait for report data.

Open state templatePingpongkong GitHub

Helm install

helm install ppk oci://registry-1.docker.io/kimc1992/pingpongkong \  --namespace pingpongkong --create-namespace \  --history-max 2 \  --set CONFIG_GIT_TOKEN="{{git token}}" \  --set CONFIG_GIT_CLUSTERNAME="{{cluster path/name in Git}}" \  --set CONFIG_GIT_URL="{{git URL}}"

Only add these overrides when needed. If you append them, add a trailing backslash to the CONFIG_GIT_URL line first; otherwise chart defaults are used.

--set LOG_LEVEL=INFO \--set COLLECTOR_UPDATE_INTERVAL=5m \--set AGENT_CHECK_INTERVAL=5m \--set AGENT_API_PORT=8080 \--set COLLECTOR_API_PORT=8081

Notifications as UI

If a dashboard is not needed, do not operate one.

Pingpongkong reports through the destinations you configure. A report notification says whether the cluster is Healthy, Degraded, or Unreachable, and each destination is rate-limited independently.

Discord default

Start with notification/discord.yaml and a webhook environment variable.

Multiple destinations

Discord, Teams, email, Telegram, and SMS providers are represented in the collector logic.

Failure visibility

Sync failures notify using the last accepted notification config, so bad Git state is visible.

Issue-driven support

When behavior looks wrong, leave an issue on the Pingpongkong GitHub page.

Network drift checks should be easy to run and easy to remove.

Pingpongkong keeps the contract in Git, probes from where the traffic starts, and lets notifications carry the result.

Leave an issue on GitHub