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

本页面介绍如何安装和配置 kubectl 命令行工具以与 Google Kubernetes Engine (GKE) 集群进行交互。

概览

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

gcloud

  1. 安装 kubectl 组件：

    gcloud components install kubectl

  2. 通过检查是否具有最新版来确认 kubectl 已安装：

    kubectl version --client

apt

  1. 验证您是否拥有 cloud-sdk 代码库：

    grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"

    输出类似于以下内容：

    deb  [signed-by=/usr/share/keyrings/cloud.google.gpg]  https://packages.cloud.google.com/apt cloud-sdk main

  2. 如果未列出 cloud-sdk 代码库，请安装 gcloud CLI。

  3. 安装 kubectl 组件：

    apt-get update
apt-get install -y kubectl

  4. 通过检查是否具有最新版来确认 kubectl 已安装：

    kubectl version --client

yum

  1. 验证您是否拥有 cloud-sdk 代码库：

    yum repolist | grep "google-cloud-sdk"

    输出类似于以下内容：

    google-cloud-sdk    Google Cloud SDK    2,205

  2. 安装 kubectl 组件：

    yum install -y kubectl

  3. 通过检查是否具有最新版来确认 kubectl 已安装：

    kubectl version --client

安装所需的插件

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

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

  gcloud components install gke-gcloud-auth-plugin

apt

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

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

yum

安装 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 条目包含：

如需在您的环境中生成 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

问题排查

如需了解更多问题排查相关信息，请参阅排查常见问题。

身份验证范围不足

运行 gcloud container clusters get-credentials 时，您收到以下错误：

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

出现此错误的原因是您正在尝试从没有 cloud-platform 范围的 Compute Engine 虚拟机访问 Kubernetes Engine API。如需了解如何在 Compute Engine 虚拟机实例上更改范围，请参阅为实例创建和启用服务账号。

错误：找不到可执行的 gke-gcloud-auth-plugin

如果在尝试运行 kubectl 或与 GKE 交互的自定义客户端时收到以下错误，请按照安装说明中的说明安装 gke-gcloud-auth-plugin。错误消息类似于以下内容：

  • 错误示例
Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.

To learn more about this feature, consult the documentation available at:
      https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.
  • 错误示例
Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory

错误：故障：找不到名称 GCP 的身份验证提供商

如果 kubectl 或自定义 Kubernetes 客户端使用 Kubernetes client-go 1.26 版或更高版本构建，则会收到 no Auth Provider found for name "gcp" 错误，如工作原理中所述。这可以通过以下步骤解决：

  1. 按照安装说明安装 gke-gcloud-auth-plugin。

  2. 使用 gcloud components update 更新到最新版 gcloud CLI。

  3. 更新 kubeconfig 文件。

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

    请替换以下内容：

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

警告：GCP 身份验证插件已弃用，请改用 gcloud

在安装 gke-gcloud-auth-plugin 并对 GKE 集群运行 kubectl 命令后，您可能会注意到此警告消息。如果您的客户端版本低于 1.26，则会显示此消息。

如需指示客户端改用 gke-gcloud-auth-plugin 身份验证插件，请执行以下操作：

  1. 在文本编辑器中打开 shell 登录脚本：

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    如果您使用的是 PowerShell，请跳过此步骤。

  2. 设置以下环境变量：

    Bash

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    Zsh

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    PowerShell

    [Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')

  3. 在您的环境中应用该变量：

    Bash

    source ~/.bashrc

    Zsh

    source ~/.zshrc

    PowerShell

    退出终端并打开新的终端会话。

  4. 更新 gcloud CLI：

    gcloud components update

  5. 向集群进行身份验证：

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

    请替换以下内容：

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

后续步骤

自行试用

如果您是 Google Cloud 新手，请创建一个账号来评估 GKE 在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

免费试用 GKE