minikube Cannot Reach a Private API? Check the Driver First

A private API answers from your laptop and a Pod in minikube cannot reach it. Before you change anything on the host, name the driver behind the active profile, because that single fact decides which network the request actually leaves from. Then test the same endpoint from the host, from the node and from the Pod. Only one of those three is the thing that failed, and guessing wrong costs an afternoon.

Step 0: name the driver and the origin

Ask minikube which profile is active and how it is running. A container driver puts the node in a container on your machine, a VM driver puts it in a virtual machine, and a remote driver puts it somewhere else entirely.

minikube profile list
minikube status
kubectl config current-context

From that, write down where the request originates. The answer determines whose resolver and whose routes matter, and it is not always the host's. Two profiles on the same laptop can behave completely differently for the same URL.

Step 1: test the same endpoint three times

Use one harmless endpoint and keep the hostname, the port and the address family identical across all three tests. Changing any of them between runs makes the results incomparable.

curl -sS -o /dev/null -w '%{http_code}\n' https://api.corp.example/health
minikube ssh -- curl -sS -o /dev/null -w '%{http_code}\n' https://api.corp.example/health
kubectl run probe --rm -it --image=curlimages/curl --restart=Never -- \
  curl -sS -o /dev/null -w '%{http_code}\n' https://api.corp.example/health

A successful image pull by the node proves nothing about name resolution for a private host. A successful public request proves even less. Keep the results separated by context, because a pattern across three rows is a diagnosis and a single failure is a clue.

If the host row fails too, stop. You have a host networking problem and the cluster is a distraction.

Step 2: keep the host's path to the cluster

There is a second direction that people forget: the host has to keep reaching the cluster's own API and services. A VPN client can install routes that compete with the prefixes minikube uses for its node network, its service range and its pod range.

When that happens the symptom is confusing, because the tunnel works and kubectl stops responding or a NodePort refuses connections. It looks like a cluster fault and it is a laptop routing fault.

Check the host routing table against minikube's ranges before you blame the tunnel for anything else. The overlap is usually visible as a more specific route pointing at the tunnel interface for a prefix the cluster expects to own.

Step 3: resolve overlap without disabling the VPN

minikube's own VPN and proxy handbook discusses these conflicts and treats its example ranges as things to inspect, not as a universal list. Read it alongside the profile you actually have.

Where a real overlap exists, the supported answer is a non-overlapping range or a deliberate local-access policy approved by whoever owns the VPN. Changing the service range is not the same as changing the pod range, and neither is the same as changing the node network.

Disabling the corporate tunnel to make a local cluster work is not a workaround; it is a policy decision someone else has to make. Take it to them rather than doing it quietly after everyone else has gone home. If you already did, put it back before you ask.

Step 4: separate proxy, DNS and four failure shapes

If a proxy is required, identify which context needs it. A browser setting on the host does not configure a process inside the node, and a Pod needs the environment variables or a cluster-level proxy configuration.

Then classify the failure instead of describing it. A name that does not resolve is DNS. A name that resolves and refuses a connection is routing or a listener. A connection that establishes and fails identity is TLS. A successful connection with an error body is the application.

Each of those four belongs to a different fix, and only one of them is about the VPN. Write down which one you observed at each context, and the next person inherits evidence instead of a story.