安装 kubectl 并配置集群访问权限

本页面介绍了如何安装和配置 kubectl 命令行工具。

本页面适用于负责设置、监控和管理云基础设施以及预配和配置云资源的 IT 管理员、运维人员和开发者。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

概览

kubectl 是一个命令行工具，可用来与 GKE 集群进行交互。如需将 kubectl 与 GKE 搭配使用，您必须安装该工具并将其配置为与集群通信。如果您在 Google Cloud 中运行多个集群，则需要进一步配置 kubectl。

本页面向您介绍以下内容：

• kubectl 的工作方式。
• 如何安装 kubectl 以及任何必需的依赖项。
• 如何为 kubectl 设置默认集群。
• 如何针对特定集群运行 kubectl 命令。

准备工作

在开始之前，请确保您已执行以下任务：

• 启用 Google Kubernetes Engine API。
启用 Google Kubernetes Engine API
• 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。 如果您之前安装了 gcloud CLI，请运行 gcloud components update 以获取最新版本。

安装 kubectl

您可以使用 Google Cloud CLI 或外部软件包管理器（如 apt 或 yum）安装 kubectl。

安装所需的插件

kubectl 和其他 Kubernetes 客户端需要身份验证插件 gke-gcloud-auth-plugin，该插件使用 Client-go 凭据插件框架提供身份验证令牌来与 GKE 集群通信。

在 Kubernetes 1.26 版发布之前，gcloud CLI 将开始要求安装 gke-gcloud-auth-plugin 二进制文件。如果未安装，则现有 kubectl 或其他自定义 Kubernetes 客户端的安装将停止运作。

必须安装此插件才能使用 kubectl 和其他客户端与 GKE 进行交互。如果未安装此插件，现有客户端会显示错误消息。

开始之前，请检查是否已安装该插件：

gke-gcloud-auth-plugin --version

如果输出显示版本信息，请跳过此部分。

您可以使用 gcloud CLI 或外部软件包管理系统（例如 apt 或 yum）安装身份验证插件。

  gcloud components install gke-gcloud-auth-plugin

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

验证 gke-gcloud-auth-plugin 二进制文件安装：

1. 检查 gke-gcloud-auth-plugin 二进制文件版本：

   gke-gcloud-auth-plugin --version
   

2. 更新 kubectl 配置以使用该插件：

   gcloud container clusters get-credentials CLUSTER_NAME \
       --region=COMPUTE_REGION
   

   请替换以下内容：

   • CLUSTER_NAME：您的集群的名称。
   • COMPUTE_REGION：集群的 Compute Engine 区域。 对于可用区级集群，请使用 --zone=COMPUTE_ZONE。

3. 验证配置：

   kubectl get namespaces
   

   输出类似于以下内容：

   NAME              STATUS   AGE
   default           Active   51d
   kube-node-lease   Active   51d
   kube-public       Active   51d
   kube-system       Active   51d
   

如需详细了解需要此插件的原因，请参阅 Kubernetes KEP。

与 kubectl 交互

Kubernetes 使用名为 kubeconfig 的 YAML 文件来存储 kubectl 的集群身份验证信息。默认情况下，该文件保存在 $HOME/.kube/config。

kubeconfig 包含一组称为“上下文”的访问参数。每个上下文都包含一个 Kubernetes 集群、一个用户和一个可选的默认命名空间。kubectl 是指运行命令时的上下文。

您可以完成以下任务来配置 kubectl：

• 选择与 kubectl 通信的集群。
• 通过在 kubeconfig 文件中设置当前上下文，为 kubectl 设置默认集群。
• 使用 --cluster 标志针对特定集群运行 kubectl 命令。

查看kubeconfig

若要查看环境的 kubeconfig，请运行以下命令：

kubectl config view

该命令返回已生成 kubeconfig 条目所对应的所有集群的列表。如果系统列出了某一 GKE 集群，您可以在当前环境中对其运行 kubectl 命令。否则，您需要存储 kubectl 的集群信息。

查看 kubectl 的当前上下文

当前上下文是 kubectl 当前的默认集群。所有 kubectl 命令都针对该集群运行。

使用 gcloud container clusters create-auto 创建集群时，系统会自动将条目添加到环境中的 kubeconfig 文件，并且当前上下文将更改为该集群。例如：

gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

若要查看 kubectl 的当前上下文，请运行以下命令：

kubectl config current-context

存储 kubectl 的集群信息

当您使用 Google Cloud 控制台或使用 gcloud CLI 从其他计算机创建集群时，您所在环境的 kubeconfig 文件不会更新。此外，如果项目团队成员使用 gcloud CLI 从他们的计算机上创建集群，他们的 kubeconfig 会进行更新，但您的不会。kubeconfig 条目包含：

• gcloud auth list 中所示的您的凭据，或
• 应用默认凭据（如果已配置）。

如需在您的环境中生成 kubeconfig 上下文，请确保您拥有 container.clusters.get 权限。提供此权限的最小特权 IAM 角色为 container.clusterViewer。

如需为特定集群生成 kubeconfig 上下文，请运行以下命令：

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=CLUSTER_REGION

请替换以下内容：

• CLUSTER_NAME：您的集群的名称。
• COMPUTE_REGION：集群的 Compute Engine 区域。 对于可用区级集群，请使用 --zone=COMPUTE_ZONE。

使用专用集群的内部 IP 地址生成 kubeconfig 条目

所有集群都有一个规范端点。此端点公开了 kubectl 和其他服务用来与集群控制平面通信的 Kubernetes API 服务器。

专用集群有两个单独的端点 IP 地址：privateEndpoint（内部 IP 地址）和 publicEndpoint（外部 IP 地址）。endpoint 字段指外部 IP 地址，只有在停用对端点的公共访问权限的情况下使用专用 IP 地址。

对于专用集群，如果您希望使用内部 IP 地址作为端点，请运行以下命令：

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

将 CLUSTER_NAME 替换为您的集群名称。

默认情况下，如果运行 get-credentials，则系统会使用 endpoint 字段中指定的 IP 地址。

为 kubectl 命令设置默认集群

如果您之前为集群生成了 kubeconfig 条目，则可以通过运行以下命令，将 kubectl 的当前上下文切换为该集群：

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

请替换以下内容：

• CLUSTER_NAME：您的集群的名称。
• COMPUTE_REGION：集群的 Compute Engine 区域。 对于可用区级集群，请使用 --zone=COMPUTE_ZONE。

举例来说，假设一个项目有 my-cluster 和 my-new-cluster 这两个集群。当前上下文是 my-new-cluster，但是您希望针对 my-cluster 运行所有 kubectl 命令。如需将当前上下文从 my-new-cluster 切换为 my-cluster，请运行以下命令：

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

针对特定集群运行单独的 kubectl 命令

您可以使用 --cluster=CLUSTER_NAME 针对特定集群运行单独的 kubectl 命令。

举例来说，假设一个环境中有 my-cluster 和 my-new-cluster 这两个集群，当前上下文为 my-cluster。您希望将某个应用部署到 my-new-cluster，但您不希望更改当前上下文。如需在不更改当前上下文的情况下将应用部署到 my-new-cluster，您需要运行以下命令：

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

后续步骤

• 了解如何授予对 GKE 集群中资源的访问权限。
• 从 GKE 工作负载向 Google Cloud 服务进行身份验证。
• 阅读 kubectl 备忘单。
• 排查 kubectl 命令行工具问题。