|
| 1 | +--- |
| 2 | +title: "Diagnose connection issues for Azure Arc-enabled Kubernetes clusters" |
| 3 | +ms.date: 11/04/2022 |
| 4 | +ms.topic: how-to |
| 5 | +description: "Learn how to resolve common issues when connecting Kubernetes clusters to Azure Arc." |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +# Diagnose connection issues for Azure Arc-enabled Kubernetes clusters |
| 10 | + |
| 11 | +If you are experiencing issues connecting a cluster to Azure Arc, it's probably due to one of the issues listed here. We provide two flowcharts with guided help: one if you're [not using a proxy server](#connections-without-a-proxy), and one that applies if your network connection [uses a proxy server](#connections-with-a-proxy-server). |
| 12 | + |
| 13 | +> [!TIP] |
| 14 | +> The steps in this flowchart apply whether you're using Azure CLI or Azure PowerShell to [connect your cluster](quickstart-connect-cluster.md). However, some of the steps require the use of Azure CLI. If you haven't already [installed Azure CLI](/cli/azure/install-azure-cli), be sure to do so before you begin. |
| 15 | +
|
| 16 | +## Connections without a proxy |
| 17 | + |
| 18 | +Review this flowchart in order to diagnose your issue when attempting to connect a cluster to Azure Arc without a proxy server. More details about each step are provided below. |
| 19 | + |
| 20 | +:::image type="content" source="media/diagnose-connection-issues/no-proxy-flowchart.png" alt-text="Flowchart showing a visual representation of checking for connection issues when not using a proxy."::: |
| 21 | + |
| 22 | +### Does the Azure identity have sufficient permissions? |
| 23 | + |
| 24 | +Review the [prerequisites for connecting a cluster](quickstart-connect-cluster.md?tabs=azure-cli#prerequisites) and make sure that the identity you're using to connect the cluster has the necessary permissions. |
| 25 | + |
| 26 | +### Is Azure CLI version above 2.30.0? |
| 27 | + |
| 28 | +Make sure you [have the latest version installed](/cli/azure/install-azure-cli). |
| 29 | + |
| 30 | +If you connected your cluster by using Azure PowerShell, make sure you are running [Azure PowerShell version 6.6.0 or later](/powershell/azure/install-az-ps). |
| 31 | + |
| 32 | +### Is the `connectedk8s` extension the latest version? |
| 33 | + |
| 34 | +Update the Azure CLI `connectedk8s` extension to the latest version by running this command: |
| 35 | + |
| 36 | +```azurecli |
| 37 | +az extension update --name connectedk8s |
| 38 | +``` |
| 39 | + |
| 40 | +If you haven't installed the extension yet, you can do so by running the following command: |
| 41 | + |
| 42 | +```azurecli |
| 43 | +az extension add --name connectedk8s |
| 44 | +``` |
| 45 | + |
| 46 | +### Is kubeconfig pointing to the right cluster? |
| 47 | + |
| 48 | +Run `kubectl config get-contexts` to confirm the target context name. Then set the default context to the right cluster by running `kubectl config use-context <target-cluster-name>`. |
| 49 | + |
| 50 | + |
| 51 | +### Are all required resource providers registered? |
| 52 | + |
| 53 | +Be sure that the Microsoft.Kubernetes, Microsoft.KubernetesConfiguration, and Microsoft.ExtendedLocation resource providers are [registered](quickstart-connect-cluster.md#register-providers-for-azure-arc-enabled-kubernetes). |
| 54 | + |
| 55 | +### Are all network requirements met? |
| 56 | + |
| 57 | +Review the [network requirements](quickstart-connect-cluster.md#meet-network-requirements) and ensure that no required endpoints are blocked. |
| 58 | + |
| 59 | +### Are all pods in the `azure-arc` namespace running? |
| 60 | + |
| 61 | +If everything is working correctly, your pods should all be in the `Running` state. Run `kubectl get pods -n azure-arc` to confirm whether any pod's state is not `Running`. |
| 62 | + |
| 63 | +### Still having problems? |
| 64 | + |
| 65 | +The steps above will resolve many common connection issues, but if you're still unable to connect successfully, generate a troubleshooting log file and then [open a support request](/azure/azure-portal/supportability/how-to-create-azure-support-request) so we can investigate the problem further. |
| 66 | + |
| 67 | +To generate the troubleshooting log file, run the following command: |
| 68 | + |
| 69 | +```azurecli |
| 70 | +az connectedk8s troubleshoot -g <myResourceGroup> -n <myK8sCluster> |
| 71 | +``` |
| 72 | + |
| 73 | +When you [create your support request](/azure/azure-portal/supportability/how-to-create-azure-support-request), in the **Additional details** section, use the **File upload** option to upload the generated log file. |
| 74 | + |
| 75 | +## Connections with a proxy server |
| 76 | + |
| 77 | +If you are using a proxy server on at least one machine, complete the first five steps of the non-proxy flowchart (through resource provider registration) for basic troubleshooting steps. Then, if you are still encountering issues, review the next flowchart for additional troubleshooting steps. More details about each step are provided below. |
| 78 | + |
| 79 | +:::image type="content" source="media/diagnose-connection-issues/proxy-flowchart.png" alt-text="Flowchart showing a visual representation of checking for connection issues when using a proxy." ::: |
| 80 | + |
| 81 | +### Is the machine executing commands behind a proxy server? |
| 82 | + |
| 83 | +Be sure you have set all of the necessary environment variables. For more information, see [Connect using an outbound proxy server](quickstart-connect-cluster.md#connect-using-an-outbound-proxy-server). |
| 84 | + |
| 85 | +### Does the proxy server only accept trusted certificates? |
| 86 | + |
| 87 | +Be sure to include the certificate file path by including `--proxy-cert <path-to-cert-file>` when running the `az connectedk8s connect` command. |
| 88 | + |
| 89 | +```azurecli |
| 90 | +az connectedk8s connect --name <cluster-name> --resource-group <resource-group> --proxy-cert <path-to-cert-file> |
| 91 | +``` |
| 92 | + |
| 93 | +### Is the proxy server able to reach required network endpoints? |
| 94 | + |
| 95 | +Review the [network requirements](quickstart-connect-cluster.md#meet-network-requirements) and ensure that no required endpoints are blocked. |
| 96 | + |
| 97 | +### Is the proxy server only using HTTP? |
| 98 | + |
| 99 | +If your proxy server only uses HTTP, you can use `proxy-http` for both parameters. |
| 100 | + |
| 101 | +If your proxy server is set up with both HTTP and HTTPS, run the `az connectedk8s connect` command with the `--proxy-https` and `--proxy-http` parameters specified. Be sure you are using `--proxy-http` for the HTTP proxy and `--proxy-https` for the HTTPS proxy. |
| 102 | + |
| 103 | +```azurecli |
| 104 | +az connectedk8s connect --name <cluster-name> --resource-group <resource-group> --proxy-https https://<proxy-server-ip-address>:<port> --proxy-http http://<proxy-server-ip-address>:<port> |
| 105 | +``` |
| 106 | + |
| 107 | +### Does the proxy server require skip ranges for service-to-service communication? |
| 108 | + |
| 109 | +If you require skip ranges, use `--proxy-skip-range <excludedIP>,<excludedCIDR>` in your `az connectedk8s connect` command. |
| 110 | + |
| 111 | +```azurecli |
| 112 | +az connectedk8s connect --name <cluster-name> --resource-group <resource-group> --proxy-https https://<proxy-server-ip-address>:<port> --proxy-http http://<proxy-server-ip-address>:<port> --proxy-skip-range <excludedIP>,<excludedCIDR> |
| 113 | +``` |
| 114 | + |
| 115 | +### Are all pods in the `azure-arc` namespace running? |
| 116 | + |
| 117 | +If everything is working correctly, your pods should all be in the `Running` state. Run `kubectl get pods -n azure-arc` to confirm whether any pod's state is not `Running`. |
| 118 | + |
| 119 | +### Still having problems? |
| 120 | + |
| 121 | +The steps above will resolve many common connection issues, but if you're still unable to connect successfully, generate a troubleshooting log file and then [open a support request](/azure/azure-portal/supportability/how-to-create-azure-support-request) so we can investigate the problem further. |
| 122 | + |
| 123 | +To generate the troubleshooting log file, run the following command: |
| 124 | + |
| 125 | +```azurecli |
| 126 | +az connectedk8s troubleshoot -g <myResourceGroup> -n <myK8sCluster> |
| 127 | +``` |
| 128 | + |
| 129 | +When you [create your support request](/azure/azure-portal/supportability/how-to-create-azure-support-request), in the **Additional details** section, use the **File upload** option to upload the generated log file. |
| 130 | + |
| 131 | + |
| 132 | +## Next steps |
| 133 | + |
| 134 | +- View more [troubleshooting tips for using Azure Arc-enabled Kubernetes](troubleshooting.md). |
| 135 | +- Review the process to [connect an existing Kubernetes cluster to Azure Arc](quickstart-connect-cluster.md). |
0 commit comments