一个用于为测试cloud.redhat.com应用程序部署临时环境的CLI工具
项目描述
bonfire
一个由Red Hat工程师使用的CLI工具，用于将console.redhat.com应用程序部署到kubernetes/OpenShift。此工具主要用于创建临时测试环境。
例如，输入bonfire deploy host-inventory将在4分钟内部署主机清单应用程序及其所有依赖项并准备好运行
目录
关于
bonfire 与正在运行的 qontract-server 实例交互（该组件为 AppSRE 团队 的内部 app-interface graphql API 提供动力），以获取应用程序的 OpenShift 模板，处理它们并部署它们。您可以定义一个本地配置文件，以便在需要时覆盖应用程序配置。
它还与 ephemeral namespace operator 交互，以管理测试中临时命名空间的预留。
它与 Clowder operator 和 Frontend operator 相关的特殊功能，例如自动部署 ClowdApp 依赖项。
广泛的各种 CLI 选项允许您自定义部署到命名空间中的组件的确切组合。
注意：有关 app-interface 配置的信息，请参阅内部 ConsoleDot 文档
安装
本地安装
我们建议为 bonfire 设置虚拟环境
VENV_DIR=~/bonfire_venv
mkdir -p $VENV_DIR
python3 -m venv $VENV_DIR
. $VENV_DIR/bin/activate
pip install crc-bonfire
为防止 bonfire 调用 GitHub API 时出现 GitHub 速率限制问题，在您的 GitHub 账户上创建一个 个人访问令牌，该令牌授予 bonfire 读取您仓库的权限。
使用以下命令配置 bonfire 使用该令牌
echo 'GITHUB_TOKEN=<your api token>' >> ~/.config/bonfire/env
请注意：当使用 Github 令牌（经典版）时，它必须具有 read:project 范围。此外，由于某些项目可能是私有的，您还需要添加 repo（私有仓库的完全控制）范围，以便模板检索功能正常工作！
使用容器镜像（podman/docker）
我们在 quay.io/cloudservices/bonfire 提供了一个容器镜像。该镜像包含一个 Python 虚拟环境，并在其中安装了 crc-bonfire。
为了使用 Bonfire，您必须提供有效的 KUBECONFIG 或连接到目标 OpenShift 集群的 URL 和令牌。
容器的入口点已调用 bonfire CLI，并传递了传递给容器的参数，因此您应该能够运行您通常运行的任何 bonfire 命令，例如
podman run -it --rm quay.io/cloudservices/bonfire version
使用凭据
Bonfire 镜像可以使用 OC_LOGIN_SERVER 和 OC_LOGIN_TOKEN 变量连接到 OpenShift 集群。
podman run -it --rm -e OC_LOGIN_SERVER=https://api.openshift.example.com:6443 \
-e OC_LOGIN_TOKEN=some-api-token \
quay.io/cloudservices/bonfire namespace list
您还可以通过将其挂载到容器的 $HOME 目录中，使用主机上的 kubeconfig 文件。
podman run -it --rm --userns=keep-id:uid=1000,gid=1000 -v ${KUBECONFIG:="$HOME/.kube/config"}:/opt/bonfire/.kube/config:Z \
quay.io/cloudservices/bonfire namespace list
如果您希望 kubeconfig 在容器中位于非标准位置，您可以将 kubeconfig 挂载到容器的另一个路径中，并设置 KUBECONFIG 环境变量
podman run -it --rm --userns=keep-id:uid=1000,gid=1000 -v $HOME/.kube/config:/opt/kubeconfig:Z \
-e KUBECONFIG=/opt/kubeconfig \
quay.io/cloudservices/bonfire namespace list
快速入门
从 bonfire --help 开始，熟悉基本命令组。如果您想了解有关不同的 CLI 命令、选项和参数的更多信息，请不要忘记在子命令上使用 --help 标志。
部署
您最可能使用的命令是 bonfire deploy。
如果您在 Red Hat VPN 上，bonfire 将与 App-SRE 团队的 qontract-server API 的内部实例通信。您需要使用 oc login 登录到临时集群。
登录后，您应该能够键入 bonfire deploy advisor
这将导致 bonfire 执行以下操作
- 预留命名空间
- 检索 'advisor' 应用中所有组件的模板并处理它们。默认情况下，bonfire 将使用每个组件在应用中定义的 'main'/'master' 分支查找模板和提交哈希。它将查找该分支的 git 提交哈希，并自动设置传递给模板的
IMAGE_TAG参数。 - 如果找到 ClowdApp 资源，确定要检索和处理的附加 ClowdApps
- 将所有处理过的模板资源应用到您预留的命名空间中
- 等待所有资源达到“就绪”状态
运行bonfire namespace list --mine，您将看到您的命名空间。
使用oc project <NAMESPACE>切换到该命名空间
在您的命名空间中运行oc get clowdapp，您应该会看到已部署的几个ClowdApps。
如果您想延长您在命名空间中工作的时间，请使用bonfire namespace extend <NAMESPACE>
完成与命名空间的工作后，键入bonfire namespace release <NAMESPACE>以指示短暂的命名空间操作员删除您的预订。
部署命令是一个“一站式”命令，它将4个步骤结合起来
bonfire namespace reserve用于预留命名空间bonfire process用于获取并处理应用程序模板oc apply将处理过的应用程序模板应用到命名空间中bonfire namespace wait-on-resources <NAMESPACE>等待命名空间中的所有资源达到“就绪”状态
命名空间管理
- 使用
bonfire namespace reserve预留命名空间- 默认情况下，时长为1小时。使用
-d/--duration <time>增加时长 -- 示例时间格式：48h - 已设置不同的命名空间池以提供不同的测试环境配置。如果需要选择非默认池，请使用
--pool <pool>。要获取有效池的列表，请使用bonfire pool list
- 默认情况下，时长为1小时。使用
- 使用
bonfire namespace list查找命名空间- 使用
--mine只查看您预留的命名空间
- 使用
- 使用
bonfire namespace extend <NAMESPACE> -d <time>延长您的预订 -- 示例时间格式：48h - 使用
bonfire namespace release <NAMESPACE>释放您的命名空间预订
命名空间上下文
截至v4.12.0，bonfire现在分析在oc/kubectl上下文中设置的命名空间。这意味着在您使用oc project切换到命名空间后，可以运行诸如namespace extend、namespace release或deploy之类的命令，您不再需要在CLI上指定命名空间。bonfire将尝试使用您的当前命名空间（它将运行检查以确保您拥有它，并在您没有时发出警告）。此外，当使用bonfire deploy或bonfire namespace reserve预留新的命名空间时，bonfire还会为您自动运行oc project <NAMESPACE>以切换您的上下文到该新命名空间。
如果您希望忽略当前命名空间并强制进行命名空间预留，可以使用deploy命令的--reserve标志。
当bonfire在“机器人”模式下运行时（即当环境变量BONFIRE_BOT设置为true时），会禁用自动将“oc”上下文切换到新预留的命名空间。当在Jenkins等自动化CI/CD环境中使用bonfire时，应运行在机器人模式下以禁用自动上下文切换。
常见用例示例
在这些示例中，我们将使用名为“advisor”的应用程序，它有一个名为“advisor-backend”的ClowdApp组件
- 使用自定义git分支部署advisor-backend
bonfire deploy advisor --set-template-ref advisor-backend=custom_branch
- 使用自定义git提交部署advisor-backend
bonfire deploy advisor --set-template-ref advisor-backend=df0d7a620b1ac02e59c5718eb22fe82b8a4cfd3d
- 使用某个分支处理advisor-backend模板，但为容器设置不同的标签
bonfire deploy advisor --set-template-ref advisor-backend=some_branch --set-parameter advisor-backend/IMAGE_TAG=some_tag
- 部署advisor及其依赖项的生产版本
bonfire deploy advisor --ref-env insights-production
- 部署所有内容的生产版本，但使用开发分支为advisor-backend
bonfire deploy advisor --ref-env insights-production --set-template-ref advisor-backend=dev_branch
- 在部署时调整‘REPLICAS’参数值
bonfire deploy advisor --set-parameter advisor-backend/REPLICAS=3
- 覆盖特定容器镜像的所有出现的标签
bonfire deploy advisor --set-image-tag quay.io/cloudservices/advisor-backend=my_tag
常用CLI选项
部署/处理
--frontends=true-- 默认情况下，bonfire不会部署前端资源。使用此标志启用应用程序前端部署。--set-image-tag <image uri>=<tag>-- 使用此命令来更改模板中出现的容器镜像的标签。这将执行对<image uri>的搜索/替换操作，并将标签设置为<tag>--target-env-- 此命令更改bonfire查找的部署目标，以确定处理应用程序模板时要应用的参数。默认情况下，目标环境设置为insights-ephemeral--ref-env-- 此命令更改bonfire查找的部署目标，以确定获取应用程序配置的 git ref。例如，使用--ref-env insights-stage将导致bonfire部署应用程序的阶段 git ref，而使用--ref-env insights-production将导致bonfire部署应用程序的生产 git ref。如果未找到匹配环境的目标，则bonfire将默认回滚到部署 'main'/'master' 分支。--set-template-ref <component>=<ref>-- 使用此命令来更改单个组件部署的 git ref。--set-parameter <component>/<name>=<value>-- 使用此命令在特定组件的模板上设置参数值。--optional-deps-method <hybrid|all|none>-- 修改 bonfire 处理 ClowdApp 可选依赖项的方式（请参阅“依赖项处理”部分）--prefer PARAM_NAME=PARAM_VALUE-- 在bonfire发现多个部署目标的情况下，使用此命令设置参数名称和值，以便选择“首选”部署目标。此选项可以多次传递。bonfire将选择具有最多“首选参数”的目标。默认设置为ENV_NAME=frontends以在 consoledot 环境中选择“稳定”前端。
受信任/不受信任资源配置
在处理模板时，bonfire 将从 OpenShift 模板中的 ClowdApp/ClowdJob/ClowdJobInvocation 对象中删除所有不受信任的 CPU/内存请求和限制（这是因为 --remove-resources 的默认值是 all）。如果在 ClowdApp 中未设置资源配置，Clowder 将设置部署使用在“ClowdEnvironment”中定义的默认值。
此行为的原因是许多应用程序模板在模板中请求的 CPU/内存比实际测试环境中需要的要多。
您可以使用 --no-remove-resources 选项关闭此行为，但对于某些应用程序或组件，首选的方法是审计您的 CPU/内存配置，并设置 bonfire 可信的资源配置。
一旦您已审核了测试环境中的容器 CPU/mem 使用情况，并确定了您想使用的有效值，您可以通过遵守以下要求来指示 bonfire 相信 CPU/Memory 请求和限制
- 在您的模板中请求使用请求或限制获取 CPU/mem 的任何 ClowdApp/ClowdJob/ClowdJobInvocation 都应使用以下格式的参数名称
-
CPU_REQUEST_<NAME> -
CPU_LIMIT_<NAME> -
MEM_REQUEST_<NAME>或MEMORY_REQUEST_<NAME> -
MEM_LIMIT_<NAME>或MEMORY_LIMIT_<NAME>其中
<NAME>可以是您想要使用的任意名称，包含A-Z，0-9和_。例如，以下两种都是有效的CPU_REQUEST_MQ_CONSUMERMEM_LIMIT_API
注意： 如果您的模板中只有一个组件，您可以根据需要从参数名称中省略
_<NAME>。
- 您必须明确为组件的部署配置定义这些参数的值。对于临时环境，通常这意味着在 app-interface 的临时部署目标下定义您的参数。
如果遵循这些步骤，则您的资源配置被视为“可信”，并且 bonfire 不会删除请求/限制配置。
注意： 未来将更改的一些内容
- “host-inventory”应用程序默认可信，但一旦它们的配置经过调整以可信，我们将删除此设置
- 当前不分析如Deployment/StatefulSet/DaemonSet等对象类型。一旦团队审核完所有容器资源配置，我们将会开始对所有对象类型进行bonfire的信任配置检查。
与临时命名空间操作器的交互
bonfire在集群中创建/修改NamespaceReservation资源以保留和释放命名空间。bonfire应用到集群中的对象的模板可以在此处找到。
有关临时命名空间操作符的工作方式，请参阅其文档此处
与Clowder操作器的交互
ClowdEnvironments
-
bonfire期望在部署之前为命名空间创建一个ClowderClowdEnvironment资源。这个ClowdEnvironment已经由临时命名空间操作符创建。 -
当执行命名空间的
bonfire deploy时，它将尝试找到与该命名空间关联的ClowdEnvironment，并为它处理的每个模板设置相应的ENV_NAME参数。所有定义了ClowdApp资源的模板都应该在它们的spec中使用名为${ENV_NAME}的参数设置environment映射。
依赖项处理
在ClowdApp定义中，列在dependencies下的应用被认为是必须存在的应用，以便您的应用能正常运行，而列在optionalDependencies下的应用则被认为是可能不存在，但您的应用仍然可以启动并运行的应用。
当bonfire处理模板时，如果它找到一个ClowdApp，它会执行以下操作
-
如果ClowdApp有
dependencies，它将尝试在app-interface中查找该ClowdApp的配置并获取其模板 -
如果ClowdApp有
optionalDependencies，它将根据所选的optional dependencies方法有所不同hybrid（默认）：如果在CLI上明确指定了应用组（例如：当运行bonfire deploy app-a时，应用组'app-a'被明确指定），则将为该应用组部署optionalDependencies。对于任何bonfire遇到的不是明确指定应用组成员的ClowdApp，将不会部署optionalDependencies。例如app-a在optionalDependencies下列出了app-b-clowdappapp-b-clowdapp在其optionalDependencies下列出了app-c-clowdapp- 您最终将在您的命名空间中获得
app-a和app-b-clowdapp的所有组件。app-c-clowdapp将不会被部署到命名空间中。
all：bonfire将部署它遇到的ClowdApp的所有optionalDependencies。它将递归处理依赖项。例如app-a在optionalDependencies下列出了app-b-clowdappapp-b-clowdapp在其optionalDependencies下列出了app-c-clowdapp- 您将最终在命名空间中部署
app-a、app-b-clowdapp和app-c-clowdapp的所有组件。
none：bonfire将忽略它遇到的ClowdApp上的所有optionalDependencies
配置详情
注意：有关 app-interface 配置的信息，请参阅内部 ConsoleDot 文档
在运行bonfire process/bonfire deploy时，默认使用app-sre团队的内部GraphQL API服务器。bonfire将查询GraphQL API并读取应用的部署配置。
注意：您需要连接到内部VPN才能访问默认的GraphQL API URL。
bonfire依赖于一些关键信息来处理应用配置
- 应用名称。这通常是列在
app-interface中的app.yaml中的名称 - 一个'target env'——bonfire查看的
app-interface环境名称，以确定在处理应用模板时应用的参数。只有当应用配置设置了部署目标，指向此环境中的命名空间时（默认："ephemeral"），才会处理应用的配置 - 一个“ref env”——我们要使用的
app-interface环境的名称，以便确定要部署的组件的哪个 git 引用以及要设置哪个IMAGE_TAG值。默认情况下，没有设置任何值，这会导致 bonfire 使用所有组件的 ‘main’/‘master’ git 分支。 - 您希望覆盖的任何模板引用（可选）
- 您希望覆盖的任何镜像标签（可选）
- 您希望覆盖的任何参数（可选）
默认情况下，如果应用程序组件在模板中使用 ClowdApp 资源，则 bonfire 将动态加载依赖项（请参阅“依赖项处理”部分）
使用本地配置
bonfire 随带一个 默认配置，这对于大多数内部 Red Hat 员工来说应该足够开始使用。
默认情况下，配置文件将存储在 ~/.config/bonfire/config.yaml。
如果您希望覆盖任何应用程序配置，可以通过键入 bonfire config edit 编辑您的本地配置文件。然后您可以在配置的 apps 键下定义一个应用程序。您可以使用 bonfire config write-default 在任何时间将配置重置为默认值。
截至 bonfire v5，有两种方式来加载本地配置（由 CLI 选项 --local-config-method 控制）。假设我们已按如下方式在 app-interface 中配置了一个应用程序
resourceTemplates:
- name: mycomponent1
path: /deployment.yaml
url: https://github.com/myorg/myrepo1
targets:
- namespace:
$ref: /services/insights/ephemeral/namespaces/ephemeral-base.yml
parameters:
MIN_REPLICAS: 1
- name: mycomponent2
path: /deployment.yaml
url: https://github.com/myorg/myrepo2
targets:
- namespace:
$ref: /services/insights/ephemeral/namespaces/ephemeral-base.yml
parameters:
MIN_REPLICAS: 2
SOME_OTHER_PARAM: some_other_value
并且本地配置文件有如下条目
apps:
- name: myapp
components:
- name: mycomponent2
parameters:
MIN_REPLICAS: 10
bonfire 可以使用两种方法之一覆盖远程配置
-
--local-config-method merge（默认）。在这种模式下，您的本地配置中的应用程序配置与 bonfire 远程获取的配置合并。在上述配置中，只有应用程序“myapp”中“mycomponent2”的“MIN_REPLICAS”参数将被覆盖。其他参数“SOME_OTHER_PARAM”仍然存在，“mycomponent1”将保持不变。 -
--local-config-method override。在这种模式下，本地应用程序配置将优先于 bonfire 远程获取的应用程序配置。换句话说，定义本地应用程序配置将替换该应用程序中所有组件在 app-interface 中定义的配置。因此，“mycomponent1”将被完全删除，“mycomponent2”将只具有您在本地配置中定义的参数。
本地配置示例
部署本地仓库更改
如果您想测试对应用程序所做的更改，但这些更改尚未推送到 git 仓库，本地配置可能如下所示
apps:
- name: my_app
components:
- name: service
host: local
repo: ~/dev/projects/my-app
path: /clowdapp.yaml
parameters:
SOME_PARAMETER: some_value
- 其中 host 设置为
local表示在本地目录中查找仓库 - 其中 repo 表示您的 git 仓库文件夹的路径
- 其中 path 指定在 git 仓库中的 ClowdApp 模板文件的相对路径
默认情况下，bonfire 将运行 git rev-parse 以确定仓库文件夹中的当前工作提交哈希，这将确定在部署模板时设置哪个 IMAGE_TAG。这意味着您需要为该提交哈希推送有效的容器镜像。但是，您可以使用 --set-image-tag/--set-parameter 或在您的配置中定义 IMAGE_TAG 参数来覆盖您在部署期间希望使用的镜像。
部署远程git分支的更改
如果您想部署您正在工作的已推送到 PR/分支的应用程序更改，本地配置可能如下所示
apps:
- name: my_app
components:
- name: service
host: github
repo: MyOrg/MyRepo
ref: my_branch
path: /clowdapp.yaml
- 其中 host 设置为
github或gitlab表示仓库托管的位置 - 其中 repo 表示
OrganizationName/RepoName - 其中 path 指定在 git 仓库中的 ClowdApp 模板文件的相对路径
- 其中 ref 指定要部署的仓库的分支或提交
默认情况下，bonfire 将使用在指定的 git 引用中找到的最新提交哈希来确定传递给部署模板的 IMAGE_TAG。
高级
运行本地qontract-server
默认情况下，bonfire 配置为指向 app-sre 团队的内部 GraphQL API，但通过使用环境变量，您可以将其指向您的 qontract-server 实例。
export QONTRACT_BASE_URL="https://localhost:4000/graphql"
export QONTRACT_USERNAME=myUsername
export QONTRACT_PASSWORD=myPassword
出于测试/调试目的，您可以直接在本地运行自己的app-interface API服务器副本，而不是直接提交更改到app-interface。
- 克隆 https://github.com/app-sre/qontract-server
- 克隆内部
app-interface仓库
在 qontract-server 中运行
npm install yarn
yarn install
yarn build
make bundle APP_INTERFACE_PATH=/path/to/app-interface
LOAD_METHOD=fs DATAFILES_FILE=bundle/bundle.json yarn run server
下载文件
下载适用于您平台上的文件。如果您不确定选择哪个，请了解更多关于 安装包 的信息。
源分发
构建分发
crc_bonfire-5.11.0.tar.gz 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 68a4116c50b9080d99813eb2d0762cfd967b25324c8694997a28483eb8bd4c9b |
|
| MD5 | b065b6383730f7c659f2fe8834db97a0 |
|
| BLAKE2b-256 | d167ee102be6140c59de3cb097c30514c6b6383a02ecc716c55e7d6fa41c2830 |
crc_bonfire-5.11.0-py3-none-any.whl 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 191e4b91f986898242343c7ecbdbdcd5a8140f24899037f2538f7dbbd0917db0 |
|
| MD5 | 0b2b864c11d469841674f16b8bc9d745 |
|
| BLAKE2b-256 | 30111539bfd98a6844ebbc2df9a8bddac2e987f23e92c4400247e2a23c46b865 |