nvkectl get 命令详解:查询 NVKE 管理平面上的集群、节点池、发布版本与 kubeconfig

原创2026-11-09 18:49:561,624 阅读
文章标签:云原生容器编排集群管理微服务运维身份认证

nvkectl get 命令详解:查询 NVKE 管理平面上的集群、节点池、发布版本与 kubeconfig

nvkectl get 是 NVKE 控制平面 CLI 中唯一的只读查询入口:它把「租户集群」「节点池」这两类走控制器 API 的资源,与「机器镜像」「集群发布」「节点池发布」「基础设施 provider」以及「管理集群 Secret」这些直接读 Kubernetes 的对象,统一收敛到同一套命令行风格下。本文以命令参考页 nvkectl_get.md 为主干,结合 cli/internal/nvkectl 下的命令树实现与各子命令源码,逐项说明每个子命令的可用参数、表格列的确切含义、状态判定规则、退出行为以及在真实运维流程中的用法。

命令的定位与文档来源

参考页开头就明确说明它是生成文件:内容来自 cli/internal/nvkectl 中的 cobra 命令树,修改 Short/Long/Example/Args/Aliases/标志用法字符串后需要执行 make -C cli docs 重新生成,make -C cli docs-check 会在提交页与命令树不一致时失败。这一点不只是工程细节——它意味着参考页与二进制行为在构造上是同源的:

func newGetCmd() *cobra.Command {
	cmd := &cobra.Command{
		Use:   "get",
		Short: "Display one or more resources",
	}
	cmd.AddCommand(clusters.NewGetCmd(loadClient))
	cmd.AddCommand(nodepools.NewGetCmd(loadClient))
	cmd.AddCommand(operatorcmd.NewGetCmds(loadOperator)...)
	cmd.AddCommand(providercmd.NewGetCmd(loadSite, controllerdeploy.ExecCommandRunner{}, credentials.NewDynamicLister))
	cmd.AddCommand(mgmtcommand.NewGetKubeconfigCmd(loadSite, newMgmtClient))
	cmd.AddCommand(newGetBootstrapManifestCmd())
	return cmd
}

见 get.go。这段代码同时揭示了 get 的两类后端:

  • 控制器 API 客户端(loadClient):clusters、nodepools;
  • 管理集群/动态客户端(loadSite、loadOperator):providers、kubeconfig、machineimages、clusterreleases、nodepoolreleases;
  • 纯本地(无需 site):bootstrap-manifest,直接读取编译进二进制的清单,源码注释直言 "it reads the embedded manifest and needs no site"。

命令树在构建时不读取任何配置、不连接任何集群(root.go),因此即使机器上没有任何已配置的 site,nvkectl get --help 与 nvkectl get bootstrap-manifest 依然可用;其余子命令在使用到客户端时才解析 site 配置。

子命令总览

参考页的 SEE ALSO 列出了 7 个子命令,其能力边界如下表(表内容直接来自各参考页与源码注册关系):

子命令 别名 数据来源 用途
nvkectl get bootstrap-manifest 无 二进制内嵌清单 打印 bootstrap 会拉取的 chart 与镜像,含版本与 digest
nvkectl get clusters cluster 控制器 API 列出租户集群
nvkectl get nodepools nodepool 控制器 API 列出节点池,可按集群过滤
nvkectl get providers provider 管理集群 + kubectl(Alpha) 列出基础设施 provider 及其状态与凭据健康
nvkectl get kubeconfig 无 管理集群 Secret 取出某个租户集群的 admin kubeconfig
nvkectl get clusterreleases clusterrelease 管理集群动态客户端 列出已发布的控制平面版本
nvkectl get machineimages machineimage 管理集群动态客户端 列出机器镜像
nvkectl get nodepoolreleases nodepoolrelease 管理集群动态客户端 列出已发布的工作节点版本

可以对照上级页面 nvkectl.md 了解 get 在 bootstrap、create、patch、delete、deprecate、validate、generate、config、version 之间的位置。

标志体系:显式选项与继承选项

get 自身只暴露帮助标志:

  -h, --help   help for get

真正决定「查哪个站点」「日志长什么样」的是从根命令继承的持久化标志:

      --json-logs     Emit logs as JSON
      --site string   Override the active site for this invocation
  -v, --verbose       Enable debug logging

它们在 root.go 中注册,因此对每一个 get 子命令都生效:

  • --site <name>:仅覆盖本次调用使用的 site,不会改写配置文件。解析逻辑见 resolveSiteConfig(root.go):为空时取 current-site,否则在 sites 映射中查找,找不到报 site %q not found in config。这让「同时管理多个 Tier0 站点、临时看一眼另一个站点」成为一条命令的事。
  • -v, --verbose:把 slog 级别从 Info 降到 Debug。
  • --json-logs:切换为 JSON handler,并对时间属性统一输出 UTC;两类 handler 都会经过 redact.ReplaceAttr 做脱敏处理(root.go)。

需要特别注意一个与其他命令不同的行为:get 被列入 queryCommands(root.go),因此成功时不打印 Trace ID: 行,只在 Debug 日志里记录;而一旦失败,trace ID 会被追加到错误末尾,便于对照后端日志排障。

输出格式:-o json | yaml | table

除 bootstrap-manifest 与 kubeconfig 外,所有子命令都提供:

  -o, --output string   Output format: json or yaml (default: table)

格式校验集中在 printer.go:

func ParseFormat(s string) (Format, error) {
	switch Format(s) {
	case FormatTable, FormatJSON, FormatYAML:
		return Format(s), nil
	default:
		return FormatTable, fmt.Errorf("unknown output format %q: must be json or yaml", s)
	}
}

由此可以确认几个实用细节:

  1. 默认空串即 table,不是 -o table;传入 table 会被拒绝,错误信息为 unknown output format "table": must be json or yaml。
  2. json 使用两空格缩进(enc.SetIndent("", " ")),适合直接喂给 jq 或写入文件。
  3. yaml 的实现是 先 Marshal 成 JSON 再转 YAML,目的是让生成的 API 类型(只有 json: tag)保持预期的字段名,而不是退化成 Go 字段名的小写形式(printer.go)。这对「把查出来的对象改个名字再 create」的场景至关重要。
  4. table 分支不是 Print 的责任,各子命令自行用 text/tabwriter 渲染,因此不同子命令的列集合不同。

nvkectl get clusters:租户集群列表

参考页 nvkectl_get_clusters.md 给出的用法是 nvkectl get clusters [name ...],Args 为 cobra.ArbitraryArgs,别名 cluster。

# 列出全部集群
nvkectl get clusters

# 只列两个集群,并按给定顺序输出为 YAML
nvkectl get clusters prod staging -o yaml

「按给定顺序」不是文案修饰,而是实现事实:带名字时,命令行会对每个名字单独发起一次列表请求(用 ListClustersParams{Name: &name} 过滤),再把结果按参数顺序追加(get.go):

for _, name := range names {
	found, err := client.ListClusters(cmd.Context(), &api.ListClustersParams{Name: &name})
	...
	if len(found) == 0 {
		missing = append(missing, name)
		continue
	}
	cls = append(cls, found...)
}

这带来两个可观测行为:

  • 部分命中仍然输出:有效集群会正常打印,未命中的名字被收集到 missing,最后通过 notFoundError 以 cluster "x" not found(多个时为 clusters "x", "y" not found)返回非零退出码。也就是说「先看到能看到的,再拿到失败信号」。
  • N 个名字是 N 次请求,不带名字时只有 1 次(ListClusters(ctx, nil))。

默认表格的列由 printClusters 固定(get.go):

NAME   KUBERNETES VERSION   CNI   STATUS   ID   AGE

各列取值:ControlPlaneKubernetesVersion、CniPlugin、由 clusterstate.Status 派生的状态、ID(添加节点池时需要的 clusterID)、以及 util.FormatAge(CreatedAt)。Age 采用 kubectl 风格的分桶格式——s/m/h/d,负值归零(printer.go)。

STATUS 列的优先级规则

集群状态不是简单三元组,而是按「破坏性/终态优先」依次判定(clusterstate.go):

顺序 条件 显示
1 Deleting 为 True Deleting
2 UpdateFailed 为 True UpdateFailed
3 UpdateInProgress 非空 Updating
4 ControlPlaneUpgrading 为 True Upgrading
5 CpNodesRecycling 为 True Recycling
6 Provisioning 为 True Provisioning
7 Provisioned 为 True Provisioned
8 Provisioning=False 且 Provisioned=False ProvisioningFailed
9 其他 Unknown

该函数的包注释值得引用:这份判断被 nvkectl get clusters 与 nvkectl bootstrap site 共享,"the two must not be able to disagree about what a cluster is doing"。因此你用 get clusters 看到 Provisioned,bootstrap 的等待逻辑也必然认为它已完成。

nvkectl get nodepools:节点池与 --cluster 过滤

节点池子命令多了一个过滤器(nvkectl_get_nodepools.md):

  -c, --cluster string   Filter output to node pools of the named cluster
  -h, --help             help for nodepools
  -o, --output string    Output format: json or yaml (default: table)
nvkectl get nodepools --cluster my-cluster
nvkectl get nodepools control-plane gpu-workers --cluster my-cluster
nvkectl get nodepools gpu-workers --cluster my-cluster -o yaml

为什么要 --cluster?参考页说得很直接:节点池名字在集群内唯一,单独的池名可能同时命中每个集群的同名池。源码中两个过滤条件都由控制器侧处理,而不是本地筛选(get.go 与 get.go):params.ClusterName 与 query.Name 一起传给 ListNodePools。因此 --cluster + 名字是「精确到某个集群的某个池」的唯一可靠写法。

实现里还有一处体贴的设计:指定了 --cluster 时,命令会先 FindClusterByName 做一次存在性校验(get.go),这样集群名打错时报的是「集群不存在」,而不是含糊的「池不存在」。反之,如果因为过滤器选不到池,错误信息会带上集群限定:

node pool "gpu-workers" not found in cluster "my-cluster"

(见 notFoundError,get.go。)

表格列:

NAME   CLUSTER   DESIRED   K8S VERSION   CP   STATUS   ID

CLUSTER 列需要把 ClusterID(UUID)映射成名字,代价是额外一次 ListClusters;源码明确说明「已给 --cluster 或无池时不需要这次调用」。当某个池的集群不在映射表里,该列退化为打印 UUID,不会留空。另外注意这里没有 AGE 列,原因写在注释里:api.NodePool 不携带创建时间戳。

CP 列直接渲染 p.ControlPlane 布尔值(true/false),DESIRED 是 DesiredNodeCount。STATUS 的判定比集群简单,且删除优先(get.go):Deleting → Provisioning → Provisioned → Unknown。

nvkectl get providers:provider 状态与凭据健康

这是 get 下语义最丰富、也唯一被明确标注 Alpha(输出可能随版本变化) 的子命令。参考页 nvkectl_get_providers.md 说明它绕过控制器 API,直接读站点的 Kubernetes 集群,因此需要 nvkectl config set-site --kubeconfig 注册过的 kubeconfig,以及 PATH 上的 kubectl。

  -h, --help            help for providers
  -o, --output string   Output format: json or yaml (default: table)

表格列(get.go):

PROVIDER   STATE   REPLICAS   CREDENTIALS   LAST CHECK   DETAIL
  • REPLICAS 形如 2/2;当期望与实际都为 0(没找到 manager)时显示 -(replicas())。
  • LAST CHECK 来自 provider 自己最近一次凭据检查的时间,无可用时间或出现「UNKNOWN 且时间在未来」的异常时显示 -(lastCheck())。
  • DETAIL 优先展示 STATE 的问题描述,其次才是凭据描述(detail())。

两列状态不要混淆

参考页用两大段文字区分了两件事,这是使用该命令时最容易误读的地方:

CONFIGURED 只代表三件事同时成立:provider 的 CRD 已 established、manager 可用、凭据 Secret 存在。文档特别强调——它不代表凭据能用。

CREDENTIALS 才是「凭据能不能用」,且它不是 nvkectl 现场执行的检查,而是读取 NicoIdentity 中记录的 provider 自检结果。nvkectl 从不发起检查:provider 每隔几分钟自行检查,LAST CHECK 只是「距上次检查多久」。取值语义如下:

取值 含义
HEALTHY 上一次检查成功认证并读取了当前租户
FAILING (reason) 凭据缺失、无效、被拒绝或被禁止
UNKNOWN (reason) 检查无法判定,例如后端中断期间
STALE 该检查时没有检查;若 provider 未发布可用调度,则上次检查(或创建时间)过旧
PENDING 尚未检查
NO-IDENTITY 没有任何 NicoIdentity 指向该 provider 的凭据 Secret
UNSUPPORTED provider 不提供 NicoIdentity
UNREADABLE nvkectl 无法列出 NicoIdentity
- 该 provider 没有可报告的凭据健康信息

实践结论:寻找 CONFIGURED 且 HEALTHY 的组合。但文档同时声明两条边界——HEALTHY 不保证后续 provisioning 一定成功;列出的 provider 集合只是「nvkectl 知道如何描述」的集合,不是限制,控制器接受任何手写的基础设施清单。所以你看不到某个 provider,不等于不能用它。

nvkectl get kubeconfig:取出租户集群的 admin kubeconfig

参考页 nvkectl_get_kubeconfig.md 描述了完整的数据来源与回退策略,这是 get 下唯一强制单参数的子命令(cobra.ExactArgs(1))。

  -h, --help                 help for kubeconfig
      --namespace string     Management namespace holding the kubeconfig Secret (default: nvke-system, then nke-system)
      --output-file string   Write kubeconfig to file instead of stdout
nvkectl get kubeconfig my-cluster
nvkectl get kubeconfig my-cluster --output-file ~/.kube/my-cluster.yaml
nvkectl get kubeconfig my-cluster --site prod
nvkectl get kubeconfig my-cluster --namespace nke-system

它读取的是 tenantaccess 控制器发布到管理集群的 Secret:

<namespace>/<cluster-name>-admin-kubeconfig   (key: value)

命名空间默认先试 nvke-system,再回退 nke-system(DefaultSecretsNamespace / LegacySecretsNamespace,client.go)。回退存在的理由写在常量注释里:在 nvkeSystemNamespace.name 出现之前安装的站点仍沿用旧名,且可能永久保持;读取方不应要求运维者先记住站点装在哪一代命名空间上。

回退与错误优先级的实现细节值得了解(client.go):

  • 多个命名空间按顺序尝试,某个命名空间 NotFound 不算终止性错误,会继续尝试下一个;
  • Forbidden 优先于 NotFound:注释解释了原因——「Secret 不在那里」只有在我们被允许查看的命名空间里才成立,报 NotFound 会让运维者去怀疑一个可能完全正确的集群名;
  • 拿到的 Secret 若缺少 value 键或内容为空,返回 admin kubeconfig secret <ns>/<name> has no "value" key;
  • 所有候选都失败时,若有 Forbidden 则报 Forbidden,否则报最后一个 NotFound,并提示「检查集群名,或集群尚未完成 provision」。

--output-file 的写入不是普通的 os.WriteFile:util.WritePrivateFile 会先在目标目录创建临时文件、chmod 0600、写入、关闭,再 rename 覆盖目标(file.go)。注释说明了两个安全动机——不把已存在的 0644 文件留在全局可读状态,且符号链接会被替换而不是跟随。写入成功后 stdout 只输出一行 kubeconfig written to <path>;不指定文件时,kubeconfig 原文直接写到 stdout,便于管道重定向。

注意 --namespace 只在显式给出时生效,并且此时只试该命名空间(源码中 namespaces = []string{namespace}),回退链被关闭。

nvkectl get bootstrap-manifest:不依赖任何站点的可复现清单

参考页 nvkectl_get_bootstrap-manifest.md 的全部约束集中在「列了什么、没列什么」上:

  • 列出:nvkectl bootstrap site 用 Helm 拉取并安装的 chart,以及 bootstrap 运行的镜像;chart 按清单里的版本安装;digest 是给镜像搬运(mirroring)留的记录,bootstrap 不校验 digest;
  • 不列出:控制器 chart、Postgres chart、provisioned provider 的清单(这些打包在 nvkectl 内部);clusterctl init 安装的组件;kindest/node 镜像。

实现上它极简:Args: cobra.NoArgs,RunE 直接把 manifest.Bytes() 写到 stdout(get.go)。因为不解析 site,它可以用来在没有 kubeconfig 的构建机上核对「这个版本的 nvkectl 会拉哪些东西」,配合内部镜像仓库做离线搬运。

三个 release/image 子命令:共享一套实现

clusterreleases、machineimages、nodepoolreleases 由同一个工厂按 kindInfo 表生成(command.go、get.go),因此行为高度一致:

nvkectl get machineimages
nvkectl get machineimages <name> -o yaml
nvkectl get clusterreleases <name> -o yaml
nvkectl get nodepoolreleases

三者的 Long 文本只有名词不同(见 nvkectl_get_machineimages.md、nvkectl_get_clusterreleases.md、nvkectl_get_nodepoolreleases.md),核心语义是:

用 -o json/-o yaml 时,一个名字输出单个对象,其 metadata+spec 形状正是 nvkectl create <kind> 接受的形状,因此可以改一改再以新名字创建;不带名字或带多个名字时,输出这些对象的列表。

这与 kubectl 的直觉一致,但在实现上是显式分支(get.go):

if len(args) == 1 {
	if len(items) == 0 {
		return notFoundError(k, missing)
	}
	return util.Print(cmd.OutOrStdout(), format, items[0])
}

为什么这个形状很重要?因为发布内容不可变。operator 包的接口注释写明:ErrAlreadyExists 的语义是「同名资源已存在,而发布内容是 immutable,所以变更必须以新名字发布」(operator.go)。于是「get ... -o yaml → 改 metadata.name → create」成为升级/换版的常规路径,而不是 patch。

Resource 类型也解释了为什么输出里没有 namespace、uid、resourceVersion 这些字段(operator.go):Metadata 只保留 name 与 annotations,Kubernetes 传输字段被显式排除;CreatedAt 标记为 json:"-",只用于渲染 AGE,不进入可移植文档。这是「运维者写下的东西不依赖资源如何被存储」的设计。

表格列按 kind 分叉(get.go):

kind 列
MachineImage NAME OS VERSION ARCH VARIANT BUILT AGE
ClusterRelease / NodePoolRelease NAME IMAGE DEPRECATED AGE

MachineImage 的 OS 列取 spec.operatingSystem.family,VERSION 取 spec.operatingSystem.version,其余取 spec.architecture、spec.variant、spec.buildDate;release 的 IMAGE 取 spec.machineImageRef.name,DEPRECATED 取 spec.lifecycle.deprecated 布尔值。字段缺失时对应单元格为空字符串而不是报错(specString 忽略错误)。

列表的排序也有保证:Client.List 的契约是「按名字排序返回」(operator.go),所以表格输出是稳定的,适合做 diff。

退出码、错误与「部分成功」

get 的错误处理遵循一条统一约定:先把能展示的展示出来,再返回未命中错误。三个实现分支(clusters、nodepools、operator kinds)都是先 Print/printXxx,最后 return notFoundError(...)。源码中把这一点写成了注释:"Like kubectl: one name is one object"。

对应的错误文案:

  • cluster "prod" not found / clusters "prod", "staging" not found(get.go)
  • node pool "x" not found 或 node pool "x" not found in cluster "y"(get.go)
  • machine image "x" not found 或 machine images not found: a, b(command.go)

由于根命令设置了 SilenceErrors 与 SilenceUsage(root.go),错误只打印一次,并且由 main 统一映射到退出码;失败时错误文本会附带 Trace ID:。

前置条件与站点配置

不同子命令对环境的依赖并不相同,按需准备即可:

需求 适用子命令 说明
已配置 site(current-site 或 --site) clusters、nodepools、providers、kubeconfig、三个 release/image 子命令 否则报 no site configured: run 'nvkectl config set-site' first
控制器 API URL + 认证 clusters、nodepools 由 clients.New(siteCfg) 构建
管理集群 kubeconfig(site.kubeconfig) providers、kubeconfig、release/image mgmtcluster.RESTConfig 对空路径直接报错,且不会回退到 KUBECONFIG 或 ~/.kube/config
kubectl 在 PATH 上 providers 参考页明确要求
无任何依赖 bootstrap-manifest 仅读内嵌清单

站点注册方式(摘自 user-flow.md 第 6 步):

nvkectl config set-site --name my-tier0-site \
  --url http://<VIP>:30080 \
  --kubeconfig ./my-tier0-site.kubeconfig
nvkectl config view

配置文件位置由 XDG_CONFIG_HOME 决定,默认 ~/.config/nvkectl/config.yaml,写入时目录 0700、文件 0600(config.go、config.go)。若当前路径尚无配置文件,会尝试读取二进制旧名 nkectl 的同级目录并一次性迁移过来(config.go)。这两个细节解释了为什么「升级 CLI 后 site 配置还在」。

需要提醒的是 SiteConfig 的字段语义:URL 是控制器 API,Kubeconfig 是管理集群。get providers 和 get kubeconfig 只用后者,get clusters/get nodepools 用前者并通过该 kubeconfig 换取 token(见 config.go 与 user-flow 中的认证说明)。proxy-client-cert/proxy-client-key 则用于需要 TLS 客户端证书的代理场景。

一条完整的排障链路

把上述子命令串起来,可以形成一条从「站点是否可用」到「拿到 kubeconfig」的标准检查顺序。以下命令均来自参考页示例的组合,不引入未文档化的用法:

# 1) 这个 nvkectl 会拉什么(无需 site)
nvkectl get bootstrap-manifest

# 2) 站点基础设施 provider 是否就绪、凭据是否健康
nvkectl get providers

# 3) 已发布哪些可用版本(升级前比对)
nvkectl get clusterreleases -o yaml
nvkectl get machineimages
nvkectl get nodepoolreleases --site prod

# 4) 租户集群现状
nvkectl get clusters
nvkectl get clusters my-cluster -o yaml

# 5) 该集群的节点池(集群名唯一确定范围)
nvkectl get nodepools --cluster my-cluster

# 6) 取 admin kubeconfig 落地
nvkectl get kubeconfig my-cluster --output-file ~/.kube/my-cluster.yaml

解读要点:

  • 第 2 步若出现 CONFIGURED 但 CREDENTIALS 为 FAILING/STALE/NO-IDENTITY,问题在 provider 侧凭据或其自检调度,不在集群创建流程;
  • 第 4 步 STATUS 停在 ProvisioningFailed 意味着控制器把 Provisioning 置为 False 而从未置 Provisioned(clusterstate.go),此时 get kubeconfig 很可能返回 ... not found -- check the cluster name, or the cluster may not be provisioned yet;
  • 第 5 步若报 not found in cluster "...",先确认 --cluster 拼写;节点池名跨集群重名是常态;
  • 第 6 步若报 not allowed to read secret ...,按错误提示给站点 kubeconfig 的身份补 get 权限——实现刻意让 Forbidden 优先于 NotFound,正是为了避免你误删一个名字正确的集群。

修改参考页的正确方式

最后回到文档本身。由于 nvkectl_get.md 及其子页都是生成物,直接编辑会被下一次生成覆盖,make -C cli docs-check 也会失败。要改变 get 的行为描述,应修改对应命令的元数据(Short/Long/Example/Args/Aliases/弃用说明/标志用法字符串),例如 get 的 Short 在 get.go,clusters 的 Long 与示例在 get.go,providers 的状态语义文字在 get.go。改完后重新执行 make -C cli docs,让参考页与二进制再次同源。

理解这一点,也就能理解为什么这篇参考页虽然只有一屏文字,却足以支撑一整套查询语义:它的每条描述都能在 cli/internal 的实现里找到对应分支,而 -o yaml 的输出形状、--cluster 的唯一性约束、CONFIGURED 与 HEALTHY 的区别,恰恰是日常使用 nvkectl get 时最容易踩坑的三处。

登录后查看全文
nvke