# standalone-ingress

**Repository Path**: akikali/standalone-ingress

## Basic Information

- **Project Name**: standalone-ingress
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Standalone Ingress Controller with WAF Support

standalone-ingress 是一个独立的 Cilium Ingress 控制器，支持自定义 WAF（Web Application Firewall）规则注入。

## 功能特性

- **WAF 规则注入** - 支持三种配置方式（内联、ConfigMap、默认规则）
- **独立 IngressClass** - 避免与原生 cilium-operator 冲突
- **灵活的部署模式** - 支持 dedicated 和 shared 负载均衡模式
- **完整的 RBAC 权限** - 最小化权限原则

## 架构设计

### 核心原理

```
┌─────────────────────────────────────────────────────────────────┐
│                     Kubernetes Cluster                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Standalone Ingress                       ││
│  │  cmd/standalone-ingress/                                    ││
│  │                                                             ││
│  │  ┌─────────────────────────────────────────────────────┐    ││
│  │  │  Ingress Reconciliation                             │    ││
│  │  │  - Listens to Ingress                               │    ││
│  │  │  - Generates CiliumEnvoyConfig (CEC)                │    ││
│  │  └─────────────────────────────────────────────────────┘    ││
│  │           │                                                 ││
│  │           ▼                                                 ││
│  │  ┌─────────────────────────────────────────────────────┐    ││
│  │  │  injectCustomFilters()                              │    ││
│  │  │  - Parses Listener protobuf of CEC                  │    ││
│  │  │  - Injects Wasm HTTP filter                         │    ││
│  │  │  - Re-serializes to protobuf                        │    ││
│  │  └─────────────────────────────────────────────────────┘    ││
│  │           │                                                 ││
│  │           ▼                                                 ││
│  │  ┌─────────────────────────────────────────────────────┐    ││
│  │  │  CiliumEnvoyConfig                                  │    ││
│  │  │  - Contains Wasm filter config                      │    ││
│  │  │  - Applied by Cilium Agent to Envoy Proxy           │    ││
│  │  └─────────────────────────────────────────────────────┘    ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### WAF 注入流程

1. **读取配置** - 从 Ingress annotations 或 ConfigMap 获取 WAF 规则
2. **构建 Wasm Filter** - 创建 Coraza WAF filter 配置
3. **解析 Listener** - 反序列化为 protobuf
4. **修改 HCM** - 在 http_filters 链中插入 Wasm filter
5. **序列化 CEC** - 重新序列化为 protobuf 并更新到集群

### 三种配置方式

| 方式 | Annotation | 说明 |
|------|------------|------|
| 内联规则 | `cilium.io/waf-rules` | 直接在 Ingress 中定义规则 |
| ConfigMap | `cilium.io/waf-configmap` | 引用外部 ConfigMap |
| 默认配置 | 无 | 使用内置的 OWASP CRS 规则 |

## 快速开始

### 前置条件

- Kubernetes 1.19+
- Cilium 已部署并启用 Hubble
- 可选的: Wasm 运行时支持

### 1. 构建

```bash
# 构建二进制
go build ./cmd/standalone-ingress

# 构建容器镜像
docker build -t cilium/standalone-ingress:latest -f cmd/standalone-ingress/Dockerfile .
```

### 2. 部署 RBAC

```bash
kubectl apply -f cmd/standalone-ingress/rbac.yaml
```

### 3. 创建 IngressClass (推荐)

```yaml
# independent-ingressclass.yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: standalone-waf
  annotations:
    ingressclass.kubernetes.io/is-default-class: "false"
spec:
  controller: standalone-ingress-controller
```

```bash
kubectl apply -f independent-ingressclass.yaml
```

### 4. 部署控制器

```bash
# 编辑 deployment.yaml 取消 --ingress-class 注释
kubectl apply -f cmd/standalone-ingress/deployment.yaml
```

### 5. 验证部署

```bash
# 检查 Pod 状态
kubectl get pods -n kube-system -l app=standalone-ingress-controller

# 检查日志
kubectl logs -n kube-system -l app=standalone-ingress-controller -f
```

## 配置说明

### 命令行参数

#### 必需配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--leader-elect` | false | 单实例部署，无需选举 |
| `--ingress-class` | cilium | IngressClass 名称 (推荐独立名称) |
| `--cilium-namespace` | kube-system | Cilium 命名空间 |
| `--secrets-namespace` | cilium-secrets | TLS 证书命名空间 |

#### 可选配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--default-lb-mode` | dedicated | 负载均衡模式 (dedicated/shared) |
| `--enforce-https` | true | 强制 HTTPS |
| `--shared-service-name` | cilium-ingress | 共享 LB Service 名称 |
| `--lb-annotation-prefixes` | (见下方) | LB 注解前缀列表 |
| `--hostnetwork-enabled` | false | 使用主机网络 |
| `--hostnetwork-shared-listener-port` | 0 | 主机网络监听端口 |
| `--xff-num-trusted-hops` | 0 | XFF 信任跳数 |
| `--enable-proxy-protocol` | false | 启用代理协议 |

默认 `lb-annotation-prefixes`:
```
lbipam.cilium.io,service.beta.kubernetes.io,service.kubernetes.io,cloud.google.com
```

## WAF 配置示例

### 1. 内联规则

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: waf-inline
  annotations:
    cilium.io/waf-enabled: "true"
    cilium.io/waf-rules: |
      SecRuleEngine On
      SecDebugLogLevel 9
      SecRule REQUEST_URI "@contains /test" "id:100,deny,status:418"
spec:
  ingressClassName: standalone-waf
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp
            port:
              number: 80
```

### 2. ConfigMap 引用

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: waf-rules
  namespace: default
data:
  rules.conf: |
    SecRuleEngine On
    SecRule REQUEST_URI "@contains /attack" "id:101,deny,status:403"
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: waf-configmap
  annotations:
    cilium.io/waf-enabled: "true"
    cilium.io/waf-configmap: "waf-rules"
spec:
  ingressClassName: standalone-waf
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp
            port:
              number: 80
```

### 3. 默认 OWASP CRS 规则

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: waf-default-rules
  annotations:
    cilium.io/waf-enabled: "true"
spec:
  ingressClassName: standalone-waf
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp
            port:
              number: 80
```

## 与原生 Cilium Operator 的兼容性

### 问题说明

原生 Cilium operator 默认会监听所有 Ingress 并覆盖 CEC，导致 standalone-ingress 的 WAF 配置被覆盖。

### 解决方案

#### 方案 1: 使用独立 IngressClass (推荐)

```yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: standalone-waf
  annotations:
    ingressclass.kubernetes.io/is-default-class: "false"
spec:
  controller: standalone-ingress-controller
```

部署时指定独立 IngressClass:
```bash
--ingress-class=standalone-waf
```

#### 方案 2: 禁用原生 ingress controller

```bash
kubectl patch configmap cilium-config -n kube-system -p '{"data":{"enable-ingress-controller":"false"}}'
kubectl rollout restart deployment cilium-operator -n kube-system
```

### 验证隔离效果

```bash
# 创建使用独立 IngressClass 的 Ingress
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-standalone
  annotations:
    cilium.io/waf-enabled: "true"
spec:
  ingressClassName: standalone-waf
  rules:
  - host: test.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp
            port:
              number: 80
EOF

# 检查是否有 CEC 被创建 (原生 operator 不会处理 standalone-waf)
kubectl get cec -A | grep test-standalone
```

## Wasm 配置注意事项

### 重要: Wasm Configuration 值必须是 JSON 字符串

Envoy Wasm filter 的 `configuration` 字段需要接收 **JSON 字符串**，而不是直接的 JSON 对象。

**错误做法:**
```yaml
# configuration 直接是 JSON 对象
configuration:
  "@type": type.googleapis.com/google.protobuf.StringValue
  value: {"directives_map": {"default": [...]}}  # 错误: 这是 JSON 对象
```

**正确做法:**
```yaml
# configuration 是 JSON 字符串
configuration:
  "@type": type.googleapis.com/google.protobuf.StringValue
  value: '{"directives_map": {"default": [...]}}'  # 正确: 这是 JSON 字符串
```

standalone-ingress 会自动处理序列化，确保 WAF 规则被正确包装为字符串。

## 开发指南

### 目录结构

```
cmd/standalone-ingress/
├── main.go                    # 程序入口，命令行参数解析
├── Dockerfile                 # 容器镜像构建
├── deployment.yaml            # Kubernetes 部署配置
├── rbac.yaml                  # RBAC 权限配置
├── agent.md                   # 任务说明文档
├── ingress/
│   ├── ingress.go             # 控制器注册和 Predicates
│   ├── ingress_reconcile.go   # 核心 reconcile 逻辑
│   ├── ingress_test.go        # 控制器测试
│   ├── ingress_waf_test.go    # WAF 功能测试
│   ├── standalone.go          # RegisterStandaloneController 导出函数
│   ├── helpers.go             # Ingress 判断工具函数
│   ├── secretsync.go          # Secret 同步处理
│   ├── annotations/
│   │   └── waf.go             # WAF 注解解析
│   └── lb.go                  # 负载均衡注解处理
└── examples/
    ├── waf-ingress.yaml       # WAF Ingress 完整示例
    └── waf-configmap.yaml     # ConfigMap 配置示例
```

### 运行测试

```bash
# 运行所有测试
go test ./cmd/standalone-ingress/... -v

# 运行特定测试
go test ./cmd/standalone-ingress/... -v -run "TestBuildWAFRules"
```

### 本地调试

```bash
# 使用本地 kubeconfig
export KUBECONFIG=~/.kube/config

# 运行二进制
./standalone-ingress --leader-elect=false --ingress-class=standalone-waf
```

## 故障排查

### WAF 不生效

1. 检查 Ingress annotations 配置正确
   ```bash
   kubectl describe ingress <name>
   ```

2. 检查 Wasm 配置格式
   ```bash
   kubectl get cec <cec-name> -n <namespace> -o yaml
   ```

3. 查看控制器日志
   ```bash
   kubectl logs -n kube-system -l app=standalone-ingress-controller
   ```

### CEC 被覆盖

如果使用 `cilium` IngressClass，检查原生 operator:
```bash
# 检查 operator 日志
kubectl logs -n kube-system -l name=cilium-operator

# 确认 IngressClass 设置
kubectl get ingressclass cilium -o yaml
```

### 独立 IngressClass 不工作

1. 确认 IngressClass controller 名称匹配
   ```bash
   kubectl get ingressclass standalone-waf -o jsonpath='{.spec.controller}'
   ```

2. 确认部署时指定了正确的 `--ingress-class`

## 已知问题

1. **cilium-operator 冲突** - 使用独立 IngressClass 可避免
2. **Wasm 文件路径** - 需要确保 Wasm 文件对 Envoy 可用
3. **默认 IngressClass** - 如果未指定 ingressClassName，控制器会检查默认 IngressClass

## License

Apache-2.0