在 macOS 上安装和设置 kubectl

准备工作

你使用的 kubectl 版本必须与你的集群版本在一个小版本差异之内。例如，v1.34 客户端可以与 v1.33、v1.34 和 v1.35 控制平面通信。使用最新兼容的 kubectl 版本有助于避免意外问题。

在 macOS 上安装 kubectl

以下是 macOS 上安装 kubectl 的方法：

使用 curl 在 macOS 上安装 kubectl 二进制文件

  1. 下载最新版本

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

  2. 验证二进制文件（可选）

    下载 kubectl 校验和文件

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl.sha256"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl.sha256"

    根据校验和文件验证 kubectl 二进制文件

    echo "$(cat kubectl.sha256)  kubectl" | shasum -a 256 --check

    如果有效，输出为

    kubectl: OK

    如果检查失败，shasum 将以非零状态退出并打印类似如下的输出

    kubectl: FAILED
shasum: WARNING: 1 computed checksum did NOT match

  3. 使 kubectl 二进制文件可执行。

    chmod +x ./kubectl

  4. 将 kubectl 二进制文件移动到系统 PATH 中的文件位置。

    sudo mv ./kubectl /usr/local/bin/kubectl
sudo chown root: /usr/local/bin/kubectl

  5. 测试以确保你安装的版本是最新的

    kubectl version --client

    或者使用此命令查看详细版本信息

    kubectl version --client --output=yaml

  6. 安装并验证 kubectl 后，删除校验和文件

    rm kubectl.sha256

使用 Homebrew 在 macOS 上安装

如果你在 macOS 上使用 Homebrew 包管理器，你可以使用 Homebrew 安装 kubectl。

  1. 运行安装命令

    brew install kubectl

    或者

    brew install kubernetes-cli

  2. 测试以确保你安装的版本是最新的

    kubectl version --client

使用 Macports 在 macOS 上安装

如果你在 macOS 上使用 Macports 包管理器，你可以使用 Macports 安装 kubectl。

  1. 运行安装命令

    sudo port selfupdate
sudo port install kubectl

  2. 测试以确保你安装的版本是最新的

    kubectl version --client

验证 kubectl 配置

为了使 kubectl 能够找到并访问 Kubernetes 集群，它需要一个 kubeconfig 文件，该文件在你使用 kube-up.sh 创建集群或成功部署 Minikube 集群时自动创建。默认情况下，kubectl 配置位于 ~/.kube/config。

通过获取集群状态来检查 kubectl 是否配置正确

kubectl cluster-info

如果你看到 URL 响应，则 kubectl 已正确配置以访问你的集群。

如果你看到类似以下消息，则 kubectl 配置不正确或无法连接到 Kubernetes 集群。

The connection to the server <server-name:port> was refused - did you specify the right host or port?

例如，如果你打算在笔记本电脑（本地）上运行 Kubernetes 集群，你需要先安装 Minikube 等工具，然后重新运行上述命令。

如果 kubectl cluster-info 返回 URL 响应但你无法访问你的集群，要检查它是否配置正确，请使用

kubectl cluster-info dump

解决“未找到身份验证提供程序”错误消息

在 Kubernetes 1.26 中，kubectl 移除了对以下云提供商托管 Kubernetes 产品内置的身份验证。这些提供商已经发布了 kubectl 插件来提供特定于云的身份验证。有关说明，请参阅以下提供商文档

（也可能存在其他原因导致出现相同的错误消息，与此更改无关。）

可选的 kubectl 配置和插件

启用 shell 自动补全

kubectl 为 Bash、Zsh、Fish 和 PowerShell 提供自动补全支持，这可以为你节省大量打字时间。

以下是为 Bash、Fish 和 Zsh 设置自动补全的步骤。

介绍

Bash 的 kubectl 补全脚本可以通过 kubectl completion bash 生成。在你的 Shell 中加载此脚本可启用 kubectl 补全。

但是，kubectl 补全脚本依赖于 bash-completion，因此你必须事先安装它。

升级 Bash

这里的说明假设你使用 Bash 4.1+。你可以通过运行以下命令检查你的 Bash 版本

echo $BASH_VERSION

如果它太旧，你可以使用 Homebrew 安装/升级它

brew install bash

重新加载你的 Shell 并验证是否正在使用所需版本

echo $BASH_VERSION $SHELL

Homebrew 通常将其安装在 /usr/local/bin/bash。

安装 bash-completion

你可以通过 type _init_completion 测试是否已安装 bash-completion v2。如果没有，你可以使用 Homebrew 安装它

brew install bash-completion@2

如该命令的输出所述，将以下内容添加到你的 ~/.bash_profile 文件中

brew_etc="$(brew --prefix)/etc" && [[ -r "${brew_etc}/profile.d/bash_completion.sh" ]] && . "${brew_etc}/profile.d/bash_completion.sh"

重新加载你的 Shell 并通过 type _init_completion 验证 bash-completion v2 是否正确安装。

启用 kubectl 自动补全

你现在必须确保 kubectl 补全脚本在所有 shell 会话中都已加载。有多种方法可以实现此目的

  • 在你的 ~/.bash_profile 文件中加载补全脚本

    echo 'source <(kubectl completion bash)' >>~/.bash_profile

  • 将补全脚本添加到 /usr/local/etc/bash_completion.d 目录

    kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl

  • 如果你有 kubectl 的别名，你可以扩展 Shell 补全以与该别名一起使用

    echo 'alias k=kubectl' >>~/.bash_profile
echo 'complete -o default -F __start_kubectl k' >>~/.bash_profile

  • 如果你使用 Homebrew 安装了 kubectl（如此处所述），那么 kubectl 补全脚本应该已经在 /usr/local/etc/bash_completion.d/kubectl 中了。在这种情况下，你无需执行任何操作。

无论如何，重新加载你的 Shell 后，kubectl 补全应该可以工作了。

Fish 的 kubectl 补全脚本可以通过命令 kubectl completion fish 生成。在你的 Shell 中加载补全脚本可启用 kubectl 自动补全。

要在所有 Shell 会话中执行此操作，请将以下行添加到你的 ~/.config/fish/config.fish 文件中

kubectl completion fish | source

重新加载 shell 后，kubectl 自动补全应该可以工作了。

Zsh 的 kubectl 补全脚本可以通过命令 kubectl completion zsh 生成。在你的 Shell 中加载补全脚本可启用 kubectl 自动补全。

要在所有 Shell 会话中执行此操作，请将以下内容添加到你的 ~/.zshrc 文件中

source <(kubectl completion zsh)

如果你有 kubectl 的别名，kubectl 自动补全将自动与其一起工作。

重新加载 shell 后，kubectl 自动补全应该可以工作了。

如果你收到类似 2: command not found: compdef 的错误，请将以下内容添加到你的 ~/.zshrc 文件开头

autoload -Uz compinit
compinit

配置 kuberc

有关更多信息，请参阅 kuberc。

安装 kubectl convert 插件

一个用于 Kubernetes 命令行工具 kubectl 的插件，它允许你在不同的 API 版本之间转换清单。这对于将清单迁移到具有更新 Kubernetes 版本的非弃用 API 版本特别有用。有关更多信息，请访问 迁移到非弃用 API

  1. 使用命令下载最新版本

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl-convert"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl-convert"

  2. 验证二进制文件（可选）

    下载 kubectl-convert 校验和文件

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl-convert.sha256"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl-convert.sha256"

    根据校验和文件验证 kubectl-convert 二进制文件

    echo "$(cat kubectl-convert.sha256)  kubectl-convert" | shasum -a 256 --check

    如果有效，输出为

    kubectl-convert: OK

    如果检查失败，shasum 将以非零状态退出并打印类似如下的输出

    kubectl-convert: FAILED
shasum: WARNING: 1 computed checksum did NOT match

  3. 使 kubectl-convert 二进制文件可执行

    chmod +x ./kubectl-convert

  4. 将 kubectl-convert 二进制文件移动到系统 PATH 中的文件位置。

    sudo mv ./kubectl-convert /usr/local/bin/kubectl-convert
sudo chown root: /usr/local/bin/kubectl-convert

  5. 验证插件是否成功安装

    kubectl convert --help

    如果你没有看到错误，则表示插件已成功安装。

  6. 安装插件后，清理安装文件

    rm kubectl-convert kubectl-convert.sha256

在 macOS 上卸载 kubectl

根据你安装 kubectl 的方式，使用以下方法之一。

使用命令行卸载 kubectl

  1. 在你的系统上找到 kubectl 二进制文件

    which kubectl

  2. 删除 kubectl 二进制文件

    sudo rm <path>

    将 <path> 替换为上一步中 kubectl 二进制文件的路径。例如，sudo rm /usr/local/bin/kubectl。

使用 Homebrew 卸载 kubectl

如果你使用 Homebrew 安装了 kubectl，请运行以下命令

brew remove kubectl

下一步

上次修改时间：2025 年 5 月 15 日上午 9:23 PST：添加 kuberc 专用页面 (edac5dbf0e)