IPBlock-Operator-Plus

项目简介

IPBlock-Operator-Plus 是一个基于 Kubernetes 的 Operator，构建了一个插件化、模块化的恶意 IP 封禁管理平台。该项目通过自定义资源（IPBlock CR）实现对恶意 IP 的声明式管理，支持手动和自动限流与封禁功能。其架构高度可扩展，便于集成多种触发器（Trigger）和通知机制（Notify），从而实现智能化的安全防护与运维管理。

项目架构

架构图

IPBlock-Operator-Plus 项目由以下五个核心模块组成：

Controller（控制器）

负责核心业务逻辑的调度和协调，监听 Kubernetes 中 IPBlock 自定义资源的变化，维护和管理其生命周期。它是整个项目的核心部分，协调各个模块协同工作。
Engine（封禁后端）

负责封禁命令的实际执行。目前支持接入多种封禁机制（如XDP，iptables等）。通过插件化设计，便于快速扩展和替换不同的封禁技术方案。
Notify（通知机制）

负责将封禁、解封等事件以多种方式通知给运维人员或其他系统。现支持飞书通知渠道，开发人员可通过自定义插件（实现接口）灵活添加更多通知方式。
Trigger（触发器）

事件触发中心，负责监听外部告警系统或业务事件（如 Grafana Alert等），并根据 Alert 策略触发相关封禁操作，自动创建 IPBlock CR，且支持自动解封。模块设计也方便开发人员接入多种告警来源。
Policy（封禁策略）

定义 IP 封禁的判定规则和执行策略。现支持白名单机制，保障了封禁行为的精准与合理。

项目部署

环境要求

go version v1.24.0+
kubectl version v1.11.3+.
Access to a Kubernetes v1.11.3+ cluster.
Python 3
Make

项目支持 Helm 和 Make两种部署方式

封禁后端部署

封禁后端需要在监测目标机器上手动执行python3 ../../ipblock-operator/internal/engine/control.py

最好将其制作成Service，保证后台持久运行。

这里提供get_ip.service文件供参考。

[Unit] 
Description=Get IP Service 
After=network.target 
[Service] 
User=root 
WorkingDirectory=/root/yiiong/get_ip  # control.py所在目录
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/bin/bash -c 'source /root/yiiong/get_ip/venv/bin/activate && exec python3 control.py' # 运行Python程序，注意文件路径
Restart=always 
[Install] 
WantedBy=multi-user.target

Helm

项目的helm/下存放了IPBlock-Operator-Plus的helm chart，在安装前，请先填写values.yaml

# values.yaml
image:
  repo: beatrueman/ipblock-operator
  tag: "6.0"
  pullPolicy: IfNotPresent

config:
  gatewayHost: ""                                    # 封禁后端 URL
  engine: ""                                         # 可选: xdp, iptables
  whiteList: |			                     # IP 白名单，支持在 ConfigMap中动态更新
    1.2.3.4
  notifyType: ""                                     # 可选: lark
  notifyWebhookURL: ""                               # larkRobot Webhook
  notifyTemplate:                                    # larkRobot发送的card消息模板
    ban: "/templates/lark/ban.json"
    resolve: "templates/lark/resolve.json"
    common: "/templates/lark/common.json"
  triggers:                                          # 触发器，目前仅支持 Grafana
    - name: grafana
      addr: ":8090"
      path: "/trigger/grafana"

填写完成后，安装helm chart即可

注意需要将IPblock-Operator部署在default命名空间下。

helm install ipblock-operator .

Make

在集群上部署

将 CRD 安装到集群中

make install

将 Manager 部署到集群中

填写../../IPBlock-Operator-Plus/config/default下的configmap.yaml

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: ipblock-operator-config
data:
  gatewayHost: ""                                             # 封禁后端 URL
  engine: ""                                                  # 可选: xdp, iptables
  trigger: |                                                  # 触发器，目前仅支持 Grafana
    - name: grafana
      addr: ":8090"
      path: "/trigger/grafana"
  whitelist: |                                                # IP 白名单，支持在 ConfigMap中动态更新
    1.2.3.4
  notifyType: ""                                              # 可选: lark
  notifyWebhookURL: ""                                        # larkRobot Webhook
  notifyTemplate_ban: "/templates/lark/ban.json"              # larkRobot发送的card消息模板，请勿更改路径
  notifyTemplate_resolve: "/templates/lark/resolve.json"
  notifyTemplate_common: "/templates/lark/common.json"

注意：如果您遇到 RBAC 错误，您可能需要授予自己 cluster-admin 权限或以 admin 身份登录。

make deploy

创建样例

kubectl apply -k config/samples/

卸载

从集群中删除实例（CRs）

kubectl delete ipblock --all

从集群中删除API（CRDs）

make uninstall

从集群中删除控制器

make undeploy

配置项说明

ConfigMap

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: ipblock-operator-config
data:
  gatewayHost: ""                                             # 封禁后端 URL
  engine: ""                                                  # 可选: xdp, iptables
  trigger: |                                                  # 触发器，目前仅支持 Grafana
    - name: grafana
      addr: ":8090"
      path: "/trigger/grafana"
  whitelist: |                                                # IP 白名单，支持在 ConfigMap中动态更新
    1.2.3.4
  notifyType: ""                                              # 可选: lark
  notifyWebhookURL: ""                                        # larkRobot Webhook
  notifyTemplate_ban: "/templates/lark/ban.json"              # larkRobot发送的card消息模板，请勿更改路径
  notifyTemplate_resolve: "/templates/lark/resolve.json"
  notifyTemplate_common: "/templates/lark/common.json"

values.yaml

# values.yaml
image:
  repo: beatrueman/ipblock-operator
  tag: "6.0"
  pullPolicy: IfNotPresent

config:
  gatewayHost: ""                                    # 封禁后端 URL
  engine: ""                                         # 可选: xdp, iptables
  whiteList: |					     # IP 白名单，支持在 ConfigMap中动态更新
    1.2.3.4
  notifyType: ""                                     # 可选: lark
  notifyWebhookURL: ""                               # larkRobot Webhook
  notifyTemplate:                                    # larkRobot发送的card消息模板
    ban: "/templates/lark/ban.json"
    resolve: "templates/lark/resolve.json"
    common: "/templates/lark/common.json"
  ServiceType: NodePort
  triggers:                                          # 触发器，目前仅支持 Grafana
    - name: grafana
      addr: ":8090"
      path: "/trigger/grafana"

Trigger配置

Grafana

字段介绍

字段	说明	必需
name	触发器名称，当前支持 `grafana`	是
addr	监听地址和端口，例如 `":8090"`	是
path	Webhook请求路径，例如 `/trigger/grafana`	是

Grafana Alert配置

配置联络点

将配置好的URL填入联络点的URL中。

举例：http://<your-ip>:<NodePort>/trigger/grafana

配置警报规则

自定义警报规则，并选择联络点为刚才配置好的联络点。

本例为1min内若访问次数超过80，则触发警报。

Notigy配置

目前仅支持飞书Lark，后续将添加更多，如邮件、钉钉、企业微信等。

Lark

添加自定义机器人，并将获取到的Webhook地址填入配置的notifyWebhookURL即可。

使用示例

创建一个 IPBlock 资源

apiVersion: ops.yiiong.top/v1
kind: IPBlock
metadata:
  name: test-ipblock
spec:
  ip: "1.2.3.4"                       # 支持单IP / CIDR形式
  reason: "模拟异常请求"               # 封禁原因
  source: "manual"                    # 封禁源
  by: "admin"                         # 封禁者
  duration: "10m"                     # 封禁时长，当字段为空时，永久封禁

CR创建成功后，如接入飞书，会向用户发起通知。

对IP解封

apiVersion: ops.yiiong.top/v1
kind: IPBlock
metadata:
  name: test-ipblock
spec:
  ip: "1.2.3.4"                      
  reason: "模拟异常请求"                
  source: "manual"                    
  by: "admin"                         
  unblock: true                      # 解封字段

成功后，飞书会通知用户

手动强制封禁

apiVersion: ops.yiiong.top/v1
kind: IPBlock
metadata:
  name: test-ipblock
spec:
  ip: "1.2.3.4"                      
  reason: "模拟异常请求"                
  source: "manual"                    
  by: "admin"                         
  trigger: true                      # 重复封禁

白名单跳过

当在配置文件中指定了WhiteList（支持单IP / CIDR），CR会检测封禁IP是否在白名单中，如在则跳过。

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
api/v1		api/v1
cmd		cmd
config		config
docs		docs
hack		hack
helm		helm
internal		internal
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yml		.golangci.yml
Dockerfile		Dockerfile
Makefile		Makefile
PROJECT		PROJECT
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

IPBlock-Operator-Plus

项目简介

项目架构

项目部署

环境要求

封禁后端部署

Helm

Make

在集群上部署

将 CRD 安装到集群中

将 Manager 部署到集群中

创建样例

卸载

从集群中删除实例（CRs）

从集群中删除API（CRDs）

从集群中删除控制器

配置项说明

ConfigMap

values.yaml

Trigger配置

Grafana

字段介绍

Grafana Alert配置

Notigy配置

Lark

使用示例

创建一个 IPBlock 资源

对IP解封

手动强制封禁

白名单跳过

About

Uh oh!

Releases

Packages

Languages

Beatrueman/IPBlock-Operator-Plus

Folders and files

Latest commit

History

Repository files navigation

IPBlock-Operator-Plus

项目简介

项目架构

项目部署

环境要求

封禁后端部署

Helm

Make

在集群上部署

将 CRD 安装到集群中

将 Manager 部署到集群中

创建样例

卸载

从集群中删除实例（CRs）

从集群中删除API（CRDs）

从集群中删除控制器

配置项说明

ConfigMap

values.yaml

Trigger配置

Grafana

字段介绍

Grafana Alert配置

Notigy配置

Lark

使用示例

创建一个 IPBlock 资源

对IP解封

手动强制封禁

白名单跳过

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages