Kubernetes / Editorial solution guide

Service connectivity: distinguish DNS, endpoints, and NetworkPolicy

Trace a failed application connection through discovery, selection, policy, transport, and protocol without broad scans or unsafe exposure changes.

About 4 min readContent reviewed

Read-only knowledge base · No public comments

Recognize the symptoms

A caller cannot reach a Service, succeeds only in one namespace, times out after a policy change, or receives an HTTP authentication error. These symptoms should not all be labeled DNS failure. A successful name lookup can coexist with zero ready endpoints, a wrong target port, denied traffic, or an unhealthy application.

Understand the likely causes

  • Typical causes include ambiguous short names, incorrect caller namespace or cluster domain assumptions, selector mismatch, readiness exclusion, named-port mismatch, application binding, missing egress or ingress allowance, and an unsupported policy implementation. TLS identity and application authorization are separate layers. NetworkPolicy enforcement and address-translation details depend on the installed network stack.

Locate the caller and intended peer

Record the authorized context, source namespace and Pod identity, intended Service namespace and name, protocol, Service port, target port, and time. localhost in the caller is not another Pod’s loopback. A short service name can be interpreted through the caller’s DNS search context, so compare the installation’s documented full name and domain. Preserve the exact safe error class rather than a credential-bearing URL. The first synthetic matrix states what each observation establishes and deliberately avoids claiming a real resolver, route, or endpoint was queried.

text Synthetic connectivity evidence matrix 
observation                     established evidence
DNS returns Service address      name resolution returned data
zero ready endpoint addresses    selection or readiness lacks eligible targets
TCP connection established       limited transport success
HTTP 401 response                an HTTP peer rejected authentication
TLS identity error               peer trust or identity needs investigation

The rows represent independent lab observations. No one row proves the whole route, intended identity, application health, or authorization.

Check Service selection before routing changes

Compare the Service selector with the actual intended Pod labels in its namespace. Inspect endpoint addresses, readiness conditions, and named-port resolution through approved read access. A declared port does not start an application listener, and targetPort need not equal the Service port. If no eligible endpoint exists, investigate selection or workload readiness before changing DNS or opening a public load balancer. A headless Service has different discovery behavior and should be interpreted according to that contract. Keep evidence tied to current object lifetimes so an old endpoint snapshot does not override present state.

Evaluate both policy directions and implementation

A selected source may require egress allowance and a selected destination ingress allowance. Standard policies are additive, so an apparent default deny does not override every other allow. The second fragment keeps namespaceSelector and podSelector in one peer entry, requiring both; separating them changes the logic to alternatives. DNS dependencies may need UDP and TCP access according to the resolver. Confirm that the plugin supports the expected rules. Do not disable all policy to test a hunch, and do not assume namespace separation itself provides isolation or that standard policy authenticates the application user.

yaml Illustrative conjunctive peer fragment 
ingress:
  - from:
      - namespaceSelector:
          matchLabels: {team: reporting}
        podSelector:
          matchLabels: {app: reports}
    ports:
      - {protocol: TCP, port: 8080}

Both labels must match within this single peer entry. The fragment omits the NetworkPolicy wrapper, egress, and DNS policy and is not deployable.

Separate transport, TLS, and application results

A refused connection suggests a different path from a timeout, but neither identifies one universal cause. A TLS certificate failure indicates identity or trust investigation after the relevant transport stage. An HTTP 401 or 403 establishes an HTTP peer response and requires the appropriate authentication or authorization contract, not automatic DNS changes. Review the intended endpoint and recent release or configuration changes. Choose a scoped repair in the reviewed source of truth and verify any required compatibility. No packet, name query, port forward, cluster command, credential, or real service is used by this guide.

Verify the fix

In an authorized isolated environment, verify intended allowed and denied paths from the actual caller context, then check the bounded application outcome. Confirm DNS, current endpoints, named port, transport, identity, and authorization independently. Preserve negative-path evidence so a successful request does not hide an unintended broader grant. This guide itself performs only static interpretation.

Keep it from recurring

  • Keep discovery names, selectors, named ports, readiness, and traffic rules under review together. Record network-plugin capabilities and cluster-domain assumptions. Test policy exclusions and DNS dependencies before promotion, and avoid broad public exposure or all-traffic allowances as a permanent workaround for a missing internal contract.

Official references