Support & Troubleshooting

This page discusses support and troubleshooting resources available for Kubernetes and Kubernetes Engine, as well as solutions to common issues.

Support

The following is a list of support resources for Kubernetes Engine and Kubernetes:

Kubernetes bugs and feature requests

If you encounter a bug or want to request a feature, file an issue on GitHub.

Before you file an issue, search existing issues to ensure that your issue has not already been addressed.

For bugs, include detailed information about how to reproduce the problem, such as:

  • Kubernetes version: kubectl version
  • Cloud provider, OS distro, network configuration, and Docker version
  • Steps to reproduce the problem

Troubleshooting

The following sections discuss common issues encountered in Kubernetes Engine.

Debugging Kubernetes resources

If you are experiencing an issue related to your cluster, refer to Troubleshooting Clusters in the Kubernetes documentation.

If you are having an issue with your application, its Pods, or its controller object, refer to Troubleshooting Applications.

The kubectl command isn't found

First, install the kubectl binary by running the following command:

sudo gcloud components update kubectl

Answer "yes" when the installer prompts you to modify your $PATH environment variable. Modifying this variables enables you to use kubectl commands without typing their full file path.

Alternatively, add the following line to ~/.bashrc (or ~/.bash_profile in macOS, or wherever your shell stores environment variables):

export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/

Finally, run the following command to load your updated .bashrc (or .bash_profile) file:

source ~/.bashrc

kubectl commands return "connection refused" error

Set the cluster context with the following command:

gcloud container clusters get-credentials CLUSTER_NAME

If you are unsure of what to enter for CLUSTER_NAME, use the following command to list your clusters:

gcloud container clusters list

kubectl commands return "failed to negotiate an api version" error

Ensure kubectl has authentication credentials:

gcloud auth application-default login

The kubectl logs, attach, exec, and port-forward commands hang

These commands rely on the cluster's master being able to talk to the nodes in the cluster. However, because the master isn't in the same Compute Engine network as your cluster's nodes, we rely on SSH tunnels to enable secure communication.

Kubernetes Engine saves an SSH public key file in your Compute Engine project metadata. All Compute Engine VMs using Google-provided images regularly check their project's common metadata and their instance's metadata for SSH keys to add to the VM's list of authorized users. Kubernetes Engine also adds a firewall rule to your Compute Engine network allowing SSH access from the master's IP address to each node in the cluster.

If any of the above kubectl commands don't run, it's likely that the master is unable to open SSH tunnels with the nodes. Check for these potential causes:

  1. The cluster doesn't have any nodes.

    If you've scaled down the number of nodes in your cluster to zero, SSH tunnels won't work.

    To fix it, resize your cluster to have at least one node.

  2. Pods in the cluster have gotten stuck in a terminating state and have prevented nodes that no longer exist from being removed from the cluster.

    This is an issue that should only affect Kubernetes version 1.1, but could be caused by repeated resizing of the cluster.

    To fix it, delete the pods that have been in a terminating state for more than a few minutes. The old nodes will then be removed from the master's API and replaced by the new nodes.

  3. Your network's firewall rules don't allow for SSH access to the master.

    All Compute Engine networks are created with a firewall rule called "default-allow-ssh" that allows SSH access from all IP addresses (requiring a valid private key, of course). Kubernetes Engine also inserts an SSH rule for each cluster of the form gke-<cluster_name>-<random-characters>-ssh that allows SSH access specifically from the cluster's master IP to the cluster's nodes. If neither of these rules exists, then the master will be unable to open SSH tunnels.

    To fix it, re-add a firewall rule allowing access to VMs with the tag that's on all the cluster's nodes from the master's IP address.

  4. Your project's common metadata entry for "sshKeys" is full.

    If the project's metadata entry named "sshKeys" is close to the 32KiB size limit, then Kubernetes Engine isn't able to add its own SSH key to enable it to open SSH tunnels. You can see your project's metadata by running gcloud compute project-info describe [--project=PROJECT], then check the length of the list of sshKeys.

    To fix it, delete some of the SSH keys that are no longer needed.

  5. You have set a metadata field with the key "sshKeys" on the VMs in the cluster.

    The node agent on VMs prefers per-instance sshKeys to project-wide SSH keys, so if you've set any SSH keys specifically on the cluster's nodes, then the master's SSH key in the project metadata won't be respected by the nodes. To check, run gcloud compute instances describe <VM-name> and look for an "sshKeys" field in the metadata.

    To fix it, delete the per-instance SSH keys from the instance metadata.

It's worth noting that these features are not required for the correct functioning of the cluster. If you prefer to keep your cluster's network locked down from all outside access, be aware that features like these won't work.

Metrics from your cluster aren't showing up in Stackdriver

Ensure that you have activated the Stackdriver Monitoring API and the Stackdriver Logging API on your project, and that you are able to view your project in Stackdriver.

If the issue persists, check the following potential causes:

  1. Ensure that you have enabled monitoring on your cluster.

    Monitoring is enabled by default for clusters created from the Developers Console and the gcloud command-line tool, but you can verify by running the following command or clicking into the cluster's details in the Developers Console:

    gcloud container clusters describe cluster-name
    

    The output from the gcloud command-line tool should state that the "monitoringService" is "monitoring.googleapis.com", and Cloud Monitoring should be enabled in the Developers console.

    If monitoring is not enabled, run the following command to enable it:

    gcloud container clusters update cluster-name --monitoring-service=monitoring.googleapis.com
    
  2. How long has it been since your cluster was created or had monitoring enabled?

    It can take up to an hour for a new cluster's metrics to start appearing in Stackdriver Monitoring.

  3. Is a heapster running in your cluster in the "kube-system" namespace?

    It's possible that this pod is failing to schedule due to your cluster being too full. Check whether it's running by calling kubectl get pods --namespace=kube-system.

  4. Is your cluster's master able to communicate with the nodes?

    Stackdriver Monitoring relies on that. You can check whether this is the case by running kubectl logs [POD-NAME] If this command returns an error, then the SSH tunnels may be causing the issue. See this section.

If you are having an issue related to the Stackdriver Logging agent, see its troubleshooting documentation.

For more information, refer to the Stackdriver documentation.

Error 404: Resource "not found" when calling gcloud container commands

Re-authenticate to the gcloud command-line tool:

gcloud auth login

Error 400: Missing edit permissions on account

Your Compute Engine service account has been deleted or edited.

When you enable the Compute Engine API, this account is created and given edit permissions on your project. If at any point you edit the permissions, or remove the account entirely, cluster creation will fail.

To resolve the issue, you must recreate the account and/or restore edit permission to your project for the account.

Send feedback about...

Kubernetes Engine