Introduction

When PostgreSQL works inside Kubernetes but not from outside the cluster, the problem is usually not PostgreSQL alone. It is typically one of four layers: the Kubernetes Service exposure, cloud or node networking, PostgreSQL listener configuration, or PostgreSQL client authentication rules such as pg_hba.conf.

Start with the Service Type

A ClusterIP Service is reachable only inside the cluster. If you need external access, you typically need one of these patterns:

• 'NodePort'
• 'LoadBalancer'
• 'kubectl port-forward for debugging'

A minimal external Service might look like this:

1apiVersion: v1
2kind: Service
3metadata:
4  name: postgres
5spec:
6  type: LoadBalancer
7  selector:
8    app: postgres
9  ports:
10    - port: 5432
11      targetPort: 5432

If the Service is still ClusterIP, outside clients will not reach it directly.

Test with kubectl port-forward First

Before debugging cloud load balancers and firewalls, confirm that PostgreSQL itself is healthy by forwarding a local port.

kubectl port-forward svc/postgres 5432:5432

Then connect locally:

psql -h 127.0.0.1 -p 5432 -U myuser mydb

If this works, PostgreSQL and the pod are probably fine. The issue is then in external exposure or network policy.

Confirm PostgreSQL Is Listening Broadly Enough

Even with a correct Service, PostgreSQL must listen on an address reachable from the pod network.

A common setting is:

listen_addresses = '*'

If PostgreSQL is configured to listen only on localhost, Kubernetes networking will not help. The pod may be running correctly while the database refuses non-local connections.

Check pg_hba.conf

PostgreSQL can be reachable at the TCP layer and still reject the client because host-based authentication rules do not allow the source address.

A typical permissive example looks like this:

host    all    all    0.0.0.0/0    md5

That is broad and often too open for production, but it demonstrates the mechanism. In a real deployment, use the narrowest CIDR range that matches the expected source network.

If pg_hba.conf blocks the client, the network path may look fine and you still will not get a successful login.

Check the Network Outside Kubernetes

If the Service is NodePort or LoadBalancer, verify the external path:

• cloud firewall or security group allows port 5432
• the load balancer or node IP is correct
• no corporate firewall blocks outbound database traffic
• the target node or load balancer is healthy

For a NodePort Service, remember that clients connect to a node IP plus the allocated node port, not directly to 5432 on the node unless you explicitly configured it that way.

NetworkPolicy Can Also Block You

Even when the Service exists and PostgreSQL is listening, Kubernetes NetworkPolicy may deny traffic to the pod. If your cluster uses restrictive policies, inspect both ingress rules to the PostgreSQL pods and egress rules from any in-cluster clients used for testing.

This layer is easy to miss because the Service object itself can look perfectly correct.

A Good Debugging Sequence

A practical order of operations is:

1. confirm the pod is healthy
2. test with kubectl port-forward
3. verify the Service type and external address
4. confirm PostgreSQL listen_addresses
5. confirm pg_hba.conf
6. check firewall, security group, and network policy rules

This narrows the problem much faster than changing several layers at once.

Avoid Exposing the Database Casually

External connectivity is sometimes needed, but do not expose PostgreSQL publicly unless there is a strong reason. For admin access, kubectl port-forward, a bastion host, or a private VPN path is often safer than opening the database broadly to the internet.

That is both a security decision and an operational one.

Common Pitfalls

• Expecting a ClusterIP Service to be reachable from outside the cluster.
• Forgetting to test the pod with kubectl port-forward before debugging the external path.
• Leaving PostgreSQL on listen_addresses = 'localhost'.
• Overlooking pg_hba.conf while focusing only on Kubernetes resources.
• Ignoring cloud firewall, security group, or NetworkPolicy restrictions.

Summary

• External PostgreSQL connectivity from Kubernetes depends on both Kubernetes exposure and PostgreSQL configuration.
• Start by testing with kubectl port-forward to separate internal health from external networking issues.
• Use the right Service type for external access.
• Verify listen_addresses and pg_hba.conf inside PostgreSQL.
• Check firewalls and network policies before assuming the database itself is broken.