Kubernetes

对应的官方页面地址

Bitwarden Secrets Manager Kubernetes Operator (sm-operator) 是一个工具，用于帮助团队无缝地将 Bitwarden Secrets Manager 集成到他们的 Kubernetes 工作流中。

sm-operator 使用控制器将 Bitwarden Secrets 同步到 Kubernetes secrets 中。它的做法是将 BitwardenSecret 的自定义资源定义注册到集群中。它会监听群集上已注册的新 BitwardenSecrets，然后按可配置的时间间隔进行同步。

如果您是 Secrets Manager 的新手，您应该首先阅读帮助中心文档，以了解其工作原理。

要求​

大部分所需的设置都可以使用 Visual Studio Code Dev Containers 来完成。这是推荐的方案，尤其是对于 macOS 和 Windows 用户。

Dev 容器

• Visual Studio Code

• Docker

• Visual Studio Code Dev Containers Extension

如果您使用的是除 Docker 以外的容器引擎，开发容器将无法正常工作。

直接设置

• Visual Studio Code

• Visual Studio Code Go Extension

• Go 版本 1.21

• musl-gcc

• Make

• kubectl

• Docker 或 Podman 或其他容器引擎

• Kind Cluster 或将 Kubectl 指向它作为本地开发的当前上下文的其他 Kubernetes 集群。

您还需要：

• 一个具有 Secrets Manager 的 Bitwarden 组织 。需要您的组织 ID GUID。

• Secrets Manager 机器账户（以前称为服务账户）的访问令牌，与您要提取的项目绑定。

设置和配置​

克隆存储库：

git clone https://github.com/bitwarden/sm-kubernetes.git

在存储库根目录下打开 Visual Studio Code。

Dev 容器

开发容器的设置是自动化的。这将创建一个 Kind 集群并设置所有必要的软件。

• 打开命令调板（根据用户设置，使用 Cmd/Ctrl+Shift+P 或 F1）

• 输入 Dev Containers: Reopen in Container 以开始

直接设置

请注意，如果通过路径中任意位置的符号链接打开工作区，Visual Studio Code 的 Go 调试器将无法正常工作。要使调试正常工作，应从软件源的完整路径打开。

• 安装直接设置要求中所列出的所有要求

• 使用 kind create cluster 创建 Kind 群集

• 运行 make setup 创建默认的 .env 文件。

配置设置​

创建了 Dev 容器或运行了 make setup 后，就会在存储库根目录下创建一个 .env 文件。可以更新以下环境变量设置来改变 operator 的行为：

• BW_API_URL - 设置 Secrets Manager SDK 使用的 Bitwarden API URL。这对于自托管场景以及访问欧洲服务器非常有用。

• BW_IDENTITY_API_URL - 设置 Secrets Manager SDK 使用的 Bitwarden Identity 服务 URL。这对于自托管场景以及访问欧洲服务器非常有用。

• BW_SECRETS_MANAGER_STATE_PATH - 设置 Secrets Manager SDK 存储其状态文件的基本路径。

• BW_SECRETS_MANAGER_REFRESH_INTERVAL - 指定 Secrets Manager 和 K8s secrets 之间同步秘密的刷新间隔（以秒为单位）。最小值为 180。

运行和调试​

1. 使用 make install 或通过在命令面板中使用来自「Tasks: Run Task」的被称为「apply-crd」的 Visual Studio 任务，将自定义资源定义安装到群集中。

2. 要调试代码，只需按一下 F5。您还可以在命令行中使用 make run 来运行，而无需调试。，

您也可以通过运行以下命令（不使用调试器）一步到位：make install run

卸载自定义资源定义​

要从集群中删除 CRD：

make uninstall

运行 make --help 获取所有潜在 make 目标的更多信息。

创建 BitwardenSecret 用于测试​

调试器运行中，我们现在将创建一个 BitwardenSecret 对象，以将 Secret Manager 机密同步到 K8s 机密中：

通过 kubectl 创建下面的授权令牌机密后，您的授权令牌就会出现在机器终端历史记录中。对于生产系统，请考虑使用 CSI 机密驱动程序或通过一个短暂的构建代理应用该机密。

确保在 VS Code 的 Dev 容器终端中运行以下命令。

1. 在创建 BitwardenSecret 对象的命名空间中创建一个秘密，用于存放 Secrets Manager 身份验证令牌：kubectl create secret generic bw-auth-token -n <some-namespace> --from-literal=token="<Auth-Token-Here>"

要获取命名空间列表，请运行 kubectl get namespaces

1. 安装 BitwardenSecret 实例。config/samples/k8s_v1_bitwardensecret.yaml 中有一个示例。您需要复制这个示例并根据自己的需要进行更新。然后按照这个方式应用：kubectl apply -n <some-namespace> -f k8s_v1_bitwardensecret.yaml

2. 在调试控制台窗口中，您应该看到表示机密已启动并完成同步的的消息

3. 运行以下命令查看是否已创建了机密：kubectl get secrets -n <some-namespace>

4. 运行以下命令查看已同步机密的结构和数据：kubectl get secret -n <some-namespace> <secret-name> -o yaml

机密值以 Base64 编码的字符串形式存储。

BitwardenSecret 清单​

将 BitwardenSecret 对象视为 operator 用来创建和同步 Kubernetes 机密的同步设置。这个 Kubernetes 机密将位于命名空间内，并将注入 Secrets Manager 机器账户（以前称为服务账户）可用的数据。生成的 Kubernetes 机密将包括特定机器账户可以访问的所有机密。示例文件 (config/samples/k8s_v1_bitwardensecret.yml) 提供了 BitwardenSecret 清单的基本结构。下面列出了需要更新的关键设置：

• metadata.name：您要部署的 BitwardenSecret 对象的名称

• spec.organizationId：您要从其中提取 Secrets Manager 数据的 Bitwarden 组织 ID

• spec.secretName：将创建并注入 Secrets Manager 数据的 Kubernetes 机密的名称。

• spec.authToken：BitwardenSecrets 对象部署到的 Kubernetes 名称空间中的机密名称，其中包含用于访问机密的 Secrets Manager 机器账户授权令牌。

Secrets Manager 不保证跨项目机密名称的唯一性，因此默认情况下，机密将以 Secrets Manager 机密 UUID 作为键创建。为了使生成的机密更容易使用，您可以创建一个 Bitwarden 机密 ID 到 Kubernetes 机密键的映射。生成的机密将用您提供的映射友好名称替换 Bitwarden 机密 ID。以下是可以使用的映射设置：

• bwSecretId：这是 Secrets Manager 中机密的 UUID。可以在 Secrets Manager 门户网站或使用 Bitwarden Secrets Manager CLI 在机密名称下找到

• secretKeyName：在 Kubernetes 机密中生成的键，用于替换 UUID

注意，自定义映射仅作为信息目的在已生成的机密中提供，可在 k8s.bitwarden.com/custom-map 注解中找到。

测试 Docker 镜像​

Windows 上的 Kind 很难从本地注册表中提取数据，因此我们提供了两种不同的路径来部署映像。

使用注册表

1. 构建并推送您的镜像到由 IMG 指定的注册表位置（本地或其他位置）： make docker-build docker-push IMG=<some-registry>/sm-operator:tag

2. 使用 IMG 指定的镜像将控制器部署到集群中：make deploy IMG=<some-registry>/sm-operator:tag

推送到 Kind

1. 直接使用 Visual Studio Code 命令面板构建并推送镜像到 Kind。打开面板（按 F1），选择「Tasks: Run Task」，然后选择「docker-build」和「kind-push」。

2. 使用 Visual Studio Code 命令面板部署 Kubernetes 对象到 Kind。打开面板（按 F1），选择「Tasks: Run Task」，然后选择「deploy」。

在使用容器时，可通过更新 config/manager/manager.yaml 中的环境变量对 URL、刷新间隔和状态路径进行自定义配置。

安装后，根据本文档中之前所述创建您的 K8s 授权令牌机密和 BitwardenSecret 以进行测试。

查看 Pod 日志​

要查看通过上述步骤部署的 operator 日志：

1. 运行 kubectl get pods -n sm-operator-system 。这将获取已安装的 operator pod 的名称。

2. 运行 kubectl logs -n sm-operator-system <name-of-pod-from-previous-step>

卸载控制器​

要从集群中移除已安装的控制器 pod，请运行：

make undeploy

单元测试​

单元测试目前位于以下文件中：

• internal/controller/suite_test.go

• cmd/suite_test.go

要运行单元测试，请运行 make test。要调试单元测试，请打开您想调试的文件。在 Visual Studio Code 的 「Run and Debug」选项卡中，将启动配置从「Debug」更改为「Test current file」，然后按 F5。

在调试测试之前，您需要运行 make test，这将设置一些必要的软件以进行 operator 测试。

目前不支持使用 Visual Studio Code 的「Testing」选项卡。

修改 API 定义​

如果您正在通过 api/v1/bitwardensecret_types.go 编辑 API 定义，请使用以下命令重新生成清单：

make manifests

更多信息请参阅 Kubebuilder 文档。