Network & DNS Checks

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/dns-resolution-check/main.go
• cmd/network-connection-check/main.go
• cmd/http-check/main.go
• cmd/http-content-check/main.go
• cmd/dns-resolution-check/README.md
• deploy/helm/kuberhealthy/templates/khcheck-dns-external.yaml
• cmd/network-connection-check/README.md

Network and DNS checks within Kuberhealthy are synthetic monitoring tools designed to verify the connectivity and resolution capabilities of a Kubernetes cluster. These checks emulate real-world workloads by attempting to resolve hostnames, establish TCP/UDP connections, and perform HTTP transactions to ensure that the underlying networking infrastructure and DNS services are performing as expected.

The scope of these checks includes internal service discovery (e.g., kubernetes.default), external internet connectivity (e.g., google.com), and raw network path verification. By running these as KuberhealthyCheck resources, the system provides continuous validation and exports results to Prometheus and the Kuberhealthy JSON status page.

Sources: README.md, cmd/dns-resolution-check/README.md:3-10, cmd/network-connection-check/README.md:3-8

DNS Resolution Check

The DNS Resolution check verifies the health of the cluster's DNS providers by performing lookups against specific hostnames. It can be configured to use the standard system resolver or to query specific DNS pod endpoints directly using label selectors.

Architecture and Logic

The checker operates by creating a net.Resolver. If a DNS_POD_SELECTOR is provided, the check bypasses the standard service load balancer and queries individual DNS backend pods directly to ensure every instance in a DNS deployment is functional.

The diagram shows the logic path between standard system resolution and direct endpoint querying.
Sources: cmd/dns-resolution-check/main.go:214-257, cmd/dns-resolution-check/main.go:261-285

Configuration

Environment Variable	Description	Default/Example
HOSTNAME	The target hostname to resolve.	kubernetes.default
DNS_POD_SELECTOR	Label selector to find specific DNS pods.	apps=k8s-dns
NAMESPACE	Namespace where DNS pods reside.	kube-system
NODE_NAME	The node where the check pod is running.	From spec.nodeName

Sources: cmd/dns-resolution-check/README.md:41-55, cmd/dns-resolution-check/main.go:66-100

Network Connection Check

This module validates lower-level network reachability using TCP or UDP protocols. It is used to confirm that specific egress paths are open or, conversely, that sensitive endpoints (like cloud metadata services) are properly blocked.

Connection Logic

The checker utilizes a net.Dialer with a configurable timeout. It supports a "negative check" mode where the target is expected to be unreachable.

The sequence diagram illustrates the two operational modes: verifying connectivity vs. verifying isolation.
Sources: cmd/network-connection-check/main.go:142-167, cmd/network-connection-check/README.md:3-16

Configuration Options

Sources: cmd/network-connection-check/main.go:37-43, cmd/network-connection-check/README.md:27-40

Variable	Description
CONNECTION_TARGET	Target in protocol://address:port format (e.g., tcp://github.com:443).
CONNECTION_TARGET_UNREACHABLE	Boolean. If true, the check passes if the connection fails.

HTTP & Content Checks

Kuberhealthy includes specialized HTTP checkers to verify higher-level application availability and data integrity.

HTTP Status Check

This check sends requests (GET, POST, PUT, DELETE, PATCH) and verifies the response status code. It supports multiple attempts and a passing percentage threshold.

The flow shows how the checker aggregates multiple requests to determine a final health status.
Sources: cmd/http-check/main.go:129-165

HTTP Content Check

The http-content-check extends basic connectivity by searching the response body for a specific string. This ensures that the returned page is not just "up" but contains the expected data.
Sources: cmd/http-content-check/main.go:73-81, cmd/http-content-check/README.md:3-10

// findStringInContent parses through URL bytes for specified string and returns bool
func findStringInContent(b []byte, s string) bool {
	stringbody := string(b)
	return strings.Contains(stringbody, s)
}

Sources: cmd/http-content-check/main.go:107-111

Implementation Summary

All Network and DNS checks follow a standard lifecycle:

1. Wait for Node: Checks often wait for the node to reach a minimum age or for the Kuberhealthy endpoint to be reachable before starting.
2. Execute Logic: Perform the DNS lookup, network dial, or HTTP request.
3. Report: Send results to the Kuberhealthy API via checkclient.ReportSuccess() or checkclient.ReportFailure().

These checks are vital for detecting issues like CNI failures, DNS pod crashes, or misconfigured NetworkPolicies.

Sources: cmd/dns-resolution-check/main.go:117-133, cmd/network-connection-check/main.go:189-198, README.md:145-160