codenotary/kube-notary

kube-notary

用于通过CodeNotary验证镜像信任的Kubernetes监控工具

!https://raw.githubusercontent.com/v***us/kube-notary/master/docs/images/info.png

工作原理

kube-notary 是一款通过 CodeNotary 实现 持续验证 (CV) 的监控工具。持续验证的核心思想是在运行时持续监控集群，当发现未知或不受信任的容器镜像运行时发出通知。

在集群中安装 kube-notary 后，系统将每分钟检查所有Pod（检查间隔及其他设置可通过配置调整）。对于每个Pod中的每个运行容器，kube-notary 会将容器镜像的 ImageID 解析为实际镜像哈希，并最终在CodeNotary***中查询https://github.com/v***us/vcn/blob/master/docs/user-guide/signatures.md#signatures%E3%80%82

此外，kube-notary提供内置导出器，可将验证指标发送至Prometheus，并通过提供的Grafana仪表板实现可视化。

可使用CodeNotary https://github.com/v***us/vcn CLI工具对信任的镜像进行签名。

[***]

安装

kube-notary 通过Helm图表安装。

集群需安装Kubernetes 1.9及以上版本，以及Helm 2.8及以上版本。

首先，确保本地配置指向目标集群上下文（检查 kubectl config current-context）。然后执行以下步骤安装 kube-notary：

• 克隆仓库到本地：https://github.com/v***us/kube-notary
• 进入 kube-notary 目录
• 执行安装命令：

Helm v2

helm install -n kube-notary helm/kube-notary

Helm v3

helm install kube-notary helm/kube-notary -n kube-notary

详细安装说明参见配置部分。

命名空间级安装

若没有集群级访问权限，可在单个命名空间内安装 kube-notary：

helm install -n kube-notary helm/kube-notary --set watch.namespace="default"

此配置下，系统会创建命名空间级 Role 而非默认的 ClusterRole，以适应Kubernetes RBAC 单命名空间权限控制。kube-notary 仅获取并监控配置的命名空间。

手动安装（不使用Helm）

也可不使用Helm手动安装 kube-notary。手动安装的说明和模板位于 kubernetes文件夹。

卸载

可随时使用以下命令卸载 kube-notary：

helm delete --purge kube-notary

使用

kube-notary 提供详细日志输出和Prometheus指标端点，用于监控运行中容器的验证状态。安装后将提供访问这些功能的说明。

示例：

  # 指标端点
  export SERVICE_NAME=service/$(kubectl get service --namespace default -l "app.kubernetes.io/name=kube-notary,app.kubernetes.io/instance=kube-notary" -o jsonpath="{.items[0].metadata.name}")
  echo "指标端点地址：http://127.0.0.1:9581/metrics"
  kubectl port-forward --namespace default $SERVICE_NAME 9581

  # 结果端点
  export SERVICE_NAME=service/$(kubectl get service --namespace default -l "app.kubernetes.io/name=kube-notary,app.kubernetes.io/instance=kube-notary" -o jsonpath="{.items[0].metadata.name}")
  echo "验证结果端点地址：http://127.0.0.1:9581/results"
  kubectl port-forward --namespace default $SERVICE_NAME 9581

  # 流式日志
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=kube-notary,app.kubernetes.io/instance=kube-notary" -o jsonpath="{.items[0].metadata.name}")
  kubectl logs --namespace default -f $POD_NAME

  # 批量签名所有运行中镜像
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=kube-notary,app.kubernetes.io/instance=kube-notary" -o jsonpath="{.items[0].metadata.name}")
  kubectl exec --namespace default -t $POD_NAME sh /bin/bulk_sign > vcn_bulk_sign.sh
  chmod +x vcn_bulk_sign.sh && ./vcn_bulk_sign.sh

状态页面

kube-notary 提供嵌入式状态页面，显示运行中容器和验证详情。运行后可通过 http://$SERVICE_ADDRESS:9581/status/ 访问（服务地址取决于安装方式）。若使用提供的Helm图表安装，获取状态页面URL的最简单方式：

  # 状态页面
  export SERVICE_NAME=service/$(kubectl get service --namespace default -l "app.kubernetes.io/name=kube-notary,app.kubernetes.io/instance=kube-notary" -o jsonpath="{.items[0].metadata.name}")
  echo "状态页面地址：http://127.0.0.1:9581/status/"
  kubectl port-forward --namespace default $SERVICE_NAME 9581

指标

若集群中运行Prometheus，kube-notary 提供的指标将被自动发现。此外，可参考此处获取预配置的Grafana仪表板示例。

配置

默认情况下，kube-notary 安装到当前命名空间（可通过 helm install --namespace 修改），但会监控所有命名空间的Pod。

安装时可通过Helm的 --set 选项修改 helm/kube-notary/values.yaml 中的任何值。例如，仅监控 kube-system 命名空间：

helm install -n kube-notary helm/kube-notary --set watch.namespace="kube-system"

信任签名者

可通过以下选项配置信任的签名者。

配置信任密钥列表

列表需用 {} 包含，密钥间用 , 分隔。例如：

helm install -n kube-notary helm/kube-notary --set "trust.keys={0x123..., 0x123...}"

配置信任组织

helm install -n kube-notary helm/kube-notary --set "trust.org=your.organization.com"

注意

若同时设置 trust.org 和 trust.keys，仅 trust.org 会生效。

若均未设置，验证时将使用具有最高https://github.com/v***us/vcn/blob/master/docs/user-guide/signatures.md#level%E7%9A%84%E7%AD%BE%E5%90%8D%E8%80%85%E7%9A%84%E6%9C%80%E6%96%B0https://github.com/v***us/vcn/blob/master/docs/user-guide/signatures.md#signatures%E3%80%82

运行时配置

helm/kube-notary/values.yaml 中的以下选项影响 kube-notary 运行行为：

# 运行时配置
log:
  level: info # 日志级别，可选：trace, debug, info, warn, error, fatal, panic
watch:
  namespace: "" # 监控的命名空间
  interval: 60s # 监控间隔时间
trust:
  org: "" # 信任组织ID，若不为空则忽略上方的keys配置
  keys: # 用于验证的签名密钥数组
   - ...
   - ...

安装时，配置存储在 configmap 中。支持配置热重载，可在 kube-notary 运行时修改并应用configmap。

例如，将监控间隔从默认60s修改为30s：

kubectl patch configmaps/kube-notary \
    --type merge \
    -p '{"data":{"config.yaml":"log:\n  level: debug\nwatch: \n  namespace: \n  interval: 30s"}}'

CodeNotary Ledger Compliance集成

kube-notary 支持与 CodeNotary Ledger Compliance 集成。 在CNLC模式下运行需执行以下步骤：

• 创建api-key密钥

shell
kubectl create secret generic vcn-lc-api-key --from-literal=api-key=trqgnxwyjdwmcuajmczcrtjccagzhiawzkod

• 使用以下参数安装Helm图表

helm install \
    -n kube-notary ../../helm/kube-notary \
    --set image.repository=$KUBE_NOTARY_IMAGE --set image.tag=$KUBE_NOTARY_TAG \
    --set image.pullPolicy=Always \
    --set cnlc.host={CNLC IP地址，默认空} \
    --set cnlc.port={CNLC端口，默认3324} \
    --set cnlc.cert={CNLC证书，默认空} \
    --set cnlc.noTls={CNLC启用非安全连接，默认true} \
    --set cnlc.skipTlsVerify={CNLC跳过TLS验证，默认false} \
    --set cnlc.signerID={CNLC用于过滤特定签名者ID的参数，默认空} \
    --set cnlc.crossLedgerKeyLedgerName={CNLC在提供跨账本密钥时指定后续操作账本，默认空} \
    --wait

若需连接本地（或集群主机）CNLC实例进行调试，使用：

--set cnlc.host=$(hostname) \

签名镜像需使用至少 https://github.com/v***us/vcn v0.9.5 版本或提交 572eaab2c322079f12f36ac8b3abed67fbba2c59。

常见问题

为什么需要持续验证？

环境会随时间变化。假设您因信任而签名某个镜像，之后发现该镜像存在安全问题或需要弃用该版本，可使用 https://github.com/v***us/vcn#basic-usage 将其https://github.com/v***us/vcn/blob/master/docs/user-guide/signatures.md#statuses%E3%80%82%E4%B8%80%E6%97%A6%E9%95%9C%E5%83%8F%E4%B8%8D%E5%86%8D%E5%8F%97%E4%BF%A1%E4%BB%BB%EF%BC%8C%60kube-notary%60 可帮助您发现该镜像是否仍在集群中运行。

通常，仅在执行前验证镜像并不足够，因为镜像状态或容器使用的镜像可能随时间变化。持续验证确保您能及时发现异常行为。

如何签名镜像？

可使用单独提供的 https://github.com/v***us/vcn 轻松签名容器镜像。

vcn 原生支持本地Docker安装，使用 docker:// 前缀加镜像名称或引用。只需拉取要签名的镜像，然后运行 vcn sign。详细说明见https://github.com/v***us/vcn/blob/master/docs/user-guide/schemes/docker.md%E3%80%82

若需批量签名集群中所有运行的镜像，可生成自动化脚本：

导出 POD_NAME 为 kube-notary 的Pod名称，然后运行：

kubectl exec --namespace default -t $POD_NAME sh /bin/bulk_sign > vcn_bulk_sign.sh
chmod +x vcn_bulk_sign.sh && ./vcn_bulk_sign.sh

需拥有 CodeNotary 账户和本地安装的 https://github.com/v***us/vcn%E3%80%82%E7%A1%AE%E4%BF%9D kubectl 指向目标集群上下文。

如何在发现不受信任镜像时收到通知？

首先需在集群中安装Prometheus和Grafana。

然后使用提供的 Grafana仪表板 轻松创建告警。

为什么无法签名镜像？（manifest v2 schema 1）

镜像manifest v2 schema 1格式已弃用，推荐使用v2 schema 2格式。

请尽快迁移至v2 schema 2。通常只需重新推送镜像至仓库即可解决。

无法创建资源"clusterrolebindings"

新版本Kubernetes采用基于角色的访问控制（RBAC）系统进行授权决策。可能您的账户没有足够权限创建集群级访问所需的 ClusterRole。

请使用高权限账户安装 kube-notary。若没有集群级访问权限，可在有权限的单个命名空间内安装，详见命名空间级安装。

Helm错误：release kube-watch failed: namespaces "..." is forbidden

可能Helm的服务端组件 tiller 没有安装 kube-notary 的权限。

在启用RBAC的Kubernetes集群中，可能需要为 tiller 添加集群管理员角色的服务账户。

简单方法是创建 rbac-config.yaml，复制Helm文档中的示例，然后执行：

$ kubectl create -f rbac-config.yaml
serviceaccount "tiller" created
clusterrolebinding "tiller" created
$ helm init --service-account tiller --history-max 200

Prometheus Operator的ServiceMonitor

参见 https://github.com/v***us/kube-notary/issues/11%E3%80%82

测试

make test/e2e

开发

如需使用Kubernetes启动调试环境，可使用make工具：

shell
make image/debug
make kubernetes/debug

此命令将使用 https://github.com/kubernetes-sigs/kind 启动Kubernetes集群，并在Pod内启动dlv调试服务器，支持远程调试。

许可

本软件基于 GPL3 许可发布。