nvkectl get 命令详解:查询 NVKE 管理平面上的集群、节点池、发布版本与 kubeconfig
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)
}
}
由此可以确认几个实用细节:
- 默认空串即 table,不是
-o table;传入table会被拒绝,错误信息为unknown output format "table": must be json or yaml。 json使用两空格缩进(enc.SetIndent("", " ")),适合直接喂给jq或写入文件。yaml的实现是 先 Marshal 成 JSON 再转 YAML,目的是让生成的 API 类型(只有json:tag)保持预期的字段名,而不是退化成 Go 字段名的小写形式(printer.go)。这对「把查出来的对象改个名字再create」的场景至关重要。- 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 时最容易踩坑的三处。