使用 nomos 命令

nomos 命令(Windows 上的 nomos.exe)是一个可选的命令行工具,您可以在工作站或笔记本电脑等本地系统中安装该工具。您可以使用 nomos 命令与 Config Management Operator 进行交互,在将 config 提交到代码库之前检查其语法,以及排查 Anthos Config Management、您的集群或代码库的问题。

前提条件

在使用 nomos 命令与集群进行交互之前,Operator 必须已安装在目标集群上,并且 kubectl 命令必须配置为向目标集群进行身份验证。如需了解详情,请参阅安装 Anthos Config Management

安装 nomos 命令

nomos 命令是通过 Go 代码编译的二进制文件。该命令是可选的,不包含在默认的 Anthos Config Management 安装中。

要为每个版本的 Anthos Config Management 下载 nomos 命令,请参阅下载

注意:Anthos Config Management 需要有效的 Anthos 授权。否则,下载将失败并显示 404 File not found 错误。
如需了解详情,请参阅 Anthos 的价格

针对 macOS 和 Linux 客户端的额外步骤

下载二进制文件后,请将其配置为可执行文件:

chmod +x /path/to/nomos

您可以将此命令移动到系统搜索二进制文件的位置(例如 /usr/local/bin),也可以使用其完全限定的路径运行此命令。

基本用法

nomosnomos.exe 命令包含子命令,可用于初始化代码库检查语法错误、获取每个注册集群的状态,以及以一系列 CustomResourceDefinition 的形式查看代码库

对于基本命令语法,请使用 --help 参数:

nomos --help

nomos 命令用于从您的代码库的本地克隆读取内容。使用 --path 标志可以指定代码库的顶层位置。默认情况下,--path 设置为 .(当前目录)。

nomos --path=path/to/your/repo status

检查安装状态

您可以使用 nomos status 命令检查所有集群上是否已正确安装并配置了 Anthos Config Management。该命令会报告任何阻止 Anthos Config Management 运行的错误。例如:

nomos status
my_managed_cluster-1
  --------------------
  NOT INSTALLED

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR
  Error:   git-creds not found. Create git-creds secret in config-management-system namespace.

my_managed_cluster-3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

在此输出中,managed-cluster-1 上未安装 Anthos Config Management。在 managed-cluster-2 上,Config Sync 已安装,但没有进行正确配置。在 managed-cluster-3 上,Config Sync 已安装并正常运行。

此外,未正确配置 managed-cluster-2 的原因是 git-creds Secret 不存在。

初始化新代码库

要初始化新的 Anthos Config Management 代码库,请创建一个空目录,切换至该目录,初始化一个新的 Git 代码库,然后运行 nomos init 命令:

mkdir my-repo
cd my-repo
git init
nomos init

这样将创建代码库的基本目录结构,包括 system/cluster/namespaces/ 目录。

检查代码库中的错误

在将配置提交到代码库之前,请使用 nomos vet 命令检查代码库中配置的语法和有效性:

nomos vet

如果发现语法错误,nomos vet 命令会以非零状态退出,并将错误消息记录到 STDERR

如果 nomos vet 无法确定类型是否带命名空间,则 nomos 将连接到 API 服务器。因为 nomos 了解核心的 Kubernetes 类型和 Anthos Config Management CRD,所以只有在存在没有相应声明的 CRD 的 CR 时,它才会尝试连接到 API 服务器。在这种情况下,如果 API 服务器未应用 CRD,则 nomos vet 会返回错误。如需停用这项检查并抑制由于缺少 CRD 而导致的错误,请传递 --no-api-server-check 标志。

提交时自动检查是否存在语法错误

如果您提交的文件包含 JSON 或 YAML 错误,Anthos Config Management 不会应用相应的更改。但是,您可以使用客户端服务器端钩子来防止这些类型的错误被提交到代码库中。

在 Git 预提交钩子中使用 nomos vet

您可以配置运行 nomos vet 的预提交钩子,以在您向代码库的本地 Git 克隆提交更改时检查是否存在语法错误。如果预提交钩子以非零状态退出,则表示 git commit 操作失败。

如需将 nomos vet 命令作为预提交钩子运行,请修改代码库中的 .git/hooks/pre-commit 文件(注意 .git. 字符开头)。您可能需要手动创建该文件。将 nomos vet 命令添加到脚本中的新行。--path 参数是可选的。

nomos vet --path=/path/to/repo

确保 pre-commit 文件可执行:

chmod +x .git/hooks/pre-commit

现在,当您在代码库的克隆中运行 git commit 命令时,nomos vet 会自动运行。

代码库本身不会跟踪其 .git/ 目录的内容,并且您不能将这些内容提交到代码库中的同一位置。您可在代码库中为 Git 钩子创建目录,使用该代码库的人员可以将钩子复制到其本地克隆中的相应位置。

在服务器端钩子中使用 nomos vet

Git 提供了一种执行 git push 操作期间在服务器(而不是客户端)上运行检查的机制。如果检查失败,git push 也会失败。客户端无法绕过这些服务器端钩子。配置服务器端钩子的方法取决于您的 Git 服务器的托管方式。如需了解详情,请访问以下某个链接,或查看 Git 托管服务的文档。

查看代码库中所有配置的结果

您可以使用 nomos hydrate 命令查看每个注册集群上代码库的组合内容。

如果您在没有使用选项的情况下运行 nomos hydrate,则该命令会在当前工作目录中创建一个 compiled/ 目录。在该目录中,系统会为每个注册集群创建一个子目录,该子目录包含 Operator 将应用到集群的完全解析的配置。

您可以通过提供目录路径作为命令的参数来指定输出目录的名称:

nomos hydrate [/path/to/directory]

如需将输出限定到单个集群或一组集群,请使用 --clusters 标志并提供以英文逗号分隔的集群名称列表。

如需模拟 nomos view 的行为并将有效配置保存到单个文件,请使用 --flat 标志。

如需了解详情,请使用 --help 标志:

nomos hydrate --flat

nomos view

当 Anthos Config Management 从代码库导入配置时,会将这些配置转换为 ClusterConfigNamespaceConfig 类型的 CustomResourceDefinition (CRD)。借助 nomos view 命令,您能够以 JSON 格式查看根据代码库的当前状态生成的 CRD。在提交更改之前,或者使用 nomos vet 命令排查不明显的配置问题时,这种方式很实用。

nomos view --path=/path/to/your/repo

检查集群中的错误

每当您将 Git 提交推送到代码库时,Operator 都会检测到更改并将新配置应用到所有注册集群。您可以使用 nomos status 命令监控所有注册集群上的 Anthos Config Management 状态。对于每个集群,该命令会报告上次应用到该集群的 Git 提交的哈希值,以及尝试应用最近的任何更改时发生的任何错误。例如:

nomos status
my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  PENDING  9edf8444

my_managed_cluster-3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.

my_managed_cluster-4
  --------------------
  NOT INSTALLED

my_managed_cluster-5
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

您可以看到,两个集群已同步最近的更改,一个集群仍在同步,一个集群出现了错误(该错误导致系统无法应用更改)。在此示例中,managed-cluster-3 似乎缺少其他集群已安装的 CRD。

默认情况下,nomos status 命令将输出每个集群的状态,然后退出。不过,您可以使用 poll 标志持续运行该命令,并让该命令定期重新输出状态表。

nomos status --poll 2s

检查集群(多代码库)中的错误

如果您为集群启用了多代码库选项,则可以从多个 Git 代码库进行同步。nomos status 命令将输出每个代码库的状态(按集群分组)。例如:

nomos status
my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

您可以看到每个集群都配置了两个 Git 代码库。<root> 代码库属于集群管理员,而 bookstore 代码库可能属于应用开发团队。

默认情况下,nomos status 命令将输出集群上所有代码库的状态。但是,您可以使用 namespace 标志将该命令限制为输出特定命名空间代码库的状态。这使得应用团队可以对其代码库使用 nomos status

nomos status --namespace bookstore

关于上次同步的令牌

nomos status 会在其输出的 Last Synced Token 下显示已应用于集群的最新 Git 提交哈希值。如需获取此值,请查询 Repo 对象并查看 status.sync 字段:

kubectl get repos.configmanagement.gke.io -o yaml
apiVersion: v1
kind: Repo
items:
- status:
    sync:
      lastUpdate: "2019-09-26T10:17:57Z"
      latestToken: f1739af550912034139aca51e382dc50c4036ae0

此提交表示针对集群的最近提交。但是,每次提交并不会影响集群中的所有命名空间;如需查看特定命名空间中的最新提交,请查询特定 NamespaceConfig 对象并查看 status 字段。例如:

kubectl get namespaceconfigs.configmanagement.gke.io my-namespace -o yaml
apiVersion: configmanagement.gke.io/v1
kind: NamespaceConfig
status:
  syncState: synced
      lastUpdate: "2019-09-26T08:24:32Z"
      latestToken: 1850bad9419d3baec8af220c15d5e952dbeb3b25

即使某命名空间可能会受到提交的影响,也并非该命名空间中的所有资源都可能受到影响。如需查找特定资源的最近同步的提交,请查询该特定资源并查看 metadata.annotations.configmanagement.gke.io/token。例如:

kubectl get clusterrolebindings.rbac.authorization.k8s.io my-role-binding -o yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/token: e56b09554ca8004a2c38185a4ed11364fd6986c4

创建错误报告

如果 Anthos Config Management 遇到问题,需要 Google Cloud 支持的帮助,则可以使用 nomos bugreport 命令向他们提供有价值的调试信息。

nomos bugreport

此命令会生成一个带有时间戳的 ZIP 文件,其中包含有关在 kubectl 上下文中设置的 Kubernetes 集群的信息。

该文件包含来自 Anthos Config Management Pod 的日志。它不包含来自与 Anthos Config Management 同步的资源的信息。

问题排查

在 Linux 上执行 nomos 命令时,您可能会看到以下错误:

failed to create client configs: while getting config path: failed to get current user: user: Current not implemented on linux/amd64

请创建 USER 环境变量来解决此问题:

export USER=$(whoami)

后续步骤