# Troubleshoot common issues

This page shows you how to resolve common issues with GKE on Azure.
If you need additional assistance, reach out to [Cloud Customer Care](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/getting-support.md.txt).

## Common error messages

The following sections explain the causes and resolutions for some common
error messages.

### Server doesn't have a resource

Errors such as `error: the server doesn't have a resource type "services"` can
happen when a cluster has no running node pools, or Connect gateway cannot
connect to a node pool. To check the status of your node pools, run the
following command:

```bash
gcloud container azure node-pools list \
    --cluster-name CLUSTER_NAME \
    --location LOCATION
```

Replace the following:

- `CLUSTER_NAME`: your cluster's name
- `LOCATION`: the Google Cloud location that manages your cluster

The output includes the status of your cluster's node pools. If you don't have
a node pool listed, [Create a node pool](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/create-node-pool.md.txt).

### Forbidden user

The following error occurs when your username does not have administrator access
to your cluster:

    Error from server (Forbidden): users "administrator@example.com" is forbidden:
    User "system:serviceaccount:gke-connect:connect-agent-sa" cannot impersonate
    resource "users" in API group "" at the cluster scope

You can configure additional users by passing the
[`--admin-users`](https://docs.cloud.google.com/sdk/gcloud/reference/container/azure/clusters/create#--admin-users)
flag when you create a cluster.

If you use Connect gateway and can't connect to your cluster, try the following
steps:

1. Get the authorized users for your cluster.

   ```bash
   gcloud container azure clusters describe CLUSTER_NAME \
       --format 'value(authorization.admin_users)'
   ```

   Replace `CLUSTER_NAME` with your cluster's name.

   The output includes the usernames with administrator access to the cluster.
   For example:

       {'username': 'administrator@example.com'}

2. Get the username currently authenticated with the Google Cloud CLI.

   ```bash
   gcloud config get-value account
   ```

   The output includes the account authenticated with the Google Cloud CLI. If
   the output of the `gcloud containers azure clusters describe` and `gcloud
   config get-value account` don't match, run `gcloud auth login` and
   authenticate as the username with administrative access to the cluster.

## Issues with kubectl commands

The following sections provide guidance on how to resolve issues with
unresponsive or failing `kubectl` commands.

### kubectl commands stop responding

If your cluster runs a Kubernetes version earlier than 1.25 and `kubectl`
commands are unresponsive or time out, the most common reason is that you have
not yet created a node pool. By default, GKE on Azure generates
`kubeconfig` files that use Connect gateway as an internet-reachable endpoint.
For this to work, the `gke-connect-agent` Deployment needs to be running in
a node pool on the cluster.

For more diagnostic information, run the following command:

```bash
kubectl cluster-info -v=9
```

If there are no running node pools, you see requests to
`connectgateway.googleapis.com` fail with a 404
`cannot find active connections for cluster` error.

For clusters with a Kubernetes version of 1.25 or later, the `gke-connect-agent`
runs on the control plane, and a node pool is not required. If the `kubectl` command
is unresponsive, check the control plane component logs with
[Cloud Logging](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/cloud-logging.md.txt#control_plane_logs).

### kubectl exec, attach, and port-forward commands fail

The `kubectl exec`, `kubectl attach`, and `kubectl port-forward` commands might
fail with the message `error: unable to upgrade connection` when using
Connect gateway. This is a limitation when using Connect gateway as your
Kubernetes API Server endpoint.

To work around this, use a `kubeconfig` that specifies the cluster's
private endpoint. For instructions on accessing the cluster through its
private endpoint, see
[Configure cluster access for kubectl](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/configure-cluster-access-for-kubectl.md.txt).

### Generic kubectl troubleshooting

If you use Connect gateway:

- Ensure you have enabled Connect gateway in your Google Cloud project:

  ```bash
  gcloud services enable connectgateway.googleapis.com
  ```
- For clusters with a Kubernetes version earlier than 1.25, ensure that you have at
  least one Linux node pool running and that the `gke-connect-agent` is running.
  For details, see
  [Troubleshoot cluster connections](https://docs.cloud.google.com/anthos/fleet-management/docs/troubleshooting).

- For clusters with a Kubernetes version of 1.25 or later, check the `gke-connect-agent`
  logs with [Cloud Logging](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/cloud-logging.md.txt#control_plane_logs).

## What's next

- If you need additional assistance, reach out to [Cloud Customer Care](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/getting-support.md.txt).