Kubernetes, while fairly mature as a platform, is still considered an emerging technology in the business space. Due to this, lots of engineers are spending their free time trying to learn about Helm which can lead to some pretty frustrating errors.

Let's discuss why you might be receiving Error: Kubernetes cluster unreachable when trying to connect to your cluster for the first time.

Related Articles

Kubernetes Install

There are a lot of different mechanisms on the market today to get Kubernetes up and running depending on your environment. How you installed Kubernetes is important for troubleshooting later. Review the install methods and make sure you align underneath one of them in some fashion.

Local Environment

Local Kubernetes is going to use k3s or minikube to run and install a local version on a standard workstation. This is a great way to get familiar with Kubernetes because these products will download and install all the requisite dependencies to bootstrap anyone regardless of their skill level.

On-Prem Environment

I am differentiating local and on-prem simply from the viewpoint of servers vs desktops. In a more server-focused environment, many people will use kubespray or kops to deploy their Kubernetes clusters. Kubespray will ensure that servers are properly configured through IaC while downloading and installing baseline Kubernetes. By the time you are done, a fully functional cluster should be available.

Kubespray does come with a lot more knobs and dials since it makes fewer opinionated decisions about what your cluster setup should look like. In a local environment, ingress is going to be handled in a very specific way. In an on-prem environment, you may have network appliances that want to handle ingress in a very specific way. Kubespray should be able to get most of your configurations taken care of for your special circumstances.

Cloud Environment

Cloud environments can be configured the same way on-prem environments are through kubespray and kops. Cloud-based VM instances would be spun up on management networks and tools would be run against them to achieve a functioning cluster.

Most cloud providers will have their own managed Kubernetes to be used as well. Those are probably a much safer way to get started when just starting to dabble in the Kubernetes space.

These solutions generally are only a few clicks away from a full-stack deployment. Once you get a bit more comfortable, it would be a good idea to toss out your test cluster and start to move into Terraform, CloudFormation, or Azure Resource Manager automation to ensure your clusters are codified for future upgrades.

Error: Kubernetes cluster unreachable

There are going to be a few troubleshooting steps you should take to diagnose this issue. Each of them is going to be a little bit different depending on your deployment setup.

Check Your Kubeconfig

The first thing to check is your $HOME/.kube/config file. This file contains all of the relevant information for connecting to your Kubernetes cluster. It is also very important you keep this file safe and secret since it holds credentials for that connection as well.

My Kubeconfig is Missing!

If your kubeconfig file is missing, review your Kubernetes installation instructions for anything specific about copying a kubeconfig to the proper folder on your local machine. The instructions may also walk you through how to create one. Helm will not work without this file being created and in the proper location.

My Kubeconfig Exists!

If you open that file to read it, you will find that it is YAML formatted with connection parameters in it. These parameters should include some certificate information, which are credentials and cluster identification verification, and a hostname for the cluster management API address.

If you have kubectl installed on the same machine as your kubeconfig, a simple test would be to run kubectl get nodes to see if you get a list of servers back from the kubernetes API. If you get an error, then either you do not have the right level of access, or your kubeconfig is not properly configured. See above "My Kubeconfig is Missing".

If this works as intended, and you see a list of servers the next step is to ensure that your kubeconfig is on the same computer that you would like to run helm from. If you are running helm from a local workstation, make sure you have a proper kubeconfig on that workstation. If you are running helm from a different server, ensure a kubeconfig is provided for that server. Make sure to re-test.

Check Networking

Helm communicates with the Kubernetes API over port 6443. Using NMap to check ports, ensure that the machine you are intending to run helm from has clear line of sight communication with the Kubernetes cluster over port 6443. This can be achieved on Linux via this command: nmap –p 6443 {{cluster address/master hostname}}. You can find the cluster address/master hostname inside of a validated kubeconfig.

If you are using Windows and looking for an example of how to do port scans, I would suggest switching to Linux or Mac.

If ports show closed or filtered, network communication will not be established with the cluster and Helm will not be able to run configurations.

Additional Resources

The steps outlined above should get you pointed in the right direction when you receive Helm errors when trying to contact your cluster for the first time.

If you did not find the answers you needed via this article, I have added a few additional resources below that may be able to help get you sorted out. If you have additional information to share on this topic, please contact me and I will update this post to reflect any changes.