This page discusses support and troubleshooting resources available for Kubernetes and Kubernetes Engine, as well as solutions to common issues.
The following is a list of support resources for Kubernetes Engine and Kubernetes:
- Ask programming- and development-related questions on StackOverflow's Kubernetes and Kubernetes Engine tags.
- Interact with the Kubernetes team and other Kubernetes users on Kubernetes Slack channel
- Ask questions and engage in discussions in the Kubernetes Users email group.
- Learn about Kubernetes special-interest groups and events in the Kubernetes community
- Purchase a support plan from Google Cloud Support
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:
- Cloud provider, OS distro, network configuration, and Docker version
- Steps to reproduce the problem
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.
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
variable. Modifying this variables enables you to use
kubectl commands without
typing their full file path.
Alternatively, add the following line to
~/.bash_profile in macOS, or wherever
your shell stores environment variables):
Finally, run the following command to load your updated
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
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:
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.
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 are then removed from the master's API and replaced by the new nodes.
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>-sshthat 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.
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.
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
If the issue persists, check the following potential causes:
Ensure that you have enabled monitoring on your cluster.
Monitoring is enabled by default for clusters created from the Developers Console and the
gcloudcommand-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
gcloudcommand-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
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.
heapsterrunning 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.
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/403: Missing edit permissions on account
Your Compute Engine and/or Kubernetes Engine service account has been deleted or edited.
When you enable the Compute Engine or Kubernetes Engine API, a service account is created and given edit permissions on your project. If at any point you edit the permissions, remove the account entirely, or disable the API, cluster creation and all management functionality will fail.
To resolve the issue, you must re-enable the Kubernetes Engine API - this will correctly restore your service accounts and permissions.
- Visit the APIs & Services page.
- Select your project.
- Enable the Kubernetes Engine API - if you have previously enabled the API, you must first Disable it and then Enable it again. Wait for the API and related services to be enabled. This can take several minutes.
Alternatively, use the
gcloud command-line tool:
gcloud services enable container.googleapis.com
Replicating 1.8.x (and earlier) automatic firewall rules on 1.9.x and later
If your cluster is running Kubernetes version 1.9.x, the automatic firewall rules have changed to disallow workloads in a Kubernetes Engine cluster to initiate communication with other Compute Engine VMs that are outside the cluster but on the same network.
You can replicate the automatic firewall rules behavior of a 1.8.x (and earlier) cluster by performing the following steps:
First, find your cluster's network:
gcloud container clusters describe [CLUSTER_NAME] --format=get"(network)"
Then get the cluster's IPv4 CIDR used for the containers:
gcloud container clusters describe [CLUSTER_NAME] --format=get"(clusterIpv4Cidr)"
Finally create a firewall rule for the network, with the CIDR as the source range, and allow all protocols:
gcloud compute firewall-rules create "[CLUSTER_NAME]-to-all-vms-on-network" --network="[NETWORK]" --source-ranges="[CLUSTER_IPV4_CIDR]" --allow=tcp,udp,icmp,esp,ah,sctp