This documentation is for the most recent version of GKE on Azure, released in November 2021. See the Release notes for more information.

Configure cluster access for kubectl

This page explains how to configure cluster access for the kubectl command-line tool for GKE on Azure.

This page is for IT administrators and Operators who want to set up, monitor, and manage cloud infrastructure. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE Enterprise user roles and tasks.

Overview

To access your GKE on Azure, you need to configure kubectl. You can set a default cluster for kubectl by setting the current context in Kubernetes' kubeconfig file. Additionally, you can run kubectl commands against a specific cluster using the --cluster flag.

For more information about kubeconfig and cluster endpoints, see About Kubeconfig.

Before you begin

If you use the Connect gateway for kubectl access, you must grant admin users who aren't project owners the IAM roles described in Use kubectl with identity from the gcloud CLI.

Check current kubeconfig

This section explains how to check your current kubeconfig.

View kubeconfig contexts

To view your environment's kubeconfig and all of the contexts it contains, run the following command:

kubectl config view

The command returns a list of all clusters for which kubeconfig entries have been generated. If a GKE on Azure cluster is listed, you can run kubectl commands against it in your current environment. Otherwise, you need to generate a kubeconfig entry for the cluster.

View the current context for kubectl

To view the current context that the kubectl command-line tool uses, run the following command:

kubectl config current-context

kubectl outputs the name of the current context.

Generate a kubeconfig entry

To run kubectl commands against GKE clusters, you need to generate a kubeconfig entry. How you generate a kubeconfig file depends on how you want to connect to your cluster. We recommend that you use the Connect gateway. When you use the Connect gateway, the gke-connect-agent Deployment sends requests through Google to the cluster control plane.

To check which kubectl commands are supported by the Connect gateway, see Limitations.

If you want to connect through a private endpoint, you need to have a connection and routing to the control plane endpoint in your Azure Virtual Network. The cluster's kube-apiserver is part of the control plane. In order to send requests directly to the private endpoint, you might need to widen firewall rules. For more information on connecting to your control plane, see Network security groups.

Connect gateway

gcloud container azure clusters get-credentials CLUSTER_NAME \
  --location GOOGLE_CLOUD_LOCATION

Replace the following:

CLUSTER_NAME: the name of your cluster
GOOGLE_CLOUD_LOCATION: the Google Cloud region or zone where your GKE on Azure are managed

Private endpoint

To connect to the private endpoint, you need connectivity to the cluster's control plane. See Connect to your cluster's control plane.

gcloud container azure clusters get-credentials CLUSTER_NAME \
  --location GOOGLE_CLOUD_LOCATION \
  --private-endpoint

Replace the following:

CLUSTER_NAME: the name of your cluster
GOOGLE_CLOUD_LOCATION: the Google Cloud region or zone where your GKE on Azure are managed

Work with multiple clusters

This section describes how to use kubectl with multiple GKE clusters.

Set a default cluster for kubectl commands

You can switch the current context for kubectl to that cluster by running:

gcloud container azure clusters get-credentials CLUSTER_NAME \
  --location GOOGLE_CLOUD_LOCATION \

Replace the following:

CLUSTER_NAME: the name of your cluster
GOOGLE_CLOUD_LOCATION: the Google Cloud region or zone where your GKE on Azure are managed

For example, consider a project with two clusters, cluster-1 and cluster-2. The current context is cluster-2. To switch the current context from cluster-2 to cluster-1, run the following command:

gcloud container azure clusters get-credentials cluster-1 \
  --location GOOGLE_CLOUD_LOCATION

Run individual kubectl commands against a specific cluster

You can run individual kubectl commands against a specific cluster by passing in the name of the cluster as it appears in kubeconfig as the argument to the --cluster flag.

For example, consider an environment with two clusters, cluster-1 and cluster-2, in which the current context is cluster-1. You don't want to change the current context. To get a list of Pod objects on cluster-2 without changing the current context, run the following command:

kubectl get pod --cluster cluster-2