仅监控应用

在此模式下，Operator不会部署 SmartAgent DaemonSet，因此不会收集宿主机的基础指标。该方案利用 Kubernetes 准入控制（Admission Control）机制来监控 Pod 的创建过程，并动态修改 Pod 的资源配置。

具体而言，Operator会为目标 Pod 添加一个 Init Container（初始化容器）。这个 Init Container 负责部署探针模块，并通过给业务容器配置 LD_PRELOAD 环境变量来实现探针的自动注入，从而完成对应用的监控。

支持范围

支持应用探针的自动识别和注入
支持通过 Kubernetes Annotations/Labels 控制监控粒度
不支持进程/容器的深度监控规则，可通过 Kubernetes 注解控制监控
不支持自定义进程组识别规则
- **进程组名（服务名）**默认为：(<namespace>) <容器名称> <进程名称>
- **进程组实例名称（探针名）**默认为：(<进程组名>-<Pod名称后缀>-<进程ID>
- 可以通过为业务容器添加 BR_APM_PROCESS_GROUP_NAME 环境变量来设置自定义进程组名称, 详细见：Deployment YAML示例
技术类型支持矩阵
主机资源要求

创建 Smart Operator 所需的 kubernetes 资源对象

信息

kubernetes.yaml
kubernetes-webhook-only.yaml
kubernetes-csi.yaml

完整部署, 可随时切换全栈监控模式
仅部署webhook，权限最小化

信息

webhook 所需证书由 smartagent-operator 容器自动生成
详情请参见 更新 webhook 证书

创建 kubernetes 资源
# 创建 Kubernetes namespace
kubectl create namespace bonree-agent
# 部署 smartagent-operator 和 bonree-webhook
kubectl apply -f kubernetes.yaml
# [可选] 在仅监控应用的部署场景下，如果需要启用 CSI driver 来缓存每个节点的 smartagent serverless 探针，则需要应用以下配置
kubectl apply -f kubernetes-csi.yaml
# 查看部署日志
kubectl -n bonree-agent logs -f deployment/smartagent-operator

信息

默认 YAML 文件中包含了有效期为 10 年的证书（仅限 bonree-agent 命名空间使用）
若需在其他命名空间中使用，则需要手动创建证书。详情请参考 更新 webhook 证书
有关权限的更多信息，请参阅 权限说明

创建 kubernetes 资源
# 创建 Kubernetes namespace
kubectl create namespace bonree-agent
# 部署 bonree-webhook
kubectl apply -f kubernetes-webhook-only.yaml
# [可选] 在仅监控应用的部署场景下，如果需要启用 CSI driver 来缓存每个节点的 smartagent serverless 探针，则需要应用以下配置
kubectl apply -f kubernetes-csi.yaml
# 查看部署日志
kubectl -n bonree-agent logs -f deployment/bonree-webhook

创建存储 PaaSToken 的 Secret

PaaSToken来源

PaaSToken 需要从平台获取（请将下面命令中的 <Token> 替换为 Bonree One 平台 部署配置 -> 安装部署 -> SmartAgent 中部署命令里的 PaaSToken 值），该 Token 用于下载探针及相关接口的访问。

创建 secret
kubectl -n bonree-agent create secret generic smartkube --from-literal="PaaSToken=<Token>"

创建 SmartKube CRD

SmartKube CRD（Custom Resource Definition）是 Bonree SmartAgent Operator 的核心配置对象，用于定义和管理应用监控的相关参数。以下配置文件示例展示了如何配置仅监控应用模式，包括探针下载地址、连接信息、监控类型以及初始化容器的相关配置。

kubectl apply -f smartkube.yaml

smartkube.yaml 仅监控应用

smartkube.yaml
apiVersion: bonree.com/v1alpha1
kind: SmartKube
metadata:
  name: smartkube
  namespace: bonree-agent
spec:
  # bonree apm base api url
  apiUrl: https://one.bonree.com/rest/apm/agentDown

  # 探针连接相关配置
  controllerInfo:
    controllerUrl: https://oneupload.bonree.com/APM
    accountGUID: xxx-xxx-xxx-xxxx-xxxxxx

  # 启用探针类型
  # 全栈监控模式下，默认值，不修改
  # 仅监控应用模式下，默认值："java,php,dotnet,python,nodejs,nginx,go,apache"
  agentTypes: "java,php,dotnet,python,nodejs,nginx,go,apache"

  # [可选] 指定网络区域
  # 默认：不设置
  # networkZone: default

  # [可选] 指定集群名
  # 默认：不设置
  # clusterName: default

  # [可选] 指定环境id
  # 默认：不设置
  # envId: default

  # [可选]: 指定存储 token 的 secret 名称
  # 默认值为 smartkube
  # tokens: ""

  # [可选]: 下载安装包或api请求时，跳过证书验证
  # 默认：false
  # skipCertCheck: false

  # [1.1.0+] [SmartAgent 9.1.0+] [可选]：指定主机属性（数据中心）
  # 默认：不设置
  # 格式："k=v,k1=v1"
  # hostAttributes: ""

  # [1.1.0+] [SmartAgent 9.1.0+] [可选]：指定主机标签
  # 默认：不设置
  # 格式："k=v,k1=v1"
  # hostTags: ""

  # 仅监控应用配置
  agentModules:
    # 开启仅应用安装模式
    enabled: true

    # [可选]: Kubernetes init container 容器实例资源限制。请调整合适的值。
    # 详细见：https://kubernetes.io/zh/docs/concepts/configuration/manage-resources-containers/
    # resources:
    #   requests:
    #     cpu: 30m
    #     memory: 30Mi
    #   limits:
    #     cpu: 100m
    #     memory: 60Mi

    # [可选]: 启用CSI driver缓存每个节点的smartagent探针
    # 默认值: false
    #
    #  Container Storage Interface (CSI) 是一个用于容器编排系统（如 Kubernetes）的规范，它定义了插件与存储系统之间的接口，以便可以动态地挂载和卸载存储卷。
    #  探针包缓存于每个节点以下目录中:  /var/lib/kubelet/plugins/csi.smartagent.bonree.com/data
    #  true: 使用 SmartAgent CSI 卷（容器存储接口）缓存每个节点的探针 (管理探针版本及更新)
    #        详细见：https://github.com/kubernetes-csi/node-driver-registrar
    # false: 每次启动应用Pod时，下载 SmartAgent-serverless 探针
    #
    # 如果你的 Kubernetes 集群节点不支持 CSIDriver，可以将 UseCSIDriver 设为 false。
    useCSIDriver: true

    # [1.1.0+] [可选] 使用内置serverless探针的镜像作为 init container的镜像
    # 默认：空
    #
    # 当设置该值时，将直接使用该镜像内置的探针包，不使用CSI缓存探针或运行时下载
    # 镜像来源请使用：docker.bonree.com/agent/smartagent-serverless:<version>
    image: ""

    # [1.1.0+] [可选] 设置init container镜像的拉取策略
    # 默认值：IfNotPresent
    # imagePullPolicy: IfNotPresent

为需要监控的命名空间指定 SmartKube 自定义资源配置名称

信息

在仅监控应用模式下，所有带有 smartagent.bonree.com/instance 标签的命名空间中新建的 Pods 都将自动注入并配置探针模块。
您可以通过 Kubernetes Annotations 或 Labels 来控制监控的粒度。

Smart Operator 将监控带有标签 smartagent.bonree.com/instance 的命名空间下的所有 Pods。该标签的值应设置为对应的 SmartKube 自定义资源的 metadata.name（参见 smartkube.yaml）。

您需要为每个待监控的命名空间指定相应的 SmartKube 自定义资源配置。通过为不同命名空间配置不同的 SmartKube 设置，可以实现更精细的监控管理，例如实现探针版本的灰度测试等。

为命名空间指定生效的 SmartKube 自定义资源配置名称
# 为 default 命名空间指定使用名为 smartkube 的 SmartKube 自定义资源配置
# 其中 smartkube 为 smartkube.yaml 中 metadata.name 指定的名称
kubectl label namespace default smartagent.bonree.com/instance=smartkube

# 删除 default 命名空间的监控配置标签，取消对该命名空间的监控
kubectl label namespace default smartagent.bonree.com/instance-

自定义监控粒度 [可选]

可通过 Kubernetes Annotations 控制监控粒度。

以下注解的控制功能仅在已设置 smartagent.bonree.com/instance 标签的命名空间下生效。

Namespace 级别注解

smartagent.bonree.com/inject: "true" 或 "false"
控制该 namespace 下的 Pod 是否需要注入探针模块
当命名空间存在 smartagent.bonree.com/instance 标签但未设置该注解时，默认监控该命名空间下的所有 Pods
示例：

# 为 <your-ns-name> 命名空间下的 Pods 设置默认不注入探针模块
kubectl annotate namespace <your-ns-name> smartagent.bonree.com/inject=false

Pod 注解配置

Pod 级别支持以下注解，用于调整探针模块的安装路径、下载链接和允许监控的探针类型：

注解	可选值	说明	缺省值
`smartagent.bonree.com/inject`	`"true"` 或 `"false"`	控制当前 Pod 是否需要注入探针模块	`true`
`smartagent.bonree.com/install-path`	`"path"`	自定义 smartagent-serverless 探针安装路径	`/opt/bonree/apm-serverless`
`smartagent.bonree.com/installer-url`	`"url"`	仅在 `useCSIDriver` 为 `false`（不使用 smartagent CSI 驱动插件）且非镜像内置探针时生效，自定义 smartagent-serverless 探针下载链接	从`SmartKube`配置的 apiUrl 中进行下载
`smartagent.bonree.com/agent-types`	`"java,..."`	自定义允许监控的探针类型	见配置 agentTypes

Pod 注解配置示例
apiVersion: apps/v1
kind: Deployment
metadata:
  name: some-app
spec:
  selector:
    matchLabels:
      app: some-app
  strategy:
    type: Recreate
  template:
    metadata:
      annotations:
        smartagent.bonree.com/agent-types: "java,nginx"
        smartagent.bonree.com/inject: "true"
        smartagent.bonree.com/install-path: "/opt/bonree/apm-serverless"
        smartagent.bonree.com/installer-url: "https://my-custom-url/route/smartagent-serverless.tar.gz"
      labels:
        app: sample-app
    spec:
      containers:
      - command: [ "java", "-jar", "/app/app.jar" ]
        image: "my-image"
        name: "xxx"
        env:
          # 【可选】自定义进程组名（服务名）
          - name: BR_APM_PROCESS_GROUP_NAME
            value: "my-service"

支持范围​

创建 Smart Operator 所需的 kubernetes 资源对象​

创建存储 PaaSToken 的 Secret​

创建 SmartKube CRD​

smartkube.yaml 仅监控应用​

为需要监控的命名空间指定 SmartKube 自定义资源配置名称​

自定义监控粒度 [可选]​

Namespace 级别注解​

Pod 注解配置​