kubevious/cli

Kubevious CLI

Kubevious CLI 是一个以应用为中心的 Kubernetes 保障和验证工具。它帮助现代团队快速发布云原生应用，避免灾难、代价高昂的故障和合规违规，通过在变更到达集群之前进行验证实现这一目标。Kubevious CLI 检测并防止错误（拼写错误、配置不当、冲突、不一致）和最佳实践违规。其核心优势在于能够跨多个清单进行验证，无论这些清单是已在 K8s 集群中还是尚未应用。Kubevious CLI 可用作独立工具在 YAML 清单的主动开发期间使用，也可轻松集成到 GitOps 流程和 CI/CD 管道中，以验证对实时 Kubernetes 集群的变更。Kubevious CLI 基于 https://github.com/kubevious/kubevious 项目的经验和教训创建，并使用其规则框架的演进版本。

!https://raw.githubusercontent.com/kubevious/media/master/cli/intro/demo_light.gif

✨ 核心功能

🔘 最佳实践验证

• 社区驱动的 https://github.com/kubevious/rules-library
  • 验证 K8s 原生清单和流行项目（如 CertManager、Traefik、Istio 等）的使用
• 自定义验证规则：
  • 来自文件系统
  • 来自实时 Kubernetes 集群
  • 在集群级别或命名空间内作用域
• 了解更多关于使用 https://github.com/kubevious/kubik 编写自定义验证规则的信息。

🔘 清单验证

• 验证 YAML 语法
• 验证清单 API 正确性
• 针对自定义 K8s 版本或实时 K8s 集群版本进行验证

🔘 CRD 和自定义资源

• 验证 CRD 定义
• 针对文件系统中的 CRD 验证自定义资源
• 针对实时 K8s 集群中的 CRD 验证自定义资源

🔘 验证来源

Kubevious CLI 支持从多种来源验证清单：

• 文件和目录
• 搜索模式
• Web URL
• 标准输入流（用于验证 Helm、Kustomize、Ytt 等包管理器的输出）
• 已存在于 Kubernetes 集群中的实时清单
• 以上所有来源的组合

📥 安装

👇 选项 1：(Homebrew)

sh
$ brew tap kubevious/cli
$ brew install kubevious/cli/kubevious

sh
$ kubevious guard samples/

👇 选项 2：(NPM 包)

如果已安装 Node.js v14 或更高版本：

sh
$ npm install -g kubevious

sh
$ kubevious guard samples/

👇 选项 3：(预编译二进制文件)

适用于 Linux、Alpine、Mac OS 和 Windows 的一体化可执行文件，包括 x64 和 arm64 架构。 从 https://github.com/kubevious/cli/releases 或 Google Drive 下载。

👇 选项 4：(Docker 容器中运行)

在容器中运行：

sh
$ docker run --rm kubevious/cli --help

验证整个清单目录：

sh
$ docker run --rm -v ${PWD}/samples:/src kubevious/cli guard /src

验证 Helm Chart 或管道流中的任何清单：

sh
$ helm template traefik/traefik | docker run --rm -i kubevious/cli guard --stream
$ kustomize build config/default | docker run --rm -i kubevious/cli guard --stream

🃏 使用方法和用例

亲自尝试：

sh
$ git clone https://github.com/kubevious/cli.git kubevious-cli.git
$ cd kubevious-cli.git/samples

💂 Guard - 全面的跨清单语义验证

guard 命令执行 YAML 语法和 API 正确性的检查，并检查最佳实践规则的违规情况。

🔘 验证单个 K8s 清单

会提示无法找到与标签选择器匹配的相应应用：

sh
$ kubevious guard pepsi/service.yaml

📜 [集群规则] service-selector-ref
   🌐 网页：https://raw.githubusercontent.com/kubevious/rules-library/master/k8s/service/service-selector-ref.yaml
   ❌ 规则失败
   违规：
      ❌ 命名空间：pepsi，API：v1，类型：Service，名称：emailservice
         📄 文件：pepsi/service.yaml
         🔴 无法为服务找到应用

🔘 验证多个 K8s 清单

同时传递 Deployment 和 Service 将帮助验证通过：

sh
$ kubevious guard pepsi/service.yaml pepsi/deployment.yaml

📜 [集群规则] service-selector-ref
   🌐 网页：https://raw.githubusercontent.com/kubevious/rules-library/master/k8s/service/service-selector-ref.yaml
   ✅ 规则通过
   通过：
      ✅ 命名空间：pepsi，API：v1，类型：Service，名称：emailservice
         📄 文件：pepsi/service.yaml

🔘 针对实时 K8s 集群验证清单

或者，如果依赖的 Deployment 已存在于 K8s 集群中，可针对实时集群验证 Service：

sh
$ kubevious guard pepsi/service.yaml --live-k8s

📜 [集群规则] service-selector-ref
   🌐 网页：https://raw.githubusercontent.com/kubevious/rules-library/master/k8s/service/service-selector-ref.yaml
   ✅ 规则通过
   通过：
      ✅ 命名空间：pepsi，API：v1，类型：Service，名称：emailservice
         📄 文件：pepsi/service.yaml

但如果修改 pepsi/deployment.yaml 中的 Pod 标签，即使集群中已有正确的 Deployment，也会破坏 Service 标签选择器：

yaml
spec:
  selector:
    matchLabels:
      app: emailserviceX      # 标签与 Service 标签选择器不一致
  template:
    metadata:
      labels:
        app: emailserviceX    # 标签与 Service 标签选择器不一致

sh
$ kubevious guard pepsi/service.yaml pepsi/deployment.yaml --live-k8s

📜 [集群规则] service-selector-ref
   🌐 网页：https://raw.githubusercontent.com/kubevious/rules-library/master/k8s/service/service-selector-ref.yaml
   ❌ 规则失败
   违规：
      ❌ 命名空间：pepsi，API：v1，类型：Service，名称：emailservice
         📄 文件：pepsi/service.yaml
         🔴 无法为服务找到应用

✅ Lint - YAML 语法、K8s 架构和 CRD/CR 的验证

guard 命令在底层执行 lint，因此使用 guard 的用户无需单独运行 lint。

🔘 检查 API 正确性：

sh
$ kubevious lint invalid-service-1.yaml
ℹ️  针对 Kubernetes 版本 lint：1.25.2

❌ 📄 文件：invalid-service-1.yaml
   ❌ API：v1，类型：Service，名称：db
      ❌ "/spec/ports/0" 下缺少必填属性 "port"

🔘 针对特定 K8s 版本 lint

sh
$ kubevious lint hpa.yaml --k8s-version 1.21
ℹ️  针对 Kubernetes 版本 lint：1.21.14

❌ 📄 文件：hpa.yaml
   ❌ 命名空间：ordering，API：autoscaling/v2，类型：HorizontalPodAutoscaler，名称：orderservice
      🔴 未知 API 资源。apiVersion: autoscaling/v2，kind: HorizontalPodAutoscaler。

sh
$ kubevious lint hpa.yaml --k8s-version 1.23
ℹ️  针对 Kubernetes 版本 lint：1.23.12

✅ 📄 文件：hpa.yaml
   ✅ 命名空间：ordering，API：autoscaling/v2，类型：HorizontalPodAutoscaler，名称：orderservice

🔘 忽略未知资源

sh
$ kubevious lint istio-gateway.yaml --ignore-unknown

⚠️  📄 文件：istio-gateway.yaml
   ⚠️  命名空间：hipster，API：networking.istio.io/v1alpha3，类型：Gateway，名称：frontend-gateway
      ⚠️  未知 API 资源。apiVersion: networking.istio.io/v1alpha3，kind: Gateway。

✅ Lint 成功。

🔘 针对实时 K8s 集群（含 CRD）验证

sh
$ kubevious lint istio-gateway.yaml --live-k8s
ℹ️  针对 Kubernetes 版本 lint：v1.24.0

✅ 📄 文件：data/istio-gateway.yaml
   ✅ 命名空间：hipster，API：networking.istio.io/v1alpha3，类型：Gateway，名称：frontend-gateway

🔘 验证自定义资源和对应的 CRD

sh
$ kubevious lint cr-good.yaml crd.yaml
ℹ️  针对 Kubernetes 版本 lint：1.25.2

✅ 📄 文件：cr-good.yaml
   ✅ 命名空间：coke，API：example.com/v1alpha1，类型：MyPlatform，名称：test-dotnet-app

✅ 📄 文件：crd.yaml
   ✅ API：apiextensions.k8s.io/v1，类型：CustomResourceDefinition，名称：myplatforms.example.com

🩻 排查实时集群问题

该工具可用于排查现有集群和清单问题：

sh
kubevious guard --live-k8s --include-remote-targets --namespace default

🕹 多种来源的输入

🔘 多个目录

sh
$ kubevious guard sveltos/ pepsi/

🔘 流输入

主要用于验证模板输出，如 Helm Charts、Kustomize、Carvel 等。

sh
$ helm repo add traefik https://helm.traefik.io/traefik
$ helm template traefik/traefik | kubevious guard --stream

❌ ♒ 流：stream
   ✅ 命名空间：default，API：v1，类型：Service，名称：release-name-traefik
   ✅ 命名空间：default，API：v1，类型：ServiceAccount，名称：release-name-traefik
   ✅ 命名空间：default，API：apps/v1，类型：Deployment，名称：release-name-traefik
   ❌ 命名空间：default，API：traefik.containo.us/v1alpha1，类型：IngressRoute，名称：release-name-traefik-dashboard
      🔴 未知 API 资源。apiVersion: traefik.containo.us/v1alpha1，kind: IngressRoute。
   ✅ API：networking.k8s.io/v1，类型：IngressClass，名称：release-name-traefik
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRole，名称：release-name-traefik-default
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRoleBinding，名称：release-name-traefik-default

也可传递额外清单（如 CRD、规则等）与流输入一起验证。

sh
$ helm template traefik/traefik | kubevious guard --stream https://raw.githubusercontent.com/traefik/traefik-helm-chart/master/traefik/crds/ingressroute.yaml

✅ ♒ 流：stream
   ✅ 命名空间：default，API：v1，类型：Service，名称：release-name-traefik
   ✅ 命名空间：default，API：v1，类型：ServiceAccount，名称：release-name-traefik
   ✅ 命名空间：default，API：apps/v1，类型：Deployment，名称：release-name-traefik
   ✅ 命名空间：default，API：traefik.containo.us/v1alpha1，类型：IngressRoute，名称：release-name-traefik-dashboard
   ✅ API：networking.k8s.io/v1，类型：IngressClass，名称：release-name-traefik
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRole，名称：release-name-traefik-default
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRoleBinding，名称：release-name-traefik-default

📦 在容器内运行

🔘 验证整个目录

将本地目录挂载到容器中的 /src。其余参数相同。

sh
$ docker run --rm -v ${PWD}/pepsi:/src kubevious/cli guard /src
❌ Guard 失败

🔘 验证文件

要验证单个文件，必须将目录挂载到容器中的 /src。可在命令行参数中传递文件名。

sh
$ docker run --rm -v ${PWD}/pepsi:/src kubevious/cli guard /src/service.yaml /src/deployment.yaml
✅ Guard 成功。

🔘 流输入

不要忘记 -i 参数。

sh
$ helm template traefik/traefik | docker run --rm -i kubevious/cli guard --stream

❌ ♒ 流：stream
   ✅ 命名空间：default，API：v1，类型：Service，名称：release-name-traefik
   ✅ 命名空间：default，API：v1，类型：ServiceAccount，名称：release-name-traefik
   ✅ 命名空间：default，API：apps/v1，类型：Deployment，名称：release-name-traefik
   ❌ 命名空间：default，API：traefik.containo.us/v1alpha1，类型：IngressRoute，名称：release-name-traefik-dashboard
      🔴 未知 API 资源。apiVersion: traefik.containo.us/v1alpha1，kind: IngressRoute。
   ✅ API：networking.k8s.io/v1，类型：IngressClass，名称：release-name-traefik
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRole，名称：release-name-traefik-default
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRoleBinding，名称：release-name-traefik-default

传递 CRD 作为输入可解决此问题：

sh
$ helm template traefik/traefik | docker run --rm -i kubevious/cli guard --stream https://raw.githubusercontent.com/traefik/traefik-helm-chart/master/traefik/crds/ingressroute.yaml

✅ ♒ 流：stream
   ✅ 命名空间：default，API：v1，类型：Service，名称：release-name-traefik
   ✅ 命名空间：default，API：v1，类型：ServiceAccount，名称：release-name-traefik
   ✅ 命名空间：default，API：apps/v1，类型：Deployment，名称：release-name-traefik
   ✅ 命名空间：default，API：traefik.containo.us/v1alpha1，类型：IngressRoute，名称：release-name-traefik-dashboard
   ✅ API：networking.k8s.io/v1，类型：IngressClass，名称：release-name-traefik
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRole，名称：release-name-traefik-default
   ✅ API：rbac.authorization.k8s.io/v1，类型：ClusterRoleBinding，名称：release-name-traefik-default

🪝 Git 预提交钩子

可在对 GitOps 仓库进行更改时执行 guard 和 lint 命令。Kubevious 使用 pre-commit 项目设置预提交钩子。为方便起见，提供了安装钩子的命令：

sh
$ kubevious install-git-hook guard
   ℹ️  仓库：/Users/django/example.git
   ℹ️  预提交配置文件：/Users/django/example.git/.pre-commit-config.yaml
   ℹ️  钩子仓库：https://github.com/kubevious/cli
   ℹ️  钩子 ID：kubevious-guard

✅ 安装 Git 钩子成功。
   现在可运行：
     $> cd /Users/django/example.git
     $> git add .pre-commit-config.yaml
     $> pre-commit autoupdate

或

sh
$ kubevious install-git-hook lint

✍️ 编写自定义规则

Kubevious 规则使用名为 https://github.com/kubevious/kubik 的领域特定语言表达。开始