为 kubectl 配置集群访问权限

本页面介绍了如何为 Google Kubernetes Engine 中的 kubectl 命令行工具配置集群访问权限。

概览

如果您在 Google Cloud 项目中运行多个集群，则需要选择要与 kubectl 通信的集群。您可以通过在 Kubernetes 的 kubeconfig 文件中设置当前上下文来为 kubectl 设置默认集群。此外，您可以使用 --cluster 标志针对特定集群运行 kubectl 命令。

以下部分说明了 kubeconfig 的工作方式、如何为 kubectl 设置默认集群，以及如何针对特定集群运行单独的 kubectl 命令。

准备工作

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

使用以下任一方法设定默认的 gcloud 设置：

  • 使用 gcloud init（如果您想要在系统引导下完成默认设置）。
  • 使用 gcloud config（如果您想单独设置项目 ID、区域和地区）。

使用 gcloud init

如果您收到 One of [--zone, --region] must be supplied: Please specify location 错误，请完成本部分。

  1. 运行 gcloud init 并按照说明操作：

    gcloud init

    如果您要在远程服务器上使用 SSH，请使用 --console-only 标志来防止命令启动浏览器：

    gcloud init --console-only
  2. 按照说明授权 gcloud 使用您的 Google Cloud 帐号。
  3. 创建新配置或选择现有配置。
  4. 选择 Google Cloud 项目。
  5. 选择默认的 Compute Engine 区域。

使用 gcloud config

  • 设置默认项目 ID： 
    gcloud config set project project-id
  • 如果您使用的是可用区级集群，请设置默认计算可用区：
    gcloud config set compute/zone compute-zone
  • 如果您使用的是区域级集群，请设置默认计算区域：
    gcloud config set compute/region compute-region
  • 将 gcloud 更新到最新版本： 
    gcloud components update

Kubernetes 配置文件

Kubernetes 使用名为 kubeconfig 的 YAML 文件存储 kubectl 的集群身份验证信息。kubeconfig 包含 kubectl 在运行命令时引用的上下文列表。默认情况下，该文件保存在 $HOME/.kube/config。

上下文是一组访问参数。每个上下文都包含一个 Kubernetes 集群、一个用户和一个命名空间。当前上下文是 kubectl 当前的默认集群：所有 kubectl 命令都针对该集群运行。

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

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

当您使用 Google Cloud Console 或使用 gcloud 通过其他计算机创建集群时，您所在环境的 kubeconfig 不会进行更新。此外，如果项目团队成员使用 gcloud 从他们的计算机上创建集群，他们的 kubeconfig 会进行更新，但您的不会。请按照以下说明将这些集群添加到本地 kubeconfig。

关于集群端点

所有集群都有一个规范端点。此端点公开了 kubectl 和其他服务用来与集群控制层面（主实例）通信的 Kubernetes API 服务器。端点 IP 显示在 Cloud Console 中集群“详细信息”标签页的端点字段下，以及 gcloud container clusters describe 输出内容的 endpoint 字段中。

运行 gcloud container clusters get-credentials 时，您会看到该命令将集群端点作为更新 kubeconfig 的一部分。

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

运行 get-credentials 默认使用 endpoint 字段中指定的 IP。对于专用集群，如果您希望使用内部 IP 作为端点，请参阅使用专用集群的内部 IP 地址生成 kubeconfig 条目。

关于 kubectl 的身份验证

通过验证 kubectl 提供的凭据，并检索与用户或服务帐号身份关联的电子邮件地址，所有 GKE 集群都配置为接受 Google Cloud 用户和服务帐号身份。因此，这些帐号的凭据必须包含 userinfo.email OAuth 范围才能成功进行身份验证。

当您使用 gcloud 为新集群或现有集群设置环境的 kubeconfig 时，gcloud 会为 kubectl 提供 gcloud 自身使用的同一凭据。例如，如果使用 gcloud auth login，您的个人凭据会提供给 kubectl，包括 userinfo.email 范围。这样一来，GKE 集群就能够对 kubectl 客户端进行身份验证。

或者，您可以选择对 kubectl 进行配置，使其在 Compute Engine 实例上运行时使用 Google Cloud 服务帐号的凭据。不过，默认情况下，userinfo.email 范围并不包含在 Compute Engine 实例创建的凭据中。因此，您必须明确添加此范围，例如在创建 Compute Engine 实例时使用 --scopes 标志。

当用户或 Google Cloud 服务帐号经过身份验证后，还必须获得授权才能对 GKE 集群执行任何操作。如需了解如何配置授权，请参阅基于角色的访问权限控制。

如需了解在连接到 Kubernetes API 服务器时受支持的身份验证方法，请参阅向 Kubernetes API 服务器进行身份验证。

查看 kubectl 的当前上下文

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

kubectl config current-context

查看 kubeconfig

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

kubectl config view

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

生成 kubeconfig 条目

如需对在 Cloud Console 中、从其他计算机或由其他项目成员创建的集群运行 kubectl 命令，您需要在自己的环境中生成 kubeconfig 条目。

运行以下命令，生成 kubeconfig 条目：

gcloud container clusters get-credentials cluster-name

其中，cluster-name 是集群的名称。

如需运行此命令，您必须具有 container.clusters.get 权限。提供此权限的最小特权 IAM 角色为 container.clusterViewer。

kubeconfig 条目包含：

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

运行 get-credentials 时，您可以指定 --internal-ip，以便将专用集群的内部 IP 地址写入 kubeconfig：

gcloud container clusters get-credentials --internal-ip cluster-name

为 kubectl 命令设置默认集群

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

gcloud container clusters get-credentials

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

gcloud container clusters get-credentials my-cluster

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

您可以针对特定集群运行单独的 kubectl 命令，只需将 kubeconfig 中显示的该集群名称作为 --cluster 标志的参数传入即可。

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

kubectl run my-app --image gcr.io/my-bucket/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 虚拟机实例上更改范围，请参阅为实例创建和启用服务帐号。

后续步骤